Skip to main content
Richiede un abbonamento Silver o superiore — sia per candidarsi sia per ogni chiamata autenticata. Se l’abbonamento del titolare della chiave scade, il progetto viene congelato finché non si riabbona.
Un’API REST che permette alla tua applicazione di operare sul saldo Vito di un utente da dentro Discord: leggerlo, addebitarlo, accreditarlo o spostarlo tra utenti. Tutti gli endpoint restituiscono JSON e sono versionati sotto /v1.
I Vito non si convertono mai in denaro reale, né viceversa. Si spostano soltanto tra saldi Vetox.

Ottenere l’accesso

L’accesso viene concesso per progetto. Servono tutti e quattro i requisiti:
1

Un abbonamento attivo, Silver o superiore

Verificato a ogni chiamata, non solo in fase di approvazione.
2

Una richiesta da sviluppatore approvata

Si invia dalla pagina Vito API della dashboard. Viene esaminata manualmente dal team Vetox.
3

I Termini per sviluppatori dell'API accettati

Si accettano al momento dell’invio della richiesta.
4

Gli scope di cui il progetto ha bisogno

Concessi dal team Vetox in base a quanto hai descritto.
Sii concreto su cosa stai costruendo e su come conserverai la chiave. Sono le richieste vaghe a essere respinte.

Scope

Autenticazione

Invia la tua chiave segreta come token Bearer:
Due livelli facoltativi rafforzano ulteriormente un progetto:
  • Allowlist di IP — limita le chiamate a IP di server specifici
  • Limiti di frequenza — tetti per progetto che crescono con il livello di abbonamento del titolare

Chiavi, rotazione e conservazione

La chiave e il segreto di firma vengono mostrati esattamente una volta. Dopo l’approvazione hai una finestra di 7 giorni per rivelarli dalla scheda delle chiavi API. Vetox conserva solo un hash e non può mostrarli di nuovo: se perdi la finestra devi effettuare una rotazione.
  • Tienila solo lato server — chiunque la possieda può addebitare i tuoi utenti
  • Ruota dalla scheda delle chiavi API. La chiave precedente resta valida per un periodo di tolleranza di 24 ore, così puoi rilasciare senza interruzioni
  • Il segreto di firma dei webhook si ruota separatamente, con una sovrapposizione di 24 ore propria
  • In caso di fuga, ruota subito

Addebitare un utente

La tua chiave da sola non può spostare i Vito di un utente. Ogni addebito richiede l’approvazione dell’utente con il PIN del suo portafoglio, su vetox.io — mai dentro la tua app né dentro Discord.
1

La tua app chiama POST /v1/deduct

Con l’utente, l’importo, il guildId di origine e i dettagli dell’articolo.
2

Vito restituisce una confirmUrl

Una conferma in sospeso, valida 10 minuti. L’utente riceve anche un MP.
3

L'utente approva con il suo PIN

Su vetox.io.
4

Vito liquida e notifica

Il saldo viene addebitato, la transazione registrata e viene inviato un webhook firmato, se ne hai configurato uno.
5

La tua app verifica e completa

Controlla la firma, poi sblocca il contenuto o consegna l’articolo.
Completa la tua azione solo su confirmation.completed — mai sulla risposta di /deduct. A quel punto l’addebito non è ancora definitivo.

Parametri della richiesta — /v1/deduct

Accreditare un utente

POST /v1/add accredita Vito a un utente dal tuo saldo — per premi o rimborsi. Stessi campi di /deduct tranne guildId e product.
A differenza di un addebito, un accredito non ha una fase di conferma: viene liquidato subito. Richiede lo scope credit:create e saldo sufficiente, altrimenti la chiamata restituisce 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Commissioni

Ogni addebito ti viene liquidato al netto della commissione della piattaforma, secondo lo stesso schema dei trasferimenti Vito nell’app e in base al tuo livello di abbonamento:
Gli importi di 5 Vito o meno sono esenti da commissioni, e gli accrediti tramite /v1/add lo sono sempre.

Webhook

Aggiungi uno o più URL di callback https nella scheda delle impostazioni. Vito invia un POST firmato ogni volta che una conferma raggiunge uno stato finale.
I webhook partono solo se il progetto ha sia un URL di callback sia un segreto di firma. Rivela il segreto (whsec_…) una sola volta dalla scheda delle chiavi API.

Verificare la firma

Ogni consegna porta un header X-Vito-Signature:
Altri due header accompagnano ogni consegna — usa X-Vito-Event-Id come chiave di deduplicazione, perché un nuovo tentativo rimanda lo stesso id:
Durante una rotazione del segreto di firma l’header porta più di una firma, la più recente per prima:
Accetta la consegna se corrisponde una qualsiasi delle h1. Un verificatore che legge solo la prima rifiuterà ogni webhook finché non avrà rilasciato il nuovo segreto, vanificando lo scopo della sovrapposizione di 24 ore.
Ricalcola l’HMAC su <ts>:<rawBody> con il tuo segreto di firma e confronta a tempo costante.
Verifica sul corpo grezzo, prima di qualunque parsing JSON o middleware che lo riscriva.

Eventi

Cinque tipi di evento, tutti con la stessa struttura di payload. data.status porta l’esito.
I webhook vengono ritentati 5 volte con backoff. Rispondi rapidamente con 2xx ed esegui la consegna in modo asincrono.

Codici di errore

Ogni risposta è incapsulata. Un successo porta data, un errore porta error, mai entrambi:
Ogni codice ha il prefisso VITO_. Confronta la stringa completa: un RATE_LIMITED o FORBIDDEN da solo non compare mai nelle risposte.

Limiti di frequenza

Esiste anche un limite per IP pari alla metà della tua quota al minuto, con un minimo di 30.
Sotto carico gli endpoint di scrittura falliscono in modo chiuso — un addebito viene rifiutato anziché rischiare una doppia spesa. Le letture falliscono in modo aperto. Tratta una scrittura rifiutata come «non avvenuta» e riprova.
Invia un header Idempotency-Key per deduplicare i tentativi in sicurezza.

Endpoint

Limiti

  • Le conferme scadono dopo 10 minuti — considera abbandonate le richieste non confermate
  • amount deve essere un intero positivo
  • metadata è limitato a 10 chiavi
  • I tetti per transazione e giornalieri sono fissati dal team Vetox e appaiono in sola lettura nella scheda delle impostazioni

Checklist di sicurezza

La chiave API e il segreto di firma non vanno mai nel codice client. Se uno dei due trapela, ruota subito.
Controlla la firma sul corpo grezzo e rifiuta le consegne più vecchie di ~5 minuti.
Non consegnare mai sulla base della risposta di /deduct: l’addebito è definitivo solo con confirmation.completed.
Richiedi solo gli scope che usi davvero e attiva l’allowlist di IP.

Risoluzione dei problemi

L’abbonamento del titolare è scaduto. Viene ricontrollato a ogni chiamata.
Non è recuperabile — viene conservato solo un hash. Ruota per ottenerne una nuova.
Accetta entrambi i segreti durante la sovrapposizione di 24 ore.
L’utente non l’ha approvato. Le conferme scadono dopo 10 minuti.
Un progetto ha bisogno di URL di callback e segreto di firma. Con uno solo dei due non viene consegnato nulla.
È la commissione di liquidazione. Usa importi di 5 Vito o meno per evitarla, oppure includila nel prezzo.
/v1/add è finanziato dal tuo saldo, non creato dal nulla. Ricarica.

Vito

Saldi, PIN e commissioni.

Richieste di pagamento

Cosa vede l’utente quando lo addebiti.