Uwierzytelnianie i limity API resellera
Tokeny Bearer, zakresy, lista dozwolonych IP, limit zapytań, kody błędów, klucze idempotentności i paginacja API resellera OneProvider, z przykładami.
Tokeny Bearer, uprawnienia, lista dozwolonych IP, limit zapytań, kody błędów, klucze idempotentności i paginacja w API resellera.
Wszystkie modele, możliwości i ceny Indeks dokumentacji dla agentów AI:https://oneprovider.dev/docs/llms.txt Tokeny
Token wygląda jak rsk_ i 40 kolejnych znaków. Utworzysz go w Panelu (zakładka resellera, „API i ustawienia”); wartość widać tylko raz, przechowujemy wyłącznie hash i ostatnie 4 znaki. Możesz mieć do 10 aktywnych tokenów i w każdej chwili unieważnić dowolny z nich. Przy tworzeniu tokenowi można nadać okres ważności (od 1 do 365 dni): po jego upływie token odpowiada 401 token_expired, a expires_at w GET /me podaje, kiedy to nastąpi (null: bez wygaśnięcia).
httpAuthorization: Bearer rsk_...Uprawnienia
Token ma przypisany zestaw uprawnień. Uprawnienia są niezależne: keys nie obejmuje read. GET /me działa z każdym ważnym tokenem. Bez wymaganego uprawnienia odpowiedź to 403 forbidden_scope.
| Uprawnienie | Co odblokowuje |
|---|---|
read | Odczyt: saldo i transakcje, cennik, modele, klienci, klucze i ich zużycie, zamówienia, plany, statystyki, ustawienia sklepu GET /settings, dziennik działań GET /audit (każde GET z wyjątkiem kodów, webhooków, botów i bramek płatności oraz statusu płatności doładowania). |
keys | Zapis: klienci (także blokowanie), wydawanie, edycja, wstrzymywanie, doładowywanie, rotacja i usuwanie kluczy, POST /orders, ustawienia sklepu PATCH /settings (to od nich zależy, jak wyglądają wydawane klucze). |
codes | Partie kodów i same kody (odczyt, tworzenie, unieważnianie, aktywacja). Kody są sekretami, dlatego mają osobne uprawnienie. |
plans | Tworzenie, edycja i usuwanie planów (odczyt planów wymaga read). |
billing | Doładowania salda resellera: POST /balance/topups i status płatności. |
webhooks | Zarządzanie webhookami, wysyłanie testu, odczyt dziennika dostarczeń. |
support | Zarezerwowane dla przyszłych metod wsparcia. |
bot | Odczyt stanu botów i bramek płatności: GET /bot i GET /payment-providers (w odpowiedziach nie ma tokenów). Boty podłącza się wyłącznie w Panelu. |
Uprawnienie każdej metody podano w dokumentacji metod .
Lista dozwolonych IP
Token można ograniczyć do listy adresów IPv4/IPv6 lub zakresów CIDR (do 20). Żądanie z innego adresu dostaje 403 ip_not_allowed. Listę ustawia się przy tworzeniu tokena.
Limit zapytań
20 żądań na sekundę na token i 100 na sekundę na źródłowy adres IP. Po przekroczeniu: 429 rate_limited i nagłówek Retry-After. Odczekaj tyle sekund i spróbuj ponownie.
Błędy
Każdy błąd ma taką samą strukturę. Ten sam identyfikator jest wysyłany w nagłówku X-Request-Id: podaj go wsparciu.
{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}Rozgałęziaj logikę według error.code, a nie według treści komunikatu.
| HTTP | code | Znaczenie |
|---|---|---|
| 400 | invalid | Brakuje pola lub jego wartość jest poza dozwolonym zakresem. |
| 400 | bad_request | Nie udało się przetworzyć żądania. |
| 400 | idempotency_key_required | Brak nagłówka Idempotency-Key w metodzie, która wydaje pieniądze. |
| 400 | invalid_url | URL webhooka nie przeszedł walidacji (tylko https, bez adresów IP i sieci prywatnych). |
| 400 | limit_below_spent | Nowy limit klucza jest niższy niż kwota, którą klucz już wydał. |
| 400 | currency_required | POST /balance/topups: bramka płatności obsługuje kilka walut, przekaż currency (dozwolone są w topup_providers). |
| 400 | method_unavailable | POST /balance/topups: nie ma takiej bramki w topup_providers (bad_currency, bad_email i email_required odpowiadają tak samo dla waluty i adresu e-mail). |
| 401 | unauthorized | Token nie został podany, jest nieznany lub unieważniony. |
| 401 | token_expired | Token wygasł (expires_at w GET /me): utwórz nowy. |
| 403 | forbidden_scope | Token nie ma wymaganego uprawnienia. |
| 403 | ip_not_allowed | Adres IP żądania nie znajduje się na liście dozwolonych tokena. |
| 403 | reseller_disabled | Reseller utracił dostęp; każdy token odpowiada w ten sposób. |
| 403 | banned | Konto jest zablokowane. |
| 404 | not_found | Obiekt nie istnieje lub należy do innego resellera. |
| 404 | key_not_found | Klucz nie istnieje. |
| 409 | insufficient_balance | Kwota nie mieści się w pozycji Dostępne (available_usd), zobacz zasadę dotyczącą pieniędzy. |
| 409 | idempotency_key_reused | Ten sam Idempotency-Key został już użyty z inną treścią żądania: użyj nowego klucza. |
| 409 | fund_first | Najpierw doładuj saldo resellera. |
| 409 | not_activated | Panel resellera nie jest jeszcze aktywowany. |
| 409 | name_taken | Klucz o tej nazwie już istnieje. |
| 409 | key_limit | Osiągnięto limit kluczy. |
| 409 | plan_limit | Osiągnięto limit planów (20). |
| 409 | customer_limit | Osiągnięto limit klientów (10 000). |
| 409 | plan_in_use | Planu nie można usunąć, podnieść jego ceny ani zmienić jego waluty, dopóki korzysta z niego świeży nieopłacony rachunek lub opłacony, ale niedostarczony zakup w bocie. |
| 409 | key_exhausted | Rotacja: w kluczu nie ma już czego przenieść, pozostało 0. |
| 409 | key_expired | Rotacja: klucz wygasł, najpierw go przedłuż. |
| 409 | action_failed | Akcja na kluczu nie powiodła się z innego powodu; ponów ją lub sprawdź klucz. |
| 409 | code_used | Kod został już aktywowany. |
| 409 | code_revoked | Kod został unieważniony. |
| 409 | code_busy | Kod jest w trakcie przetwarzania lub nie można go teraz aktywować. |
| 409 | external_order_id_conflict | external_order_id został już użyty z innymi parametrami. |
| 409 | customer_exists | Klient z tym external_id już istnieje. |
| 409 | customer_blocked | Klient jest zablokowany: jego klucze, zamówienia i aktywacje kodów są odrzucane. |
| 409 | token_limit | Osiągnięto limit aktywnych tokenów (10). |
| 409 | webhook_limit | Osiągnięto limit webhooków (5). |
| 429 | rate_limited | Ponad 20 żądań na sekundę na token (lub 100 na sekundę na adres IP); odczekaj Retry-After sekund. |
| 429 | too_many_invoices | POST /balance/topups: zbyt wiele nieopłaconych rachunków z rzędu; opłać otwarte lub spróbuj ponownie za minutę. |
| 501 | sandbox_not_implemented | Sandbox (rsk_test_...) nie jest jeszcze dostępny. |
| 503 | provider_unavailable | Bramka płatności lub dostawca modeli jest chwilowo niedostępny: spróbuj później. |
Idempotentność
Metody, które wydają pieniądze, wymagają nagłówka Idempotency-Key (od 1 do 128 znaków drukowalnych); bez niego (lub z nieprawidłowym) odpowiedź to 400 idempotency_key_required. Oznaczono je w dokumentacji metod. Powtórzenie żądania z tym samym kluczem i tą samą treścią (w obrębie resellera) nigdy nie wydaje pieniędzy dwa razy i zwraca ten sam obiekt, łącznie z sekretem klucza utworzonego tym wywołaniem: odpowiedź zgubioną po drodze można odzyskać, powtarzając wywołanie. Ten sam klucz z inną treścią to 409 idempotency_key_reused. Do każdej nowej płatności lub zamówienia używaj nowego klucza; w POST /orders tożsamość określa external_order_id. Nagłówek jest opcjonalny (i uwzględniany, jeśli go wyślesz) w PATCH /keys/{id} (powtórzone extend_days/extend_hours przedłuża tylko raz), POST /plans i POST /webhooks (powtórzenie zwraca ten sam obiekt; sekret webhooka nie jest pokazywany ponownie).
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'Przechowuj klucz idempotentności razem z własnym rekordem zamówienia, aby po błędzie sieci ponowić dokładnie to samo żądanie.
Paginacja
Endpointy list przyjmują ?limit=1..100 (domyślnie 50) i &cursor=. Odpowiedź ma postać {"items": [...], "next": "<cursor>"}; na ostatniej stronie next ma wartość null. Kursor jest nieprzezroczysty: odeślij go bez zmian.
curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"Sandbox
Tokeny testowe rsk_test_... pojawią się wkrótce. Na razie taki token dostaje 501 sandbox_not_implemented.