Descripción general de la API

La API REST de VelaFi te permite gestionar de forma programática on-ramps de fiat a cripto, off-ramps de cripto a fiat y pagos globales de fiat a fiat a través de canales de stablecoin. La API sigue las convenciones RESTful: cada recurso se identifica con una URL, cada interacción usa métodos HTTP estándar y cada cuerpo de respuesta es JSON. Toda la comunicación se realiza por HTTPS, y los códigos de estado HTTP estándar indican el resultado de cada solicitud.

URL base

Elige el entorno que corresponda a la etapa de tu integración. Usa el entorno sandbox para desarrollo y pruebas, de modo que no se mueva dinero real. Cambia a la URL de producción solo cuando estés listo para salir en vivo.

Entorno	URL base
Producción	`https://api.velafi.com`
Sandbox	`https://api-test.velafi.com`

Las credenciales de sandbox y de producción no son intercambiables. Usa la clave de API, el secreto de API y el token emitidos para el entorno al que estás llamando.

Formato de la solicitud

Envía todos los cuerpos de solicitud como JSON y configura el header Content-Type en consecuencia:

Content-Type: application/json

Toda solicitud que acceda a un recurso protegido también debe incluir un token de negocio en el header X-BH-TOKEN. Obtén el token desde GET /v2/token/generate firmando la solicitud con tu clave de API y tu secreto de API. Consulta la página de Autenticación para más detalles. Ejemplo de solicitud

curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"

Estructura de la respuesta

Las respuestas exitosas vienen envueltas en esta estructura JSON. Las respuestas de error incluyen code y msg, pero no data; consulta Códigos de error.

{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}

number

200 si la solicitud es exitosa (algunos endpoints devuelven 0). En caso de error, code es el código de error (negativo, excepto 30012). No refleja el estado HTTP: las respuestas que incluyen un code de error usan HTTP 400 o 500. Consulta Códigos de error.

string

Un mensaje breve y legible que resume el resultado, por ejemplo "SUCCESS" o una descripción del error.

object | array | null

El payload que devuelve el endpoint. Su forma varía según el endpoint y se documenta en cada página de referencia.

Códigos de estado HTTP

La siguiente tabla lista los códigos de estado HTTP que devuelve la API.

Código	Significado
`200 OK`	La solicitud fue exitosa.
`400 Bad Request`	Cualquier error de autenticación, validación, límite de tasa o de negocio. El cuerpo incluye el `code` y el `msg` del error y, para la mayoría de los errores, el código se repite en el header de respuesta `error_code`.
`404 Not Found`	La ruta no existe.
`405 Method Not Allowed`	La ruta no acepta este método HTTP.
`500 Internal Server Error`	Ocurrió un error inesperado. El cuerpo incluye el código `-1001`.

Un token faltante, inválido o vencido devuelve 400 con el código -1002 o -1022, no 401. Exceder un límite de tasa devuelve 400 con el código -1006, no 429. Basa siempre tu lógica en el campo code. Consulta Códigos de error para ver todos los códigos y cuáles indican que el resultado es desconocido.

Límites de tasa

Los siguientes endpoints tienen un límite de tasa predeterminado, que se cuenta por cuenta de VelaFi y por separado para cada endpoint. La ventana de un minuto comienza con tu primera solicitud y se reinicia un minuto después.

Endpoint	Límite predeterminado
`GET /v2/user/crypto-quote`	500 solicitudes por minuto
`GET /v2/user/fiat-quote`	500 solicitudes por minuto
`POST /v2/order/fiat_to_crypto`	500 solicitudes por minuto
`POST /v2/order/crypto_to_fiat`	500 solicitudes por minuto
`POST /v2/order/fiat_to_fiat`	500 solicitudes por minuto
`GET /v2/merchant/check/alias`	100 solicitudes por minuto
`GET /v2/merchant/check/cvu`	100 solicitudes por minuto

Una solicitud que excede el límite se rechaza con HTTP 400 y el código -1006 (Execution status unknown.), no con 429. Además, cualquier endpoint puede devolver el código 30012 (HTTP 400) cuando recibe demasiadas solicitudes concurrentes. Espera antes de reintentar. Para las llamadas de creación de órdenes, sigue la sección “Resultado desconocido: verifica antes de reintentar” de Códigos de error, porque -1006 también se usa para otras fallas.

Otros endpoints pueden tener sus propios límites. Contacta al soporte de VelaFi si necesitas un límite de throughput mayor para tu caso de uso.

Secciones principales

Usa las tarjetas siguientes para ir directamente al grupo de recursos que necesitas.

Comercios

Configura perfiles de comercio, consulta los detalles del comercio y gestiona la configuración a nivel de comercio.

Órdenes

Crea, consulta y gestiona órdenes de pago on-ramp, off-ramp y de fiat a fiat.

Beneficiarios

Agrega y gestiona las cuentas bancarias y billeteras cripto que reciben los pagos.

Webhooks

Suscríbete a notificaciones de eventos en tiempo real sobre cambios de estado de órdenes y más.