FAQ – Integracje z Z24 (Webhooki i API)

W tej sekcji znajdziesz odpowiedzi na najczęściej zadawane pytania dotyczące integracji Z24, webhooków oraz pobierania danych dokumentów przez API. 

SPIS TREŚCI

• Czy webhook z Z24 zawiera pełne dane zamówienia?
• Dlaczego dane nie są wysyłane bezpośrednio w webhooku?
• Co to jest GUID dokumentu?
• Czy jeden webhook może obsłużyć wiele integracji?
• Czy mogę używać API Z24 bez webhooków?
• Jak zabezpieczone jest API Z24?
• Czy klucz API można wykorzystać w kilku systemach?
• Co oznacza błąd 401 przy wywołaniu API?
• Co oznacza błąd 403 przy wywołaniu API?
• Co oznacza błąd 404 przy wywołaniu API?
• Czy mogę pobrać dane zamówienia wielokrotnie?
• Jak sprawdzić, czy integracja faktycznie działa?
• Czy Z24 narzuca konkretny system integracyjny?
• Co zrobić, jeśli integracja przestanie działać?

Czy webhook z Z24 zawiera pełne dane zamówienia?

Nie.
Webhook z Z24 zawiera tylko podstawowe informacje o zdarzeniu oraz GUID dokumentu.
Pełne dane zamówienia (nagłówek, kontrahent, pozycje, ceny) należy pobrać przez API, używając endpointu document_get.

Dlaczego dane nie są wysyłane bezpośrednio w webhooku?

Webhook pełni rolę sygnału o zdarzeniu, a API jest źródłem danych.
Takie rozwiązanie:

• jest szybsze i bardziej niezawodne,

• pozwala pobrać zawsze aktualną wersję dokumentu,

• umożliwia ponowne pobranie danych w razie błędu,

• sprawdza się w integracjach z różnymi systemami (ERP, Make, BaseLinker).

Co to jest GUID dokumentu?

GUID to globalny, unikalny identyfikator dokumentu w Z24.
Jest on przekazywany w webhooku i używany do pobierania danych dokumentu przez API.

Czy jeden webhook może obsłużyć wiele integracji?

Tak.
Ten sam webhook może wyzwalać różne procesy:

• import do ERP,

• zapis do arkusza,

• automatyzacje operacyjne,

• integracje z BaseLinker lub Make.

Każda integracja może niezależnie pobrać dane dokumentu przez API.

Czy mogę używać API Z24 bez webhooków?

Tak, technicznie API Z24 może być wywoływane bez użycia webhooków, ale należy pamiętać o jednej ważnej rzeczy: do pobrania dokumentu przez API potrzebny jest GUID dokumentu.

W praktyce:

• webhook z Z24 jest najczęstszym i rekomendowanym źródłem GUID dokumentu,

• to właśnie webhook informuje, który dokument należy pobrać,

• API służy do pobrania szczegółowych danych tego konkretnego dokumentu.

Możliwe scenariusze bez webhooka:

• ręczne testy (np. w Postmanie, gdy znasz GUID),

• ponowne pobranie danych wcześniej przetworzonego dokumentu,

• integracje, które przechowują GUID-y dokumentów po swojej stronie.

W typowej integracji produkcyjnej webhook + API zawsze działają razem:

• webhook wskazuje dokument,

• API dostarcza dane.

Jak zabezpieczone jest API Z24?

API Z24 jest zabezpieczone kluczami API, zaprojektowanymi zgodnie z dobrymi praktykami bezpieczeństwa:

• każdy klucz API jest przypisany do konkretnego zespołu,

• klucz posiada określone zakresy dostępu (np. odczyt zamówień),

• pełna wartość klucza jest widoczna tylko raz — w momencie jego utworzenia,

• Z24 nie przechowuje klucza w postaci jawnej — w systemie zapisywana jest wyłącznie jego bezpieczna postać (hash),

• w dowolnym momencie można dezaktywować klucz lub wygenerować nowy.

Dzięki temu nawet w przypadku nieautoryzowanego dostępu do bazy danych, rzeczywiste klucze API pozostają bezpieczne.

Czy klucz API można wykorzystać w kilku systemach?

Tak, ale rekomendujemy:

• osobny klucz API dla każdej integracji,

• dzięki temu łatwiej kontrolować dostęp i diagnozować problemy.

Co oznacza błąd 401 przy wywołaniu API?

Błąd 401 oznacza problem z autoryzacją:

• brak nagłówka z kluczem API,

• nieprawidłowy klucz,

• klucz został dezaktywowany.

Co oznacza błąd 403 przy wywołaniu API?

Błąd 403 oznacza, że klucz API nie ma wymaganych uprawnień.
Najczęściej oznacza to brak włączonego zakresu Odczyt zamówień.

Co oznacza błąd 404 przy wywołaniu API?

Błąd 404 może oznaczać:

• nieprawidłowy GUID dokumentu,

• dokument nie istnieje,

• dokument nie należy do zespołu przypisanego do klucza API.

Czy mogę pobrać dane zamówienia wielokrotnie?

Tak.
API Z24 nie ogranicza liczby odczytów tego samego dokumentu.
Dzięki temu możesz:

• ponowić pobranie po błędzie,

• przetestować integrację,

• porównać dane po zmianach statusu.

Jak sprawdzić, czy integracja faktycznie działa?

Najprościej:

1. Odbierz webhook z Z24.

2. Pobierz document_guid.

3. Wykonaj zapytanie API (np. przez Postman).

4. Sprawdź, czy API zwraca poprawne dane zamówienia.

Jeśli to działa w Postmanie, będzie działać również w Make, BaseLinker lub ERP.

Czy Z24 narzuca konkretny system integracyjny?

Nie.
Z24 udostępnia webhooki i API w standardzie HTTP/JSON.
Możesz integrować się z dowolnym systemem, który potrafi:

• odebrać webhook,

• wykonać zapytanie HTTP,

• przetworzyć dane JSON.

Co zrobić, jeśli integracja przestanie działać?

W pierwszej kolejności sprawdź:

• czy klucz API jest aktywny,

• czy ma odpowiednie zakresy,

• czy endpoint API jest poprawny,

• czy GUID dokumentu pochodzi z Twojego zespołu.

Jeśli problem nadal występuje, skontaktuj się z zespołem wsparcia Z24.