API resellera: jak to działa

Jak działa platforma resellera: saldo resellera, rezerwa, klucze klientów, kody, plany i wszystko, co robi Panel, dostępne przez REST API dla własnej strony lub bota.

Jak to działa

Reseller doładowuje własne saldo po cenie hurtowej i sprzedaje tokeny swoim klientom w postaci kluczy i kodów. Wszystko, co zrobisz w Panelu (zakładka resellera w app.oneprovider.dev), jest dostępne także przez API, więc możesz zbudować własną stronę, bota lub kasę.

• Saldo resellera. Saldo w USD oddzielone od twoich osobistych środków. Doładowujesz je po cenie hurtowej; GET /pricing zwraca cenę za 1 USD i rabat.
• Klucze klientów. Każdy klucz ma limit wydatków w USD i termin ważności (klucz z planu lub partii kodów może też nie mieć terminu: wtedy expires_at to null, a limit nadal obowiązuje). Klient używa go jak każdego klucza OneProvider.
• Kody. Partie kodów jednorazowych, które sprzedajesz gdziekolwiek. Aktywowany kod staje się kluczem, którego limit równa się kwocie kodu.
• Plany. Twoje ceny dla klientów: kwota klucza, cena, waluta i termin ważności. Klucze wydaje się z nich przez POST /orders.
• Neutralny panel klucza. Każdy klucz ma link dashboard_url: klient widzi zużycie i pozostałe saldo bez twojego brandingu i bez ujawniania sekretu klucza.

Zasada dotycząca pieniędzy: rezerwa i obciążenie

Saldo resellera składa się z trzech liczb:

Saldo resellera (balance_usd) = twoje pieniądze na platformie
Zarezerwowane (reserved_usd) = niezaktywowane kody + pozostałe limity działających kluczy
Dostępne (available_usd) = Saldo resellera - Zarezerwowane

Pieniądze nie są pobierane w chwili utworzenia czegokolwiek, lecz wtedy, gdy klient otrzyma wartość i zacznie ją wydawać. Do tego czasu są tylko zarezerwowane:

• Partia kodów tylko rezerwuje kwotę. Unieważnienie niezaktywowanych kodów zwalnia rezerwę.
• Aktywowany kod staje się kluczem, którego limit pozostaje zarezerwowany.
• Wydanie klucza rezerwuje jego limit; wydatki na kluczu obciążają saldo resellera.
• Usunięcie klucza lub obniżenie jego limitu natychmiast zwraca niewykorzystaną resztę do pozycji Dostępne.
• Wstrzymanie klucza nie zwalnia jego rezerwy.

Każdy nowy klucz, doładowanie klucza i partia kodów muszą się zmieścić w pozycji Dostępne; w przeciwnym razie odpowiedź to 409 insufficient_balance. Wszystkie trzy liczby zwraca GET /balance: balance_usd, reserved_usd, available_usd.

Pierwsze żądanie

1. W Panelu otwórz zakładkę resellera, „API i ustawienia”, i utwórz token. Wartość widać tylko raz.
2. Umieść token w zmiennej środowiskowej na swoim serwerze i wywołaj /balance:

export OP_PARTNER_TOKEN="rsk_..."
curl -s https://app.oneprovider.dev/partner/v1/balance \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"balance_usd": "120.00",
"reserved_usd": "35.50",
"available_usd": "84.50"
}

Przykład pokazuje tylko część pól odpowiedzi; pieniądze są zawsze ciągiem znaków z dwoma miejscami po przecinku. Pełny zestaw znajdziesz w dokumentacji metod i w OpenAPI .

Doładowanie salda resellera

Dostępne bramki płatności i ich minimalne kwoty znajdują się w topup_providers w GET /balance. Płatność tworzy się przez POST /balance/topups (uprawnienie billing; wymagany jest nagłówek Idempotency-Key). Zwrócony link do płatności przekazujesz płatnikowi.

curl -s -X POST https://app.oneprovider.dev/partner/v1/balance/topups \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-2026-10-08-001" \
-H "Content-Type: application/json" \
-d '{"balance_usd":"100.00","provider":"<id from topup_providers>"}'

Odpowiedź zawiera order_id i pay_url (201). Status płatności: GET /balance/topups/{order_id}; zaksięgowanie ogłasza także zdarzenie webhooka balance.topped_up.

Dziennik audytu

GET /audit (uprawnienie read) zwraca dziennik każdego działania na twoim koncie: z Panelu, przez tokeny API i przez system. Wpisów nie można zmienić (nie ma trasy edycji ani usuwania) i nigdy nie zawierają sekretów: kluczy, tokenów, kodów ani sekretów webhooków. Obiekt jest pokazany skrótowo: końcówka klucza, etykieta partii lub nazwa planu.

curl -s "https://app.oneprovider.dev/partner/v1/audit?period=7d&action=key.&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"items": [
{
"id": "<row id>",
"at": "2026-10-08T12:00:00Z",
"actor": { "kind": "token", "label": "shop backend" },
"action": "key.created",
"object": { "type": "key", "label": "anna-main (...4f2a)" },
"money": { "reserve_delta": "25.00", "debit_delta": "0.00", "available_after": "59.50" },
"ip": "203.0.113.7",
"request_id": "req_..."
}
],
"next": null,
"actions": ["key.created", "key.topped_up"]
}

actor.kind to user (Panel), token, system lub bot (bot sklepu resellera). money (null, gdy działanie nie dotyczyło pieniędzy) pokazuje zmiany rezerwy i obciążenia ze znakiem; available_after może mieć wartość null. Odpowiedź zawiera też pełną listę działań w actions:

key.created key.topped_up key.limit_changed key.updated key.paused key.resumed key.exhausted key.rotated key.extended key.expiry_changed key.deleted
code_batch.created code_batch.revoked code_batch.expired code.redeemed
plan.created plan.updated plan.deleted
token.created token.revoked
webhook.created webhook.deleted webhook.tested webhook.retried
balance.topup order.completed
customer.created customer.updated customer.blocked customer.unblocked
settings.updated account.activated

Konwencje

• Base URL: https://app.oneprovider.dev/partner/v1.
• Wszędzie JSON; pieniądze to ciąg znaków w USD z dwoma miejscami po przecinku ("12.50"); czasy w formacie ISO 8601 UTC (2026-10-08T12:00:00Z).
• Wywołuj API wyłącznie ze swojego serwera: nie ma CORS, a token nie może trafić do przeglądarki ani aplikacji mobilnej.
• Tokeny, uprawnienia, limit zapytań, błędy, idempotentność i paginacja: Autoryzacja i limity .

Dalej

• Klucze i klienci : wydawanie, doładowywanie, wstrzymywanie, usuwanie.
• Zamówienia : jak zbudować własną stronę.
• Kody i plany .
• Webhooki : zdarzenia i weryfikacja podpisu.
• Dokumentacja metod i openapi.yaml .