ARi LogoPortal de Desarrolladores
|
Volver a Documentacion

FxOrder

Una FxOrder es el registro persistente de una conversión FX ejecutada (o en vuelo): cuánto de origin_currency se está vendiendo, qué destination_currency se está comprando, el tipo de cambio aplicado (o nulo hasta que se complete), y a dónde va el saldo convertido. A diferencia de un `FxQuote` — que es una previsualización sin estado y con vigencia limitada — una orden tiene ciclo de vida, código de referencia y emite eventos de estado.

La forma en el cable que reciben los socios es FxOrderResponseDto para las vistas de creación/listado y FxOrderStatusResponseDto para la vista detallada de estado (que incluye desgloses anidados de origen/destino).
Endpoint que la crea POST /api/v1/fxorder/createOrder
Endpoints que la devuelven POST /api/v1/fxorder/createOrder, POST /api/v1/fxorder/getStatus, POST /api/v1/fxorder/getHistory
Esquemas en el cable FxOrderResponseDto (resumen), FxOrderStatusResponseDto (detallado)
Ciclo de vida PENDING_NEW → NEW → ACCEPTED → FILLED (camino feliz), o → REJECTED / → CANCELED
Webhooks Sí — vea eventos SSE para fxorder.status_changed

Garantías del objeto

  • reference_code es el identificador legible para el socio — aparece en recibos, tickets de soporte y conciliación. Formato: FXT-YYYYMMDD-NNNNNN.
  • rate es nulo hasta que la orden esté FILLED — no asuma un valor antes de eso, aunque haya enviado un quote_id.
  • amount es el importe del lado origen en origin_currency; converted_amount es el importe del lado destino en destination_currency.
  • status toma uno de seis valores (vea la tabla del ciclo de vida abajo).
  • quote_id se completa únicamente cuando se usó un rate fijado — socios que enviaron lock_rate=true en getQuote y luego referenciaron el quote_id resultante en createOrder.
  • created_at es monotónico por reference_code — nunca retrocede; updated_at avanza en cada cambio de estado.

Ciclo de vida

Estado Significado ¿Terminal?
PENDING_NEW Orden recibida; esperando que ARi valide y enrute. No
NEW Validada; encolada para envío aguas arriba. No
ACCEPTED Aguas arriba aceptó; pendiente el llenado del rate. No
FILLED Rate fijado, saldo convertido liquidado al destino. Sí
REJECTED Aguas arriba rechazó. Inspeccione el contexto de error del evento SSE correspondiente. Sí
CANCELED Orden cancelada antes del fill (por acción del socio o regla del sistema). Sí

Las transiciones solo avanzan — no hay rollback de FILLED → REJECTED.

Campos (`FxOrderResponseDto` — respuesta de `createOrder`)

Campo Tipo Requerido Descripción
reference_code string sí ID legible para el socio. Ejemplo: "FXT-20260202-123456".
status FxOrderStatus sí Uno de los seis valores anteriores.
origin_currency string (ISO 4217) sí Moneda vendida.
destination_currency string (ISO 4217) sí Moneda comprada.
amount string (decimal-2) sí Importe del lado origen.
converted_amount string (decimal-2) no Importe del lado destino. Se completa una vez FILLED.
rate string (decimal-6) no Rate aplicado. Nulo hasta FILLED.
quote_id string no Si se usó una cotización fijada. Formato: fxq_{uuid}.
created_at string (ISO 8601) sí Marca de creación de la orden.
updated_at string (ISO 8601) no Último cambio de estado.

Campos (`FxOrderStatusResponseDto` — respuesta de `getStatus`)

Igual al resumen más:

Campo Tipo Requerido Descripción
description string no Descripción opcional enviada por el socio en la creación.
last_updated_at string (ISO 8601) sí Marca de tiempo del cambio de estado más reciente.
origin FxOrderStatusOriginDto sí Detalles del lado originante (IBAN, titular, ID externo).
destination FxOrderStatusDestinationDto sí Detalles del beneficiario.

Anidado: `FxOrderStatusOriginDto`

Campo Tipo Requerido Descripción
iban string sí IBAN que fondeó la orden FX.
id_external string sí Identificador aguas arriba del cliente originante.
name string sí Nombre legible mostrado en libros/recibos.

Anidado: `FxOrderStatusDestinationDto`

Campo Tipo Requerido Descripción
iban string sí IBAN que recibe los fondos convertidos.
id string sí Identificador externo del beneficiario.
name string sí Nombre legible del beneficiario.

Ejemplo (respuesta de `getStatus`)

{
  "reference_code": "FXT-20260202-123456",
  "status": "FILLED",
  "origin_currency": "USD",
  "destination_currency": "CRC",
  "amount": "1000.00",
  "converted_amount": "512750.00",
  "rate": "512.750000",
  "description": "Conversión FX USD a CRC",
  "last_updated_at": "2024-05-01T12:05:00.000Z",
  "origin": {
    "iban": "CR05015102001020012345",
    "id_external": "3012300456",
    "name": "Servicios Profesionales XYZ"
  },
  "destination": {
    "iban": "CR05015202001026284060",
    "id": "115880999",
    "name": "Comercial La Sabana"
  }
}

Véase también