API i webhooki

Przez API allverto sklepy, operatorzy logistyczni, programy księgowe lub własne aplikacje wymieniają dane z allverto: artykuły, stany magazynowe, klientów, zamówienia, płatności, wysyłkę, zwroty, kanały sprzedaży, faktury i zakupy. Webhooki natychmiast zgłaszają zmiany na wybrany przez ciebie adres – np. „Zamówienie utworzone” lub „Stan zmieniony”.

Wszystko konfigurujesz w Ustawienia → API i webhooki. Znajdziesz tam też pełną Dokumentację wszystkich endpointów.

#Zanim zaczniesz

• Kluczami API i webhookami zarządzają role z uprawnieniem Zarządzanie kluczami API i webhookami – zwykle Właściciel i Administracja. Zob. Użytkownicy i role.
• Klucz otrzymuje najwyżej te uprawnienia, które masz sam. Jeśli później stracisz jakieś uprawnienie, traci je również klucz.
• To samo dotyczy webhooków: możesz subskrybować tylko zdarzenia, których dane sam możesz czytać – np. „Klient zmieniony” tylko z uprawnieniem „Wyświetlanie klientów”, „Faktura utworzona” tylko z „Wyświetlanie dokumentów”. Zdarzenia bez odpowiedniego uprawnienia allverto ukrywa.

#Tworzenie klucza API

1. Otwórz Ustawienia → API i webhooki, karta Klucze API.
2. Kliknij Utwórz klucz.
3. Wpisz Nazwę, po której rozpoznasz system zewnętrzny (np. „Połączenie Shopify”).
4. Wybierz Uprawnienia, np. „Odczyt zamówień” i „Import zamówień”. Wybierz tylko to, czego system zewnętrzny naprawdę potrzebuje.
5. Opcjonalnie: ogranicz klucz do jednej Firmy (wtedy widzi i zapisuje tylko zamówienia i dokumenty tej firmy), ustaw Datę ważności i Limit żądań na minutę.
6. Kliknij Utwórz klucz. allverto pokazuje klucz (av_…) dokładnie raz – skopiuj go przyciskiem Kopiuj i zapisz w systemie zewnętrznym.

W menu wiersza możesz Kopiuj prefiks (dzięki temu odnajdziesz klucz w systemie zewnętrznym) i w każdej chwili Unieważnij klucz. Od tej chwili API natychmiast go odrzuca. Na liście widzisz, kiedy klucz był Ostatnio użyty i z jakiego adresu IP.

#Żądania do API

Każde żądanie zawiera klucz w nagłówku Authorization: Bearer av_…. Endpointy znajdują się pod /api/v1, na przykład:

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Listy zwracają { data, page: { nextCursor, hasMore } }. Następną stronę pobierasz przez cursor=<nextCursor>. Z updatedSince=2026-10-01T00:00:00Z dostajesz tylko wpisy utworzone lub zmienione od tego momentu – idealne do regularnych synchronizacji.
• Błędy mają zawsze postać { error, message, fields } z odpowiednim statusem HTTP (400 dane wejściowe, 401 klucz, 403 brak uprawnienia, 404 nie znaleziono, 409 konflikt, 429 limit).
• Idempotencja: przy żądaniach POST wysyłaj unikalny nagłówek Idempotency-Key. Jeśli powtórzysz żądanie (np. po błędzie sieci), allverto niczego nie zaksięguje podwójnie, tylko przez 24 godziny zwraca tę samą odpowiedź.
• Limit żądań: domyślnie 120 żądań na minutę na klucz. Po jego przekroczeniu API odpowiada kodem 429 i nagłówkiem Retry-After (w sekundach).
• Zwroty i kanały sprzedaży: GET /api/v1/returns i /returns/{id} zwracają zwroty z pozycjami, przyczynami i zwrotem pieniędzy (uprawnienie „Odczyt zwrotów”), GET /api/v1/channels kanały sprzedaży – odpowiednik channelId w zamówieniach i zwrotach.

Zmiany wprowadzone przez API widać w Dzienniku zmian jako „API: nazwa klucza”.

#Konfiguracja webhooków

1. Karta Webhooki, kliknij Dodaj webhook.
2. Wpisz nazwę i Adres (https://…) odbiorcy oraz wybierz Zdarzenia, np. „Zamówienie utworzone”, „Płatność otrzymana”, „Stan zmieniony”. Przy kilku firmach możesz ograniczyć webhook do jednej firmy – zamówienia, dokumenty, zwroty i zamówienia zakupu innych firm nie trafią wtedy pod ten adres.
3. Kliknij Zapisz. allverto pokazuje sekret do weryfikacji podpisu – również tylko raz.
4. Przyciskiem Wyślij test sprawdzasz połączenie. Wynik pojawia się w Dzienniku dostarczeń.
5. Nowe webhooki są nieaktywne. Dopiero po kliknięciu Aktywuj allverto wysyła prawdziwe zdarzenia – tak jak przy wszystkich synchronizacjach.

Zdarzenia powstają w tej samej transakcji co zmiana: jeśli księgowanie zostanie przerwane, webhook również nie zostanie wysłany. Treść (data) ma ten sam format co API (np. GET /api/v1/orders/{id}, przy zwrotach GET /api/v1/returns/{id}).

Przy każdym dostarczeniu allverto sprawdza aktualne uprawnienia osoby, która utworzyła lub ostatnio zmieniła webhook. Jeśli brakuje jej uprawnienia do odczytu zdarzenia albo nie ma już aktywnego dostępu, żadna treść nie zostaje wysłana; dziennik dostarczeń pokazuje dostarczenie jako nieudane z przyczyną. Kto zapisze webhook później, staje się osobą odpowiedzialną.

#Weryfikacja podpisu

Każde wywołanie zawiera nagłówek allverto-signature: t=<czas Unix>,v1=<podpis>. Podpis to HMAC-SHA256 z sekretem obliczony z t + "." + Body. Sprawdzaj go na niezmienionym body i odrzucaj wywołania, których czas różni się o więcej niż 5 minut.

#Nieudane dostarczenia

Jeśli odbiorca nie odpowie kodem 2xx, allverto ponawia próbę – po 1 minucie, 5 minutach, 30 minutach, 2, 6, 12 i 24 godzinach. Po 20 kolejnych niepowodzeniach webhook zostaje automatycznie dezaktywowany; otrzymasz powiadomienie. W Dzienniku dostarczeń (okres domyślnie „Ostatnie 30 dni”) widzisz status, kod odpowiedzi i czas trwania każdego dostarczenia i możesz je Wyślij ponownie.

Webhooki mogą wywoływać tylko adresy publiczne – cele wewnętrzne, takie jak localhost czy sieci prywatne, są zablokowane.