Lista de verificación para salir a producción

​

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

​

Webhooks

• Registra un webhook de producción para cada tipo de evento que uses con Crear un webhook (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.
• 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.

{"callbackStatus":"SUCCESS"}

• 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

​

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.
• 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 y ante 30012 (demasiadas solicitudes simultáneas).
• Para las órdenes fallidas, lee failCode y failReason con Obtener una orden. 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

• 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, y los límites por canal (monthBuyLimit, monthSellLimit) con Listar cuentas de comercio.
• 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.
• Respeta los límites de tasa 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