Autenticación

VelaFi autentica las solicitudes a la API en dos pasos. Primero, tu servidor firma una solicitud con tu clave de API y tu secreto de API y llama a GET /v2/token/generate para obtener un token de negocio. Después, envía ese token en el encabezado X-BH-TOKEN en todas las demás solicitudes autenticadas. La clave de API nunca va en X-BH-TOKEN.

Encabezado	Valor	Envíalo en
`X-BH-APIKEY`	Tu clave de API	Solo en `GET /v2/token/generate`
`X-BH-TOKEN`	El token que devuelve `GET /v2/token/generate`	Todas las demás solicitudes autenticadas

Nunca envíes tu secreto de API en ningún encabezado ni parámetro. Se queda en tu servidor y solo se usa para calcular el parámetro de consulta signature de la solicitud de token.

Antes de empezar

Necesitas estos tres requisitos antes de poder obtener un token:

Acceso a la API habilitado. VelaFi debe habilitar el acceso a la API en tu cuenta. Mientras no lo haga, las solicitudes de token fallan con el código -5033.
Una clave de API y un secreto de API. Créalos en la página Gestión de API del panel de VelaFi. Consulta Crea tu clave de API.
Una lista blanca de IP en la clave. Una clave sin direcciones IP en la lista blanca no puede obtener un token (código -1023). Agrega las direcciones IP públicas de los servidores que llamarán a la API.

Paso 1: Obtén un token

Firma la cadena timestamp=<ms> con tu secreto de API (HMAC-SHA256, hexadecimal en minúsculas) y llama a GET /v2/token/generate con tu clave de API en el encabezado X-BH-APIKEY:

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(( $(date +%s) * 1000 ))
SIGNATURE=$(printf 'timestamp=%s' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

curl --request GET \
  --url "https://api-test.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"

Una respuesta exitosa contiene el token y su hora de expiración:

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "token": "00000000-0000-0000-0000-000000000006",
    "expireTime": "1740568725231"
  }
}

Paso 2: Envía el token

Incluye el token en el encabezado X-BH-TOKEN en cada solicitud autenticada:

X-BH-TOKEN: your_token

Ejemplo: solicitud GET autenticada con curl

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

Consulta Generar token para ver la referencia completa de la solicitud de token.

Vigencia del token

Todos los tokens expiran. El campo expireTime de la respuesta del token es la hora de expiración como marca de tiempo Unix en milisegundos. Solicita un token nuevo antes de esa hora. Una solicitud con un token expirado o desconocido falla con el código -1022.

Errores de autenticación

Los fallos de autenticación devuelven el estado HTTP 400. El campo code del cuerpo es negativo e identifica el problema:

{
  "code": -1022,
  "msg": "Signature for this request is not valid."
}

Código	Lo devuelve	Significado
`-1002`	Solicitud de token	Falta el encabezado `X-BH-APIKEY` o está mal formado.
`-1002`	Llamada a la API	Falta el encabezado `X-BH-TOKEN`.
`-1004`	Solicitud de token	Falta el parámetro de consulta `signature`, o falta `timestamp` mientras se envían otros parámetros de consulta. El `msg` indica el parámetro faltante.
`-1103`	Solicitud de token	La solicitud no tiene parámetros de consulta, o `signature` es el único.
`-1022`	Solicitud de token	La firma no coincide, o la clave de API no existe.
`-1022`	Llamada a la API	El token es inválido o expiró. Solicita un token nuevo.
`-1023`	Solicitud de token o llamada a la API	La clave de API no tiene lista blanca de IP.
`-2015`	Solicitud de token	La clave de API o tu cuenta está deshabilitada, o la dirección IP de la solicitud no está en la lista blanca de la clave.
`-2015`	Llamada a la API	La clave de API fue deshabilitada o eliminada, o tu cuenta está deshabilitada.
`-2019`	Llamada a la API	La dirección IP de la solicitud no está en la lista blanca de la clave.
`-5033`	Solicitud de token	El acceso a la API no está habilitado en tu cuenta. Contacta a VelaFi.

Claves de sandbox y de producción

Sandbox
Producción

Usa tu clave de sandbox con la URL base de pruebas durante el desarrollo y QA:

Base URL: https://api-test.velafi.com
Token:    GET https://api-test.velafi.com/v2/token/generate
Header:   X-BH-TOKEN: your_sandbox_token

Las transacciones en sandbox no mueven fondos reales. Úsalas libremente para explorar la API, probar casos límite y validar tu integración de punta a punta antes de salir a producción.

Usa tu clave de producción con la URL base de producción solo cuando tu integración esté completa y verificada:

Base URL: https://api.velafi.com
Token:    GET https://api.velafi.com/v2/token/generate
Header:   X-BH-TOKEN: your_production_token

Las solicitudes en producción inician transacciones financieras reales. Trata tu clave de producción con el mismo cuidado que una clave criptográfica privada.

Nunca uses credenciales de sandbox contra la URL de producción, ni credenciales de producción contra la URL de sandbox. Mantén los dos juegos separados en tu configuración.

Buenas prácticas de seguridad

Sigue estas prácticas para proteger tu clave de API y limitar tu exposición en caso de una filtración.

Nunca expongas la clave en código del lado del cliente

Tu clave de API, tu secreto de API y tus tokens solo deben usarse en código del lado del servidor. No los incluyas en JavaScript del navegador, binarios de apps móviles, repositorios públicos ni en ningún entorno al que tengan acceso los usuarios finales. Usa variables de entorno o un gestor de secretos (como AWS Secrets Manager, HashiCorp Vault o GCP Secret Manager) para inyectar las claves en tiempo de ejecución.

Rota las claves con regularidad

Establece una política de rotación de claves (por ejemplo, cada 90 días) aunque no tengas motivos para sospechar que alguna se vio comprometida. Crea la clave nueva en la página API Management, agrega su lista blanca de IP, cambia tus sistemas a la nueva clave y luego elimina la anterior.

Configura la lista blanca de IP

La lista blanca de IP es obligatoria. Una clave sin lista blanca no puede obtener un token (código -1023). Una solicitud de token desde una dirección IP que no está en la lista falla con el código -2015, y una llamada a la API desde esa dirección falla con el código -2019. Limita la lista a los servidores que llaman a la API.Para configurarla, abre Gestión de API en el panel de VelaFi y selecciona Lista blanca en la clave. Puedes agregar hasta 5 direcciones IPv4 o IPv6 por clave. Ingresa cada dirección por separado; no se aceptan rangos CIDR.

Monitorea el uso anómalo

Registra cada solicitud de token y cada llamada a la API que hagan tus sistemas, y genera alertas para las llamadas que no esperas. Si detectas actividad sospechosa, elimina la clave en la página API Management, crea una nueva y contacta al soporte de VelaFi.

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Autenticación

Antes de empezar

Paso 1: Obtén un token

Paso 2: Envía el token

Vigencia del token

Errores de autenticación

Claves de sandbox y de producción

Buenas prácticas de seguridad

​Antes de empezar

​Paso 1: Obtén un token

​Paso 2: Envía el token

​Vigencia del token

​Errores de autenticación

​Claves de sandbox y de producción

​Buenas prácticas de seguridad

Antes de empezar

Paso 1: Obtén un token

Paso 2: Envía el token

Vigencia del token

Errores de autenticación

Claves de sandbox y de producción

Buenas prácticas de seguridad