Fakturnia Developers Szybki start Dokumentacja API English

Słowniki

Wszystkie wartości enumów potrzebne przy tworzeniu dokumentów zwraca jeden endpoint:

curl -s https://prod.api.fakturnia.pl/external/v1/dictionaries \
  -H "Authorization: Bearer $TOKEN"

To źródło prawdy dla integracji. Endpoint wymaga jedynie ważnego tokenu OAuth (bez dodatkowego scope), a dane są statyczne i niewrażliwe. Zamiast wpisywać poniższe wartości na sztywno, pobierz je raz przy starcie integracji — dzięki temu nowa pozycja w słowniku nie zepsuje Twojego kodu.

Poniżej pełna zawartość każdego słownika. Listy używasz przy tworzeniu dokumentów.

Typy dokumentów (documentTypes)

To wszystkie typy obsługiwane przez External API. Nie ma tu osobnych typów na mechanizm podzielonej płatności, procedurę marży, odwrotne obciążenie czy fakturę zwolnioną z VAT, jakie spotyka się w innych systemach. Fakturnia jest w pełni zgodna z KSeF i te cechy dokumentu ustawia się przez adnotacje. To obecny standard: mniej typów dokumentów i prostsza integracja. Kolumna „Wysyłka do KSeF" mówi, czy dany typ można wysłać do KSeF.

Wartość Wysyłka do KSeF
Faktura nie (dokument poza KSeF, dla zwolnionych z VAT)
FakturaVAT tak
FakturaKorygujaca tak
FakturaKorygujacaZaliczkowa tak
FakturaKorygujacaRozliczeniowa tak
FakturaZaliczka tak
FakturaRozliczeniowa tak
FakturaProforma nie (dokument informacyjny)
FakturaProformaBezVAT nie (dokument informacyjny)
Zamowienie nie (zamówienie, nie faktura)

Stawki VAT (vatRates)

value to wartość przesyłana w vatRate. Kody specjalne (string) oznaczają netto = brutto, VAT = 0.

value Etykieta Opis
np I np. I Nie podlega - z wyłączeniem art. 100 ust. 1 pkt 4 ustawy
np II np. II Nie podlega - na podstawie art. 100 ust. 1 pkt 4 ustawy
zw zw. Zwolnione od podatku
oo o.o. Odwrotne obciążenie
0 KR 0% - KR 0% w przypadku sprzedaży towarów i usług na terytorium kraju
0 WDT 0% - WDT 0% w przypadku wewnątrzwspólnotowej dostawy towarów (WDT)
0 EX 0% - EX 0% w przypadku eksportu towarów
marza marża Procedura marży (art. 119 i 120): na fakturze tylko kwoty brutto, w KSeF suma w P_13_11. Wymaga annotations.marginProcedure. Nie ma jej na liście vatRates.
3 3%
4 4%
5 5%
7 7%
8 8%
22 22%
23 23%

Metody płatności (paymentMethods)

Wartość paymentMethodId przesyłasz w dokumencie.

paymentMethodId Nazwa
1 Gotówka
2 Karta
3 Bon
4 Czek
5 Kredyt
6 Przelew
7 Płatność mobilna

Statusy płatności (paymentStatuses)

id Nazwa
0 Zapłacono
1 Do zapłaty

Waluty (currencies)

availableExchangeRate mówi, czy dla danej waluty można podać exchangeRate.

id Nazwa availableExchangeRate
PLN Złoty polski nie
EUR Euro tak
USD Dolar amerykański tak
GBP Funt brytyjski tak
CHF Frank szwajcarski tak
DKK Korona duńska tak
NOK Korona norweska tak
SEK Korona szwedzka tak
CZK Korona czeska tak
HUF Forint tak
Pokaż wszystkie (18)
id Nazwa availableExchangeRate
RUR Rubel nie
LTL Lit litewski nie
UAH Hrywna tak
BGN Lewa tak
ROL Lej rumuński nie
JPY Jen tak
TRL Lira turecka nie
HRK Kuna nie

Kody krajów (countries)

Kod ISO 3166-1 alpha-2 przesyłasz w countryCode (kontrahent).

code Nazwa
PL Polska
AT Austria
BE Belgia
BG Bułgaria
HR Chorwacja
CY Cypr
CZ Czechy
DK Dania
EE Estonia
FI Finlandia
Pokaż wszystkie (68)
code Nazwa
FR Francja
GR Grecja
ES Hiszpania
NL Holandia
IE Irlandia
LT Litwa
LU Luksemburg
LV Łotwa
MT Malta
DE Niemcy
PT Portugalia
RO Rumunia
SK Słowacja
SI Słowenia
SE Szwecja
HU Węgry
IT Włochy
GB Wielka Brytania
US Stany Zjednoczone
CA Kanada
CH Szwajcaria
NO Norwegia
UA Ukraina
RU Rosja
CN Chiny
JP Japonia
KR Korea Południowa
IN Indie
BR Brazylia
MX Meksyk
AU Australia
NZ Nowa Zelandia
ZA Republika Południowej Afryki
TR Turcja
IL Izrael
AE Zjednoczone Emiraty Arabskie
SA Arabia Saudyjska
SG Singapur
TH Tajlandia
VN Wietnam
ID Indonezja
MY Malezja
PH Filipiny
AR Argentyna
CL Chile
CO Kolumbia
EG Egipt
IS Islandia
RS Serbia
BA Bośnia i Hercegowina
ME Czarnogóra
MK Macedonia Północna
AL Albania
BY Białoruś
MD Mołdawia
GE Gruzja
AM Armenia
AZ Azerbejdżan

Kody GTU (gtu)

Opcjonalny gtu w pozycji dokumentu.

id Opis
GTU_01 Dostawa napojów alkoholowych
GTU_02 Dostawa paliw silnikowych
GTU_03 Dostawa oleju opałowego, olejów smarownych oraz smarów plastycznych itp.
GTU_04 Dostawa wyrobów tytoniowych oraz wyborów nowatorskich
GTU_05 Dostawa odpadów
GTU_06 Dostawa urządzeń elektronicznych oraz części i materiałów do nich
GTU_07 Dostawa pojazdów oraz części samochodowych
GTU_08 Dostawa metali szlachetnych oraz nieszlachetnych
GTU_09 Dostawa leków oraz wyrobów medycznych
GTU_10 Dostawa budynków, budowli i gruntów
GTU_11 Świadczenie usług w zakresie przenoszenia uprawnień do emisji gazów cieplarnianych
GTU_12 Świadczenie usług doradczych, księgowych, prawnych, zarządczych, szkoleniowych, marketingowych, reklamowych, badania rynku i prac rozwojowych
GTU_13 Świadczenie usług transportowych i gospodarki magazynowej

Procedury marży (marginProcedures)

id przesyłasz w annotations.marginProcedure.procedureId.

id Opis
1 Procedura marży dla biur podróży
2 Procedura marży - towary używane
3 Procedura marży - dzieła sztuki
4 Procedura marży - przedmioty kolekcjonerskie i antyki

Typy zwolnienia z VAT (vatExemptionTypes)

type przesyłasz w annotations.vatExemption.exemptionType, a podstawę prawną w legalBasis (wzór w kolumnie „Przykład").

type Opis Przykład (legalBasis)
A Przepis ustawy albo aktu wydanego na podstawie ustawy, na podstawie którego podatnik stosuje zwolnienie np. art. 43 ust. 1 pkt 19 ustawy o VAT
B Przepis dyrektywy 2006/112/WE, który zwalnia od podatku taką dostawę lub usługę np. art. 132 ust. 1 lit. c dyrektywy 2006/112/WE
C Inna podstawa prawna wskazująca na zwolnienie dostawy lub usługi np. zwolnienie wynikające z umowy międzynarodowej

Nagłówki dat płatności (paymentDateHeaders)

id przesyłasz w additionalPaymentDateHeaderId.

id Nazwa
0 Data płatności
1 Data dokonania płatności
2 Data otrzymania zapłaty
3 Końcowa data płatności

Nagłówki dat dodatkowych (additionalDateHeaders)

id przesyłasz w subDateHeaderId (nagłówek nad datą sprzedaży).

id Nazwa
0 Data sprzedaży
1 Data wykonania usługi
2 Data dokonania dostawy towarów
3 Data zakończenia dostawy towarów
4 Data zakończenia świadczenia usług
5 Data otrzymania zaliczki
6 Data otrzymania zapłaty
7 Termin realizacji zamówienia
8 Data otrzymania towaru
9 Data wydania towaru
10 Data zaliczki
11 Termin ważności oferty