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

# Sandbox

> Usa el sandbox de VelaFi para construir y validar tu integración con datos simulados: sin fondos reales, sin KYC y sin riesgo antes de pasar a producción.

El sandbox de VelaFi es un entorno de pruebas aislado que replica la estructura y el comportamiento de la API de producción usando datos completamente simulados. Puedes crear órdenes, consultar cuentas y recorrer todo el ciclo de solicitud y respuesta sin mover dinero real, verificar identidades reales ni afectar ninguna cuenta de comercio en vivo. Es el punto de partida recomendado para cualquier integración nueva y un lugar seguro para validar cambios antes de desplegarlos en producción.

## URL base del sandbox

Apunta tu cliente HTTP a la siguiente URL base para acceder al sandbox:

```
https://api-test.velafi.com
```

Todos los endpoints de producción están disponibles en esta URL base con la misma estructura de rutas. Por ejemplo, para obtener los pares de trading fiat en el sandbox:

```bash theme={null}
curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols
```

Este endpoint es público, así que no necesita token. Los endpoints que operan sobre tu cuenta sí lo necesitan: consulta [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md).

## Cómo obtener credenciales del sandbox

Las claves de API del sandbox se emiten por separado de las de producción y no se generan desde el panel. Para obtener tu clave de API y tu secreto de API del sandbox, contacta directamente al equipo de VelaFi:

* **Correo:** [contact@velafi.com](mailto:contact@velafi.com)

> [!NOTE]
>
> No necesitas completar KYC/KYB ni crear una cuenta de comercio para acceder al sandbox. El equipo de VelaFi te dará una cuenta de prueba preconfigurada con datos simulados de usuario y de comercio, lista para usar.

Cuando recibas tus credenciales, úsalas para obtener un token de `GET /v2/token/generate` e inclúyelo en el header `X-BH-TOKEN` de cada solicitud, exactamente igual que en producción:

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

## Sandbox vs. producción

La siguiente tabla resume las principales diferencias de comportamiento entre los dos entornos. Úsala como lista de verificación para decidir qué entorno es adecuado para cada actividad.

| Característica | Sandbox | Producción |
| - | - | - |
| **KYC / KYB obligatorio** | No: se proporcionan cuentas de prueba preconfiguradas | Sí: se requiere verificación de identidad completa |
| **Creación de clave de API** | No es necesaria: VelaFi proporciona las credenciales | Obligatoria: se genera desde el panel con 2FA |
| **Datos de usuarios y cuentas** | Virtuales y simulados; no están vinculados a personas reales | Datos reales vinculados a comercios y usuarios verificados |
| **Transferencias de fondos** | No se mueven fondos reales; todas las transacciones son simuladas | Fondos reales transferidos por canales de pago en vivo |
| **Callbacks de webhook** | No se disparan: no se envía ningún evento de callback | Se disparan con los cambios de estado de las órdenes |
| **URL base** | `https://api-test.velafi.com` | `https://api.velafi.com` |

> [!WARNING]
>
> Nunca uses claves de API de producción con la URL base del sandbox, ni credenciales del sandbox con la URL base de producción. Mantén los dos conjuntos de credenciales estrictamente separados en la configuración de tus entornos.

## Ejemplo: obtener pares de trading fiat

La siguiente solicitud muestra una llamada completa a la API del sandbox. Usa un endpoint público, así que confirma que puedes acceder al sandbox, pero no prueba tus credenciales.

```bash cURL theme={null}
curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api-test.velafi.com/v2/base/fiat/symbols",
)
print(response.json())
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api-test.velafi.com/v2/base/fiat/symbols",
  {
    method: "GET",
  }
);
const data = await response.json();
console.log(data);
```

Una respuesta exitosa devuelve la lista de pares de trading fiat disponibles en el entorno de pruebas:

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "symbol": "ARS_USDT",
      "base_currency": "ARS",
      "quote_currency": "USDT",
      "status": "active"
    },
    {
      "symbol": "MXN_USDT",
      "base_currency": "MXN",
      "quote_currency": "USDT",
      "status": "active"
    }
  ]
}
```

> [!TIP]
>
> Recorre completos tus flujos de órdenes de on-ramp, off-ramp y pagos globales en el sandbox antes de cambiar a producción. Como los callbacks de webhook no se disparan en el sandbox, consulta manualmente el endpoint de estado de la orden para verificar las transiciones de estado durante las pruebas.

## Flujo de pruebas recomendado

Sigue esta secuencia en el sandbox para validar tu integración de punta a punta antes de salir a producción:

**1. Confirma tus credenciales**

Obtén un token de `GET https://api-test.velafi.com/v2/token/generate` con tu clave y secreto de API del sandbox y luego llama a `GET /v2/user/account` con ese token. Una respuesta exitosa confirma que tu clave, tu secreto, tu lista blanca de IP y tu acceso a la API están configurados.

**2. Prueba la creación de órdenes de on-ramp**

Crea una orden fiat a cripto con datos simulados de comercio y de cuenta. Verifica que el sistema devuelva un `order_id` y que puedas consultar la orden por su ID.

**3. Prueba la creación de órdenes de off-ramp**

Crea una orden cripto a fiat y confirma que la respuesta incluya los datos de liquidación y la información del beneficiario esperados.

**4. Prueba la creación de órdenes de pago global**

Crea una orden fiat a fiat con un comercio remitente y un comercio destinatario configurados para monedas fiat distintas. Confirma que el estado de la orden avance como se espera.

**5. Cambia a producción**

Reemplaza la URL base del sandbox por `https://api.velafi.com`, usa tu clave y secreto de API de producción y obtén los tokens del host de producción. Vuelve a ejecutar una prueba rápida contra el endpoint `/v2/user/account` de producción para confirmar el cambio.

***

## Herramientas de prueba del sandbox

El sandbox tiene dos endpoints que simulan depósitos entrantes, para que puedas fondear comercios de prueba sin mover dinero real. Solo existen en `https://api-test.velafi.com`. En `https://api.velafi.com` devuelven `404`.

Ambos endpoints:

* Aceptan solo `POST`, con los parámetros enviados como parámetros de consulta.
* Requieren el header `X-BH-TOKEN` con un token de negocio del sandbox y una solicitud desde una dirección IP incluida en tu lista blanca de IP del sandbox, como cualquier otro endpoint autenticado.
* Tienen un límite de 20 solicitudes por minuto.

### Simular un depósito fiat

`https://api-test.velafi.com/v2/platform/test/deposit`

Simula un depósito bancario entrante en la cuenta fiat activada de un comercio.

**merchantId** `number` *required*

ID del comercio al que se acreditará.

**fiat** `string` *required*

Código de la moneda fiat, por ejemplo `MXN`.

**fiatAmount** `number` *required*

Monto a depositar. Debe ser mayor que `0`.

**paymentId** `number` *required*

ID del método de pago de la cuenta fiat activada del comercio para esta moneda.

**depositAlias** `string`

Alias de una cuenta virtual con el mismo `merchantId`, `fiat` y `paymentId`. Si lo envías, el depósito va a esa cuenta virtual.

Mensajes de error comunes:

* `The merchant has not activated the corresponding fiat currency account.`: el comercio no tiene una cuenta activa para este `fiat` y `paymentId`.
* `The depositAlias invalid.`: ninguna cuenta virtual coincide con `depositAlias`.
* `This method of currency recharge is not currently supported.`: este método de pago no tiene simulador de depósitos.

```bash cURL theme={null}
curl -X POST "https://api-test.velafi.com/v2/platform/test/deposit?merchantId=100001&fiat=MXN&fiatAmount=1000&paymentId=105" \
  -H "X-BH-TOKEN: YOUR_SANDBOX_TOKEN"
```

### Simular un depósito de cripto

`https://api-test.velafi.com/v2/platform/test/crypto/deposit`

Agrega fondos de cripto de prueba a la billetera de un comercio.

**merchantId** `number` *required*

ID de un comercio aprobado.

**crypto** `string` *required*

`USDT` o `USDC`. Otros valores devuelven `{"code":500, "msg":"crypto is invalid"}`.

**amount** `number` *required*

Monto a agregar. Debe ser mayor que `0`.

Si la operación es exitosa, el `code` de la respuesta es `200`.

```bash cURL theme={null}
curl -X POST "https://api-test.velafi.com/v2/platform/test/crypto/deposit?merchantId=100001&crypto=USDT&amount=500" \
  -H "X-BH-TOKEN: YOUR_SANDBOX_TOKEN"
```

> [!NOTE]
>
> Los simuladores solo cubren depósitos exitosos. No pueden generar un depósito fallido ni devuelto.

***

## Siguientes pasos

> [card] [Inicio rápido](https://docs.velafi.com/es/docs/quickstart.md)
>
> Configura tu cuenta de producción y genera tu clave de API en vivo.

> [card] [Referencia de la API](https://docs.velafi.com/es/api-reference/overview.md)
>
> Explora todos los endpoints disponibles, sus parámetros y los esquemas de respuesta.


## Related topics

- [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md)
- [URL base](https://docs.velafi.com/es/api-reference/basic-configuration/api-endpoint.md)
- [Métodos de pago](https://docs.velafi.com/es/docs/payment-methods.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Crear una clave de API](https://docs.velafi.com/es/docs/guides/creating-api-key.md)


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