Pobieranie danych zamówienia przez API

Zmodyfikowano dnia pon, 9 Mar o 6:06 RANO

Jeśli korzystasz z webhooków Z24, możesz automatycznie pobierać pełne dane zamówienia przez nasze API.

Typowy scenariusz wygląda tak:

Z24wysyła webhook (np. „nowe zamówienie”).
W webhooku otrzymujesz GUID dokumentu.
Korzystając z API Z24, pobierasz komplet danych zamówienia (nagłówek + pozycje).

Dzięki temu webhook jest lekki i szybki, a szczegółowe dane pobierasz na żądanie, kiedy faktycznie ich potrzebujesz.

Endpoint API

GET

https://api.z24.io/functions/v1/document_get/{DOCUMENT_GUID}

gdzie:

{DOCUMENT_GUID} to identyfikator dokumentu (UUID) otrzymany w webhooku.

Autoryzacja

Każde wywołanie API musi zawierać klucz API, który wygenerujesz w panelu Zamawiaj24.

Możesz przekazać klucz na jeden z dwóch sposobów:

Opcja 1: nagłówek `x-api-key`

x-api-key: TWÓJ_KLUCZ_API

Opcja 2: Authorization Bearer

Authorization: Bearer TWÓJ_KLUCZ_API

Klucz API musi mieć włączony zakres Odczyt zamówień.

Przykład wywołania (curl)

curl -X GET "https://api.z24.io/functions/v1/document_get/e0e71675-c8de-4e67-bb19-bc4544496629" \
  -H "x-api-key: TWÓJ_KLUCZ_API"

Struktura odpowiedzi

API zwraca jeden obiekt JSON składający się z dwóch części:

{
  "order": { ... },
  "items": [ ... ]
}

Sekcja `order` – dane zamówienia (nagłówek)

Pole	Opis
`document_guid`	Globalny identyfikator zamówienia (UUID)
`number`	Numer zamówienia
`status`	Aktualny status zamówienia
`workflow_status`	Status procesu (np. przekazane, zaakceptowane)
`created_at`	Data utworzenia
`updated_at`	Data ostatniej zmiany
`activated_at`	Data aktywacji (jeśli dotyczy)
`created_by`	ID użytkownika, który utworzył zamówienie
`currency`	Waluta (np. `PLN`)
`net_total`	Wartość netto
`vat_total`	Wartość VAT
`gross_total`	Wartość brutto
`notes`	Uwagi do zamówienia

Dane kontrahenta (klienta)

Pole	Opis
`contractor_guid`	GUID kontrahenta
`contractor_name`	Nazwa
`contractor_nip`	NIP
`contractor_city`	Miasto
`contractor_postal_code`	Kod pocztowy
`contractor_street`	Ulica
`contractor_building_number`	Numer budynku
`contractor_unit_number`	Numer lokalu
external_contractor_id	Kod kontrahenta w systemie dystrybutora (opcjonalnie)

Dane dystrybutora (jeśli występuje)

Pole	Opis
`distributor_guid`	GUID dystrybutora
`distributor_name`	Nazwa
`distributor_nip`	NIP
`distributor_city`	Miasto
`distributor_postal_code`	Kod pocztowy
`distributor_street`	Ulica
`distributor_building_number`	Numer budynku
`distributor_unit_number`	Numer lokalu

Sekcja `items` – pozycje zamówienia

Każdy element tablicy items opisuje jedną pozycję dokumentu.

Pole	Opis
`item_guid`	GUID pozycji
`line_no`	Numer pozycji
`product_guid`	GUID produktu
`product_name`	Nazwa produktu
`product_gtin`	Kod GTIN / EAN
`quantity`	Ilość w jednostkach dokumentu
`product_unit_name`	Podstawowa jednostka produktu
`document_unit_name`	Jednostka użyta w dokumencie
`document_unit_quantity`	Ile jednostek podstawowych zawiera jednostka dokumentu
`unit_conversion_factor`	Współczynnik przeliczenia jednostek
`unit_net_price`	Cena netto za jednostkę
`vat_rate`	Stawka VAT
`net_total`	Wartość netto pozycji
`vat_total`	Wartość VAT
`gross_total`	Wartość brutto
`item_notes`	Uwagi do pozycji

Typowy scenariusz integracji (krok po kroku)

Konfigurujesz webhook w Zamawiaj24 (np. „Nowe zamówienie”).
Odbierasz webhook w swoim systemie.
Z webhooka pobierasz document_guid.
Wywołujesz endpoint document_get z tym GUID-em.
Otrzymujesz komplet danych zamówienia i pozycji.
Przetwarzasz dane (ERP, WMS, księgowość, EDI, automatyzacje).

Kody błędów API

Kod	Znaczenie
`400`	Niepoprawny lub brak GUID dokumentu
`401`	Brak lub nieprawidłowy klucz API
`403`	Brak wymaganego zakresu dostępu
`404`	Zamówienie nie istnieje lub brak dostępu
`500`	Błąd po stronie serwera

Dobre praktyki

Traktuj webhook jako sygnał, a API jako źródło danych.
Nie zapisuj na stałe klucza API w kodzie frontendowym.
Jeśli integracja przestaje działać, sprawdź:
- czy klucz API jest aktywny,
- czy ma odpowiednie zakresy,
- czy GUID dokumentu pochodzi z Twojego zespołu.

Przykład zwracanych danych

{
    "items": [
        {
            "line_no": 1,
            "quantity": 1,
            "vat_rate": 23,
            "item_guid": "2c306726-35ab-4cf3-acdf-67fd99597383",
            "net_total": 10.06,
            "vat_total": 2.31,
            "item_notes": null,
            "gross_total": 12.37,
            "product_gtin": "5900000000007",
            "product_guid": "98c82ce1-04fe-4f3e-9af4-1328cf9687dc",
            "product_name": "Produkt 000007",
            "document_guid": "e0e71675-c8de-4e67-bb19-bc4544496629",
            "unit_net_price": 10.06,
            "product_unit_name": "Szt",
            "document_unit_name": "Szt",
            "document_unit_quantity": 1,
            "unit_conversion_factor": 1
        },
        {
            "line_no": 2,
            "quantity": 1,
            "vat_rate": 12,
            "item_guid": "72ff3ce0-7dea-4b65-81f5-e4a222228273",
            "net_total": 12.08,
            "vat_total": 1.45,
            "item_notes": null,
            "gross_total": 13.53,
            "product_gtin": "5900000000009",
            "product_guid": "69c497af-c802-4a46-9b1d-4586dcc35e34",
            "product_name": "Produkt 000009",
            "document_guid": "e0e71675-c8de-4e67-bb19-bc4544496629",
            "unit_net_price": 12.08,
            "product_unit_name": "Szt",
            "document_unit_name": "Szt",
            "document_unit_quantity": 1,
            "unit_conversion_factor": 1
        },
        {
            "line_no": 3,
            "quantity": 1,
            "vat_rate": 0,
            "item_guid": "eeecbaf6-f068-4c10-b693-c39ea7368055",
            "net_total": 5.17,
            "vat_total": 0,
            "item_notes": null,
            "gross_total": 5.17,
            "product_gtin": "5901008004111",
            "product_guid": "31894508-e2e8-4d38-ab1c-fef7e9a563f8",
            "product_name": "Buraczki konserwowe kulki 460g",
            "document_guid": "e0e71675-c8de-4e67-bb19-bc4544496629",
            "unit_net_price": 5.17,
            "product_unit_name": "szt",
            "document_unit_name": "szt",
            "document_unit_quantity": 1,
            "unit_conversion_factor": 1
        },
        {
            "line_no": 4,
            "quantity": 12,
            "vat_rate": 0,
            "item_guid": "7b189c1a-7988-423b-84fa-a3379d81fa79",
            "net_total": 62.04,
            "vat_total": 0,
            "item_notes": null,
            "gross_total": 124.08,
            "product_gtin": "5901008004111",
            "product_guid": "31894508-e2e8-4d38-ab1c-fef7e9a563f8",
            "product_name": "Buraczki konserwowe kulki 460g",
            "document_guid": "e0e71675-c8de-4e67-bb19-bc4544496629",
            "unit_net_price": 5.17,
            "product_unit_name": "szt",
            "document_unit_name": "zgrz",
            "document_unit_quantity": 2,
            "unit_conversion_factor": 6
        }
    ],
    "order": {
        "notes": "",
        "number": "ZAM-2026-0009-ph1",
        "status": "in_progress",
        "currency": "PLN",
        "net_total": 89.35,
        "team_guid": "e4840bf0-6acf-40b7-ab5c-af8286d691a0",
        "vat_total": 3.76,
        "created_at": "2026-01-20T11:06:49.147+00:00",
        "created_by": "fc358061-9a63-43ca-bd60-5c16a5532c17",
        "updated_at": "2026-01-20T11:09:54.968839+00:00",
        "gross_total": 93.1134,
        "activated_at": "2026-01-20T11:09:07.380434+00:00",
        "document_guid": "e0e71675-c8de-4e67-bb19-bc4544496629",
        "contractor_nip": "8000000075",
        "contractor_city": "Kielce",
        "contractor_guid": "02ec9471-4595-43a6-8090-5c213c17d9e9",
        "contractor_name": "Kontrahent 000075",
        "distributor_nip": "9000000001",
        "workflow_status": "forwarded",
        "distributor_city": "Kraków",
        "distributor_guid": "a185f069-7497-44db-a2b8-dcf8676ef394",
        "distributor_name": "Dystrybutor testowy 1",
        "contractor_street": "ul. Spacerowa",
        "distributor_street": "ul. Logistyczna",
        "contractor_postal_code": "76-175",
        "contractor_unit_number": null,
        "distributor_postal_code": "02-101",
        "distributor_unit_number": "2",
        "contractor_building_number": "76",
        "distributor_building_number": ""
    }
}