inFakt Styleguide

Informujemy, że ze względu na udostępnienie nowej wersji API (wersja 3), dokumentacja oraz funkcjonalności APIv2 nie będą dłużej rozwijane przez zespół inFakt i zostaną wyłączone do końca maja 2015. Zapraszamy do zapoznania się z nową wersją API oraz dokumentacją na stronie: https://www.infakt.pl/developers

Invoices

Invoices

Pola dla zasobu invoice:

Zasób invoice

     1 invoice_id
     2 numer
     3 waluta
     4 zaplacono
     5 uwagi
     6 rodzaj_faktury
     7 sposob_platnosci
     8 podpis_odbiorcy
     9 podpis_sprzedawcy
    10 data_wystawienia
    11 data_sprzedazy
    12 termin_zaplaty
    13 status
    14 client_id
    15 razem_netto
    16 razem_vat
    17 razem_brutto
    18 client_nazwa_firmy
    19 client_ulica
    20 client_miejscowosc
    21 client_kod_pocztowy
    22 client_nip
    23 client_panstwo
    24 services

Pole rodzaj_faktury przy dodawaniu przyjmuje wartości:

  • „Faktura VAT”
  • „Faktura proforma”

Natomiast przy pobieraniu może przyjąć wartości:

  • „Faktura VAT”,
  • „Faktura proforma”,
  • „Faktura Marża”,
  • „Faktura Zaliczkowa”,
  • „Faktura korygująca”,
  • „Faktura Końcowa”

Pole sposob_platnosci może przyjąć następujące wartości:

  • „Przelew”
  • „Gotówka”
  • „Karta płatnicza”
  • „Barter”
  • „Czek”
  • „Weksel”
  • „Za pobraniem”
  • „Inny”
  • „Kompensata”
  • „Akredytywa”

Pole status może przyjąć następujące wartości:

  • „niezapłacona”
  • „szkic”
  • „wysłana”
  • „wydrukowana”
  • „zapłacona”

Pole services zawiera zagnieżdzone obiekty service. Są one przekazywane dla każdej faktury:

Zasób service

     1 service_id
     2 product_id
     3 nazwa
     4 stawka_vat
     5 jm
     6 ilosc
     7 cena_netto
     8 wartosc_netto
     9 wartosc_brutto
    10 vat
    11 symbol

Pole jm określa jednostkę miary.

Pole symbol określa symbol PKWiU.

Pole stawka_vat może przyjąć następujące wartości:

  • „23”
  • „22”
  • „8”
  • „7”
  • „5”
  • „3”
  • „0”
  • „zw”
  • „np”

List

Pobieranie listy faktur przypisanych do konta.

URL

Lista faktury przypisanych do konta

    1 (GET) https://www.infakt.pl/api/v2/invoices/list.:format

Wymagane parametry

brak

Opcjonalne parametry

Parametry opcjonalne

    1 page      - numer pobieranej strony wyników
    2 per_page  - ilość wyników na stronie
    3 order     - sortowanie wyników po danym polu

Pole order przyjmuje wartość skonstruowaną z nazwy pola oraz kolejności sortowania.

pole_kolejność, gdzie pole może przyjąć jedną z wartości:

  • data_wystawienia
  • data_sprzedazy
  • termin_zaplaty

kolejność przyjmuje wartości „asc” lub „desc”.

Przykładowa wartość parametru order: data_wystawienia_desc

Przykład

XML

Zapytanie:

Przykład pobierania listy faktur (XML)

    1 (GET) https://www.infakt.pl/api/v2/invoices.xml

Odpowiedź:

Kod HTTP: 200

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <invoices per_page="100" total="1" pages="1" page="1">
     3         <invoice>
     4                 <client_kod_pocztowy>31-272</client_kod_pocztowy>
     5                 <status>szkic</status>
     6                 <rodzaj_faktury>Faktura VAT</rodzaj_faktury>
     7                 <client_miejscowosc>Krak&#243;w</client_miejscowosc>
     8                 <podpis_sprzedawcy> </podpis_sprzedawcy>
     9                 <client_panstwo>Polska</client_panstwo>
    10                 <zaplacono>122.0</zaplacono>
    11                 <client_nip>5215922894</client_nip>
    12                 <razem_brutto>122.0</razem_brutto>
    13                 <data_sprzedazy>2010-12-15</data_sprzedazy>
    14                 <numer>1/12/2010</numer>
    15                 <razem_vat>22.0</razem_vat>
    16                 <termin_zaplaty>2011-06-05</termin_zaplaty>
    17                 <data_wystawienia>2010-12-15</data_wystawienia>
    18                 <uwagi></uwagi>
    19                 <client_nazwa_firmy>Klient A</client_nazwa_firmy>
    20                 <podpis_odbiorcy></podpis_odbiorcy>
    21                 <razem_netto>100.0</razem_netto>
    22                 <waluta>PLN</waluta>
    23                 <client_ulica>Krakowska</client_ulica>
    24                 <invoice_id>1012046</invoice_id>
    25                 <client_id>310947</client_id>
    26                 <sposob_platnosci>Got&#243;wka</sposob_platnosci>
    27     <podstawa_zwolnienia></podstawa_zwolnienia>
    28                 <services>
    29                         <service>
    30                                 <symbol></symbol>
    31                                 <cena_netto>100.0</cena_netto>
    32                                 <jm></jm>
    33                                 <vat>22.0</vat>
    34                                 <ilosc>1.0</ilosc>
    35                                 <product_id></product_id>
    36                                 <marza></marza>
    37                                 <wartosc_brutto>122.0</wartosc_brutto>
    38                                 <stawka_vat>22</stawka_vat>
    39                                 <service_id>1</service_id>
    40                                 <wartosc_netto>100.0</wartosc_netto>
    41                                 <nazwa>Produkt A</nazwa>
    42                         </service>
    43                 </services>
    44         </invoice>
    45         <invoice>
    46           ...
    47         </invoice>
    48 </invoices>

JSON

Zapytanie:

Przykład pobierania listy faktur (JSON)

    1 (GET) https://www.infakt.pl/api/v2/invoices.json

Odpowiedź:

Kod HTTP: 200

     1 {
     2     "info":{
     3         "per_page":100,"total":3,"pages":1,"page":1
     4     },
     5     "invoices":[
     6         {
     7             "client_panstwo":"Polska",
     8             "rodzaj_faktury":"Faktura VAT",
     9             "status":"zap\u0142acona",
    10             "client_kod_pocztowy":"31-272",
    11             "client_miejscowosc":"Krak\u00f3w",
    12             "invoice_id":1,
    13             "podpis_odbiorcy":"",
    14             "zaplacono":122.0,
    15             "razem_brutto":122.0,
    16             "client_nip":"5215922894",
    17             "numer":"1/12/2010",
    18             "data_sprzedazy":"2010-12-15",
    19             "podpis_sprzedawcy":" ",
    20             "services":[
    21                 {
    22                     "service_id":1,
    23                     "cena_netto":100.0,
    24                     "symbol":"",
    25                     "stawka_vat":"",
    26                     "jm":"",
    27                     "vat":22.0,
    28                     "product_id":null,
    29                     "ilosc":"1.0",
    30                     "wartosc_brutto":122.0,
    31                     "marza":null,
    32                     "nazwa":"Produkt A",
    33                     "wartosc_netto":100.0
    34                 }
    35             ],
    36             "uwagi":"",
    37             "data_wystawienia":"2010-12-15",
    38             "termin_zaplaty":"2010-12-22",
    39             "razem_vat":22.0,
    40             "client_nazwa_firmy":"Klient A",
    41             "waluta":"PLN",
    42             "razem_netto":100.0,
    43             "client_ulica":"Krakowska",
    44             "sposob_platnosci":"Got\u00f3wka",
    45             "podstawa_zwolnienia":"",
    46             "client_id":1
    47         },
    48         { ... }
    49     ]
    50 }

Show

Wyświetlanie rekordu danej faktury.

URL

Pobieranie rekordu faktury

    1 (GET) https://www.infakt.pl/api/v2/invoices/show.:format

lub

Pobieranie rekordu faktury (z parametrem :id)

    1 (GET) https://www.infakt.pl/api/v2/invoices/show/:id.:format

Wymagane parametry

id lub invoice_id jesli ID nie został przekazany w URL.

Opcjonalne parametry

brak

Przykład

XML

Zapytanie:

Przykład pobierania rekordu faktury (XML)

    1 (GET) @https://www.infakt.pl/api/v2/invoices/show/1.xml

Odpowiedź:

Kod HTTP: 200

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <invoice>
     3     <client_kod_pocztowy>31-272</client_kod_pocztowy>
     4     <status>szkic</status>
     5     <rodzaj_faktury>Faktura VAT</rodzaj_faktury>
     6     <client_miejscowosc>Krak&#243;w</client_miejscowosc>
     7     <podpis_sprzedawcy> </podpis_sprzedawcy>
     8     <client_panstwo>Polska</client_panstwo>
     9     <zaplacono>122.0</zaplacono>
    10     <client_nip>5215922894</client_nip>
    11     <razem_brutto>122.0</razem_brutto>
    12     <data_sprzedazy>2010-12-15</data_sprzedazy>
    13     <numer>1/12/2010</numer>
    14     <razem_vat>22.0</razem_vat>
    15     <termin_zaplaty>2011-06-05</termin_zaplaty>
    16     <data_wystawienia>2010-12-15</data_wystawienia>
    17     <uwagi></uwagi>
    18     <client_nazwa_firmy>Klient A</client_nazwa_firmy>
    19     <podpis_odbiorcy></podpis_odbiorcy>
    20     <razem_netto>100.0</razem_netto>
    21     <waluta>PLN</waluta>
    22     <client_ulica>Krakowska</client_ulica>
    23     <invoice_id>1012046</invoice_id>
    24     <client_id>310947</client_id>
    25     <sposob_platnosci>Got&#243;wka</sposob_platnosci>
    26     <podstawa_zwolnienia></podstawa_zwolnienia>
    27     <services>
    28         <service>
    29             <symbol></symbol>
    30             <cena_netto>100.0</cena_netto>
    31             <jm></jm>
    32             <vat>22.0</vat>
    33             <ilosc>1.0</ilosc>
    34             <product_id></product_id>
    35             <marza></marza>
    36             <wartosc_brutto>122.0</wartosc_brutto>
    37             <stawka_vat>22</stawka_vat>
    38             <service_id>1</service_id>
    39             <wartosc_netto>100.0</wartosc_netto>
    40             <nazwa>Produkt A</nazwa>
    41         </service>
    42     </services>
    43 </invoice>

Odpowiedź z błędem:

Kod HTTP: 404

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <hash>
    3   <message>No record found with that ID.</message>
    4   <request>https://www.infakt.pl/api/v2/invoices/show.xml?id=3</request>
    5 </hash>

JSON

Zapytanie:

Przykład pobierania rekordu faktury (JSON)

    1 (GET) https://www.infakt.pl/api/v2/invoices/show.json?invoice_id=1

Odpowiedź:

Kod HTTP: 200

     1 {
     2     "invoice":{
     3         "client_panstwo":"Polska",
     4         "rodzaj_faktury":"Faktura VAT",
     5         "status":"zap\u0142acona",
     6         "client_kod_pocztowy":"31-272",
     7         "client_miejscowosc":"Krak\u00f3w",
     8         "invoice_id":1012046,
     9         "podpis_odbiorcy":"",
    10         "zaplacono":122.0,
    11         "razem_brutto":122.0,
    12         "client_nip":"5215922894",
    13         "numer":"1/12/2010",
    14         "data_sprzedazy":"2010-12-15",
    15         "podpis_sprzedawcy":" ",
    16         "services":[
    17             {
    18                 "service_id":2,
    19                 "cena_netto":100.0,
    20                 "symbol":"",
    21                 "stawka_vat":"",
    22                 "jm":"",
    23                 "vat":22.0,
    24                 "product_id":1,
    25                 "ilosc":"1.0",
    26                 "wartosc_brutto":122.0,
    27                 "nazwa":"Produkt A",
    28                 "wartosc_netto":100.0
    29             }
    30         ],
    31         "uwagi":"",
    32         "data_wystawienia":"2010-12-15",
    33         "termin_zaplaty":"2011-06-05",
    34         "razem_vat":22.0,
    35         "client_nazwa_firmy":"Klient A",
    36         "waluta":"PLN",
    37         "razem_netto":100.0,
    38         "client_ulica":"Krakowska",
    39         "sposob_platnosci":"Got\u00f3wka",
    40         "podstawa_zwolnienia":"",
    41         "client_id":4
    42     }
    43 }

Odpowiedź z błędem:

Kod HTTP: 404

    1 {
    2     "message":"No record found with that ID.",
    3     "request":"https://www.infakt.pl/api/v2/invoices/show.json?id=5"
    4 }

Create

Tworzenie faktury.

Jeśli operacja została wykonana poprawnie zwrócony zostanie ID nowego rekordu. W przeciwnym wypadku odpowiedź będzie miała określony kod błędu oraz dołączony zostanie komunikat z opisem błędów. Obecnie możliwe jest dodawanie wyłacznie faktury VAT oraz faktury proforma.

URL

Tworzenie rekordu faktury

    1 (POST) https://www.infakt.pl/api/v2/invoices/create.:format

Wymagane parametry

W przypadku XML nalezy w treści żądania przekazać dokument XML, dla JSON string w tym formacie.

Wymagane pola dla invoice

Wymagane parametry (rekord invoice)

    1 client_id
    2 status
    3 rodzaj_faktury
    4 sposob_platnosci
    5 podstawa_zwolnienia (jeżeli faktura posiada stawkę zw.)

Wartość dla pola client_id musi byc równa ID klienta pobranego z listy klientów.

Wartość dla pola podstawa_zwolenienia musi byc równa ID podstawy pobranej z listy zwolnień.

Wartości dla pola rodzaj_faktury:

  • „Faktura VAT”
  • „Faktura Proforma”

Wymagane pola dla service

Wymagane parametry (rekord service)

    1 nazwa
    2 ilosc
    3 stawka_vat

Możliwe jest zagnieżdżenie kilku obiektów services.

Wartości na fakturze wyliczane sa na podstawie wartości zdefiniowanych w services.

Dla serwices wartości generowane są wg. następującej kolejności:

  • od ceny jednostkowej netto
  • od wartości netto
  • od wartości brutto

Opcjonalne parametry

Pozostałe parametry invoice i service. Możliwe jest również wystawienie faktury ze zduplikowanym numerem. W tym celu należy przekazać parametr unikalny_numer ustawiony na false.

Przykład

XML

Zapytanie:

Przykład tworzenia rekordu faktury (XML)

    1 (POST) https://www.infakt.pl/api/v2/invoices/create.xml

Zapytanie XML

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <invoice>
     3     <rodzaj_faktury>Faktura VAT</rodzaj_faktury>
     4     <status>szkic</status>
     5     <sposob_platnosci>Got%C3%B3wka</sposob_platnosci>
     6     <client_id>4</client_id>
     7     <services>
     8         <service>
     9             <ilosc>1</ilosc>
    10             <cena_netto>100</cena_netto>
    11             <stawka_vat>3</stawka_vat>
    12             <nazwa>Produkt 1</nazwa>
    13         </service>
    14         <service>
    15             <jm>szt.</jm>
    16             <ilosc>1</ilosc>
    17             <wartosc_brutto>122.0</wartosc_brutto>
    18             <stawka_vat>22</stawka_vat>
    19             <nazwa>Produkt B</nazwa>
    20         </service>
    21     </services>
    22 </invoice>

Odpowiedź:

Kod HTTP: 200

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <invoice>
    3     <invoice_id>6</invoice_id>
    4     <numer>1/01/2010</numer>
    5 </invoice>

Zapytanie z błędami:

Błędne zapytanie (XML)

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <invoice>
     3     <rodzaj_faktury>Faktura VAT</rodzaj_faktury>
     4     <status>szkic</status>
     5     <sposob_platnosci>Got%C3%B3wka</sposob_platnosci>
     6     <client_id>4</client_id>
     7     <services>
     8         <service>
     9             <ilosc>1</ilosc>
    10             <cena_netto>100</cena_netto>
    11             <stawka_vat>3</stawka_vat>
    12             <nazwa>Produkt 1</nazwa>
    13         </service>
    14         <service>
    15             <jm>szt.</jm>
    16             <ilosc>1</ilosc>
    17             <wartosc_brutto>122.0</wartosc_brutto>
    18             <stawka_vat>22</stawka_vat>
    19         </service>
    20     </services>
    21 </invoice>

Odpowiedź z błędem:

Kod HTTP: 409

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <hash>
     3     <message>Some fields were given invalid or no values</message>
     4     <request>/api/v2/invoices/create.xml</request>
     5     <errors>
     6         <invoice type="array">
     7             <invoice>
     8                 <message>blank</message>
     9                 <field>status</field>
    10             </invoice>
    11             <invoice>
    12                 <message>blank</message>
    13                 <field>sposob_platnosci</field>
    14             </invoice>
    15         </invoice>
    16         <services type="array">
    17             <service type="array">
    18                 <service>
    19                     <message>blank</message>
    20                     <field>stawka_vat</field>
    21                 </service>
    22             </service>
    23         </services>
    24     </errors>
    25 </hash>

Odpowiedź z błedem w przypadku osiągnięcia limitu wystawionych faktur:

Kod HTTP: 402

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <hash>
    3     <message>Request unable to process.
    4     Consider extanding your payment plan.</message>
    5     <request>/api/v2/invoices/create.xml</request>
    6 </hash>

JSON

Zapytanie:

Przykład tworzenia rekordu faktury (JSON)

    1 (POST) https://www.infakt.pl/api/v2/invoices/create.json

Zapytanie JSON

     1 {
     2     "invoice":{
     3         "status":"szkic",
     4         "rodzaj_faktury":"Faktura VAT",
     5         "sposob_platnosci":"Got%C3%B3wka",
     6         "client_id":4,
     7         "services":[
     8             {
     9                 "nazwa":"Produkt A",
    10                 "ilosc":1,
    11                 "stawka_vat":22,
    12                 "wartosc_netto":100
    13             },
    14             {
    15                 "nazwa":"Produkt B",
    16                 "ilosc":2,
    17                 "stawka_vat":3,
    18                 "cena_netto":50
    19             }
    20         ]
    21     }
    22 }

Odpowiedź:

Kod HTTP: 200

    1 {
    2     "invoice":{
    3         "invoice_id":1,
    4         "numer":"1/01/2010"
    5     }
    6 }

Zapytanie z błędami:

Błędne zapytanei (JSON)

     1 {
     2     "invoice":{
     3         "status":"szkic",
     4         "rodzaj_faktury":"Faktura VAT",
     5         "client_id":4,
     6         "services":[
     7             {
     8                 "ilosc":1,
     9                 "stawka_vat":22,
    10                 "wartosc_netto":100,
    11                 "nazwa":"Produkt A"
    12             },
    13             {
    14                 "ilosc":2,
    15                 "cena_netto":50,
    16                 "nazwa":"Produkt B"
    17             }
    18         ]
    19     }
    20 }

Odpowiedź z błędem:

Kod HTTP: 409

     1 {
     2     "message":"Some fields were given invalid or no values",
     3     "request":"/api/v2/invoices/create.json",
     4     "errors":{
     5         "invoice":[
     6             ["sposob_platnosci","blank"]
     7         ],
     8         "services":[
     9             [],
    10             [
    11                 ["stawka_vat","blank"]
    12             ]
    13         ]
    14     }
    15 }

Odpowiedź z błedem w przypadku osiągnięcia limitu wystawionych faktur:

Kod HTTP: 402

    1 {
    2     "message":"Request unable to process. 
    3                 Consider extanding your payment plan.",
    4     "request":"/api/v2/invoices/create.json"
    5 }

Update

Aktualizacja faktury.

Jeśli operacja została wykonana poprawnie zwrócony zostanie ID aktualizowanego rekordu. W przeciwnym wypadku odpowiedź będzie miała określony kod błędu oraz dołączony zostanie komunikat z opisem błędów.

URL

Aktualizacja rekordu faktury

    1 (POST) https://www.infakt.pl/api/v2/invoices/update/:id.:format

Wymagane parametry

W fakturze uaktualniane są tylko te pola, które zostaną przekazane. W przypadku aktualizacji listy produktów usuwane są wszystkie istniejące produkty i tworzone nowe wg. danych przekazanych w zapytaniu. Format zapytania XML jak i JSON jest identyczny jak w przypadku dodawania faktury.

Przykład

XML

Zapytanie:

Przykład aktualizacji rekordu faktury (XML)

    1 (POST) https://www.infakt.pl/api/v2/invoices/update/1.xml

Zapytanie XML

     1 <?xml version="1.0" encoding="UTF-8"?>
     2 <invoice>
     3     <status>szkic</status>
     4     <uwagi>Brak uwag</uwagi>
     5     <services>
     6         <service>
     7             <ilosc>1</ilosc>
     8             <cena_netto>100</cena_netto>
     9             <stawka_vat>3</stawka_vat>
    10             <nazwa>Produkt 3</nazwa>
    11         </service>
    12     </services>
    13 </invoice>

W powyższym przypadku zaktualizowany zostanie status faktury, treść uwag oraz wszystkie istniejące pozycje zostaną zastąpione pozycją Produkt 3.

Odpowiedź:

Kod HTTP: 200

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <invoice>
    3     <invoice_id>1</invoice_id>
    4     <numer>1/01/2010</numer>
    5 </invoice>

Delete

Usuwanie faktury o danym ID.

Jeśli zapytanie zostało wykonane poprawnie zwrócony zostanie ID usuniętego rekordu.

URL

Usuwanie rekordu faktury

    1 (POST) https://www.infakt.pl/api/v2/invoices/delete.:format
lub

Usuwanie rekordu faktury (z parametrem :id)

    1 (POST) https://www.infakt.pl/api/v2/invoices/delete/:id.:format

Wymagane parametry

id lub client_id jesli ID nie został przekazany w URL.

Opcjonalne parametry

brak

Przykład

XML

Zapytanie:

Przykład usuwania rekordu faktury (XML)

    1 (GET) https://www.infakt.pl/api/v2/invoices/delete/1.xml

Odpowiedź:

Kod HTTP: 200

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <invoice>
    3     <invoice_id>1</invoice_id>
    4 </invoice>

JSON

Zapytanie:

Przykład usuwania rekordu faktury (JSON))

    1 (GET) https://www.infakt.pl/api/v2/invoices/delete/1.json

Odpowiedź:

Kod HTTP: 200

    1 {
    2     "invoice":{
    3         "invoice_id":1
    4     }
    5 }

Oznaczenie danej faktury jako zapłacona.

URL

Oznaczanie faktury jako zapłacona.

    1 (GET) https://www.infakt.pl/api/v2/invoices/paid.:format

lub

Oznaczanie faktury jako zapłacona (z parametrem :id).

    1 (GET) https://www.infakt.pl/api/v2/invoices/paid/:id.:format

Wymagane parametry

id jesli ID nie został przekazany w URL.

Opcjonalne parametry

data_oplacenia

Przykład

XML

Zapytanie:

Przykład oznaczania faktury jako opłacona (XML)

    1 (GET) https://www.infakt.pl/api/v2/invoices/paid/1.xml

Odpowiedź:

Kod HTTP: 200

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <invoice>
    3     <invoice_id>1</invoice_id>
    4     <numer>1/12/2010</numer>
    5 </invoice>

JSON

Zapytanie:

Przykład oznaczania faktury jako opłacona (JSON)

    1 (GET) https://www.infakt.pl/api/v2/invoices/paid.json?id=1

Odpowiedź:

Kod HTTP: 200

    1 {
    2     "invoice":{
    3         "invoice_id":1
    4         "numer":"1/12/2010"
    5     }
    6 }