Cotizaciones (FX)

La API de Cotizaciones FX te permite solicitar y fijar tasas de cambio para un corredor de divisas y un monto específicos. El quoteId devuelto garantiza la tasa durante una ventana fija, protegiéndote a ti y a tu cliente de las fluctuaciones cambiarias durante el flujo de la transacción.

Cómo Funciona el Pricing

Dos componentes determinan el costo para el usuario final:

• Spread FX — Tu margen sobre la tasa de cambio, configurado por corredor por Inyo durante el onboarding.
• Comisión por Transacción — Una comisión por transacción, también configurada durante el onboarding. Según tu contrato, es posible que puedas sobrescribir las comisiones a nivel de cotización (p. ej., para ofertas promocionales de "cero comisión").

Tipos de Monto

Al solicitar una cotización, el campo amountType controla cómo se aplican las comisiones:

Solicitar una Cotización

Endpoint: POST /organizations/{tenant}/payout/quotes
Autenticación: Nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

Cuerpo de la Solicitud

Solicitud de Ejemplo

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/quotes \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "amount": 1000,
  "fee": {
    "amount": 4.99,
    "currency": "USD"
  },
  "amountType": "NET"
}'

Respuesta de Ejemplo

{
  "quotes": [
    {
      "id": "f28be3f9-ad4d-4a6c-a85d-ae5515a4a158",
      "agentId": "8500786a-68e9-45fd-b1d8-c590f1e06450",
      "fromAsset": "USD",
      "toAsset": "BRL",
      "effectiveRate": 5.39023,
      "totalCost": {
        "amount": 1004.99,
        "currency": "USD"
      },
      "fee": {
        "amount": 4.99,
        "currency": "USD"
      },
      "amountType": "NET",
      "product": "REMITTANCE",
      "expireAt": "2025-09-15T12:07:01Z",
      "createdAt": "2025-09-15T11:37:01Z",
      "sourceAmount": {
        "amount": 1000.00,
        "currency": "USD"
      },
      "destinationAmount": {
        "amount": 5390.23,
        "currency": "BRL"
      }
    }
  ]
}

Campos de la Respuesta

Ejemplo Detallado de Conversión

Escenario: Convertir 1,000 USD → BRL

Consultar una Cotización

Endpoint: GET /organizations/{tenant}/payout/quotes/{quoteId}
Autenticación: Nivel de agente

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/quotes/$QUOTE_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Usa esto para verificar si una cotización sigue siendo válida antes de enviar una transacción.

Manejo de la Expiración de Cotizaciones

Las cotizaciones son válidas por 30 minutos por defecto. La ventana es configurable por tenant (hasta 24 horas) — verifica expireAt en lugar de asumir una duración. Sigue estas pautas:

• Siempre verifica expireAt antes de usar una cotización en una transacción.
• Renueva proactivamente — solicita una nueva cotización cuando haya transcurrido ~90% del período de validez.
• Nunca almacenes cotizaciones en caché — a diferencia de los destinos y las listas de bancos, las cotizaciones son sensibles al tiempo y deben obtenerse frescas.
• Las cotizaciones expiradas serán rechazadas — si envías una transacción con un quoteId expirado, la API devuelve un error 400 o 422.

Patrón de UX Recomendado

1. User selects amount and destination  →  Request quote
2. Display rate, fees, and receive amount
3. Start a countdown timer based on expireAt
4. If timer reaches ~80%, show "Rate expiring" warning
5. If expired, auto-refresh and update the display
6. On "Confirm", immediately submit the transaction with the quoteId

Todos los Endpoints

Documentación Interactiva de la API