Saltar al contenido principal
Tu clave de API y tu secreto de API de VelaFi son las credenciales que usa tu servidor para obtener un token de negocio de 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


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.
No puedes crear una clave de API sin tener la 2FA habilitada. Completa este paso antes de continuar.
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.
Tu secreto de API se muestra una sola vez. La clave de API sigue visible en tu lista de claves, pero el secreto no se vuelve a mostrar. Si pierdes el secreto, elimina la clave y crea una nueva.
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.
Cada clave de API es única y otorga acceso al entorno de producción de tu cuenta.
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.
Usa la dirección IP estática de tu servidor de producción para la lista blanca. Si estás haciendo pruebas en local, puedes agregar temporalmente tu propia IP, pero elimínala antes de salir a producción.
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 encabezado X-BH-TOKEN:
  1. 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.
  2. Llama a GET /v2/token/generate?timestamp=<ms>&signature=<signature> con tu clave de API en el encabezado X-BH-APIKEY.
  3. Envía el token devuelto en el encabezado X-BH-TOKEN en cada solicitud. Solicita un token nuevo antes de expireTime.
La mayoría de los endpoints también requieren 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.