> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear una clave de API

> Habilita el acceso a la API, crea tu clave y tu secreto de API, agrega las IP de tus servidores a la lista blanca y úsalos para obtener el token que envías en el encabezado X-BH-TOKEN.

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

* Una cuenta de VelaFi activa. Consulta [Crear tu cuenta de VelaFi](https://docs.velafi.com/es/docs/guides/creating-account.md) si aún no te has registrado.
* Al menos un comercio creado y con KYC/KYB verificado. Consulta [Crear y verificar un comercio](https://docs.velafi.com/es/docs/guides/creating-merchant.md).

***

## 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](mailto:contact@velafi.com) o envía una solicitud mediante el [formulario de contacto](https://share.hsforms.com/1P1po-MZAThupnwug_qDEEAr8y9l). 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.

> [!WARNING]
>
> 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](https://www.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.

> [!WARNING]
>
> **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.

> [!TIP]
>
> 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`.

```http theme={null}
X-BH-TOKEN: <your-token>
```

La mayoría de los endpoints también requieren `Content-Type: application/json` en las solicitudes con cuerpo.

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

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

```bash cURL theme={null}
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/^.*= //')

# 1. Obtén un token
curl -X GET "https://api.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  -H "X-BH-APIKEY: ${API_KEY}"

# 2. Llama a la API con el token de data.token
curl -X GET "https://api.velafi.com/v2/user/account" \
  -H "X-BH-TOKEN: <your-token>"
```

```python Python theme={null}
import hashlib
import hmac
import time

import requests

BASE_URL = "https://api.velafi.com"
API_KEY = "<your-api-key>"
API_SECRET = "<your-api-secret>"

# 1. Obtén un token
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
    API_SECRET.encode("utf-8"),
    f"timestamp={timestamp}".encode("utf-8"),
    hashlib.sha256,
).hexdigest()
token_body = requests.get(
    f"{BASE_URL}/v2/token/generate",
    params={"timestamp": timestamp, "signature": signature},
    headers={"X-BH-APIKEY": API_KEY},
).json()
if token_body["code"] != 200:
    raise RuntimeError(f"Token request failed: {token_body}")

# 2. Llama a la API con el token
response = requests.get(
    f"{BASE_URL}/v2/user/account",
    headers={"X-BH-TOKEN": token_body["data"]["token"]},
)
print(response.json())
```

```javascript Node.js theme={null}
const crypto = require("crypto");

const BASE_URL = "https://api.velafi.com";
const API_KEY = "<your-api-key>";
const API_SECRET = "<your-api-secret>";

async function main() {
  // 1. Obtén un token
  const timestamp = Date.now().toString();
  const signature = crypto
    .createHmac("sha256", API_SECRET)
    .update(`timestamp=${timestamp}`)
    .digest("hex");
  const tokenResponse = await fetch(
    `${BASE_URL}/v2/token/generate?timestamp=${timestamp}&signature=${signature}`,
    { headers: { "X-BH-APIKEY": API_KEY } }
  );
  const tokenBody = await tokenResponse.json();
  if (tokenBody.code !== 200) {
    throw new Error(`Token request failed: ${JSON.stringify(tokenBody)}`);
  }

  // 2. Llama a la API con el token
  const response = await fetch(`${BASE_URL}/v2/user/account`, {
    headers: { "X-BH-TOKEN": tokenBody.data.token },
  });
  console.log(await response.json());
}

main();
```

***

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

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

> [!NOTE]
>
> 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.


## Related topics

- [Inicio rápido](https://docs.velafi.com/es/docs/quickstart.md)
- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Crear una orden de pago global](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-fiat-order.md)
- [Crear una orden de on-ramp](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md)
- [Crear una orden de off-ramp](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.