> ## 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.

# Lista de verificación para salir a producción

> Revisa credenciales, webhooks, idempotencia, manejo de errores, conciliación, límites y monitoreo antes de mover una integración de VelaFi a producción.

Recorre esta página antes de cambiar cualquier integración de VelaFi del sandbox a producción. Las secciones compartidas aplican a todas las integraciones. La última sección enlaza a la lista de verificación de cada página de caso de uso.

La mayoría de los incidentes en producción que vemos provienen de tres huecos: endpoints de webhook que no confirman las entregas en el formato requerido, reintentos sin `clientId` y la falta de un proceso de conciliación que detecte lo que los webhooks no entregaron.

## Credenciales y autenticación

* Mantén separadas las credenciales de sandbox y de producción. Las claves de sandbox las proporciona VelaFi y se usan con `https://api-test.velafi.com`. Las claves de producción se crean en la página **Gestión de API** y se usan con `https://api.velafi.com`. Los dos conjuntos no son intercambiables. Consulta [Claves de sandbox y de producción](https://docs.velafi.com/es/api-reference/authentication.md#sandbox-vs-production-keys).
* Agrega a la lista blanca de IP de la clave la dirección IP pública de cada servidor de producción que llame a la API (hasta 5 direcciones por clave, sin rangos CIDR). Una clave sin lista blanca no puede obtener un token (`-1023`), y las llamadas desde otras direcciones fallan con `-2015` (solicitud de token) o `-2019` (llamada a la API). Actualiza la lista antes de cambiar de servidores o de IP de salida.
* Mantén la clave de API, el secreto de API y los tokens en tu servidor. Nunca los pongas en código de navegador o móvil, en logs ni en el control de versiones.
* Guarda el token en caché y solicita uno nuevo antes de su `expireTime` (milisegundos Unix). Si una llamada devuelve `-1022`, el token expiró o es desconocido: obtén un token nuevo y envía la llamada otra vez.
* Planea la rotación de claves: crea la clave nueva, agrega sus IP a la lista blanca, haz el cambio y después elimina la clave anterior. Consulta [Buenas prácticas de seguridad](https://docs.velafi.com/es/api-reference/authentication.md#security-best-practices).

## Webhooks

Los webhooks no se disparan en el sandbox, así que producción es el primer lugar donde tu handler recibe entregas reales. Revísalo con cuidado.

* **Registra un webhook de producción para cada tipo de evento que uses** con [Crear un webhook](https://docs.velafi.com/es/api-reference/webhooks/create-webhook-endpoints.md) (`POST /v2/webhook`), usando tus credenciales de producción. Cada tipo de evento (`ORDER_WEBHOOK`, `GLOBAL_PAYMENT_WEBHOOK`, `FUNDING_WEBHOOK`, `ON_RAMP_WITHDRAW_WEBHOOK`, `CRYPTO_WITHDRAW_WEBHOOK`, `STABLE_COIN_PAYMENT_WEBHOOK`) necesita su propio registro. Los eventos que ocurren mientras no existe un webhook activo para su tipo no se ponen en cola, así que regístralo antes de tu primera transacción real.
* **Guarda la `publicKey` de cada webhook** y verifica el header `signature` RSA-SHA256 contra los bytes del cuerpo crudo de la solicitud, antes de parsear o volver a serializar el JSON. Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md).
* **Confirma cada entrega que aceptes con HTTP `2xx` y exactamente este cuerpo JSON.** Si la verificación de la firma falla, devuelve `{"callbackStatus":"FAIL"}` para que la entrega se reintente.

```json theme={null}
{"callbackStatus":"SUCCESS"}
```

> [!WARNING]
>
> Cualquier otra cosa cuenta como entrega fallida y dispara un reintento, aunque tu sistema haya procesado el evento. Cada uno de estos casos es una falla:
>
> * Un `SUCCESS`, `success` u `OK` en texto plano
> * `{"callbackStatus":"success"}` (el valor distingue mayúsculas y minúsculas)
> * `{"received":true}`, `{"status":"ok"}` o cualquier otro JSON sin `"callbackStatus":"SUCCESS"`
> * Un cuerpo vacío, o un cuerpo con espacios en blanco o una marca de orden de bytes (BOM) antes de la `{` inicial
> * Tu propio JSON de error, o cualquier status que no sea `2xx`
> * Ninguna respuesta antes de que la entrega exceda el tiempo de espera

* **Responde rápido.** Verifica la firma, guarda el evento, devuelve la confirmación y haz el trabajo lento (actualizaciones de base de datos, llamadas a otros sistemas) de forma asíncrona.
* **Maneja los duplicados.** El mismo evento puede llegar más de una vez. Haz que el procesamiento sea idempotente sobre el tipo de evento, el ID del registro (`orderId`, `txId` o `withdrawId`) y el status.
* **No dependas del orden ni de ver cada estado.** Las entregas pueden llegar fuera de orden, y un estado intermedio se puede omitir cuando el registro ya avanzó. Trata un webhook como una señal: lee el estado actual del registro con el endpoint de consulta correspondiente y actúa con base en eso.
* **Concilia lo que los webhooks no entregan.** Una entrega fallida se intenta 3 veces en total (el segundo intento entre 5 y 10 minutos después del primero, y el tercero entre 60 y 65 minutos después del segundo). Después de eso, el evento se descarta, y la API no tiene un endpoint de reenvío. Ejecuta el proceso de conciliación descrito abajo.
* **Prueba la respuesta de tu handler antes de salir a producción.** Envía un payload de ejemplo a tu propio endpoint y verifica que la respuesta cruda sea exactamente `{"callbackStatus":"SUCCESS"}` con un status `2xx`.

## Idempotencia con `clientId`

Envía un `clientId` nuevo y único en cada llamada que cree algo, guárdalo antes de enviar la solicitud y reutiliza el mismo valor cuando reintentes esa solicitud. VelaFi rechaza un `clientId` reutilizado en lugar de crear un segundo registro. La respuesta de duplicado no devuelve el registro original, así que búscalo.

| Llamada | `clientId` | Único entre | `clientId` reutilizado | Búscalo con |
| - | - | - | - | - |
| `POST /v2/order/fiat_to_crypto`, `POST /v2/order/crypto_to_fiat` | Opcional, hasta 40 caracteres | Todas las órdenes `fiat_to_crypto` y `crypto_to_fiat` de tu cuenta | Se rechaza con `-1174` | [Obtener una orden](https://docs.velafi.com/es/api-reference/order/retrieve-a-specific-order.md) con `orderType` y `clientId` |
| `POST /v2/order/fiat_to_fiat` | Opcional, hasta 40 caracteres | Todas las órdenes `fiat_to_fiat` de tu cuenta | Se rechaza con `-1174` | [Listar órdenes](https://docs.velafi.com/es/api-reference/order/retrieve-a-list-of-orders.md), relacionando por `clientId` |
| `POST /v2/merchant/claimfunds`, `POST /v2/merchant/transfer` | Envía uno en cada solicitud | Todos los registros de fondeo de tu cuenta | Se rechaza con `-1174` | [Listar registros de fondeo](https://docs.velafi.com/es/api-reference/merchant/retrieve-funding-records.md) con `clientId` |
| `POST /v2/assets/withdraw` | Obligatorio | Retiros del mismo tipo de ese comercio | Se rechaza con `Duplicate withdrawal request` | [Listar retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md) con `clientId` |
| `POST /v2/assets/internalTransfer` | Opcional | Transferencias internas enviadas por ese comercio | Se rechaza con `Duplicate withdrawal request` | [Listar transferencias cripto](https://docs.velafi.com/es/api-reference/merchant/query-crypto-transfers.md) con `clientId` |

Un `clientId` queda vinculado a su registro de forma permanente, incluso después de que el registro se cancele. Usa un valor nuevo para una operación nueva.

[Crear un comercio](https://docs.velafi.com/es/api-reference/merchant/create-merchant.md) no tiene `clientId`. Antes de reintentarlo, busca el comercio por `email` con [Listar comercios](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchants.md) (`status=-1`).

## Manejo de errores

* Toma decisiones con base en el campo `code`, no en el status HTTP. Los errores usan HTTP `400` (o `500` para `-1001`) con un `code` negativo (excepto `30012`). No existen `401` ni `429`. Consulta [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md).
* Trata `-1001`, `-1006`, `-1007` y `30012` en una llamada que crea o modifica algo como **resultado desconocido**. Es posible que la operación se haya completado. Búscala por `clientId` (tabla de arriba) y reintenta con el mismo `clientId` solo si no encuentras nada. Un `-1174` en ese reintento significa que la primera solicitud sí se procesó.
* No hagas coincidencias sobre `msg`. Puede contener valores de tiempo de ejecución y marcadores de posición.
* Espera antes de reintentar (backoff) ante `-1006` de un [endpoint con límite de tasa](https://docs.velafi.com/es/api-reference/overview.md#rate-limits) y ante `30012` (demasiadas solicitudes simultáneas).
* Para las órdenes fallidas, lee `failCode` y `failReason` con [Obtener una orden](https://docs.velafi.com/es/api-reference/order/retrieve-a-specific-order.md). `failReason` puede estar vacío o contener el texto crudo del proveedor, así que regístralo en logs y maneja la orden según su estado.

## Conciliación

Los webhooks son un canal de notificación, no tu libro contable. Ejecuta un proceso programado que lea los registros de VelaFi de las últimas horas o días y los compare con los tuyos.

| Qué | Fuente de verdad |
| - | - |
| Depósitos fiat, pagos (`claimfunds`), cargos de on-ramp, reembolsos y transferencias entre comercios sobre el saldo fiat | [Listar registros de fondeo](https://docs.velafi.com/es/api-reference/merchant/retrieve-funding-records.md) (`GET /v2/merchant/funding/records`), por `txId` o `clientId` |
| Cambios del saldo fiat línea por línea, incluidas comisiones y reversiones | [Listar flujos fiat](https://docs.velafi.com/es/api-reference/merchant/get-a-list-merchant-fiat-flow.md) (`GET /v2/merchant/fiat/flows`) |
| Órdenes de on-ramp, off-ramp y pagos globales | [Obtener una orden](https://docs.velafi.com/es/api-reference/order/retrieve-a-specific-order.md) y [Listar órdenes](https://docs.velafi.com/es/api-reference/order/retrieve-a-list-of-orders.md) |
| Retiros de cripto desde las billeteras de los comercios | [Listar retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md) |
| Depósitos de cripto | [Listar depósitos cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-deposit-history.md) |
| Saldos fiat y cripto | [Listar cuentas de comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md) y [Obtener el saldo cripto](https://docs.velafi.com/es/api-reference/merchant/get-crypto-assets-balance.md) |

* Vuelve a revisar cada registro que tu sistema tenga en un estado no final, para que un webhook perdido no deje una orden o un pago pendiente de tu lado para siempre.
* Genera alertas para los registros que permanezcan en un estado no final más tiempo del que esperas para ese riel.
* Concilia los saldos a diario: el saldo inicial más los registros de fondeo debe ser igual al saldo final.

## Límites

* Revisa los límites diarios y mensuales de cada comercio y su uso (`dayFiatLimit`, `monthFiatLimit`, `monthCryptoLimit` y los campos `...Used` correspondientes) con [Listar comercios](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchants.md), y los límites por canal (`monthBuyLimit`, `monthSellLimit`) con [Listar cuentas de comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md).
* Maneja los errores de límites: `-5050` y `-5060` (orden por debajo del mínimo o por encima del máximo), `-5029`, `-5030` y `-5081` (límite mensual o diario excedido).
* Solicita límites más altos antes del lanzamiento si tu volumen esperado los necesita. Consulta [Límites de transacción](https://docs.velafi.com/es/docs/limits.md).
* Respeta los [límites de tasa](https://docs.velafi.com/es/api-reference/overview.md#rate-limits) de los endpoints de cotizaciones y órdenes.

## Monitoreo

* Registra en logs cada solicitud y respuesta con tu `clientId` y el ID de VelaFi (`orderId`, `txId`, `withdrawId`), para que puedas rastrear cualquier transacción.
* Genera alertas ante fallas de token (`-1022`, `-1023`, `-2015`, `-2019`). Normalmente significan un token expirado, una clave deshabilitada o una IP que no está en la lista blanca.
* Genera alertas cuando dejen de llegar entregas de webhooks o cuando tu handler devuelva algo distinto de la confirmación.
* Genera alertas ante tasas de error crecientes, códigos de resultado desconocido y órdenes o pagos atorados en estados no finales.
* Vigila los saldos desde los que pagas (saldo fiat para pagos y órdenes prefondeadas, saldo cripto para off-ramps) para que los pagos no fallen por falta de fondos.

## Por caso de uso

Cada página de caso de uso termina con una lista de verificación para su propio flujo. Completa la de cada flujo que lances:

> [card] [Cobrar con cuentas virtuales](https://docs.velafi.com/es/docs/use-cases/collect-with-virtual-accounts.md#go-live-checklist)
>
> Cuenta virtual por pagador, manejo de `FUNDING_WEBHOOK`, conciliación de depósitos por `depositAlias`.

> [card] [Dispersar desde tu saldo](https://docs.velafi.com/es/docs/use-cases/payouts-from-balance.md#go-live-checklist)
>
> Beneficiarios, revisión de saldo y comisiones, seguimiento del estado de los pagos.

> [card] [Convertir a stablecoins](https://docs.velafi.com/es/docs/use-cases/convert-to-stablecoins.md#go-live-checklist)
>
> Órdenes de on-ramp prefondeadas o de pago por orden, cotizaciones, manejo de la expiración.

> [card] [Dispersar fondeado con stablecoins](https://docs.velafi.com/es/docs/use-cases/payouts-funded-by-stablecoins.md#go-live-checklist)
>
> Órdenes de off-ramp, saldo cripto, fallas de pagos y reembolsos.

> [card] [Dar de alta a tus clientes](https://docs.velafi.com/es/docs/use-cases/onboard-your-customers.md#go-live-checklist)
>
> Creación de comercios, estado de verificación, activación de canales.

> [card] [Pagos transfronterizos](https://docs.velafi.com/es/docs/guides/global-payments.md)
>
> Órdenes de fiat a fiat con `GLOBAL_PAYMENT_WEBHOOK`.


## Related topics

- [Dar de alta a tus clientes como comercios](https://docs.velafi.com/es/docs/use-cases/onboard-your-customers.md)
- [Convertir moneda local a stablecoins](https://docs.velafi.com/es/docs/use-cases/convert-to-stablecoins.md)
- [Dispersar moneda local desde el saldo](https://docs.velafi.com/es/docs/use-cases/payouts-from-balance.md)
- [Dispersar moneda local fondeada con stablecoins](https://docs.velafi.com/es/docs/use-cases/payouts-funded-by-stablecoins.md)
- [Cobrar pagos locales con cuentas virtuales](https://docs.velafi.com/es/docs/use-cases/collect-with-virtual-accounts.md)


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