Sandbox

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:

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.

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

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:

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`

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.

curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols

import requests

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

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:

{
  "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"
    }
  ]
}

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:

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.

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.

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.

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.

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.

number

requerido

ID del comercio al que se acreditará.

string

requerido

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

number

requerido

Monto a depositar. Debe ser mayor que 0.

number

requerido

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

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.

cURL

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.

number

requerido

ID de un comercio aprobado.

string

requerido

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

number

requerido

Monto a agregar. Debe ser mayor que 0.

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

cURL

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"

Los simuladores solo cubren depósitos exitosos. No pueden generar un depósito fallido ni devuelto.

Siguientes pasos

Inicio rápido

Configura tu cuenta de producción y genera tu clave de API en vivo.

Referencia de la API

Explora todos los endpoints disponibles, sus parámetros y los esquemas de respuesta.

Primeros pasos

Conceptos clave

Guías

Referencia

URL base del sandbox

Cómo obtener credenciales del sandbox

Sandbox vs. producción

Ejemplo: obtener pares de trading fiat

Flujo de pruebas recomendado

Herramientas de prueba del sandbox

Simular un depósito fiat

Simular un depósito de cripto

Siguientes pasos

Inicio rápido

Referencia de la API

​URL base del sandbox

​Cómo obtener credenciales del sandbox

​Sandbox vs. producción

​Ejemplo: obtener pares de trading fiat

​Flujo de pruebas recomendado

​Herramientas de prueba del sandbox

​Simular un depósito fiat

​Simular un depósito de cripto

​Siguientes pasos

Inicio rápido

Referencia de la API

URL base del sandbox

Cómo obtener credenciales del sandbox

Sandbox vs. producción

Ejemplo: obtener pares de trading fiat

Flujo de pruebas recomendado

Herramientas de prueba del sandbox

Simular un depósito fiat

Simular un depósito de cripto

Siguientes pasos