Skip to main content
Wymaga członkostwa Silver lub wyższego — zarówno do złożenia wniosku, jak i przy każdym uwierzytelnionym wywołaniu. Jeśli członkostwo właściciela klucza wygaśnie, projekt zostaje zamrożony do czasu odnowienia.
REST API pozwalające Twojej aplikacji operować na saldzie Vito użytkownika prosto z Discorda — odczytywać je, obciążać, uznawać albo przenosić między użytkownikami. Wszystkie endpointy zwracają JSON i są wersjonowane pod /v1.
Vito nigdy nie zamienia się w prawdziwe pieniądze ani z nich nie pochodzi. Krąży wyłącznie między saldami Vetox.

Uzyskanie dostępu

Dostęp przyznawany jest osobno dla każdego projektu. Potrzebne są wszystkie cztery warunki:
1

Aktywne członkostwo, Silver lub wyższe

Sprawdzane przy każdym wywołaniu, nie tylko przy zatwierdzaniu.
2

Zatwierdzony wniosek deweloperski

Składany ze strony Vito API w panelu. Rozpatrywany ręcznie przez zespół Vetox.
3

Zaakceptowane warunki dla deweloperów API

Potwierdzane w momencie składania wniosku.
4

Scope'y, których potrzebuje Twój projekt

Przyznawane przez zespół Vetox na podstawie Twojego opisu.
Pisz konkretnie, co budujesz i jak będziesz przechowywać klucz. Odrzucane są właśnie wnioski ogólnikowe.

Scope’y

Uwierzytelnianie

Wyślij swój tajny klucz jako token Bearer:
Dwie opcjonalne warstwy dodatkowo wzmacniają projekt:
  • Lista dozwolonych IP — ogranicza wywołania do konkretnych adresów IP serwerów
  • Limity zapytań — pułapy na projekt, rosnące wraz z poziomem członkostwa właściciela

Klucze, rotacja i przechowywanie

Klucz i sekret podpisu pokazywane są dokładnie raz. Po zatwierdzeniu masz okno 7 dni, aby odsłonić je w zakładce kluczy API. Vetox przechowuje tylko skrót i nie może pokazać ich ponownie — jeśli przegapisz okno, trzeba wykonać rotację.
  • Trzymaj go wyłącznie po stronie serwera — kto go ma, może obciążać Twoich użytkowników
  • Rotuj w zakładce kluczy API. Poprzedni klucz działa jeszcze przez 24 godziny jako okres przejściowy, żebyś mógł wdrożyć zmianę bez przestoju
  • Sekret podpisu webhooków rotuje się osobno, z własnym 24-godzinnym nakładaniem
  • W razie wycieku rotuj natychmiast

Obciążenie użytkownika

Sam klucz nie przeniesie Vito użytkownika. Każde obciążenie wymaga zatwierdzenia przez użytkownika PIN-em jego portfela, na vetox.io — nigdy w Twojej aplikacji ani w Discordzie.
1

Twoja aplikacja wywołuje POST /v1/deduct

Z użytkownikiem, kwotą, źródłowym guildId i szczegółami przedmiotu.
2

Vito zwraca confirmUrl

Oczekujące potwierdzenie, ważne 10 minut. Użytkownik dostaje też wiadomość prywatną.
3

Użytkownik zatwierdza swoim PIN-em

Na vetox.io.
4

Vito rozlicza i powiadamia

Saldo zostaje obciążone, transakcja zapisana, a podpisany webhook wysłany, jeśli go skonfigurowałeś.
5

Twoja aplikacja weryfikuje i finalizuje

Sprawdź podpis, a potem odblokuj treść lub wydaj przedmiot.
Finalizuj swoje działanie wyłącznie przy confirmation.completed — nigdy na podstawie odpowiedzi /deduct. W tym momencie obciążenie nie jest jeszcze ostateczne.

Parametry żądania — /v1/deduct

Uznanie użytkownika

POST /v1/add dodaje użytkownikowi Vito z Twojego własnego salda — na nagrody lub zwroty. Te same pola co /deduct, poza guildId i product.
W odróżnieniu od obciążenia, uznanie nie ma kroku potwierdzenia — rozliczane jest od razu. Wymaga scope’a credit:create i wystarczającego salda, w przeciwnym razie wywołanie zwróci 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Opłaty

Każde obciążenie trafia do Ciebie pomniejszone o opłatę platformy — według tego samego cennika co przelewy Vito w aplikacji, zależnie od Twojego poziomu członkostwa:
Kwoty 5 Vito lub mniejsze są bez opłat, a uznania przez /v1/add są bez opłat zawsze.

Webhooki

Dodaj jeden lub więcej adresów zwrotnych https w zakładce ustawień. Vito wysyła podpisany POST za każdym razem, gdy potwierdzenie osiąga stan końcowy.
Webhooki wychodzą tylko wtedy, gdy projekt ma jednocześnie adres zwrotny i sekret podpisu. Odsłoń sekret (whsec_…) jednorazowo w zakładce kluczy API.

Weryfikacja podpisu

Każda dostawa niesie nagłówek X-Vito-Signature:
Każdej dostawie towarzyszą jeszcze dwa nagłówki — użyj X-Vito-Event-Id jako klucza deduplikacji, bo ponowna próba wysyła to samo id:
Podczas rotacji sekretu podpisu nagłówek niesie więcej niż jeden podpis, najnowszy jako pierwszy:
Przyjmij dostawę, jeśli zgadza się którykolwiek h1. Weryfikator czytający tylko pierwszy odrzuci każdy webhook, dopóki nie wdroży nowego sekretu — a to niweczy cały sens 24-godzinnego nakładania.
Przelicz HMAC z <ts>:<rawBody> swoim sekretem podpisu i porównaj w stałym czasie.
Weryfikuj wobec surowego ciała żądania, zanim parsowanie JSON albo middleware je przepisze.

Zdarzenia

Pięć typów zdarzeń, wszystkie o tej samej strukturze ładunku. Pole data.status niesie wynik.
Webhooki są ponawiane 5 razy z narastającym odstępem. Odpowiadaj szybko kodem 2xx, a realizację wykonuj asynchronicznie.

Kody błędów

Każda odpowiedź jest opakowana. Sukces niesie data, błąd niesie error — nigdy oba naraz:
Każdy kod ma przedrostek VITO_. Porównuj cały ciąg — samo RATE_LIMITED czy FORBIDDEN nigdy nie pojawia się w odpowiedzi.

Limity zapytań

Obowiązuje też limit na adres IP równy połowie Twojego limitu minutowego, nie mniej niż 30.
Pod obciążeniem endpointy zapisu zawodzą „na zamknięte” — obciążenie zostaje odrzucone, zamiast ryzykować podwójne wydanie. Endpointy odczytu zawodzą „na otwarte”. Traktuj odrzucony zapis jako „nie wydarzył się” i ponów go.
Wysyłaj nagłówek Idempotency-Key, aby bezpiecznie deduplikować ponowienia.

Endpointy

Ograniczenia

  • Potwierdzenia wygasają po 10 minutach — traktuj niepotwierdzone żądania jako porzucone
  • amount musi być dodatnią liczbą całkowitą
  • metadata jest ograniczona do 10 kluczy
  • Limity na transakcję i dzienne ustala zespół Vetox; widnieją tylko do odczytu w zakładce ustawień

Lista kontrolna bezpieczeństwa

Klucz API i sekret podpisu nigdy nie należą do kodu klienta. Jeśli którykolwiek wycieknie, rotuj natychmiast.
Sprawdzaj podpis wobec surowego ciała żądania i odrzucaj dostawy starsze niż ~5 minut.
Nigdy nie wydawaj na podstawie odpowiedzi /deduct — obciążenie jest ostateczne dopiero przy confirmation.completed.
Proś tylko o te scope’y, których faktycznie używasz, i włącz listę dozwolonych IP.

Rozwiązywanie problemów

Członkostwo właściciela wygasło. Jest sprawdzane przy każdym wywołaniu.
Nie da się go odzyskać — przechowywany jest tylko skrót. Wykonaj rotację, aby dostać nowy.
Akceptuj oba sekrety przez 24-godzinne nakładanie.
Użytkownik go nie zatwierdził. Potwierdzenia wygasają po 10 minutach.
Projekt potrzebuje adresu zwrotnego i sekretu podpisu. Przy tylko jednym z nich nic nie jest dostarczane.
To opłata rozliczeniowa. Używaj kwot 5 Vito lub mniejszych, aby jej uniknąć, albo wliczaj ją w cenę.
/v1/add finansowane jest z Twojego własnego salda, a nie tworzone z niczego. Doładuj je.

Vito

Salda, PIN i opłaty.

Prośby o płatność

Co widzi użytkownik, gdy go obciążasz.