ARi LogoPortal de Desarrolladores
|
Volver a Documentacion

FxQuote

Un FxQuote es el resultado tarifado y con vigencia limitada que devuelve POST /api/v1/fxorder/getQuote. Captura el tipo de cambio, los bid/ask ya combinados con la mezcla de su nivel, los importes de ambos lados y la comisión calculada por ARi para una previsualización FX adaptada al tier de su socio. Cuando la solicitud incluye lock_rate=true, la cotización también lleva un quote_id y un expires_at que usted puede fijar a un createOrder posterior.

Las cotizaciones no son órdenes. No mueven dinero, no reservan liquidez y no son visibles para el cliente final hasta que las consume createOrder. La comisión mostrada es la que se cobraría si usted continúa — hasta ese momento, ningún saldo se mueve.
Endpoint que la devuelve POST /api/v1/fxorder/getQuote
Esquema en el cable M2mFxOrderQuoteResponseDto (M2M-segregado; ADR-0048)
Ciclo de vida Sin estado — el quote_id solo persiste cuando lock_rate=true
Webhooks Ninguno — las cotizaciones no emiten eventos

Garantías del objeto

Estas propiedades se cumplen en cada FxQuote que recibe su llave de suscripción:

  • rate, bid_rate, ask_rate son finales — el tier de su socio ya está incluido. Multiplique directamente; no vuelva a aplicar un margen.
  • Exactamente uno de origin_amount / destination_amount fue provisto por el llamante; el servidor calcula el otro. Los dos juntos siempre satisfacen la matemática implícita por rate y fee_amount.
  • fee_amount lo calcula ARi, denominada en fee_currency, y nunca la declara el socio. Los socios controlan el margen minorista por fuera de esta superficie.
  • quote_id y expires_at aparecen únicamente cuando la solicitud incluye lock_rate=true. Sin lock_rate, la cotización es una previsualización de precio que no se puede fijar a una orden.
  • La precisión del tipo de cambio es de 6 decimales como cadena (preserva la precisión en parsers JSON que truncan a punto flotante).
  • Las marcas de tiempo son ISO 8601 con precisión de milisegundos y sufijo Z (UTC).

Campos

Campo Tipo Requerido Descripción
origin_currency string (ISO 4217) sí Moneda que usted vende. Ejemplo: "USD".
destination_currency string (ISO 4217) sí Moneda que usted compra. Ejemplo: "CRC".
rate string (decimal-6) sí Tipo de cambio final con tier mezclado para la dirección cotizada. Ejemplo: "512.750000".
bid_rate string (decimal-6) no bid final con tier mezclado. Permite calcular la pierna inversa sin volver a cotizar. Ejemplo: "510.250000".
ask_rate string (decimal-6) no ask final con tier mezclado. Compañero de bid_rate. Ejemplo: "515.250000".
origin_amount number no Importe del lado origen. Se completa sin importar cuál de los dos lados envió el llamante. Ejemplo: 1000.
destination_amount number no Importe del lado destino. Misma regla de poblamiento que origin_amount. Ejemplo: 512750.
fee_amount number no Comisión cobrada del lado origen. Calculada por ARi según su tier. Ejemplo: 2.5.
fee_currency string (ISO 4217) no Moneda en la que está denominada fee_amount (coincide con origin_currency). Ejemplo: "USD".
quote_id string no — solo cuando lock_rate=true Identificador fijable para createOrder. Formato: fxq_{uuid}. Ejemplo: "fxq_a1b2c3d4-e5f6-7890-abcd-ef1234567890".
quoted_at string (ISO 8601) sí Hora real de cotización. Ejemplo: "2026-01-29T10:30:00.000Z".
expires_at string (ISO 8601) no — solo cuando lock_rate=true Momento en que createOrder deja de honrar el rate fijado. Ejemplo: "2026-01-29T10:35:00.000Z".
valid_for_seconds number sí Ventana de validez de la cotización. Por defecto 60.

Ejemplo

{
  "origin_currency": "USD",
  "destination_currency": "CRC",
  "origin_amount": 1000,
  "destination_amount": 512750,
  "rate": "512.750000",
  "bid_rate": "510.250000",
  "ask_rate": "515.250000",
  "fee_amount": 2.5,
  "fee_currency": "USD",
  "quote_id": "fxq_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "quoted_at": "2026-01-29T10:30:00.000Z",
  "expires_at": "2026-01-29T10:35:00.000Z",
  "valid_for_seconds": 300
}

Campos internos que usted nunca verá

Algunos metadatos internos del stream de pricing existen en la superficie interna de ARi, pero el filtro de audiencia (ADR-0048) los retira del cable M2M. La lista no es relevante para el socio por diseño: la tarifa efectiva de cada llamante M2M ya está mezclada en rate, bid_rate y ask_rate, por lo que cualquier metadato interno del stream sería redundante. Si su payload lleva campos que no están en la tabla anterior, trátelo como una regresión — por favor repórtelo.

Véase también