Developers

Órdenes e idempotencia

Crear una orden fija el tipo y asigna una dirección de depósito. Es el único lugar donde un error de integración mueve dinero: la idempotencia no es una conveniencia allí.

Contrato publicado, aún no abierto

Estos endpoints no están expuestos hoy. Están documentados para que pueda construir su integración con antelación; su forma está establecida, y cualquier cambio disruptivo pasará por una nueva versión y una entrada en el changelog.

POST/api/v1/ordersPublished contract, not open

Crear una orden

Bloquea el tipo y devuelve una dirección de depósito dedicada. La orden lleva el desglose como bloqueado: es reproducible, lo que le permite reconstruir el precio exacto aplicado incluso meses después. La cabecera Idempotency-Key es obligatoria.

Autenticación: Authorization: Bearer … Ver autenticación

Parámetros

Parámetros
Campo	Tipo	Descripción
`quoteId`obligatorio	string	Identificador de la cotización aceptada.
`beneficiary`obligatorio	object	Campos impuestos por el esquema de la vía. El nombre debe coincidir con la identidad verificada: no se permiten pagos a terceros.
`networkId`obligatorio	string	Red por la que se enviará el depósito. Determina la dirección devuelta y, en algunas redes, el memo obligatorio.

Solicitudbash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Respuesta — contrato publicadojson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

El memo es null en la mayoría de las redes y obligatorio en XRP, Stellar y TON. Omitirlo allí pierde los fondos: trate el campo como obligatorio en cuanto no sea null.

Posibles errores: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Catálogo completo

GET/api/v1/orders/{reference}Published contract, not open

Leer una orden

Estado actual e historial de transiciones con marca de tiempo. El historial es la fuente de verdad: es de solo añadidura, nunca se reescribe, y es lo que responde a «¿por qué mi orden pasó a ese estado en ese momento?».

Autenticación: Authorization: Bearer … Ver autenticación

Solicitudbash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Respuesta — contrato publicadojson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Posibles errores: unauthorized, not_found. Catálogo completo

Idempotencia

Una solicitud de creación que se agota en la red no le dice si la orden se creó. Sin una clave de idempotencia solo tiene dos malas opciones: reintentar y arriesgar dos órdenes, o no reintentar y arriesgar ninguna.

Cabecerahttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Una clave por intención

La clave identifica la intención "crear esa orden", no la solicitud HTTP. Un id único en su lado: un id de carrito, un UUID generado antes de la llamada, nunca un contador.

Una repetición devuelve la respuesta original

Repetir la misma clave con el mismo cuerpo devuelve la respuesta de la primera solicitud, con el mismo estado HTTP. Eso es lo que hace que un reintento sea seguro, incluso después de un tiempo de espera.

Misma clave, cuerpo diferente: conflicto

La respuesta es un conflicto explícito. Si el contenido cambia, la clave debe cambiar: de lo contrario, nadie puede saber cuál de las dos órdenes repetir.

Retención de 24 horas

Después de eso, la clave se olvida y una repetición crearía una nueva orden. Reintente dentro de la ventana, o verifique el estado con el endpoint de lectura.

El memo, en redes que lo requieren

En XRP, Stellar y TON la dirección de depósito no es suficiente: un identificador adicional designa al destinatario final. Es la causa más costosa de incidentes en una integración de retiro.

Un depósito sin su memo es un depósito perdido

El campo memo es null en la mayoría de las redes y no nulo en aquellas que lo requieren. Trátelo como obligatorio en cuanto no sea nulo, y muéstrelo con el mismo peso que la dirección. Un depósito que llega sin su memo a una dirección compartida necesita recuperación manual, que no siempre tiene éxito.

Estados de la orden

Los estados siguientes son los que su integración puede observar. Las transiciones se registran con marca de tiempo y se añaden, nunca se reescriben: el historial responde a "¿por qué mi orden se movió a ese estado en ese momento?".

Estados de la orden
Estado	Qué significa
`QUOTE_LOCKED`	El tipo está congelado. La orden espera los datos del beneficiario o la verificación de identidad.
`AWAITING_DEPOSIT`	La dirección de depósito está asignada y la ventana de depósito está en curso. Ese es el único momento para enviar fondos.
`DEPOSIT_DETECTED`	Se ve una transacción entrante en la red, aún no confirmada. Tranquilice al usuario, no entregue nada.
`CONFIRMING`	Las confirmaciones se están acumulando. El número requerido depende de la red, no del importe.
`DEPOSIT_CONFIRMED`	El depósito está asegurado. Las reglas de cumplimiento y re-precio se evalúan a partir de aquí.
`UNDERPAID`	El importe recibido es inferior al esperado más allá de la tolerancia. Tres resultados: completar, continuar con el importe recibido o ser reembolsado.
`OVERPAID`	El importe recibido supera lo esperado. El importe inicial se mantiene al tipo fijado, el exceso se gestiona por separado.
`PAYOUT_QUEUED`	La transferencia está en cola. La cola garantiza que un pago se envíe una sola vez, incluso si varios workers se disparan en paralelo.
`PAYOUT_SENT`	La transferencia ha salido por el canal. Enviado no es recibido: el retraso final depende del banco del beneficiario.
`COMPLETED`	El canal confirma la liquidación. Estado terminal.
`PAYOUT_FAILED`	El canal rechazó o devolvió la transferencia. No hay reintento automático: la causa casi siempre está en los detalles.
`REFUNDED`	Los fondos se devolvieron a la dirección de origen, netos de comisiones de red. Estado terminal.