> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtener una orden

> Obtén el detalle completo y el estado actual de una orden por su ID. Admite órdenes de tipo fiat a cripto, cripto a fiat y fiat a fiat.

Usa este endpoint para obtener el estado completo de cualquier orden: instrucciones de pago, tipo de cambio, montos, marcas de tiempo y el código de estado actual. Como el esquema de la respuesta es distinto entre las órdenes de una sola moneda (`fiat_to_crypto` / `crypto_to_fiat`) y las órdenes entre monedas (`fiat_to_fiat`), debes enviar el parámetro de consulta `orderType`, junto con `orderId` (o, para órdenes `fiat_to_crypto` y `crypto_to_fiat`, tu `clientId`). Consulta este endpoint periódicamente para controlar la lógica basada en estados de tu aplicación, por ejemplo para mostrar las instrucciones de pago al usuario o para disparar procesos posteriores cuando `orderStatus` llegue a `60` (completada).

## Endpoint

```text theme={null}
GET https://api.velafi.com/v2/order/detail
```

> [!NOTE]
>
> Usa `https://api-test.velafi.com/v2/order/detail` para pruebas en sandbox.

## Parámetros de consulta

**orderId** `integer`

ID numérico único de la orden que quieres consultar. Obligatorio para órdenes `fiat_to_fiat`. Para órdenes `fiat_to_crypto` y `crypto_to_fiat`, envía `orderId` o `clientId`; si envías ambos, se usa `orderId`.

**clientId** `string`

El `clientId` que enviaste al crear la orden. Solo se admite para órdenes `fiat_to_crypto` y `crypto_to_fiat`.

**orderType** `string` *required*

Tipo de la orden. Debe ser `fiat_to_crypto`, `crypto_to_fiat` o `fiat_to_fiat`.

## Códigos de estado de la orden

`orderStatus` usa un conjunto de códigos para las órdenes `fiat_to_crypto` / `crypto_to_fiat` y otro para las órdenes `fiat_to_fiat`.

| Tipo de orden | Códigos que puedes recibir |
| - | - |
| `fiat_to_crypto`, `crypto_to_fiat` | `10`, `11`, `12`, `31`, `32`, `40`, `50`, `60`, `70`, `71`, `72`, `73`, `80`, `81` |
| `fiat_to_fiat` | `10`, `11`, `12`, `31`, `41`, `51`, `60`, `71`, `72`, `90` |

> [!NOTE]
>
> Las órdenes de on-ramp/off-ramp que VelaFi crea para tu cuenta (no a través de la API ni del panel) también pueden mostrar `20` (revisión rechazada) o `30` (aprobada).

## Campos de la respuesta: fiat a cripto / cripto a fiat

**code** `integer`

Código de estado de la respuesta. `200` indica éxito.

**msg** `string`

Mensaje de respuesta legible.

**data** `object`

Objeto con el detalle de la orden.

**campos de data**

**data.orderId** `string`

ID único de la orden.

**data.clientId** `string`

Tu ID de referencia personalizado de la orden, tal como lo enviaste al crearla.

**data.merchantId** `integer`

ID del comercio asociado a esta orden.

**data.paymentId** `integer`

ID del método de pago (se llena en órdenes `fiat_to_crypto`).

**data.userPaymentId** `integer`

ID del pago del usuario (beneficiario) (se llena en órdenes `crypto_to_fiat`).

**data.country** `string`

Nombre del país de esta orden.

**data.crypto** `string`

Símbolo de la criptomoneda (p. ej., `"USDT"`).

**data.fiat** `string`

Código de la moneda fiat (p. ej., `"MXN"`).

**data.orderType** `string`

Tipo de orden: `fiat_to_crypto` o `crypto_to_fiat`.

**data.orderPrice** `string`

Tipo de cambio al crear la orden (fiat por unidad de cripto).

**data.cryptoAmount** `string`

Monto en cripto de la orden.

**data.fiatAmount** `string`

Monto en fiat de la orden.

**data.fiatFee** `string`

Comisión cobrada en moneda fiat.

**data.orderStatus** `integer`

Código de estado actual de la orden. Consulta la tabla de estados anterior.

**data.traceNumber** `string`

Número de referencia de la transacción del banco central nacional.

**data.paymentInfo** `object`

Mapa clave-valor con las instrucciones de pago de esta orden (p. ej., el número CLABE para órdenes SPEI en México). El contenido varía según el país y el método de pago.

**data.failCode** `integer`

Código de error registrado para una orden fallida. `0` cuando no hay código de falla registrado.

**data.failReason** `string`

Descripción legible del motivo por el que falló la orden.

**data.createTime** `string`

Marca de tiempo Unix (milisegundos) en que se creó la orden.

**data.completedTime** `string`

Marca de tiempo Unix (milisegundos) en que la orden llegó a un estado final. Hasta entonces, es igual a `createTime`.

**data.orderExpireTimestamp** `string`

Solo se devuelve mientras la orden está en `status: 32` (en espera del depósito de cripto, off-ramp con fondeo posterior). Es la fecha límite, como marca de tiempo Unix en segundos, para que el saldo en cripto del comercio cubra la orden.

**data.bankOrderId** `string`

Referencia de la orden del lado del banco. Actualmente se llena principalmente en órdenes ARS.

**data.orderFeeDetail** `object`

Desglose detallado de comisiones. Las líneas de comisión solo se listan en órdenes que tienen comisiones desglosadas registradas.

**campos de orderFeeDetail**

**grossAmount** `string`

Monto fiat bruto de la orden, incluidas las comisiones listadas en `feeLines`.

**netAmount** `string`

`grossAmount` menos la suma del `amount` de las líneas de comisión.

**feeLines** `array`

Una entrada por comisión. Cada entrada tiene `feeType` (por ejemplo, `CONVERT_FEE`), `rate` (fracción decimal; multiplica por 100 para obtener un porcentaje), `fixed` (comisión fija), `receivableAmount` (comisión adeudada antes de cualquier exención), `amount` (comisión cobrada realmente), `currency` y `hasWaived` (`1` si la comisión se exentó, `0` en caso contrario).

## Campos de la respuesta: fiat a fiat

**data** `object`

Objeto con el detalle de la orden fiat a fiat.

**campos de data**

**data.orderId** `string`

ID único de la orden.

**data.clientId** `string`

Tu ID de referencia personalizado de la orden.

**data.onRampMerchantId** `integer`

ID del comercio del tramo de on-ramp.

**data.onRampPaymentId** `integer`

ID del método de pago del tramo de on-ramp.

**data.onRampCountry** `string`

País donde se recauda el fiat.

**data.onRampFiat** `string`

Moneda fiat recaudada en el tramo de on-ramp.

**data.onRampFiatAmount** `string`

Monto recaudado en el tramo de on-ramp.

**data.onRampFiatFee** `string`

Comisión del tramo de on-ramp.

**data.offRampMerchantId** `integer`

ID del comercio del tramo de off-ramp.

**data.offRampPaymentId** `integer`

ID del pago del beneficiario del tramo de off-ramp.

**data.offRampCountry** `string`

País donde se entrega el fiat.

**data.offRampFiat** `string`

Moneda fiat entregada en el tramo de off-ramp.

**data.offRampFiatAmount** `string`

Monto a entregar antes de comisiones.

**data.offArriveRampFiatAmount** `string`

Monto neto que llega al beneficiario después de comisiones.

**data.offRampFiatFee** `string`

Comisión del tramo de off-ramp.

**data.orderPrice** `string`

Tipo de cambio entre monedas al crear la orden.

**data.orderStatus** `integer`

Estado actual de la orden. Consulta los códigos de estado fiat a fiat anteriores.

**data.onRampPaymentInfo** `object`

Instrucciones de pago del tramo de on-ramp (p. ej., CLABE para MXN).

**data.offRampPaymentInfo** `object`

Instrucciones de pago del tramo de off-ramp.

**data.createTime** `string`

Marca de tiempo Unix (milisegundos) en que se creó la orden.

**data.completedTime** `string`

Marca de tiempo Unix (milisegundos) en que se completó la orden.

**data.onRampOrderFeeDetail** `object`

Desglose detallado de comisiones del tramo de on-ramp. Misma estructura que `orderFeeDetail` arriba.

**data.offRampOrderFeeDetail** `object`

Desglose detallado de comisiones del tramo de off-ramp. Misma estructura que `orderFeeDetail` arriba.

## Ejemplos

> [tab] Orden fiat a cripto
>
> ```bash theme={null}
> curl -X GET "https://api.velafi.com/v2/order/detail?orderId=493829236956962816&orderType=fiat_to_crypto" \
>   -H "X-BH-TOKEN: YOUR_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "orderId": "493829236956962816",
>     "clientId": "f_c_0250222004",
>     "merchantId": 3,
>     "paymentId": 0,
>     "userPaymentId": 0,
>     "country": "Mexico",
>     "crypto": "USDT",
>     "fiat": "MXN",
>     "orderType": "fiat_to_crypto",
>     "orderPrice": "21.4104",
>     "cryptoAmount": "5.1376",
>     "fiatAmount": "110",
>     "fiatFee": "0",
>     "orderStatus": 60,
>     "hasRefund": 0,
>     "failCode": 0,
>     "failReason": "",
>     "traceNumber": "20241223907069062e51744c4f0e57",
>     "paymentInfo": {
>       "Cuenta CLABE": "000000000000000001"
>     },
>     "createTime": "1740214865000",
>     "completedTime": "1740214866000"
>   }
> }
> ```

> [tab] Orden fiat a fiat
>
> ```bash theme={null}
> curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
>   -H "X-BH-TOKEN: YOUR_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "orderId": "494541042692263936",
>     "clientId": "c_f_0250224003",
>     "onRampMerchantId": 3,
>     "onRampPaymentId": 17,
>     "onRampCountry": "Mexico",
>     "onRampFiat": "MXN",
>     "onRampFiatAmount": "110",
>     "onRampFiatFee": "1",
>     "offRampCountry": "Argentina",
>     "offRampMerchantId": 4,
>     "offRampPaymentId": 134,
>     "offRampFiat": "ARS",
>     "offRampFiatAmount": "6156.3",
>     "offArriveRampFiatAmount": "6155.3",
>     "offRampFiatFee": "1",
>     "orderPrice": "55.9664",
>     "orderStatus": 31,
>     "onRampPaymentInfo": {
>       "Cuenta CLABE": "000000000000000001"
>     },
>     "offRampPaymentInfo": {
>       "CVU/CBU": "0000000000000000000002"
>     },
>     "createTime": "1740384573000",
>     "completedTime": "1740384573000"
>   }
> }
> ```


## Related topics

- [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md)
- [Obtener una cotización fiat/fiat](https://docs.velafi.com/es/api-reference/quote/get-user-quote-for-fiat-fiat.md)
- [Obtener una cotización cripto/fiat](https://docs.velafi.com/es/api-reference/quote/get-user-quote-for-crypto-fiat.md)
- [Crear una orden de on-ramp](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md)
- [Confirmar una orden](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.