Configuración

Esta guía te ayudará a configurar el SDK de Retorna para Java según tus necesidades.

Configuración Básica

El SDK se configura usando RetornaClientOptions con un patrón builder:

import com.retorna.sdk.config.Environment;
import com.retorna.sdk.config.LoggingLevel;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.core.RetornaClientOptions;

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.DEVELOP)
        .loggingLevel(LoggingLevel.INFO)
        .clientId("YOUR_CLIENT_ID")
        .clientSecret("YOUR_CLIENT_SECRET")
        .privateKey("YOUR_PRIVATE_KEY_PEM")
        .build()
);

Parámetros de Configuración

Environment (Requerido)

Define el entorno en el que trabajarás:

.environment(Environment.DEVELOP)    // Desarrollo/Pruebas
.environment(Environment.STAGING)  // Pre-producción
.environment(Environment.PRODUCTION) // Producción

Entorno	Descripción	URL Base
DEVELOP	Entorno de desarrollo/pruebas	https://api-dev.retorna.com
STAGING	Entorno de pre-producción	https://api-staging.retorna.com
PRODUCTION	Entorno de producción	https://api.retorna.com

LoggingLevel (Opcional)

Controla el nivel de logging del SDK:

.loggingLevel(LoggingLevel.ERROR)  // Solo errores (por defecto)
.loggingLevel(LoggingLevel.WARN)  // Advertencias y errores
.loggingLevel(LoggingLevel.INFO)  // Información, advertencias y errores
.loggingLevel(LoggingLevel.DEBUG) // Todo (incluye debug)

Credenciales (Requeridas)

Client ID y Client Secret

.clientId("tu-client-id")
.clientSecret("tu-client-secret")

Private Key

La llave privada debe estar en formato PEM:

.privateKey("-----BEGIN PRIVATE KEY-----\n" +
            "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n" +
            "-----END PRIVATE KEY-----")

Importante: La llave privada debe incluir los headers -----BEGIN PRIVATE KEY----- y -----END PRIVATE KEY-----.

Base URL Personalizada (Opcional)

Si necesitas usar una URL base diferente:

.baseUrl("https://api-custom.retorna.com")

Access Token Inicial (Opcional)

Si ya tienes un token de acceso válido, puedes proporcionarlo:

.initialAccessToken("tu-access-token")

El SDK renovará automáticamente el token cuando expire.

Configuración con Variables de Entorno

Para mayor seguridad, especialmente en producción, usa variables de entorno:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.valueOf(
            System.getenv().getOrDefault("RETORNA_ENV", "DEVELOP")))
        .loggingLevel(LoggingLevel.valueOf(
            System.getenv().getOrDefault("RETORNA_LOG_LEVEL", "INFO")))
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .build()
);

Variables de entorno disponibles:

• RETORNA_CLIENT_ID - ID del cliente
• RETORNA_CLIENT_SECRET - Secret del cliente
• RETORNA_PRIVATE_KEY - Llave privada PEM
• RETORNA_ENV - Entorno (DEVELOP, STAGING, PRODUCTION)
• RETORNA_LOG_LEVEL - Nivel de logging (ERROR, WARN, INFO, DEBUG)

Configuración con Archivo de Propiedades

Crea un archivo retorna.properties:

retorna.environment=DEVELOP
retorna.logging.level=INFO
retorna.client.id=tu-client-id
retorna.client.secret=tu-client-secret
retorna.private.key=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----

Carga la configuración:

import java.util.Properties;
import java.io.FileInputStream;

Properties props = new Properties();
props.load(new FileInputStream("retorna.properties"));

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.valueOf(props.getProperty("retorna.environment")))
        .loggingLevel(LoggingLevel.valueOf(props.getProperty("retorna.logging.level")))
        .clientId(props.getProperty("retorna.client.id"))
        .clientSecret(props.getProperty("retorna.client.secret"))
        .privateKey(props.getProperty("retorna.private.key"))
        .build()
);

Configuración con Spring Boot

Si estás usando Spring Boot, crea un bean de configuración:

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class RetornaConfig {
    
    @Value("${retorna.client.id}")
    private String clientId;
    
    @Value("${retorna.client.secret}")
    private String clientSecret;
    
    @Value("${retorna.private.key}")
    private String privateKey;
    
    @Value("${retorna.environment:DEVELOP}")
    private String environment;
    
    @Bean
    public RetornaClient retornaClient() {
        return RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.valueOf(environment))
                .loggingLevel(LoggingLevel.INFO)
                .clientId(clientId)
                .clientSecret(clientSecret)
                .privateKey(privateKey)
                .build()
        );
    }
}

En application.properties o application.yml:

retorna.client.id=${RETORNA_CLIENT_ID}
retorna.client.secret=${RETORNA_CLIENT_SECRET}
retorna.private.key=${RETORNA_PRIVATE_KEY}
retorna.environment=${RETORNA_ENV:DEVELOP}

Configuración Thread-Safe

El RetornaClient es thread-safe y puede ser compartido entre múltiples threads. Se recomienda crear una única instancia y reutilizarla:

public class RetornaService {
    private static final RetornaClient client = RetornaClient.create(
        RetornaClientOptions.builder()
            // ... configuración
            .build()
    );
    
    public RetornaClient getClient() {
        return client;
    }
}

Validación de Configuración

El SDK valida automáticamente que todas las credenciales requeridas estén presentes. Si falta alguna, lanzará una IllegalArgumentException:

try {
    RetornaClient client = RetornaClient.create(
        RetornaClientOptions.builder()
            .environment(Environment.DEVELOP)
            // Faltan credenciales
            .build()
    );
} catch (IllegalArgumentException e) {
    System.err.println("Error de configuración: " + e.getMessage());
    // clientId es requerido
    // clientSecret es requerido
    // privateKey es requerido
}

Siguiente Paso

Una vez configurado, aprende sobre Autenticación o consulta las Guías de Uso.