> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vetox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# API de Vito y compras
> Permite que aplicaciones aprobadas carguen sobre tu Vito con confirmación por PIN, y gestiona las solicitudes de pago desde tu página de Compras.
Requiere una Membresía **Silver** o superior — tanto para solicitarla como para cada llamada autenticada. Si la Membresía del titular de la clave caduca, el proyecto se congela hasta que vuelva a suscribirse.
Una API REST que permite a tu aplicación trabajar con el saldo de [Vito](/es/members/vito) de un usuario desde dentro de Discord: leerlo, cobrarlo, abonarlo o moverlo entre usuarios. Todos los endpoints devuelven JSON y están versionados bajo `/v1`.
**Vito nunca se convierte en dinero real ni proviene de él.** Solo se mueve entre saldos de Vetox.
## Obtener acceso
El acceso se concede **por proyecto**. Necesitas los cuatro requisitos:
Se comprueba en cada llamada, no solo al aprobar la solicitud.
Se envía desde la página de Vito API en tu panel. La revisa manualmente el equipo de Vetox.
Se aceptan al enviar la solicitud.
Los concede el equipo de Vetox según lo que hayas descrito.
Sé concreto sobre qué estás construyendo y cómo almacenarás la clave. Las solicitudes vagas son las que se rechazan.
### Scopes
| Scope | Permite |
| ------------------- | -------------------------------------------------------- |
| `balance:read` | Leer el saldo de Vito de un usuario |
| `deduct:create` | Cobrar del saldo de un usuario |
| `credit:create` | Añadir Vito a un usuario, financiado con tu propio saldo |
| `transfer:create` | Mover Vito entre dos usuarios |
| `transactions:read` | Listar y leer las transacciones de tu proyecto |
## Autenticación
Envía tu clave secreta como token Bearer:
```bash theme={null}
Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx
```
Dos capas opcionales refuerzan aún más un proyecto:
* **Lista de IP permitidas** — restringe las llamadas a IP de servidor concretas
* **Límites de tasa** — topes por proyecto que escalan con el nivel de Membresía del titular
### Claves, rotación y almacenamiento
**Tu clave y tu secreto de firma se muestran exactamente una vez.** Tras la aprobación dispones de una **ventana de 7 días** para revelarlos en la pestaña de claves API. Vetox solo guarda un hash y no puede volver a mostrarlos: si pierdes la ventana, tendrás que rotar.
* Guárdala **solo en el servidor** — cualquiera que la tenga puede cobrar a tus usuarios
* Rota desde la pestaña de claves API. La clave anterior sigue funcionando durante un **periodo de gracia de 24 horas** para que puedas desplegar sin cortes
* El secreto de firma de webhooks rota por separado, con su propio solapamiento de 24 horas
* Si se filtra, rota de inmediato
## Cobrar a un usuario
**Tu clave por sí sola no puede mover el Vito de un usuario.** Todo cobro exige que el usuario lo apruebe con el PIN de su monedero, en `vetox.io` — nunca dentro de tu app ni dentro de Discord.
Con el usuario, el importe, el `guildId` de origen y los detalles del artículo.
Una confirmación pendiente, válida **10 minutos**. El usuario también recibe un MD.
En `vetox.io`.
Se descuenta el saldo, se registra la transacción y se envía un webhook firmado si tienes uno configurado.
Comprueba la firma y luego desbloquea el contenido o entrega el artículo.
**Completa tu acción solo con `confirmation.completed`** — nunca con la respuesta de `/deduct`. En ese punto el cobro todavía no es definitivo.
### Parámetros de la petición — `/v1/deduct`
| Campo | Obligatorio | Notas |
| ------------- | ----------- | ------------------------------------------------------------------------------------------- |
| `discordId` | **Sí** | El ID de Discord del usuario — un snowflake de 17 a 20 dígitos |
| `amount` | **Sí** | Entero positivo |
| `guildId` | **Sí** | El servidor de Discord del que parte el cobro. Todo cobro debe originarse en un servidor |
| `reason` | No | Hasta 256 caracteres. Se muestra al usuario y se devuelve en el webhook |
| `merchantRef` | No | Tu propia referencia, hasta 128 caracteres. Úsala para casar el webhook con tus registros |
| `product` | No | `{ type, name, description?, imageUrl? }` — aparece en la página de confirmación y en el MD |
| `imageUrl` | No | Debe ser `https://` |
| `metadata` | No | Hasta **10** pares clave/valor de texto, que se transmiten tal cual |
## Abonar Vito a un usuario
`POST /v1/add` abona Vito a un usuario **desde tu propio saldo**, para recompensas o reembolsos. Los mismos campos que `/deduct` salvo `guildId` y `product`.
A diferencia de un cobro, un abono **no tiene paso de confirmación**: se liquida al instante. Requiere el scope `credit:create` y saldo suficiente, o la llamada devuelve **402 `VITO_INSUFFICIENT_OWNER_FUNDS`**.
## Comisiones
Cada cobro se te liquida menos la comisión de la plataforma, con el mismo esquema que las transferencias de Vito dentro de la app y según **tu** nivel de Membresía:
| Tu Membresía | Comisión |
| -------------------- | -------- |
| Normal, Silver, Gold | 7 % |
| Platinum | 6 % |
| Diamond | 5 % |
Los importes de **5 Vito o menos no tienen comisión**, y los abonos vía `/v1/add` nunca la tienen.
## Webhooks
Añade una o varias URL de callback `https` en la pestaña de ajustes. Vito entrega un `POST` firmado cada vez que una confirmación alcanza un estado final.
Los webhooks solo se envían si tu proyecto tiene **a la vez** una URL de callback **y** un secreto de firma. Revela el secreto (`whsec_…`) una única vez desde la pestaña de claves API.
### Verificar la firma
Cada entrega lleva una cabecera `X-Vito-Signature`:
```text theme={null}
X-Vito-Signature: ts=;h1=
```
Otras dos cabeceras acompañan cada entrega — usa `X-Vito-Event-Id` como clave de deduplicación, ya que un reintento reenvía el mismo id:
| Cabecera | Contiene |
| ------------------- | ------------------------------------------------------------ |
| `X-Vito-Event-Id` | Id estable de este evento — idéntico en todos los reintentos |
| `X-Vito-Event-Type` | Por ejemplo `confirmation.completed` |
**Durante una rotación del secreto de firma la cabecera lleva más de una firma**, la más nueva primero:
```text theme={null}
X-Vito-Signature: ts=;h1=;h1=
```
Acepta la entrega si coincide **cualquiera** de los `h1`. Un verificador que solo lea el primero rechazará todos los webhooks hasta haber desplegado el secreto nuevo, que es justo lo que el solapamiento de 24 horas pretende evitar.
Recalcula el HMAC sobre `:` con tu secreto de firma y compara en tiempo constante.
```js theme={null}
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const parts = header.split(';');
const ts = parts.find(p => p.startsWith('ts='))?.slice(3);
const sigs = parts.filter(p => p.startsWith('h1=')).map(p => p.slice(3));
if (!ts || sigs.length === 0) return false;
// Reject anything older than ~5 minutes — replay protection.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = Buffer.from(
crypto.createHmac('sha256', secret).update(`${ts}:${rawBody}`).digest('hex'),
);
// Any matching signature is valid — a rotation emits several.
return sigs.some(sig => {
const actual = Buffer.from(sig);
// timingSafeEqual throws when the lengths differ, so check first.
return (
actual.length === expected.length && crypto.timingSafeEqual(actual, expected)
);
});
}
```
Verifica contra el **cuerpo en bruto**, antes de cualquier parseo de JSON o middleware que lo reescriba.
### Eventos
Cinco tipos de evento, todos con la misma forma de payload. `data.status` lleva el resultado.
| Evento | Significado |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `confirmation.completed` | Aprobado y cobrado. Incluye `transactionId`. **Completa tu acción aquí** |
| `confirmation.failed` | No se pudo completar — saldo insuficiente o error interno. Incluye `failureReason` |
| `confirmation.expired` | No se confirmó en 10 minutos. No se movió ningún Vito |
| `confirmation.cancelled` | El usuario lo canceló. No se movió ningún Vito |
| `credit.completed` | Se liquidó un `/add` financiado por el titular. Se dispara al instante, sin paso de confirmación |
Los webhooks se reintentan **5 veces con espera creciente**. Responde 2xx rápido y haz tu entrega de forma asíncrona.
## Códigos de error
Toda respuesta va envuelta. Un éxito lleva `data` y un fallo lleva `error`, nunca ambos:
```json theme={null}
{
"success": false,
"error": {
"type": "Forbidden",
"message": "API key lacks the required scope for this operation.",
"code": "VITO_INSUFFICIENT_SCOPE"
},
"requestId": "…",
"timestamp": 1735161600000
}
```
**Todos los códigos llevan el prefijo `VITO_`.** Compara la cadena completa: un `RATE_LIMITED` o `FORBIDDEN` a secas nunca aparece en la respuesta.
| Código | Estado | Significado |
| ------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `VITO_VALIDATION_ERROR` | 400 | Falta un campo o tiene un formato incorrecto |
| `VITO_INVALID_AMOUNT` | 400 | `amount` no es un entero positivo |
| `VITO_AMOUNT_LIMIT_EXCEEDED` | 400 | Supera tu tope por transacción |
| `VITO_DAILY_VOLUME_EXCEEDED` | 400 | Esta llamada rebasaría tu tope de volumen diario |
| `VITO_SELF_TRANSFER` | 400 | Emisor y receptor son el mismo usuario |
| `VITO_INVALID_API_KEY` | 401 | Clave ausente, mal formada, revocada o desconocida |
| `VITO_INSUFFICIENT_FUNDS` | 402 | El usuario no puede cubrir el cobro |
| `VITO_INSUFFICIENT_OWNER_FUNDS` | 402 | **Tu** saldo es insuficiente para financiar un `/add` |
| `VITO_INSUFFICIENT_SCOPE` | 403 | La clave no tiene el scope que exige el endpoint |
| `VITO_IP_NOT_ALLOWED` | 403 | La IP que llama no está en la lista de permitidas |
| `VITO_OWNER_MEMBERSHIP_INACTIVE` | 403 | La Membresía del titular caducó — congelado hasta que se resuscriba |
| `VITO_GUILD_NOT_ALLOWED` | 403 | `guildId` no está en la lista de servidores permitidos del proyecto |
| `VITO_TOS_NOT_ACCEPTED` | 403 | Términos para desarrolladores no aceptados, o hay una versión más reciente pendiente |
| `VITO_PROJECT_FROZEN` | 403 | Congelado — normalmente por una Membresía del titular caducada |
| `VITO_PROJECT_SUSPENDED` | 403 | Suspendido por el equipo de Vetox |
| `VITO_PROJECT_BANNED` | 403 | Baneado por el equipo de Vetox |
| `VITO_USER_BLACKLISTED` | 403 | El usuario está excluido de las operaciones con Vito |
| `VITO_ACCOUNT_LOCKED` | 403 | El monedero del usuario está bloqueado tras intentos fallidos de PIN |
| `VITO_USER_NOT_FOUND` | 404 | No hay cuenta de Vito para ese ID de Discord |
| `VITO_CONFIRMATION_NOT_FOUND` | 404 | Token de confirmación desconocido |
| `VITO_IDEMPOTENCY_CONFLICT` | 409 | Mismo `Idempotency-Key` con un cuerpo distinto |
| `VITO_IDEMPOTENCY_IN_PROGRESS` | 409 | Una petición idéntica sigue en curso — reinténtalo en breve |
| `VITO_CONFIRMATION_ALREADY_PROCESSED` | 409 | Esa confirmación ya alcanzó un estado final |
| `VITO_KEY_ROTATION_IN_PROGRESS` | 409 | Ya hay una rotación en marcha |
| `VITO_CONFIRMATION_EXPIRED` | 410 | Transcurrió la ventana de 10 minutos |
| `VITO_RATE_LIMITED` | 429 | Reduce el ritmo y reinténtalo |
| `VITO_INTERNAL_ERROR` | 500 | Fallo inesperado por nuestra parte |
## Límites de tasa
| Membresía del titular | Por minuto | Por hora |
| --------------------- | ---------- | -------- |
| Ninguna | 60 | 1.000 |
| Silver o Gold | 180 | 5.000 |
| Platinum o Diamond | 600 | 15.000 |
También existe un límite por IP igual a la mitad de tu cuota por minuto, con un mínimo de 30.
Bajo carga, **los endpoints de escritura fallan en cerrado**: se rechaza el cobro en lugar de arriesgar un doble gasto. Los de lectura fallan en abierto. Trata una escritura rechazada como «no ocurrió» y reinténtala.
Envía una cabecera `Idempotency-Key` para deduplicar los reintentos con seguridad.
## Endpoints
| Endpoint | Scope |
| ------------------------------- | ------------------- |
| `GET /v1/auth/verify` | cualquiera |
| `POST /v1/auth/rotate-key` | cualquiera |
| `GET /v1/balance/:discordId` | `balance:read` |
| `POST /v1/deduct` | `deduct:create` |
| `POST /v1/add` | `credit:create` |
| `POST /v1/transfer` | `transfer:create` |
| `GET /v1/transactions` y `/:id` | `transactions:read` |
| `GET /v1/webhooks/events` | `transactions:read` |
## Límites
* Las confirmaciones caducan a los **10 minutos** — trata las no confirmadas como abandonadas
* `amount` debe ser un entero positivo
* `metadata` está limitado a 10 claves
* Los topes por transacción y diarios los fija el equipo de Vetox y aparecen en modo lectura en la pestaña de ajustes
## Lista de comprobación de seguridad
La clave API y el secreto de firma jamás deben estar en código de cliente. Rota de inmediato si alguno se filtra.
Comprueba la firma contra el cuerpo en bruto y rechaza las entregas de más de \~5 minutos.
Nunca entregues basándote en la respuesta de `/deduct`: el cobro no es firme hasta `confirmation.completed`.
Pide solo los scopes que realmente usas y activa la lista de IP permitidas.
## Resolución de problemas
La Membresía del titular ha caducado. Se comprueba en cada llamada.
No se puede recuperar: solo se almacena un hash. Rota para obtener una nueva.
Acepta ambos secretos durante el solapamiento de 24 horas.
El usuario no lo aprobó. Las confirmaciones caducan a los 10 minutos.
Un proyecto necesita URL de callback y secreto de firma. Con solo uno de los dos no se entrega nada.
Es la comisión de liquidación. Usa importes de 5 Vito o menos para evitarla, o inclúyela en tu precio.
`/v1/add` se financia con tu propio saldo, no se crea de la nada. Recarga.
Saldos, el PIN y las comisiones.
Lo que ve el usuario cuando le cobras.