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

# Inicio rápido

> Configura tu cuenta de VelaFi, genera una clave de API y envía tu primera solicitud autenticada a la API en menos de 15 minutos con esta guía de inicio rápido paso a paso.

Esta guía de inicio rápido te lleva por los pasos mínimos necesarios para autenticarte en la API de VelaFi y hacer una solicitud exitosa. Al final, tendrás una clave de API funcional, una cuenta verificada y una respuesta real del endpoint `/v2/user/account`. Si quieres explorar la API sin riesgo antes de salir a producción, el último paso te lleva al entorno sandbox.

**1. Crea tu cuenta de VelaFi**

Ve a [velafi.com/signup](https://www.velafi.com/signup) y completa el formulario de registro. Sigue las instrucciones en pantalla para verificar tu correo electrónico y terminar de configurar tu cuenta.

Después del registro, VelaFi te asigna un **ID de usuario (UID)** único. Este UID es el identificador de nivel superior de todos los comercios, claves de API y transacciones asociados a tu cuenta. Tenlo a la mano: lo verás en todo el panel y en las respuestas de la API.

> [!TIP]
>
> Inicia sesión en el panel de VelaFi justo después de registrarte para familiarizarte con la estructura de la cuenta antes de pasar a la configuración del comercio.

**2. Crea un comercio y completa el KYC/KYB**

VelaFi requiere que toda operación de pago se realice bajo una entidad de **comercio** verificada. Un comercio puede representar tu propio negocio o a un cliente individual que estés incorporando.

Para crear un comercio:

1. En el panel, abre la sección **Merchants** y haz clic en **Create Merchant**.
2. Selecciona el tipo de entidad, **Individual** (persona física) o **Business** (empresa), y llena los datos requeridos.
3. Sube los documentos de cumplimiento solicitados para el KYC (personas físicas) o el KYB (empresas).
4. Envía el formulario y espera la aprobación del equipo de cumplimiento de VelaFi.

Una vez aprobado, VelaFi asigna un **ID de comercio (MID)** y crea automáticamente una billetera de custodia cripto para ese comercio con un límite mensual inicial de retiro de USD 10,000,000,000.

> [!NOTE]
>
> Para ver el proceso completo de creación del comercio y los requisitos de documentos, consulta la guía [Crear tu comercio](https://docs.velafi.com/es/docs/guides/creating-merchant.md).

**3. Genera tu clave de API**

Con tu cuenta activa, ya puedes crear una clave de API desde el panel de VelaFi.

1. Inicia sesión y abre [Gestión de API](https://www.velafi.com/security/interface).
2. Haz clic en **Crear clave de API**.
3. Si tu cuenta todavía no tiene activada la autenticación de dos factores (2FA), el sistema te pedirá configurarla antes de continuar. Completa la configuración de 2FA: es obligatoria para generar claves.
4. Escribe una nota (de 1 a 30 caracteres) para identificar la clave (por ejemplo, `production-backend`).
5. Haz clic en **Continuar** e ingresa tu código 2FA. La ventana de confirmación muestra tu clave de API y tu secreto de API.

> [!WARNING]
>
> Copia tu secreto de API y guárdalo de forma segura antes de cerrar la ventana de confirmación. VelaFi no vuelve a mostrar el secreto; la clave de API sigue visible en tu lista de claves. Si pierdes el secreto, elimina la clave y crea una nueva.

Después, selecciona **Lista blanca** en la nueva clave y agrega las direcciones IP públicas de los servidores que llamarán a la API. Puedes agregar hasta 5 direcciones IPv4 o IPv6; no se aceptan rangos CIDR. Una clave sin lista blanca de IP no puede obtener un token (código `-1023`).

Cada solicitud a la API se autentica enviando un token, obtenido con esta clave y este secreto desde `GET /v2/token/generate`, en el encabezado `X-BH-TOKEN`:

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

**4. Activa tu acceso a la API**

Generar una clave de API no habilita automáticamente el acceso a la API en tu cuenta. Debes contactar al equipo de soporte de VelaFi para completar la activación.

Envía un correo a [contact@velafi.com](mailto:contact@velafi.com) con el UID de tu cuenta y una breve descripción del caso de uso que planeas. El equipo te confirmará por correo cuando el acceso a la API esté activo en tu cuenta.

> [!NOTE]
>
> Mientras el acceso a la API no esté activo, las solicitudes de token fallan con el código `-5033`.

**5. Haz tu primera llamada a la API**

Una vez activada tu cuenta, obtén un token y llama al endpoint de detalles de la cuenta para verificar tu configuración.

```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. Obtener un token
curl --request GET \
  --url "https://api.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"

# 2. Llamar a la API con el token de data.token
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "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. Obtener 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. Llamar 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. Obtener 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. Llamar 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();
```

Una respuesta exitosa devuelve `"code": 200` y `"msg": "SUCCESS"`, con los detalles de tu cuenta en `data`. Consulta [Obtener detalles de la cuenta](https://docs.velafi.com/es/api-reference/account/get-account-details.md) para ver los campos.

Si una llamada falla, revisa el `code` negativo en el cuerpo de la respuesta:

* `-5033` en la solicitud de token: el acceso a la API todavía no está habilitado en tu cuenta. Contacta a VelaFi.
* `-1023` en la solicitud de token: la clave de API no tiene lista blanca de IP.
* `-2015` en la solicitud de token: la solicitud vino de una dirección IP que no está en la lista blanca de la clave, o la clave o tu cuenta están deshabilitadas.
* `-1022`: la firma es incorrecta o la clave de API no existe (solicitud de token), o el token es inválido o expiró (llamada a la API).
* `-2019` en la llamada a la API: la solicitud vino de una dirección IP que no está en la lista blanca de la clave.

Consulta [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md) para ver la lista completa de errores de autenticación.

**6. Prueba el sandbox**

Antes de construir flujos de producción, usa el sandbox de VelaFi para probar tu integración con datos simulados, sin riesgo para fondos reales. El sandbox replica la API de producción en una URL base distinta y requiere credenciales separadas que proporciona el equipo de VelaFi.

* **URL base del sandbox:** `https://api-test.velafi.com`
* **Credenciales:** escribe a [contact@velafi.com](mailto:contact@velafi.com) para solicitar credenciales de sandbox; no se requiere KYC ni crear una clave de API.

Consulta la página [Sandbox](https://docs.velafi.com/es/docs/sandbox.md) para ver una comparación completa del comportamiento del sandbox y de producción, y una solicitud de ejemplo.

***

## Siguientes pasos

> [card] [Entorno sandbox](https://docs.velafi.com/es/docs/sandbox.md)
>
> Prueba con datos simulados antes de tocar producción.

> [card] [On-ramp: fiat → cripto](https://docs.velafi.com/es/docs/guides/on-ramp.md)
>
> Construye de principio a fin tu primer flujo de órdenes fiat a cripto.

> [card] [Off-ramp: cripto → fiat](https://docs.velafi.com/es/docs/guides/off-ramp.md)
>
> Convierte saldos en cripto y entrega fiat a las cuentas de los beneficiarios.

> [card] [Referencia de la API](https://docs.velafi.com/es/api-reference/overview.md)
>
> Explora el catálogo completo de endpoints con sus parámetros y esquemas de respuesta.


## Related topics

- [Sandbox](https://docs.velafi.com/es/docs/sandbox.md)
- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Documentación de la API de VelaFi](https://docs.velafi.com/es/index.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Límites de transacción](https://docs.velafi.com/es/docs/limits.md)


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