> ## 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. # Descripción general de la API > Explora la API REST de VelaFi: URL base, formato JSON de las solicitudes, estructura estándar de las respuestas, límites de tasa y enlaces a las secciones principales de recursos. La API REST de VelaFi te permite gestionar de forma programática on-ramps de fiat a cripto, off-ramps de cripto a fiat y pagos globales de fiat a fiat a través de canales de stablecoin. La API sigue las convenciones RESTful: cada recurso se identifica con una URL, cada interacción usa métodos HTTP estándar y cada cuerpo de respuesta es JSON. Toda la comunicación se realiza por HTTPS, y los códigos de estado HTTP estándar indican el resultado de cada solicitud. ## URL base Elige el entorno que corresponda a la etapa de tu integración. Usa el entorno sandbox para desarrollo y pruebas, de modo que no se mueva dinero real. Cambia a la URL de producción solo cuando estés listo para salir en vivo. | Entorno | URL base | | - | - | | Producción | `https://api.velafi.com` | | Sandbox | `https://api-test.velafi.com` | > [!NOTE] > > Las credenciales de sandbox y de producción **no** son intercambiables. Usa la clave de API, el secreto de API y el token emitidos para el entorno al que estás llamando. ## Formato de la solicitud Envía todos los cuerpos de solicitud como JSON y configura el header `Content-Type` en consecuencia: ```http theme={null} Content-Type: application/json ``` Toda solicitud que acceda a un recurso protegido también debe incluir un token de negocio en el header `X-BH-TOKEN`. Obtén el token desde `GET /v2/token/generate` firmando la solicitud con tu clave de API y tu secreto de API. Consulta la página de [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md) para más detalles. **Ejemplo de solicitud** ```bash theme={null} curl --request GET \ --url https://api.velafi.com/v2/user/account \ --header "X-BH-TOKEN: your_token" ``` ## Estructura de la respuesta Las respuestas exitosas vienen envueltas en esta estructura JSON. Las respuestas de error incluyen `code` y `msg`, pero no `data`; consulta [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md). ```json theme={null} { "code": 200, "msg": "SUCCESS", "data": { ... } } ``` **code** `number` `200` si la solicitud es exitosa (algunos endpoints devuelven `0`). En caso de error, `code` es el código de error (negativo, excepto `30012`). No refleja el estado HTTP: las respuestas que incluyen un `code` de error usan HTTP `400` o `500`. Consulta [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md). **msg** `string` Un mensaje breve y legible que resume el resultado, por ejemplo `"SUCCESS"` o una descripción del error. **data** `object | array | null` El payload que devuelve el endpoint. Su forma varía según el endpoint y se documenta en cada página de referencia. ## Códigos de estado HTTP La siguiente tabla lista los códigos de estado HTTP que devuelve la API. | Código | Significado | | - | - | | `200 OK` | La solicitud fue exitosa. | | `400 Bad Request` | Cualquier error de autenticación, validación, límite de tasa o de negocio. El cuerpo incluye el `code` y el `msg` del error y, para la mayoría de los errores, el código se repite en el header de respuesta `error_code`. | | `404 Not Found` | La ruta no existe. | | `405 Method Not Allowed` | La ruta no acepta este método HTTP. | | `500 Internal Server Error` | Ocurrió un error inesperado. El cuerpo incluye el código `-1001`. | > [!WARNING] > > Un token faltante, inválido o vencido devuelve `400` con el código `-1002` o `-1022`, no `401`. Exceder un límite de tasa devuelve `400` con el código `-1006`, no `429`. Basa siempre tu lógica en el campo `code`. Consulta [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md) para ver todos los códigos y cuáles indican que el resultado es desconocido. ## Límites de tasa Los siguientes endpoints tienen un límite de tasa predeterminado, que se cuenta por cuenta de VelaFi y por separado para cada endpoint. La ventana de un minuto comienza con tu primera solicitud y se reinicia un minuto después. | Endpoint | Límite predeterminado | | - | - | | `GET /v2/user/crypto-quote` | 500 solicitudes por minuto | | `GET /v2/user/fiat-quote` | 500 solicitudes por minuto | | `POST /v2/order/fiat_to_crypto` | 500 solicitudes por minuto | | `POST /v2/order/crypto_to_fiat` | 500 solicitudes por minuto | | `POST /v2/order/fiat_to_fiat` | 500 solicitudes por minuto | | `GET /v2/merchant/check/alias` | 100 solicitudes por minuto | | `GET /v2/merchant/check/cvu` | 100 solicitudes por minuto | > [!NOTE] > > Una solicitud que excede el límite se rechaza con HTTP `400` y el código `-1006` (`Execution status unknown.`), no con `429`. Además, cualquier endpoint puede devolver el código `30012` (HTTP `400`) cuando recibe demasiadas solicitudes concurrentes. Espera antes de reintentar. Para las llamadas de creación de órdenes, sigue la sección "Resultado desconocido: verifica antes de reintentar" de [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md), porque `-1006` también se usa para otras fallas. Otros endpoints pueden tener sus propios límites. Contacta al [soporte de VelaFi](mailto:support@velafi.com) si necesitas un límite de throughput mayor para tu caso de uso. ## Secciones principales Usa las tarjetas siguientes para ir directamente al grupo de recursos que necesitas. > [card] [Comercios](https://docs.velafi.com/es/api-reference/merchant/create-merchant.md) > > Configura perfiles de comercio, consulta los detalles del comercio y gestiona la configuración a nivel de comercio. > [card] [Órdenes](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md) > > Crea, consulta y gestiona órdenes de pago on-ramp, off-ramp y de fiat a fiat. > [card] [Beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md) > > Agrega y gestiona las cuentas bancarias y billeteras cripto que reciben los pagos. > [card] [Webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md) > > Suscríbete a notificaciones de eventos en tiempo real sobre cambios de estado de órdenes y más. ## Related topics - [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md) - [Documentación de la API de VelaFi](https://docs.velafi.com/es/index.md) - [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md) - [Generar un token](https://docs.velafi.com/es/api-reference/generate-token.md) - [Evento de retiro de on-ramp](https://docs.velafi.com/es/api-reference/webhooks/on-ramp-withdraw-message-push.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.