GET /v2/token/generate. En el encabezado X-BH-TOKEN de cada solicitud envías ese token, no la clave. Antes de poder obtener un token, VelaFi debe habilitar el acceso a la API en tu cuenta, la autenticación de dos factores (2FA) debe estar activada y la clave debe tener una lista blanca de IP. Esta guía te lleva paso a paso.
Requisitos previos
- Una cuenta de VelaFi activa. Consulta Crear tu cuenta de VelaFi si aún no te has registrado.
- Al menos un comercio creado y con KYC/KYB verificado. Consulta Crear y verificar un comercio.
Configuración paso a paso
1
Solicita acceso a la API
El acceso a la API no está habilitado de forma predeterminada. Contacta al equipo de VelaFi para que lo active en tu cuenta.Escribe a contact@velafi.com o envía una solicitud mediante el formulario de contacto. Incluye el correo electrónico de tu cuenta y una breve descripción de la integración que planeas hacer.VelaFi te confirmará cuando el acceso a la API esté activado en tu cuenta. Mientras tanto, las solicitudes de token fallan con el código
-5033.2
Habilita la autenticación de dos factores (2FA)
Si la 2FA aún no está activa, la plataforma te pedirá habilitarla cuando intentes crear una clave de API. Habilítala antes de continuar para evitar interrupciones.Inicia sesión en tu cuenta y ve a la configuración de seguridad para activar la 2FA.
3
Ve a Gestión de API
Después de iniciar sesión, abre Gestión de API desde el menú del panel, o ve a velafi.com/security/interface.Aquí creas, consultas y administras todas tus claves de API y listas blancas de IP.
4
Crea tu clave de API
Haz clic en el botón Crear clave de API en la página Gestión de API.Escribe una etiqueta descriptiva de 1 a 30 caracteres en el campo Notas, por ejemplo,
Production Integration. El campo es obligatorio. Esta etiqueta te ayuda a identificar más adelante el propósito de la clave.Haz clic en Continuar y luego ingresa tu código de 2FA para confirmar. La ventana Clave de API creada muestra tu Clave de API y tu Secreto de API.5
Copia y guarda tu clave y tu secreto de API
Copia ambos valores de inmediato y guárdalos en un lugar seguro.Sigue estas buenas prácticas de almacenamiento:
- No guardes tu clave de API en archivos de texto plano, en el control de versiones ni en ningún lugar público.
- Sí usa un administrador de contraseñas o una herramienta de gestión de secretos (como AWS Secrets Manager, HashiCorp Vault o 1Password) para guardar la clave de forma segura.
- No compartas tu clave de API por Slack, correo electrónico ni otras plataformas de mensajería.
6
Configura las direcciones IP de la lista blanca
Agrega una lista blanca de IP a la clave. Este paso es obligatorio: una clave sin lista blanca no puede obtener un token (código
-1023).En la página Gestión de API, selecciona Lista blanca en la clave, ingresa las direcciones IP públicas de los servidores que llamarán a la API y confirma con tu código de 2FA. Puedes agregar hasta 5 direcciones IPv4 o IPv6 por clave. Ingresa cada dirección de forma individual; no se aceptan rangos CIDR. Las solicitudes desde cualquier otra dirección IP se rechazan, incluso con una clave de API o un token válidos.La lista blanca garantiza que una clave comprometida no pueda ser usada por un atacante desde una ubicación desconocida.Uso de tu clave de API
Tu servidor usa la clave y el secreto de API para obtener un token y luego envía el token en el encabezadoX-BH-TOKEN:
- Construye la cadena
timestamp=<ms>, donde<ms>es la hora Unix actual en milisegundos. Calcula su HMAC-SHA256 usando tu secreto de API como clave y codifica el resultado en hexadecimal en minúsculas. - Llama a
GET /v2/token/generate?timestamp=<ms>&signature=<signature>con tu clave de API en el encabezadoX-BH-APIKEY. - Envía el
tokendevuelto en el encabezadoX-BH-TOKENen cada solicitud. Solicita un token nuevo antes deexpireTime.
Content-Type: application/json en las solicitudes con cuerpo.
Ejemplo: obtener un token y llamar a la API
El siguiente ejemplo obtiene un token y lo usa para consultar los datos de tu cuenta.Entornos de producción y sandbox
Usa claves de API distintas para cada entorno. Nunca uses una clave de producción en tu entorno de pruebas, ni viceversa.Las claves de sandbox y las de producción son credenciales distintas. Cuando estés listo para salir a producción, genera una nueva clave de API en la configuración de tu cuenta de producción y actualiza la configuración de tu integración en consecuencia.