Guía de Cotizaciones

Esta guía te muestra cómo crear y consultar cotizaciones usando el SDK de Retorna.

Crear una Cotización

Crea una nueva cotización para conocer el tipo de cambio y los montos:

import com.retorna.sdk.quotation.CreateQuoteInput;
import com.retorna.sdk.quotation.QuoteResponse;
import com.retorna.sdk.quotation.AmountType;

CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD",              // sourceCurrency: Moneda origen
    "CO",               // targetCountry: País destino
    "COP",              // targetCurrency: Moneda destino
    100.0,              // amount: Monto
    "BANK_TRANSFER",    // payoutType: Tipo de pago
    AmountType.SOURCE   // amountType: Tipo de monto (SOURCE o TARGET)
);

QuoteResponse quote = client.quotation.createQuote(quoteInput);

System.out.println("Cotización ID: " + quote.getId());
System.out.println("Monto origen: " + quote.getSourceAmount());
System.out.println("Monto destino: " + quote.getTargetAmount());
System.out.println("Tasa de cambio: " + quote.getExchangeRate());

Parámetros de Cotización

CreateQuoteInput

Parámetro	Tipo	Descripción	Requerido
sourceCurrency	String	Código de moneda origen (ej: "USD")	✅
targetCountry	String	Código de país destino (ej: "CO")	✅
targetCurrency	String	Código de moneda destino (ej: "COP")	✅
amount	Double	Monto a cotizar	✅
payoutType	String	Tipo de plataforma de pago	✅
amountType	AmountType	SOURCE o TARGET	✅

AmountType

• SOURCE: El monto especificado es en la moneda origen
• TARGET: El monto especificado es en la moneda destino

Ejemplo con TARGET:

CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD",              // sourceCurrency
    "CO",               // targetCountry
    "COP",              // targetCurrency
    500000.0,           // amount en COP (moneda destino)
    "BANK_TRANSFER",    // payoutType
    AmountType.TARGET   // amountType: el monto es en destino
);

QuoteResponse quote = client.quotation.createQuote(quoteInput);
// quote.getSourceAmount() mostrará el equivalente en USD
// quote.getTargetAmount() será 500000.0 COP

Consultar una Cotización

Obtén los detalles de una cotización existente por su ID:

String quoteId = "12345";
QuoteResponse quote = client.quotation.getQuoteById(quoteId);

System.out.println("ID: " + quote.getId());
System.out.println("Estado: " + quote.getStatus());
System.out.println("Monto origen: " + quote.getSourceAmount() + " " + quote.getSourceCurrency());
System.out.println("Monto destino: " + quote.getTargetAmount() + " " + quote.getTargetCurrency());
System.out.println("Tasa: " + quote.getExchangeRate());
System.out.println("Válida hasta: " + quote.getExpiresAt());

Con Parámetros Opcionales

import java.util.HashMap;
import java.util.Map;

Map<String, Object> params = new HashMap<>();
params.put("includeDetails", true);

QuoteResponse quote = client.quotation.getQuoteById(quoteId, params);

Plataformas de Pago Disponibles

Diferentes países soportan diferentes plataformas:

País	Plataformas Disponibles
Argentina	BANK_TRANSFER_AR
Colombia	CASH_PICKUP_CO, INTERBANK_TRANSFER_CO
España/EU	BANK_TRANSFER_EU
Perú	BANK_TRANSFER_USD_PE, BANK_TRANSFER_PEN_PE, CASH_PICKUP_PEN_PE, WALLET_PEN_PE
USA	BANK_TRANSFER_USD
Venezuela	BANK_TRANSFER, P2P_PHONE_TRANSFER, CASH_PICKUP_USD_VE

Ejemplo Completo

import com.retorna.sdk.config.Environment;
import com.retorna.sdk.config.LoggingLevel;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.core.RetornaClientOptions;
import com.retorna.sdk.quotation.CreateQuoteInput;
import com.retorna.sdk.quotation.QuoteResponse;
import com.retorna.sdk.quotation.AmountType;

public class QuotationExample {
    public static void main(String[] args) {
        RetornaClient client = RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.DEVELOP)
                .loggingLevel(LoggingLevel.INFO)
                .clientId(System.getenv("RETORNA_CLIENT_ID"))
                .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
                .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
                .build()
        );
        
        try {
            // Crear cotización: 100 USD a COP
            CreateQuoteInput quoteInput = new CreateQuoteInput(
                "USD",
                "CO",
                "COP",
                100.0,
                "BANK_TRANSFER",
                AmountType.SOURCE
            );
            
            QuoteResponse quote = client.quotation.createQuote(quoteInput);
            
            System.out.println("=== Cotización Creada ===");
            System.out.println("ID: " + quote.getId());
            System.out.println("Origen: " + quote.getSourceAmount() + " " + quote.getSourceCurrency());
            System.out.println("Destino: " + quote.getTargetAmount() + " " + quote.getTargetCurrency());
            System.out.println("Tasa: " + quote.getExchangeRate());
            System.out.println("Válida hasta: " + quote.getExpiresAt());
            
            // Consultar cotización
            QuoteResponse retrievedQuote = client.quotation.getQuoteById(quote.getId().toString());
            System.out.println("\n=== Cotización Consultada ===");
            System.out.println("Estado: " + retrievedQuote.getStatus());
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Validación de Cotizaciones

Las cotizaciones tienen un tiempo de validez. Verifica siempre:

QuoteResponse quote = client.quotation.getQuoteById(quoteId);

if (quote.getExpiresAt() != null) {
    LocalDateTime expiresAt = LocalDateTime.parse(quote.getExpiresAt());
    if (LocalDateTime.now().isAfter(expiresAt)) {
        System.out.println("⚠️ La cotización ha expirado. Crea una nueva.");
    }
}

Manejo de Errores

try {
    QuoteResponse quote = client.quotation.createQuote(quoteInput);
} catch (IllegalArgumentException e) {
    // Parámetros inválidos
    System.err.println("Error de validación: " + e.getMessage());
} catch (RuntimeException e) {
    // Error de API
    System.err.println("Error de API: " + e.getMessage());
} catch (Exception e) {
    // Error general
    System.err.println("Error: " + e.getMessage());
    e.printStackTrace();
}

Flujo Recomendado

1. Crear cotización antes de crear una orden
2. Verificar validez de la cotización
3. Usar el ID de cotización al crear la orden
4. Consultar cotización si necesitas verificar detalles

Siguiente Paso

• Guía de Órdenes - Aprende a crear órdenes de pago usando cotizaciones