Klucze API, publiczne API i webhooki: jak połączyć własny system z Zaksio

Do czego to służy

Klucz API pozwala Twojemu sklepowi, hurtowni lub własnemu programowi czytać i zapisywać dane w Zaksio bez logowania człowieka. Publiczne API v1 działa pod adresem zaczynającym się od /v1 i obejmuje produkty, stany magazynowe, kontrahentów oraz faktury sprzedażowe (odczyt, PDF i wystawianie). Webhooki działają w drugą stronę: Zaksio samo wysyła do Twojego systemu zapytanie, gdy coś się wydarzy, np. wystawiono fakturę.

Pełny opis każdego adresu, przykłady w curl, JavaScript, Python i PHP oraz opis weryfikacji podpisu webhooków znajdziesz w dokumentacji API (strona „Dokumentacja API”). Ten artykuł opisuje stronę w aplikacji.

Gdzie to znaleźć i kto może

Ustawienia, „API i integracje” (przycisk „Jak to działa” otwiera krótką instrukcję). Ekran widzą Właściciel i Administrator firmy. Moduł jest dostępny niezależnie od profilu działalności firmy. Administrator platformy może wyłączyć publiczne API dla organizacji, wtedy ekran pokaże komunikat o wyłączonej funkcji.

Tworzenie klucza

1. W zakładce „Klucze API” kliknij „Nowy klucz”.
2. Wpisz „Nazwa klucza” (np. nazwę integracji) i wybierz „Firma”. Klucz widzi dane tylko tej jednej firmy.
3. Zaznacz „Zakresy”, czyli to, co klucz może robić (lista poniżej).
4. Opcjonalnie wpisz „Dozwolone adresy IP” (pojedyncze adresy lub zakresy CIDR), wybierz „Wygasanie” i ustaw „Limit zapytań na minutę” (domyślnie 120).
5. Podaj swoje hasło (oraz kod 2FA, jeśli masz je włączone) i kliknij „Utwórz klucz”.
6. Skopiuj klucz z okna „Skopiuj klucz API teraz” i zapisz go w bezpiecznym miejscu.

Zakresy

• Produkty: odczyt i zapis (lista, szczegóły, dodawanie, zmiana).
• Stany magazynowe: odczyt (suma i podział na magazyny).
• Kontrahenci: odczyt i zapis (dodawanie, zmiana, usuwanie, o ile kontrahent nie występuje na dokumentach).
• Faktury: odczyt (lista, szczegóły, PDF) i wystawianie (numeracja bez luk i księgowanie jak w aplikacji).
• Zamówienia i przesyłki: moduł zamówień jest już w aplikacji, ale jego adresów w publicznym API jeszcze nie ma. W oknie tworzenia klucza te zakresy są oznaczone „w przygotowaniu” i nie da się ich wybrać.

Klucz nigdy nie może więcej niż jego zakresy ani więcej niż uprawnienia osoby, która go utworzyła. Uprawnienia są sprawdzane przy każdym zapytaniu: jeśli rola tej osoby zostanie obniżona, klucz traci odpowiednie możliwości, a gdy osoba odejdzie z organizacji, jej klucze przestają działać.

Zabezpieczenia klucza

• Ograniczenie adresów IP: zapytania z innych adresów są odrzucane (kod 403), a próba trafia do dziennika zdarzeń.
• Wygasanie: po wybranym terminie klucz przestaje działać (kod 401).
• Limit zapytań na minutę: po przekroczeniu API odpowiada kodem 429 z nagłówkiem Retry-After.
• Odwołanie: „Odwołaj” działa natychmiast i jest nieodwracalne. Wymaga hasła.
• Rotacja: „Rotuj” tworzy nowy klucz o tych samych zakresach i ograniczeniach, a stary działa jeszcze przez wybrany okres przejściowy (od zera do 7 dni), żebyś zdążył wymienić go w integracji.
• Tworzenie, odwoływanie i rotacja kluczy oraz dodawanie webhooków wymagają ponownego podania hasła i kodu 2FA. Wszystkie te czynności, a także zapisy wykonane kluczem, zostają w dzienniku zdarzeń.

Pierwsze wywołanie

Klucz wysyłasz w nagłówku Authorization: Bearer zk_live_... Adres „/v1/whoami” zwraca firmę i zakresy klucza, więc nadaje się do sprawdzenia, czy klucz działa. Kwoty są w groszach, ilości jako tekst dziesiętny, a listy są stronicowane kursorem (parametry limit i cursor). Błędy mają format RFC 9457 (application/problem+json) ze stabilnym polem code.

Zapisy (POST, PATCH, DELETE) obsługują nagłówek Idempotency-Key: powtórzone zapytanie z tym samym kluczem zwraca zapamiętaną odpowiedź zamiast wykonać zapis drugi raz, np. wystawić drugą fakturę. Zawsze podawaj go przy wystawianiu faktur.

Webhooki

1. W zakładce „Webhooki” kliknij „Nowy webhook”.
2. Podaj „Adres odbiorcy (URL)”: tylko https i adres publiczny. Adresy lokalne i wewnętrzne są blokowane.
3. Wybierz zdarzenia (faktura wystawiona, faktura opłacona, kontrahent dodany lub zmieniony, produkt dodany lub zmieniony, stan produktu zmieniony) i ewentualnie jedną firmę.
4. Potwierdź hasłem. Skopiuj „Sekret podpisu”: widzisz go tylko raz.
5. Użyj przycisku „Test”, aby wysłać zdarzenie próbne i od razu zobaczyć odpowiedź odbiorcy.

Każde zapytanie jest podpisane (HMAC-SHA256 z sekretu, nagłówek Zaksio-Signature z znacznikiem czasu), więc odbiorca może sprawdzić, że pochodzi od Zaksio i nie jest powtórką sprzed kilku minut. Gotowy kod weryfikacji w czterech językach jest w dokumentacji API. Sekret można w każdej chwili wymienić przyciskiem „Nowy sekret”; poprzedni przestaje wtedy działać.

• Dostawa uznana jest za udaną po odpowiedzi 2xx. Przekierowania nie są obsługiwane.
• Nieudane dostawy są ponawiane po 1 minucie, 5 minutach, 30 minutach, 2, 6 i 12 godzinach. Po siódmej nieudanej próbie dostawa dostaje stan „Nie udało się” i możesz ją ponowić ręcznie w „Dzienniku”.
• Po 25 nieudanych próbach z rzędu subskrypcja jest wyłączana automatycznie (z podanym powodem). Włączasz ją przyciskiem „Włącz”.
• „Dziennik” pokazuje każdą dostawę: stan, liczbę prób, kod odpowiedzi, odpowiedź odbiorcy i wysłaną treść.

Użycie

Zakładka „Użycie” pokazuje liczbę zapytań dziennie (osobno część zakończona błędem) dla wszystkich kluczy albo wybranego, za 7, 30 lub 90 dni. W tabeli kluczy widzisz też datę i adres ostatniego użycia każdego klucza.

Czego jeszcze nie ma

• Zamówień i przesyłek w API: zakresy są zarezerwowane, ale adresy nie są jeszcze udostępnione. Zamówienia dodasz na razie w aplikacji.
• Limity zapytań są liczone osobno w każdej instancji serwera API.
• Wystawienie faktury przez API nie wysyła jej do KSeF: wysyłkę wykonujesz w aplikacji.