Guía de Órdenes FX

Guía completa para ejecutar órdenes de cambio de divisas a través de la API de ARi.

Descripción General

Use la API de Órdenes FX para intercambiar fondos entre diferentes monedas. Para transferencias en la misma moneda, consulte la Guía de Transferencias.

Tipo de Operación	Caso de Uso	Endpoint API
Órdenes FX	Intercambio entre diferentes monedas	`/api/v1/fxorder`

Inicio Rápido

Requisitos Previos

Antes de ejecutar cualquier orden FX, asegúrese de tener:

Credenciales API - Obtenga su clave de suscripción desde el Portal de Desarrolladores
Wallet con Fondos - Asegúrese de que su wallet de origen tenga saldo suficiente
IBANs de Cuenta - Números de cuenta de origen y destino

Flujos FX Soportados

ARi soporta todos los escenarios de cambio de divisas, incluyendo FX de extremo a extremo desde cuentas externas.

Flujo	Origen	Destino	Descripción
FX Extremo a Extremo	IBAN Externo	IBAN Externo	Corredor FX completo
FX Wallet + Pago	Wallet ARi	IBAN Externo	Wallet prefinanciado a externo
FX Interno	Wallet ARi	Wallet ARi	Entre wallets ARi

+---------------------------------------------------------------+
|                    FLUJOS FX SOPORTADOS                       |
+---------------------------------------------------------------+

  Flujo 1: FX EXTREMO A EXTREMO (Externo → Externo)
  ┌──────────────────┐      ┌──────────┐      ┌──────────────────┐
  │   IBAN Externo   │ ──>  │   ARi    │ ──>  │   IBAN Externo   │
  │   Moneda A       │      │  Wallet  │      │    Moneda B      │
  │  (Cliente paga)  │      │   (FX)   │      │   (ARi paga)     │
  └──────────────────┘      └──────────┘      └──────────────────┘

  Flujo 2: FX WALLET + PAGO (Wallet ARi → Externo)
  ┌──────────────────┐         ┌──────────────────┐
  │   Wallet ARi     │ ──FX──> │   IBAN Externo   │
  │   Moneda A       │         │    Moneda B      │
  │  (Prefinanciado) │         │   (ARi paga)     │
  └──────────────────┘         └──────────────────┘

  Flujo 3: FX INTERNO (Wallet ARi → Wallet ARi)
  ┌──────────────────┐         ┌──────────────────┐
  │   Wallet ARi     │ ──FX──> │   Wallet ARi     │
  │   Moneda A       │         │    Moneda B      │
  │  (Prefinanciado) │         │    (Recibe)      │
  └──────────────────┘         └──────────────────┘

+---------------------------------------------------------------+

Escenario 1: FX con Bloqueo de Tasa

Use el bloqueo de tasa cuando necesite garantizar el tipo de cambio para su orden.

Paso 1: Obtener Tipo de Cambio (Bloquear Tasa)

Solicite el tipo de cambio actual y bloquéelo por 60 segundos.

         +--------------------+
         | OBTENER TIPO CAMBIO|
         +--------------------+
                   |
                   v
+------------------------------------------+
| POST /api/v1/fxorder/getQuote            |
| Body: {                                  |
|   "source_currency": "CRC",              |
|   "destination_currency": "USD",         |
|   "amount": 512750,                      |
|   "lock_rate": true                      |
| }                                        |
+------------------------------------------+
                   |
                   v
+------------------------------------------+
| Respuesta:                               |
| {                                        |
|   "quote_id": "fxq_abc123...",           |
|   "rate": "512.750000",                  |
|   "expires_at": "2026-02-03T10:35:00Z",  |
|   "converted_amount": "1000.00"          |
| }                                        |
+------------------------------------------+

Opciones de Bloqueo de Tasa:

Opción	Comportamiento
`lock_rate: false`	Obtener tasa informativa (puede cambiar antes de la orden)
`lock_rate: true`	Bloquear tasa por 60 segundos, recibir `quote_id`

Paso 2: Ejecutar Orden FX

Envíe su orden de cambio de divisas. Use el quote_id del Paso 1 para garantizar su tasa bloqueada.

         +--------------------+
         | EJECUTAR ORDEN FX  |
         +--------------------+
                   |
                   v
+------------------------------------------+
| POST /api/v1/fxorder/createOrder         |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR11409860774530115159"  |
|   },                                     |
|   "parameters": {                        |
|     "amount": "512750",                  |
|     "origin_currency": "CRC",            |
|     "destination_currency": "USD",       |
|     "quote_id": "fxq_abc123...",         |
|     "description": "Cambio de CRC a USD" |
|   }                                      |
| }                                        |
+------------------------------------------+
                   |
                   v
+------------------------------------------+
| Respuesta (Inmediata):                   |
| {                                        |
|   "reference_code": "FXT-20260203-123456"|
|   "status": "filled",                    |
|   "rate": "512.750000",                  |
|   "converted_amount": "1000.00"          |
| }                                        |
+------------------------------------------+

Flujo Completo de Orden FX

+-------------------------------------------------------------------+
|                 ORDEN FX CON BLOQUEO DE TASA                      |
+-------------------------------------------------------------------+
|                                                                   |
|  [Tu App]                                                         |
|      |                                                            |
|      | 1. Solicitar cotización con lock_rate=true                 |
|      |    POST /api/v1/fxorder/getQuote                           |
|      v                                                            |
|  [API ARi]                                                        |
|      |                                                            |
|      | 2. Retorna tasa bloqueada (válida 60 seg)                  |
|      |    quote_id + rate + expires_at                            |
|      v                                                            |
|  [Tu App]                                                         |
|      |                                                            |
|      | 3. Usuario confirma orden                                  |
|      |                                                            |
|      | 4. Enviar orden con quote_id                               |
|      |    POST /api/v1/fxorder/createOrder                        |
|      v                                                            |
|  [API ARi]                                                        |
|      |                                                            |
|      | 5. Valida cotización (no expirada, no usada)               |
|      | 6. Ejecuta a tasa garantizada                              |
|      | 7. Retorna orden completada                                |
|      v                                                            |
|  [Tu App]                                                         |
|      |                                                            |
|      | 8. Mostrar confirmación al usuario                         |
|                                                                   |
+-------------------------------------------------------------------+

Escenario 2: FX Sin Bloqueo de Tasa

Para ejecución inmediata a tasa de mercado actual (sin bloqueo de cotización):

+------------------------------------------+
| POST /api/v1/fxorder/createOrder         |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR11409860774530115159"  |
|   },                                     |
|   "parameters": {                        |
|     "amount": "256375",                  |
|     "origin_currency": "CRC",            |
|     "destination_currency": "USD",       |
|     "description": "Cambio rapido CRC a USD" |
|   }                                      |
| }                                        |
+------------------------------------------+

Nota: Sin un quote_id, se aplica la tasa de mercado actual al momento de ejecución.

Escenario 3: FX Extremo a Extremo

Cambie divisas desde una cuenta bancaria externa y envíe a otra cuenta bancaria externa. Este es el corredor FX principal.

+------------------------------------------+
| POST /api/v1/fxorder/createOrder         |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27015100019876543210", |
|     "iban_holder": "Mario Herrera"       |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR67010700012345678901", |
|     "iban_holder": "Mario Herrera"       |
|   },                                     |
|   "parameters": {                        |
|     "amount": "512750",                  |
|     "origin_currency": "CRC",            |
|     "destination_currency": "USD",       |
|     "quote_id": "fxq_abc123...",         |
|     "description": "FX extremo a extremo"|
|   }                                      |
| }                                        |
+------------------------------------------+

Escenario 4: FX con Pago Externo

Cambie divisas desde un wallet ARi prefinanciado y envíe a una cuenta bancaria externa.

+------------------------------------------+
| POST /api/v1/fxorder/createOrder         |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR67010700012345678901", |
|     "iban_holder": "Mario Herrera"       |
|   },                                     |
|   "parameters": {                        |
|     "amount": "512750",                  |
|     "origin_currency": "CRC",            |
|     "destination_currency": "USD",       |
|     "quote_id": "fxq_abc123...",         |
|     "description": "Pago FX"             |
|   }                                      |
| }                                        |
+------------------------------------------+

Pares de Monedas Soportados

Desde	Hacia	Descripción
USD	CRC	Dólar Estadounidense a Colón Costarricense
CRC	USD	Colón Costarricense a Dólar Estadounidense
USD	EUR	Dólar Estadounidense a Euro
EUR	USD	Euro a Dólar Estadounidense
EUR	CRC	Euro a Colón Costarricense
CRC	EUR	Colón Costarricense a Euro

Headers Requeridos

Header	Requerido	Descripción
`Ocp-Apim-Subscription-Key`	Sí	Su clave de suscripción API
`Idempotency-Key`	Sí (operaciones de creación)	ID único para prevenir órdenes duplicadas
`Content-Type`	Sí	`application/json`

Sobre las Claves de Idempotencia

El header Idempotency-Key previene órdenes duplicadas. Si reintenta una solicitud con la misma clave, recibirá la respuesta original en lugar de crear un duplicado.

Mejores prácticas:
- Use UUID v4 para cada orden única
- Guarde la clave hasta recibir una respuesta final
- Reintente con la MISMA clave si ocurren problemas de red

Escenarios Soportados

Escenario	Órdenes FX	Transferencias
IBAN Externo → IBAN Externo	Sí	No
Wallet ARi → IBAN Externo	Sí	Sí
Wallet ARi → Wallet ARi	Sí	Sí
IBAN Externo → Wallet ARi	Sí	Sí

Estado de Orden

Formato del Código de Referencia

Cuando crea una orden FX, recibe un reference_code en el formato:

FXT-YYYYMMDD-NNNNNN

Componente	Descripción	Ejemplo
`FXT`	Prefijo fijo	`FXT`
`YYYYMMDD`	Fecha de ejecución	`20260203`
`NNNNNN`	Identificador de 6 dígitos	`123456`

Ejemplo: FXT-20260203-123456

Consultar Estado de Orden

Use el código de referencia para consultar el estado de la orden:

+------------------------------------------+
| POST /api/v1/fxorder/getStatus           |
| Body: {                                  |
|   "reference_code": "FXT-20260203-123456"|
| }                                        |
+------------------------------------------+
                  |
                  v
+------------------------------------------+
| Respuesta:                               |
| {                                        |
|   "reference_code": "FXT-20260203-123456"|
|   "status": "settled",                   |
|   "origin_currency": "CRC",              |
|   "destination_currency": "USD",         |
|   "amount": "512750.00",                 |
|   "rate": "512.750000",                  |
|   "converted_amount": "1000.00"          |
| }                                        |
+------------------------------------------+

Importante: Solo se acepta el formato FXT-YYYYMMDD-NNNNNN. Los IDs internos de orden no están expuestos.

Manejo de Errores

Errores Comunes

Error	Causa	Solución
`Quote expired`	Bloqueo de tasa excedió 60 segundos	Solicitar nueva cotización
`Quote already used`	Quote ID ya fue consumido	Solicitar nueva cotización
`Insufficient balance`	Wallet origen sin fondos suficientes	Financiar el wallet primero
`Same currency`	Orden FX con monedas iguales	Use `/transfer` en su lugar
`Invalid account`	Cuenta no encontrada o formato inválido	Verificar formato IBAN

Formato de Respuesta de Error

Todos los errores siguen RFC 7807 Problem Details:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Las órdenes FX requieren diferentes monedas de origen y destino",
  "trace_id": "0HN4G6LJN5FT0:00000001"
}

Consejo: Guarde el trace_id al contactar soporte.

Ejemplos de Código

cURL: Orden FX con Bloqueo de Tasa

# Paso 1: Obtener cotización bloqueada
curl -X POST "https://api.ariari.xyz/api/v1/fxorder/getQuote" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_currency": "CRC",
    "destination_currency": "USD",
    "amount": 512750,
    "lock_rate": true
  }'

# Paso 2: Ejecutar orden con quote_id
curl -X POST "https://api.ariari.xyz/api/v1/fxorder/createOrder" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "iban": "CR27409819882707497149" },
    "destination": { "iban": "CR11409860774530115159" },
    "parameters": {
      "amount": "512750",
      "origin_currency": "CRC",
      "destination_currency": "USD",
      "quote_id": "fxq_abc123..."
    }
  }'

Mejores Prácticas

Siempre use bloqueo de tasa para órdenes FX cuando muestre tasas a usuarios
Guarde las Idempotency-Keys hasta recibir una respuesta final
Maneje expiración de cotización elegantemente - solicite nueva cotización si expira
Valide formatos de cuenta antes de enviar (formato IBAN)
Use webhooks para notificaciones de estado en operaciones asíncronas

Límites de Tasa

Nivel	Solicitudes por Minuto
Estándar	60
Premium	120
Empresarial	Personalizado

Siguientes Pasos

Obtener Claves API - Comience a construir hoy
Transferencias - Transferencias en la misma moneda
Webhooks - Reciba notificaciones en tiempo real
Referencia API - Documentación completa de endpoints