Fakturnia Developers Szybki start Dokumentacja API English

Produkty

Produkty i usługi to katalog pozycji, z których korzystasz przy wystawianiu dokumentów. API udostępnia pełny CRUD pod /products.

Wymagane zakresy uprawnień: products:browse, products:read, products:create, products:update, products:delete (osobno dla każdej operacji).

Lista produktów

curl -s "https://prod.api.fakturnia.pl/external/v1/products?searchQuery=hosting&currentPage=1&itemsPerPage=20" \
  -H "Authorization: Bearer $TOKEN"

searchQuery filtruje po nazwie. Lista jest paginowana.

Tworzenie produktu

Jedyne pole wymagane to name. Kwoty podajesz tak jak przy pozycjach dokumentu: wystarczy netPrice albo grossPrice razem z vatRate, a API dolicza brakujące wartości według tych samych reguł co przy tworzeniu dokumentów.

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hosting WWW (rok)",
    "unitOfMeasure": "szt.",
    "netPrice": 400,
    "vatRate": 23,
    "currency": "PLN",
    "gtu": "GTU_12"
  }'
Pole Znaczenie
name nazwa produktu lub usługi (wymagana)
netPrice / grossPrice cena jednostkowa netto lub brutto
vatRate stawka VAT: liczba (np. 23) lub kod specjalny ze słowników (np. zw, oo)
quantity, discount domyślna ilość i rabat procentowy
unitOfMeasure jednostka miary (np. szt., godz.)
currency waluta, domyślnie PLN
gtu kod GTU, jeśli produkt go wymaga
pkwiu symbol PKWiU

Pobieranie, aktualizacja i usuwanie

# Szczegóły
curl -s https://prod.api.fakturnia.pl/external/v1/products/{id} \
  -H "Authorization: Bearer $TOKEN"

# Aktualizacja (PUT, pełne zastąpienie pól)
curl -s -X PUT https://prod.api.fakturnia.pl/external/v1/products/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hosting WWW (rok)", "netPrice": 450, "vatRate": 23 }'

# Usunięcie
curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/products/{id} \
  -H "Authorization: Bearer $TOKEN"

Usunięcie produktu nie zmienia dokumentów, na których został wcześniej użyty: pozycje dokumentu przechowują kopię danych produktu z chwili wystawienia.

Pola magazynowe

Produkt ma pola modułu Magazyn: productType (goods = towar prowadzący stany, service = usługa; brak = usługa), sku, ean i purchasePrice (cena zakupu netto, domyślna cena przyjęć PZ/PW). Przy tworzeniu podajesz je razem z resztą danych; przy aktualizacji zapisywane są tylko wtedy, gdy są w żądaniu, więc klient, który ich nie zna, ich nie wyczyści. quantity jest opcjonalne (domyślnie 1). Dokumenty magazynowe: Magazyn.

Webhooki

Operacje zapisu emitują zdarzenia webhook: product.created, product.updated, product.deleted.