Uwierzytelnianie i limity
Klucz API, nagłówki żądania, limity liczby zapytań i obsługa błędów w publicznym API PowerHub.
Adres bazowy
Wszystkie zasoby publiczne są dostępne pod jednym adresem bazowym. Pełną listę endpointów wraz z modelami danych znajdziesz w kolekcji Postman.
https://api.powerhub.pl
Klucz API
Klucz generujesz w panelu, w ustawieniach kluczy API. Przekazujesz go w nagłówku autoryzacji. Klucz działa w kontekście organizacji, w której powstał, więc nie trzeba podawać jej identyfikatora osobno.
curl https://api.powerhub.pl/orders?limit=20 \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json"
Nie umieszczaj klucza w kodzie wykonywanym w przeglądarce, w aplikacji mobilnej ani w publicznym repozytorium. Klucz, który wyciekł, odbierz natychmiast i wygeneruj nowy.
Limity żądań
Ruch z kluczem API jest ograniczany przepustowością liczoną na klucz. Limit działa jak kubełek żetonów: masz zapas na krótkie serie żądań, który uzupełnia się w sposób ciągły. Dzięki temu import wsadowy nie jest karany, a stałe bombardowanie już tak.
| Nagłówek odpowiedzi | Znaczenie |
|---|---|
| RateLimit-Limit | Trwała przepustowość w żądaniach na minutę. |
| RateLimit-Remaining | Ile żądań możesz jeszcze wykonać natychmiast. |
| RateLimit-Reset | Za ile sekund zapas wróci do pełna. |
| Retry-After | Wysyłany przy odmowie, po ilu sekundach ponowić. |
Czytaj nagłówki i sam reguluj tempo, zamiast czekać na odmowę. Klient, który reaguje na RateLimit-Remaining, nigdy nie zobaczy błędu 429.
Błędy
| Kod | Znaczenie | Co zrobić |
|---|---|---|
| 400 | Nieprawidłowe żądanie, błąd w danych wejściowych. | Sprawdź treść błędu; nie ponawiaj bez poprawki. |
| 401 | Brak lub nieprawidłowy klucz API. | Sprawdź nagłówek i to, czy klucz nie został odebrany. |
| 403 | Brak uprawnień do zasobu. | Zasób należy do innej organizacji albo nie jest publiczny. |
| 404 | Zasób nie istnieje. | Zweryfikuj identyfikator. |
| 409 | Konflikt, operacja narusza regułę biznesową. | Na przykład druga czynna faktura na zamówieniu. Sprawdź stan zasobu. |
| 429 | Przekroczony limit żądań. | Odczekaj czas z Retry-After i ponów. |
| 5xx | Błąd po naszej stronie. | Ponów z rosnącym odstępem. Jeżeli się utrzymuje, zgłoś. |
Co obejmuje publiczne API
Publiczne API udostępnia zasoby, których potrzebuje integrator budujący własny system: zamówienia i ich statusy, katalog i cennik, magazyn, klientów, dokumenty sprzedaży, wysyłkę, realizację, multimedia oraz rejestrację powiadomień wychodzących.
Zarządzanie integracjami, automatyzacjami, kontem i rozliczeniami wykonuje się w panelu, a nie przez publiczne API. Dzięki temu klucz API nie jest wektorem do przejęcia konfiguracji organizacji.