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

# Autenticación

> Firma una solicitud con tu clave de API y tu secreto de API para obtener un token de negocio de GET /v2/token/generate y luego envía el token en el encabezado X-BH-TOKEN.

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](https://docs.velafi.com/es/docs/guides/creating-api-key.md).
* **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`:

```bash 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/^.*= //')

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:

```json theme={null}
{
  "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:

```http theme={null}
X-BH-TOKEN: your_token
```

**Ejemplo: solicitud GET autenticada con curl**

```bash theme={null}
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"
```

Consulta [Generar token](https://docs.velafi.com/es/api-reference/generate-token.md) 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:

```json theme={null}
{
  "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

> [tab] Sandbox
>
> 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.

> [tab] 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.

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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.


## Related topics

- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Comercios](https://docs.velafi.com/es/docs/merchants.md)
- [Obtener los detalles de la cuenta](https://docs.velafi.com/es/api-reference/account/get-account-details.md)


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