Skip to main content
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 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:
1

Una Membresía activa, Silver o superior

Se comprueba en cada llamada, no solo al aprobar la solicitud.
2

Una solicitud de desarrollador aprobada

Se envía desde la página de Vito API en tu panel. La revisa manualmente el equipo de Vetox.
3

Los Términos para Desarrolladores de la API aceptados

Se aceptan al enviar la solicitud.
4

Los scopes que tu proyecto necesita

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

Autenticación

Envía tu clave secreta como token Bearer:
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.
1

Tu app llama a POST /v1/deduct

Con el usuario, el importe, el guildId de origen y los detalles del artículo.
2

Vito devuelve una confirmUrl

Una confirmación pendiente, válida 10 minutos. El usuario también recibe un MD.
3

El usuario aprueba con su PIN

En vetox.io.
4

Vito liquida y notifica

Se descuenta el saldo, se registra la transacción y se envía un webhook firmado si tienes uno configurado.
5

Tu app verifica y completa

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

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:
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:
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:
Durante una rotación del secreto de firma la cabecera lleva más de una firma, la más nueva primero:
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 <ts>:<rawBody> con tu secreto de firma y compara en tiempo constante.
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.
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:
Todos los códigos llevan el prefijo VITO_. Compara la cadena completa: un RATE_LIMITED o FORBIDDEN a secas nunca aparece en la respuesta.

Límites de tasa

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

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.

Vito

Saldos, el PIN y las comisiones.

Solicitudes de pago

Lo que ve el usuario cuando le cobras.