Zamówienie przez API w Fakturownia

Zamówienie przez API w Fakturownia tworzysz, ustawiając w żądaniu parametr kind: estimate. Ten artykuł jest przeznaczony dla użytkowników oraz integratorów łączących zewnętrzne systemy z Fakturownia. Znajdziesz tu gotowe przykłady żądań, opis dostępnych statusów oraz sposób konwersji zamówienia na fakturę.

Jak utworzyć zamówienie przez API?

Wyślij żądanie POST na endpoint /invoices.json z parametrem "kind": "estimate". Oprócz kind wymagane jest podanie przynajmniej jednej pozycji dokumentu - bez niej API zwróci błąd 422. Pozostałe dane (sprzedawca, adres nabywcy, sposób płatności) działają tak samo jak przy tworzeniu zwykłej faktury - szczegółowy opis wszystkich pól znajdziesz w dokumentacji API na GitHub.

UWAGA! Wartość kind jest wrażliwa na wielkość liter. Wpisanie Estimate lub ESTIMATE nie spowoduje błędu - żądanie zostanie przyjęte bez ostrzeżenia - ale system nie rozpozna takiej wartości jako zamówienia. Dokument zostanie zapisany, lecz nie otrzyma poprawnej numeracji i nie pojawi się tam, gdzie użytkownik by się go spodziewał.

UWAGA! Jeśli pominiesz pole kind lub zostawisz je puste, system automatycznie utworzy zwykłą fakturę VAT - to wartość domyślna.

Przykład żądania tworzącego zamówienie:

curl https://twojadomena.fakturownia.pl/invoices.json \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_token": "API_TOKEN",
    "invoice": {
      "kind": "estimate",
      "buyer_name": "Klient Sp. z o.o.",
      "buyer_tax_no": "5252445767",
      "positions": [
        {"name": "Usługa", "tax": 23, "total_price_gross": 123.00, "quantity": 1}
      ]
    }
  }'

WSKAZÓWKA! Jeśli dane sprzedawcy nie zostaną podane, system uzupełni je wartościami domyślnymi z danych firmy. W praktyce warto podać przynajmniej dane nabywcy, żeby dokument miał sens biznesowy.

Jak nie pomylić podobnych typów dokumentów?

W Fakturownia dostępnych jest kilka podobnie brzmiących typów dokumentów nieksięgowych. Różnią się przeznaczeniem i wartością parametru kind:

Co chcesz wystawić	Wartość kind
Zamówienie	estimate
Własny dokument nieksięgowy	client_order
Oferta cenowa (z terminem ważności)	price_offer

UWAGA! kind: client_order to osobny typ dokumentu - nie używaj go do zamówień. Jeśli potrzebujesz dokumentu z terminem ważności oferty, użyj price_offer zamiast estimate - zamówienie takiego pola nie posiada.

UWAGA! Typ dokumentu Zamówienie musi być włączony w ustawieniach konta, żeby zamówienia były widoczne w interfejsie aplikacji. Przez API możesz jednak zapisać zamówienie nawet bez włączonego modułu - dokument zostanie przyjęty, ale może nie pojawić się w oczekiwanym miejscu, dopóki nie włączysz odpowiedniej opcji w ustawieniach.

Jak zmienić status zamówienia?

Do zmiany statusu służy dedykowany endpoint: POST /invoices/{id}/change_status.json, z parametrem status przekazanym w adresie żądania. Wartość {id} to identyfikator dokumentu zwrócony przez API przy jego tworzeniu (pole id w odpowiedzi).

curl -X POST "https://twojadomena.fakturownia.pl/invoices/{id}/change_status.json?api_token=API_TOKEN&status=paid"

Dostępne wartości pola status:

issued – wystawione,
sent – wysłane,
paid – opłacone,
partial – częściowo opłacone,
rejected – odrzucone,
completed – zrealizowane (tylko konta z ustawieniami polskimi).

UWAGA! Status można zmienić również przez zwykłą aktualizację dokumentu (PUT/PATCH /invoices/{id}.json z polem status w treści żądania). Jeśli jednak na koncie włączona jest opcja Blokada zmiany statusu faktury (Ustawienia konta), żadna z tych metod nie zmieni statusu. Żądanie może zwrócić sukces, ale wartość pola status pozostanie bez zmian. Jeśli status nie zmienia się mimo poprawnego żądania, w pierwszej kolejności sprawdź ustawienie tej opcji.

Jak wystawić fakturę na podstawie zamówienia?

Zamówienie możesz przekształcić w fakturę VAT, fakturę zaliczkową lub fakturę końcową. W każdym przypadku używasz parametru copy_invoice_from, podając identyfikator zamówienia (wartość pola id zwróconego przy tworzeniu zamówienia).

Zwykła faktura VAT na podstawie zamówienia

{
  "api_token": "API_TOKEN",
  "invoice": {
    "kind": "vat",
    "copy_invoice_from": ID_ZAMOWIENIA
  }
}

Faktura zaliczkowa na podstawie zamówienia

Poniższy przykład tworzy fakturę zaliczkową na 10% wartości zamówienia.

UWAGA! Faktura zaliczkowa musi być powiązana dokładnie z jednym zamówieniem.

{
  "api_token": "API_TOKEN",
  "invoice": {
    "kind": "advance",
    "copy_invoice_from": ID_ZAMOWIENIA,
    "advance_creation_mode": "percent",
    "advance_value": "10"
  }
}

Faktura końcowa rozliczająca zaliczki

{
  "api_token": "API_TOKEN",
  "invoice": {
    "kind": "final",
    "copy_invoice_from": ID_ZAMOWIENIA,
    "invoice_ids": [ID_ZALICZKI_1, ID_ZALICZKI_2]
  }
}

Pole invoice_ids przyjmuje tablicę liczb całkowitych - podaj identyfikatory dokumentów zaliczkowych, np. [123, 456]. Wartości znajdziesz w polu id odpowiedzi zwróconej przy tworzeniu każdej faktury zaliczkowej.

Numeracja i uprawnienia - co warto wiedzieć

Numeracja zamówień

Zamówienia mają własną numerację, niezależną od numeracji faktur. Domyślny format możesz zmienić w zakładce Ustawienia > Ustawienia konta > Numerowanie > pole Domyślny format numerowania Zamówień lub w ustawieniach numeracji działu zgodnie z instrukcją osobne ustawienia numeracji dokumentów. Ustawienia działu są nadrzędne względem ustawień ogólnych konta.

Uprawnienia do dokumentów nieksięgowych

Jeśli wywołujesz API w imieniu pracownika z ograniczonymi uprawnieniami, upewnij się, że ma on włączony dostęp do dokumentów nieksięgowych.

Podsumowanie

Żeby przez API Fakturownia wystawić zamówienie, wyślij żądanie POST z kind: estimate i przynajmniej jedną pozycją dokumentu. Pamiętaj o małych literach w wartości kind - literówka nie zwróci błędu, ale zapisze dokument w niespójnym stanie. Konwersję na fakturę VAT, zaliczkową lub końcową obsługuje parametr copy_invoice_from.

Źródła