Dokumentacja API

Publiczne API Zakito.Venzi - połącz zamówienia, faktury, statusy i przesyłki z zewnętrznymi systemami.

Wprowadzenie

API pozwala odczytywać i zmieniać dane Twojej firmy z Zakito.Venzi w formacie JSON - zamówienia, faktury, statusy, źródła i przesyłki. Odczyt to metody GET, zapis (tworzenie/aktualizacja) to metody POST z treścią JSON. Wszystko pod jednym adresem bazowym.

Wygeneruj klucz API

Uwierzytelnianie

Każde wywołanie wymaga nagłówka Authorization: Bearer <klucz>. Klucz wygenerujesz w panelu Venzi (sekcja Klucze API). Klucz jednoznacznie identyfikuje Twoją firmę - traktuj go jak hasło i nie udostępniaj publicznie.

curl "https://staging.venzi.zakito.eu/api/v1?method=get_orders&limit=10" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API"

Adres bazowy

Wszystkie metody wywołujesz pod tym adresem, przekazując nazwę metody w parametrze method.

https://staging.venzi.zakito.eu/api/v1

Format wywołania i odpowiedzi

Odczyt: GET z parametrem method w adresie. Zapis: POST z parametrem method w adresie i treścią JSON (pola w snake_case). Odpowiedź to JSON z polem status: SUCCESS przy powodzeniu lub ERROR z polem message przy błędzie.

Stronicowanie

Metody listujące przyjmują parametry limit (1-100, domyślnie 100) oraz offset (domyślnie 0). W odpowiedzi zwracane są pola count, limit i offset.

Limit zapytań

Publiczne API jest ograniczone do 120 zapytań na minutę na klucz API (okno stałe). Po przekroczeniu limitu zwracany jest kod HTTP 429 z nagłówkiem Retry-After (liczba sekund do zwolnienia limitu) i treścią { status: ERROR, message: Rate limit exceeded }.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{ "status": "ERROR", "message": "Rate limit exceeded" }

Błędy

Błędy zwracane są ze statusem HTTP i treścią { status: ERROR, message }.

{ "status": "ERROR", "message": "Unauthorized" }

401 - brak lub nieprawidłowy klucz; 400 - brak metody lub brak wymaganego parametru; 404 - nie znaleziono zasobu.

Metody

Typ zakończony znakiem „?” oznacza, że pole może być puste (null).

GET?method=get_statusesWymaga klucza

Lista statusów zamówień (etapy) z kolorami i przypisaniem do grup.

Parametry

Bez dodatkowych parametrów.

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_statuses

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`statuses`	array<object>	Tablica statusów zamówień.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`name`	string	Nazwa statusu w bieżącym języku (z fallbackiem na inny język).
`short_name`	string	Skrócona nazwa statusu (może być pusta).
`color`	string	Kolor statusu w formacie HEX, np. #3b82f6.
`group_id`	uuid	Identyfikator grupy, do której należy status.
`is_initial`	boolean	Czy to status startowy, nadawany nowym zamówieniom.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "statuses": [
    { "id": "3f2c…", "name": "Nowe", "short_name": "",
      "color": "#3b82f6", "group_id": "a1b2…", "is_initial": true }
  ]
}

GET?method=get_statuses_groupsWymaga klucza

Lista grup statusów (kolumny tablicy zamówień).

Parametry

Bez dodatkowych parametrów.

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_statuses_groups

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`statuses_groups`	array<object>	Tablica grup statusów.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`name`	string	Nazwa grupy statusów w bieżącym języku.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "statuses_groups": [ { "id": "a1b2…", "name": "Zamówienia" } ]
}

GET?method=get_sourcesWymaga klucza

Lista źródeł zamówień - ręcznych oraz pochodzących z integracji.

Parametry

Bez dodatkowych parametrów.

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_sources

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`sources`	array<object>	Tablica źródeł zamówień.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`name`	string	Nazwa źródła w bieżącym języku.
`kind`	string	Rodzaj źródła: manual (własne) lub integration (z konektora).
`is_protected`	boolean	Czy źródło jest systemowe (chronione, nieusuwalne).
`integration`	string?	Klucz integracji dla źródła z konektora (np. allegro); null dla źródeł własnych.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "sources": [
    { "id": "…", "name": "Domyślne", "kind": "manual",
      "is_protected": true, "integration": null }
  ]
}

GET?method=get_seriesWymaga klucza

Serie numeracji dokumentów (faktury, korekty, proformy).

Parametry

Parametr	Typ	Opis
`kind`opcjonalny	string	Filtr typu dokumentu: invoice, correction lub proforma.

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_series&kind=invoice

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`series`	array<object>	Tablica serii numeracji dokumentów.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`name`	string	Symbol/nazwa serii, np. FV.
`kind`	string	Typ dokumentu serii: invoice, correction lub proforma.
`title`	string	Tytuł dokumentu drukowany na wydruku, np. Faktura VAT.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "series": [ { "id": "…", "name": "FV", "kind": "invoice",
               "title": "Faktura VAT" } ]
}

GET?method=get_invoicesWymaga klucza

Lista faktur z filtrowaniem po typie i datach oraz stronicowaniem.

Parametry

Parametr	Typ	Opis
`kind`opcjonalny	string	Filtr typu dokumentu: invoice, correction lub proforma.
`issue_date_from`opcjonalny	date	Data wystawienia od (format YYYY-MM-DD).
`issue_date_to`opcjonalny	date	Data wystawienia do (format YYYY-MM-DD).
`sell_date_from`opcjonalny	date	Data sprzedaży od (format YYYY-MM-DD).
`sell_date_to`opcjonalny	date	Data sprzedaży do (format YYYY-MM-DD).
`order_dir`opcjonalny	string	Kierunek sortowania po dacie: ASC lub DESC (domyślnie DESC).
`limit`opcjonalny	integer	Liczba wyników na stronę (1-100, domyślnie 100).
`offset`opcjonalny	integer	Przesunięcie wyników - do stronicowania (domyślnie 0).

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_invoices&kind=invoice&issue_date_from=2026-01-01&limit=100

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`count`	integer	Łączna liczba pasujących rekordów, bez uwzględnienia stronicowania.
`limit`	integer	Zastosowany limit liczby wyników na stronę.
`offset`	integer	Zastosowane przesunięcie (pominięte rekordy).
`invoices`	array<object>	Tablica faktur.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`order_id`	uuid?	Identyfikator powiązanego zamówienia lub null.
`number`	string	Numer dokumentu, np. FV/2026/01/001.
`kind`	string	Typ dokumentu: invoice, correction lub proforma.
`issue_date`	date	Data wystawienia w formacie YYYY-MM-DD.
`paid_date`	date?	Data zapłaty w formacie YYYY-MM-DD lub null.
`sell_date`	date	Data sprzedaży w formacie YYYY-MM-DD.
`currency`	string	Kod waluty ISO 4217, np. PLN, EUR.
`use_oss`	boolean	Czy zastosowano procedurę OSS (sprzedaż wewnątrzunijna do konsumenta).
`seller_fullname`	string	Pełna nazwa sprzedawcy.
`seller_tax_no`	string	NIP sprzedawcy.
`seller_address`	string	Adres sprzedawcy (ulica i numer).
`seller_postcode`	string	Kod pocztowy sprzedawcy.
`seller_city`	string	Miejscowość sprzedawcy.
`seller_country`	string	Kraj sprzedawcy (kod, np. PL).
`buyer_fullname`	string	Nazwa lub imię i nazwisko nabywcy.
`buyer_company`	string	Nazwa firmy nabywcy (jeśli dotyczy).
`buyer_tax_no`	string	NIP nabywcy.
`buyer_address`	string	Adres nabywcy (ulica i numer).
`buyer_postcode`	string	Kod pocztowy nabywcy.
`buyer_city`	string	Miejscowość nabywcy.
`buyer_country`	string	Kraj nabywcy (kod, np. PL).
`correction_reason`	string?	Przyczyna korekty; tylko dla dokumentów typu correction.
`delivery_method`	string	Metoda dostawy.
`delivery_price`	number	Koszt dostawy (kwota brutto).
`delivery_quantity`	number	Liczba jednostek dostawy.
`delivery_vat`	string	Stawka VAT dla dostawy (np. 23).
`total_price`	number	Wartość brutto całego dokumentu.
`positions`	array<object>	Pozycje dokumentu (linie faktury).
`name`	string	Nazwa pozycji.
`quantity`	number	Ilość.
`price`	number	Cena brutto jednostkowa.
`vat`	string	Stawka VAT, np. 23.
`net_price`	number	Cena netto jednostkowa.
`total_price`	number	Wartość brutto pozycji.
`net_total_price`	number	Wartość netto pozycji.
`sku`	string	SKU / indeks produktu.
`ean`	string	Kod kreskowy EAN.
`offer_id`	string	Identyfikator oferty w platformie sprzedażowej.
`product_id`	string	Identyfikator produktu w katalogu.

Przykładowa odpowiedź

{
  "status": "SUCCESS", "count": 128, "limit": 100, "offset": 0,
  "invoices": [
    { "id": "…", "number": "FV/2026/01/001", "kind": "invoice",
      "issue_date": "2026-01-15", "currency": "PLN", "total_price": 1230.00,
      "buyer_fullname": "Jan Kowalski", "buyer_tax_no": "1234563218",
      "positions": [
        { "name": "Produkt A", "quantity": 2, "price": 615.00, "vat": "23",
          "net_price": 500.00, "total_price": 1230.00 }
      ] }
  ]
}

GET?method=get_invoiceWymaga klucza

Pojedyncza faktura wraz z pozycjami - po identyfikatorze, numerze lub zamówieniu.

Parametry

Parametr	Typ	Opis
`invoice_id`opcjonalny	uuid	Identyfikator faktury (UUID).
`number`opcjonalny	string	Numer dokumentu, np. FV/2026/01/001.
`order_id`opcjonalny	uuid	Identyfikator zamówienia (UUID).

Wymagany jeden z: invoice_id, number lub order_id.

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_invoice&number=FV/2026/01/001

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`invoice`	object	Obiekt faktury wraz z pozycjami.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`order_id`	uuid?	Identyfikator powiązanego zamówienia lub null.
`number`	string	Numer dokumentu, np. FV/2026/01/001.
`kind`	string	Typ dokumentu: invoice, correction lub proforma.
`issue_date`	date	Data wystawienia w formacie YYYY-MM-DD.
`paid_date`	date?	Data zapłaty w formacie YYYY-MM-DD lub null.
`sell_date`	date	Data sprzedaży w formacie YYYY-MM-DD.
`currency`	string	Kod waluty ISO 4217, np. PLN, EUR.
`use_oss`	boolean	Czy zastosowano procedurę OSS (sprzedaż wewnątrzunijna do konsumenta).
`seller_fullname`	string	Pełna nazwa sprzedawcy.
`seller_tax_no`	string	NIP sprzedawcy.
`seller_address`	string	Adres sprzedawcy (ulica i numer).
`seller_postcode`	string	Kod pocztowy sprzedawcy.
`seller_city`	string	Miejscowość sprzedawcy.
`seller_country`	string	Kraj sprzedawcy (kod, np. PL).
`buyer_fullname`	string	Nazwa lub imię i nazwisko nabywcy.
`buyer_company`	string	Nazwa firmy nabywcy (jeśli dotyczy).
`buyer_tax_no`	string	NIP nabywcy.
`buyer_address`	string	Adres nabywcy (ulica i numer).
`buyer_postcode`	string	Kod pocztowy nabywcy.
`buyer_city`	string	Miejscowość nabywcy.
`buyer_country`	string	Kraj nabywcy (kod, np. PL).
`correction_reason`	string?	Przyczyna korekty; tylko dla dokumentów typu correction.
`delivery_method`	string	Metoda dostawy.
`delivery_price`	number	Koszt dostawy (kwota brutto).
`delivery_quantity`	number	Liczba jednostek dostawy.
`delivery_vat`	string	Stawka VAT dla dostawy (np. 23).
`total_price`	number	Wartość brutto całego dokumentu.
`positions`	array<object>	Pozycje dokumentu (linie faktury).
`name`	string	Nazwa pozycji.
`quantity`	number	Ilość.
`price`	number	Cena brutto jednostkowa.
`vat`	string	Stawka VAT, np. 23.
`net_price`	number	Cena netto jednostkowa.
`total_price`	number	Wartość brutto pozycji.
`net_total_price`	number	Wartość netto pozycji.
`sku`	string	SKU / indeks produktu.
`ean`	string	Kod kreskowy EAN.
`offer_id`	string	Identyfikator oferty w platformie sprzedażowej.
`product_id`	string	Identyfikator produktu w katalogu.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "invoice": {
    "id": "…", "order_id": "…", "number": "FV/2026/01/001",
    "kind": "invoice", "issue_date": "2026-01-15", "currency": "PLN",
    "total_price": 1230.00, "positions": [ … ]
  }
}

GET?method=get_ordersWymaga klucza

Lista zamówień wraz z pozycjami, ze stronicowaniem i filtrem statusu.

Parametry

Parametr	Typ	Opis
`status_id`opcjonalny	uuid	Filtr po identyfikatorze statusu (UUID).
`limit`opcjonalny	integer	Liczba wyników na stronę (1-100, domyślnie 100).
`offset`opcjonalny	integer	Przesunięcie wyników - do stronicowania (domyślnie 0).

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_orders&limit=50

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`count`	integer	Łączna liczba pasujących rekordów, bez uwzględnienia stronicowania.
`limit`	integer	Zastosowany limit liczby wyników na stronę.
`offset`	integer	Zastosowane przesunięcie (pominięte rekordy).
`orders`	array<object>	Tablica zamówień.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`number`	string	Numer zamówienia.
`status_id`	uuid	Identyfikator bieżącego statusu zamówienia.
`source_id`	uuid	Identyfikator źródła zamówienia.
`total_price`	number	Wartość zamówienia (brutto).
`price_paid`	number	Kwota zapłacona przez kupującego.
`currency`	string	Kod waluty ISO 4217.
`confirm_status`	string	Status potwierdzenia zamówienia.
`buyer_login`	string	Login kupującego (np. z platformy sprzedażowej).
`buyer_email`	string	Adres e-mail kupującego.
`created_at`	datetime	Data utworzenia w formacie ISO 8601 (UTC).
`products`	array<object>	Pozycje zamówienia (produkty).
`name`	string	Nazwa produktu.
`quantity`	number	Ilość.
`price`	number	Cena brutto jednostkowa.
`vat`	string	Stawka VAT, np. 23.
`sku`	string	SKU / indeks produktu.
`ean`	string	Kod kreskowy EAN.

Przykładowa odpowiedź

{
  "status": "SUCCESS", "count": 42, "limit": 50, "offset": 0,
  "orders": [
    { "id": "…", "number": "1024", "status_id": "…", "source_id": "…",
      "total_price": 199.99, "price_paid": 199.99, "currency": "PLN",
      "confirm_status": "confirmed", "buyer_login": "jan_k",
      "buyer_email": "jan@example.com", "created_at": "2026-01-15T10:22:00Z",
      "products": [ { "name": "Produkt A", "quantity": 1, "price": 199.99,
                     "vat": "23", "sku": "SKU-1", "ean": "590…" } ] }
  ]
}

GET?method=get_orderWymaga klucza

Pojedyncze zamówienie wraz z pozycjami.

Parametry

Parametr	Typ	Opis
`order_id`wymagany	uuid	Identyfikator zamówienia (UUID).

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_order&order_id=8c1e…

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`order`	object	Obiekt zamówienia wraz z pozycjami.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`number`	string	Numer zamówienia.
`status_id`	uuid	Identyfikator bieżącego statusu zamówienia.
`source_id`	uuid	Identyfikator źródła zamówienia.
`total_price`	number	Wartość zamówienia (brutto).
`price_paid`	number	Kwota zapłacona przez kupującego.
`currency`	string	Kod waluty ISO 4217.
`confirm_status`	string	Status potwierdzenia zamówienia.
`buyer_login`	string	Login kupującego (np. z platformy sprzedażowej).
`buyer_email`	string	Adres e-mail kupującego.
`created_at`	datetime	Data utworzenia w formacie ISO 8601 (UTC).
`products`	array<object>	Pozycje zamówienia (produkty).
`name`	string	Nazwa produktu.
`quantity`	number	Ilość.
`price`	number	Cena brutto jednostkowa.
`vat`	string	Stawka VAT, np. 23.
`sku`	string	SKU / indeks produktu.
`ean`	string	Kod kreskowy EAN.

Przykładowa odpowiedź

{
  "status": "SUCCESS",
  "order": {
    "id": "8c1e…", "number": "1024", "status_id": "…", "source_id": "…",
    "total_price": 199.99, "currency": "PLN", "buyer_email": "jan@example.com",
    "created_at": "2026-01-15T10:22:00Z", "products": [ … ]
  }
}

GET?method=get_shipmentsWymaga klucza

Przesyłki (numery śledzenia, przewoźnik, status) - dla zamówienia lub wszystkie.

Parametry

Parametr	Typ	Opis
`order_id`opcjonalny	uuid	Identyfikator zamówienia (UUID).
`limit`opcjonalny	integer	Liczba wyników na stronę (1-100, domyślnie 100).
`offset`opcjonalny	integer	Przesunięcie wyników - do stronicowania (domyślnie 0).

Przykładowe wywołanie

https://staging.venzi.zakito.eu/api/v1?method=get_shipments&order_id=8c1e…

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`count`	integer	Łączna liczba pasujących rekordów, bez uwzględnienia stronicowania.
`limit`	integer	Zastosowany limit liczby wyników na stronę.
`offset`	integer	Zastosowane przesunięcie (pominięte rekordy).
`shipments`	array<object>	Tablica przesyłek.
`id`	uuid	Unikalny identyfikator rekordu (UUID).
`order_id`	uuid	Identyfikator zamówienia, którego dotyczy przesyłka.
`tracking_number`	string	Numer śledzenia przesyłki.
`courier`	string?	Przewoźnik: kod z katalogu (np. inpost) lub nazwa własna.
`status`	string?	Kod statusu śledzenia przesyłki lub null.
`type`	string?	Typ przesyłki (do klienta / reklamacja / zwrot) lub null.
`status_change_date`	datetime?	Data ostatniej zmiany statusu (ISO 8601) lub null.
`created_at`	datetime	Data utworzenia rekordu (ISO 8601, UTC).

Przykładowa odpowiedź

{
  "status": "SUCCESS", "count": 1, "limit": 100, "offset": 0,
  "shipments": [
    { "id": "…", "order_id": "8c1e…", "tracking_number": "00590…",
      "courier": "inpost", "status": "in_transit", "type": null,
      "created_at": "2026-01-16T08:00:00Z" }
  ]
}

POST?method=create_orderWymaga klucza

Tworzy nowe zamówienie (pozycje, dane kupującego, dostawa). Uruchamia automatyzacje.

Treść żądania (JSON)

Pole	Typ	Opis
`number`opcjonalny	string	Numer zamówienia; pominięty przy tworzeniu = nadany automatycznie.
`status_id`opcjonalny	uuid	Identyfikator statusu; pominięty przy tworzeniu = status startowy.
`source_id`opcjonalny	uuid	Identyfikator źródła; pominięty = źródło domyślne.
`buyer_login`opcjonalny	string	Login kupującego.
`buyer_email`opcjonalny	string	Adres e-mail kupującego.
`buyer_phone`opcjonalny	string	Telefon kupującego.
`payment_method`opcjonalny	string	Metoda płatności.
`payment_currency`opcjonalny	string	Kod waluty ISO 4217 (np. PLN).
`price_paid`opcjonalny	number	Kwota zapłacona; gdy ≥ wartość zamówienia, oznacza je jako opłacone.
`delivery_method`opcjonalny	string	Metoda dostawy.
`delivery_cost`opcjonalny	number	Koszt dostawy (brutto).
`delivery_name`opcjonalny	string	Odbiorca - imię i nazwisko / nazwa.
`delivery_company`opcjonalny	string	Odbiorca - firma.
`delivery_address`opcjonalny	string	Adres dostawy (ulica i numer).
`delivery_zip_code`opcjonalny	string	Kod pocztowy dostawy.
`delivery_city`opcjonalny	string	Miejscowość dostawy.
`delivery_country`opcjonalny	string	Kraj dostawy (kod, np. PL).
`products`opcjonalny	array<object>	Pozycje zamówienia. Przy update_order podane pozycje zastępują dotychczasowe.
`name`wymagany	string	Nazwa pozycji (wymagana).
`quantity`opcjonalny	integer	Ilość (domyślnie 1).
`price`opcjonalny	number	Cena brutto jednostkowa.
`vat`opcjonalny	number	Stawka VAT (np. 23).
`sku`opcjonalny	string	SKU / indeks produktu.
`ean`opcjonalny	string	Kod EAN.

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=create_order" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "buyer_email": "jan@example.com",
  "products": [ { "name": "Produkt A", "quantity": 1, "price": 199.99, "vat": 23 } ] }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`order_id`	uuid	Identyfikator utworzonego/zmienionego zamówienia (UUID).
`number`	string	Nadany numer dokumentu / zamówienia.

Przykładowa odpowiedź

{ "status": "SUCCESS", "order_id": "8c1e…", "number": "100001" }

POST?method=update_orderWymaga klucza

Aktualizuje zamówienie: status, dane, pozycje (podane pozycje zastępują dotychczasowe).

Treść żądania (JSON)

Pole	Typ	Opis
`order_id`wymagany	uuid	Identyfikator zamówienia - wymagany tylko dla update_order.
`number`opcjonalny	string	Numer zamówienia; pominięty przy tworzeniu = nadany automatycznie.
`status_id`opcjonalny	uuid	Identyfikator statusu; pominięty przy tworzeniu = status startowy.
`source_id`opcjonalny	uuid	Identyfikator źródła; pominięty = źródło domyślne.
`buyer_login`opcjonalny	string	Login kupującego.
`buyer_email`opcjonalny	string	Adres e-mail kupującego.
`buyer_phone`opcjonalny	string	Telefon kupującego.
`payment_method`opcjonalny	string	Metoda płatności.
`payment_currency`opcjonalny	string	Kod waluty ISO 4217 (np. PLN).
`price_paid`opcjonalny	number	Kwota zapłacona; gdy ≥ wartość zamówienia, oznacza je jako opłacone.
`delivery_method`opcjonalny	string	Metoda dostawy.
`delivery_cost`opcjonalny	number	Koszt dostawy (brutto).
`delivery_name`opcjonalny	string	Odbiorca - imię i nazwisko / nazwa.
`delivery_company`opcjonalny	string	Odbiorca - firma.
`delivery_address`opcjonalny	string	Adres dostawy (ulica i numer).
`delivery_zip_code`opcjonalny	string	Kod pocztowy dostawy.
`delivery_city`opcjonalny	string	Miejscowość dostawy.
`delivery_country`opcjonalny	string	Kraj dostawy (kod, np. PL).
`products`opcjonalny	array<object>	Pozycje zamówienia. Przy update_order podane pozycje zastępują dotychczasowe.
`name`wymagany	string	Nazwa pozycji (wymagana).
`quantity`opcjonalny	integer	Ilość (domyślnie 1).
`price`opcjonalny	number	Cena brutto jednostkowa.
`vat`opcjonalny	number	Stawka VAT (np. 23).
`sku`opcjonalny	string	SKU / indeks produktu.
`ean`opcjonalny	string	Kod EAN.

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=update_order" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "8c1e…", "status_id": "3f2c…" }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`order_id`	uuid	Identyfikator utworzonego/zmienionego zamówienia (UUID).

Przykładowa odpowiedź

{ "status": "SUCCESS", "order_id": "8c1e…" }

POST?method=create_invoiceWymaga klucza

Wystawia dokument sprzedaży dla zamówienia (faktura, korekta lub proforma).

Treść żądania (JSON)

Pole	Typ	Opis
`order_id`wymagany	uuid	Identyfikator zamówienia, dla którego wystawiasz dokument (wymagany).
`series_id`wymagany	uuid	Identyfikator serii numeracji z get_series (wymagany).
`document_type`opcjonalny	string	Typ dokumentu: invoice, correction lub proforma (domyślnie invoice).
`correction_id`opcjonalny	uuid	Identyfikator korygowanej faktury (dla document_type=correction).
`correction_reason`opcjonalny	string	Przyczyna korekty.
`buyer_name`opcjonalny	string	Nabywca - nadpisuje dane z zamówienia.
`buyer_company`opcjonalny	string	Firma nabywcy.
`buyer_vat_id`opcjonalny	string	NIP nabywcy.

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=create_invoice" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "8c1e…", "series_id": "a1b2…", "document_type": "invoice" }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`invoice_id`	uuid	Identyfikator wystawionego dokumentu (UUID).
`number`	string	Nadany numer dokumentu / zamówienia.

Przykładowa odpowiedź

{ "status": "SUCCESS", "invoice_id": "…", "number": "FV/2026/01/001" }

POST?method=create_shipmentWymaga klucza

Dodaje przesyłkę do zamówienia (numer śledzenia, przewoźnik, status).

Treść żądania (JSON)

Pole	Typ	Opis
`order_id`wymagany	uuid	Identyfikator zamówienia (wymagany dla create_shipment).
`tracking_number`wymagany	string	Numer śledzenia (wymagany przy tworzeniu).
`supplier_code`wymagany	string	Kod przewoźnika z katalogu (np. inpost, dpd, dhl, gls, other).
`supplier_name`opcjonalny	string	Nazwa własna przewoźnika - gdy supplier_code = other.
`status`opcjonalny	string	Kod statusu śledzenia przesyłki.
`type`opcjonalny	string	Typ przesyłki (do klienta / reklamacja / zwrot).

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=create_shipment" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "order_id": "8c1e…", "tracking_number": "00590…",
  "supplier_code": "inpost", "status": "created" }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`shipment_id`	uuid	Identyfikator przesyłki (UUID).
`sent_to_platform`	boolean	Czy numer śledzenia przekazano do platformy sprzedażowej (jeśli dotyczy).
`platform_error`	string?	Komunikat błędu przekazania do platformy lub null.

Przykładowa odpowiedź

{ "status": "SUCCESS", "shipment_id": "…",
  "sent_to_platform": false, "platform_error": null }

POST?method=update_shipmentWymaga klucza

Aktualizuje przesyłkę (numer śledzenia, przewoźnik, status, typ).

Treść żądania (JSON)

Pole	Typ	Opis
`shipment_id`wymagany	uuid	Identyfikator przesyłki (wymagany dla update_shipment i delete_shipment).
`tracking_number`opcjonalny	string	Numer śledzenia (wymagany przy tworzeniu).
`supplier_code`opcjonalny	string	Kod przewoźnika z katalogu (np. inpost, dpd, dhl, gls, other).
`supplier_name`opcjonalny	string	Nazwa własna przewoźnika - gdy supplier_code = other.
`status`opcjonalny	string	Kod statusu śledzenia przesyłki.
`type`opcjonalny	string	Typ przesyłki (do klienta / reklamacja / zwrot).

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=update_shipment" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "shipment_id": "…", "status": "in_transit" }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`shipment_id`	uuid	Identyfikator przesyłki (UUID).

Przykładowa odpowiedź

{ "status": "SUCCESS", "shipment_id": "…" }

POST?method=delete_shipmentWymaga klucza

Usuwa przesyłkę.

Treść żądania (JSON)

Pole	Typ	Opis
`shipment_id`wymagany	uuid	Identyfikator przesyłki (wymagany dla update_shipment i delete_shipment).

Przykładowe wywołanie

curl -X POST "https://staging.venzi.zakito.eu/api/v1?method=delete_shipment" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{ "shipment_id": "…" }'

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Wynik operacji: SUCCESS przy powodzeniu, ERROR przy błędzie.
`deleted`	boolean	true, gdy rekord został usunięty.

Przykładowa odpowiedź

{ "status": "SUCCESS", "deleted": true }