Skip to main content
Nécessite un abonnement Silver ou supérieur — à la fois pour postuler et pour chaque appel authentifié. Si l’abonnement du détenteur de la clé expire, le projet est gelé jusqu’à son renouvellement.
Une API REST qui permet à votre application de manipuler le solde Vito d’un utilisateur depuis Discord : le lire, le débiter, le créditer ou le déplacer entre utilisateurs. Tous les endpoints renvoient du JSON et sont versionnés sous /v1.
Les Vito ne se convertissent jamais en argent réel, ni l’inverse. Ils circulent uniquement entre les soldes Vetox.

Obtenir l’accès

L’accès est accordé par projet. Les quatre conditions sont requises :
1

Un abonnement actif, Silver ou supérieur

Vérifié à chaque appel, pas seulement à l’approbation.
2

Une demande de développeur approuvée

Soumise depuis la page Vito API de votre tableau de bord. Examinée manuellement par l’équipe Vetox.
3

Les conditions développeur de l'API acceptées

Validées au moment de soumettre la demande.
4

Les scopes dont votre projet a besoin

Accordés par l’équipe Vetox selon ce que vous avez décrit.
Soyez précis sur ce que vous construisez et sur la façon dont vous stockerez la clé. Ce sont les demandes vagues qui sont refusées.

Scopes

Authentification

Envoyez votre clé secrète comme jeton Bearer :
Deux couches facultatives renforcent encore un projet :
  • Liste d’IP autorisées — restreindre les appels à des IP de serveur précises
  • Limites de débit — plafonds par projet qui augmentent avec le niveau d’abonnement du détenteur

Clés, rotation et stockage

Votre clé et votre secret de signature ne sont affichés qu’une seule fois. Après l’approbation, vous disposez d’une fenêtre de 7 jours pour les révéler depuis l’onglet des clés API. Vetox n’en conserve qu’un hachage et ne peut pas les réafficher — si vous manquez la fenêtre, il faut effectuer une rotation.
  • Gardez-la uniquement côté serveur — quiconque la détient peut débiter vos utilisateurs
  • Effectuez la rotation depuis l’onglet des clés API. La clé précédente reste valable pendant un délai de grâce de 24 heures, ce qui permet de déployer sans interruption
  • Le secret de signature des webhooks se renouvelle séparément, avec son propre chevauchement de 24 heures
  • En cas de fuite, effectuez immédiatement une rotation

Débiter un utilisateur

Votre clé seule ne peut pas déplacer les Vito d’un utilisateur. Chaque débit exige que l’utilisateur l’approuve avec le code PIN de son portefeuille, sur vetox.io — jamais dans votre application ni dans Discord.
1

Votre application appelle POST /v1/deduct

Avec l’utilisateur, le montant, le guildId d’origine et les détails de l’article.
2

Vito renvoie une confirmUrl

Une confirmation en attente, valable 10 minutes. L’utilisateur reçoit également un MP.
3

L'utilisateur approuve avec son code PIN

Sur vetox.io.
4

Vito règle et notifie

Le solde est débité, la transaction enregistrée, et un webhook signé est envoyé si vous en avez configuré un.
5

Votre application vérifie et finalise

Vérifiez la signature, puis débloquez le contenu ou livrez l’article.
Ne finalisez votre action que sur confirmation.completed — jamais sur la réponse de /deduct. À ce stade, le débit n’est pas définitif.

Paramètres de la requête — /v1/deduct

Créditer un utilisateur

POST /v1/add crédite des Vito à un utilisateur depuis votre propre solde — pour des récompenses ou des remboursements. Mêmes champs que /deduct, sauf guildId et product.
Contrairement à un débit, un crédit n’a pas d’étape de confirmation : il est réglé immédiatement. Nécessite le scope credit:create et un solde suffisant, sinon l’appel renvoie 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Frais

Chaque débit vous est reversé après déduction des frais de la plateforme — selon le même barème que les transferts Vito dans l’application, en fonction de votre niveau d’abonnement :
Les montants de 5 Vito ou moins sont sans frais, et les crédits via /v1/add le sont toujours.

Webhooks

Ajoutez une ou plusieurs URL de rappel https dans l’onglet des paramètres. Vito envoie un POST signé dès qu’une confirmation atteint un état final.
Les webhooks ne partent que si votre projet possède à la fois une URL de rappel et un secret de signature. Révélez le secret (whsec_…) une seule fois depuis l’onglet des clés API.

Vérifier la signature

Chaque livraison porte un en-tête X-Vito-Signature :
Deux autres en-têtes accompagnent chaque livraison — utilisez X-Vito-Event-Id comme clé de déduplication, car une nouvelle tentative renvoie le même identifiant :
Pendant une rotation du secret de signature, l’en-tête porte plusieurs signatures, la plus récente en premier :
Acceptez la livraison si l’un quelconque des h1 correspond. Un vérificateur qui ne lit que le premier rejettera tous les webhooks tant qu’il n’aura pas déployé le nouveau secret — ce qui annule tout l’intérêt du chevauchement de 24 heures.
Recalculez le HMAC sur <ts>:<rawBody> avec votre secret de signature et comparez en temps constant.
Vérifiez sur le corps brut, avant tout parsing JSON ou middleware susceptible de le réécrire.

Événements

Cinq types d’événements, partageant tous la même structure de charge utile. data.status porte le résultat.
Les webhooks sont réessayés 5 fois avec temporisation croissante. Répondez rapidement en 2xx et effectuez votre livraison de manière asynchrone.

Codes d’erreur

Chaque réponse est encapsulée. Un succès porte data, un échec porte error, jamais les deux :
Tous les codes sont préfixés par VITO_. Comparez la chaîne complète — un RATE_LIMITED ou FORBIDDEN isolé n’apparaît jamais dans les réponses.

Limites de débit

Il existe aussi une limite par IP égale à la moitié de votre quota par minute, avec un plancher de 30.
En charge, les endpoints d’écriture échouent en mode fermé — un débit est rejeté plutôt que de risquer une double dépense. Les lectures échouent en mode ouvert. Traitez une écriture rejetée comme « n’a pas eu lieu » et réessayez.
Envoyez un en-tête Idempotency-Key pour dédupliquer les nouvelles tentatives en toute sécurité.

Endpoints

Limites

  • Les confirmations expirent au bout de 10 minutes — considérez les demandes non confirmées comme abandonnées
  • amount doit être un entier positif
  • metadata est plafonné à 10 clés
  • Les plafonds par transaction et quotidiens sont fixés par l’équipe Vetox et affichés en lecture seule dans l’onglet des paramètres

Check-list de sécurité

La clé API et le secret de signature n’ont jamais leur place dans du code client. En cas de fuite de l’un ou l’autre, effectuez immédiatement une rotation.
Contrôlez la signature sur le corps brut et rejetez les livraisons datant de plus de ~5 minutes.
Ne livrez jamais sur la seule réponse de /deduct — le débit n’est définitif qu’avec confirmation.completed.
Ne demandez que les scopes réellement utilisés et activez la liste d’IP autorisées.

Dépannage

L’abonnement du détenteur a expiré. Il est revérifié à chaque appel.
Elle est irrécupérable — seul un hachage est stocké. Effectuez une rotation pour en obtenir une nouvelle.
Acceptez les deux secrets pendant le chevauchement de 24 heures.
L’utilisateur ne l’a pas approuvé. Les confirmations expirent au bout de 10 minutes.
Un projet a besoin d’une URL de rappel et d’un secret de signature. Avec un seul des deux, rien n’est livré.
Ce sont les frais de règlement. Utilisez des montants de 5 Vito ou moins pour les éviter, ou intégrez-les à votre prix.
/v1/add est financé sur votre propre solde, il n’est pas créé à partir de rien. Rechargez.

Vito

Soldes, code PIN et frais.

Demandes de paiement

Ce que voit l’utilisateur quand vous le débitez.