Dokumentacja

Faktury

Zarządzanie fakturami należącymi do użytkownika

Definicja

Obiekt Invoice zawiera następujące klucze:

ParametrTyp danychWymaganyOpis
idintegerTylko do odczytuID Faktury
numberstringNieNumer faktury. Domyślnie generowany na podstawie Następny numer faktury
currencystringNieWaluta: THB, USD, AUD, HKD, CAD, NZD, SGD, EUR, HUF, CHF, GBP, UAH, JPY, CZK, DKK, ISK, NOK, SEK, HRK, RON, BGN, TRY, LTL, LVL, PHP, MXN, ZAR, BRL, MYR, RUB, IDR, KRW, CNY, INR, LTL, domyślnie PLN.
paid_priceintegerNieZapłacono w groszach.
notesstringNieUwagi
kindstringNieRodzaj faktury:
  • proforma – Faktura proforma
  • vat – Faktura VAT
payment_methodstringNieMetoda płatności:
  • transfer – Przelew
  • cash – Gotówka
  • card – Karta płatnicza
  • barter – Barter
  • check – Czek
  • bill_of_sale – Weksel
  • delivery – Za pobraniem
  • compensation – Kompensata
  • accredited – Akredytywa
  • paypal – PayPal
  • payu – PayUl
  • other – Inny
recipient_signaturestringNieImię i nazwisko Odbiorcy
seller_signaturestringNieImię i nazwisko Sprzedawcy
invoice_datestringNieData wystawienia w formacie RRRR-MM-DD
sale_datestringNieData sprzedaży w formacie RRRR-MM-DD
statusstringTylko do odczytuStatus:
  • draft – Szkic
  • sent – Wysłana
  • printed – Wydrukowana
  • paid – Opłacona
payment_datestringNieTermin zapłaty w formacie RRRR-MM-DD
net_priceintegerNieRazem netto w groszach
tax_priceintegerNieWartość VAT w groszach
gross_priceintegerNieRazem brutto w groszach
client_idintegerNie, o ile podano dane klientaID klienta (jeśli istnieje)
client_company_namestringNieNazwa firmy klienta (jeśli klient nie istnieje)
client_streetstringNieUlica klienta (jeśli klient nie istnieje)
client_citystringNieMiasto klienta (jeśli klient nie istnieje)
client_post_codestringNieKod pocztowy klienta (jeśli klient nie istnieje)
client_tax_codestringNieNIP klienta (jeśli klient nie istnieje)
clean_client_nipstringTylko do wyszukiwaniaPozwala na wyszukiwanie NIPu klienta w postaci ciągu cyfr.
Np 111-111-11-11 można wyszukiwać jako 1111111111
client_countrystringNieKraj klienta (jeśli klient nie istnieje) (pole alpha_2 z listy obsługiwanych krajów)
check_duplicate_numberbooleanNieCzy sprawdzać duplikacje numeru faktury true lub false
bank_namestringNieNazwa banku, dotyczy faktur z przelewem
bank_accountstringNieNr konta bankowego, dotyczy faktur z przelewem
swiftstringNieNr Swift, dotyczy faktur z przelewem
sale_typestringDla klientów zagranicznych.Rodzaj sprzedaży:
  • service – Usługa
  • merchandise – Towar
invoice_date_kindstringNieRodzaj daty na fakturze:
  • sale_date – Data sprzedaży
  • service_date – Data wykonania usługi
  • cargo_date – Data zakończenia dostawy towarów
servicesarray of ServicesTakLista pozycji na fakturze (i link do services)
vat_exemption_reasonintegerW przypadku sprzedaży zwolnionej z VAT.ID podstawy zwolnienia z VAT
extensionshash (dictionary)Tylko do odczytuDodatkowe informacje:
  • payments – na temat szybkich płatności:
    link – Link do szybkiego opłacania faktury
    avaiable – Informacja czy dla faktury można uruchomić szybkie płatności
  • shares – na temat linku do faktury:
    link – link do faktury
    avaiable – Informacja czy wygenerowanie linku jest możliwe
    valid_until – Data wygaśnięcia linku

Services

Obiekt service zawiera następujące klucze:

ParametrTyp danychWymaganyOpis
namestringTakNazwa pozycji
tax_symbolstringNieStawka VAT (lista obsługiwanych stawek)
unitstringNieJednostka
quantityintegerNieIlość
unit_net_priceintegerNieCena netto za sztukę w groszach
net_priceintegerNieWartość netto w groszach
gross_priceintegerTylko do odczytuWartość brutto w groszach
tax_priceintegerNieWartość podatku VAT w groszach
symbolstringNiesymbol PKWiU
flat_rate_tax_symbolstringW przypadku korzystania z ryczałtu ewidencjonowanegoDostępne stawki:
  • 2
  • 3
  • 5.5
  • 8.5
  • 17
  • 20
lista obsługiwanych stawek
discountintegerNieWartość rabatu w procentach
unit_net_price_before_discountintegerNieCena zakupu netto w groszach przed rabatem

Listowanie faktur

GET /v3/invoices.json

Akcja listowania zwraca odpowiedź zawierającą tablicę obiektów pod kluczem entities oraz informacje pomocnicze dotyczące stronicowania. Domyślne sortowanie dla zwracanej tablicy odbywa się malejąco przy użyciu pola invoice_date.

Dodatkowo, na zbiorze danych można wykonywać nastepujące operacje:

Przykład akcji listowania:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  https://api.infakt.pl/v3/invoices.json

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 10,
      "total_count": 10,
      "next": "https://api.infakt.pl/api/v3/invoices.json?offset=10",
      "previous": "https://api.infakt.pl/api/v3/invoices.json?offset=0"
  },
  "entities": [{
    "id": 42,
    "number": "4/05/2014",
    "currency": "PLN",
    "paid_price": 0,
    "notes": ""
    ...
  }, {
    "id": 43,
    "number": "5/05/2014",
    "currency": "PLN",
    "paid_price": 0,
    "notes": ""
    ...
  }]
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu

Podgląd

GET /v3/invoices/{id}.json

Dodatkowo, na zbiorze danych można wykonywać nastepujące operacje:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
https://api.infakt.pl/v3/invoices/42.json
          

Przykładowa odpowiedź

{
  "id": 162,
  "number": "1/05/2014",
  "currency": "PLN",
  "paid_price": 0,
  "notes": "",
  "kind": "vat",
  "payment_method": "cash",
  "recipient_signature": "",
  "seller_signature": "Jan Kowalski",
  "invoice_date": "2014-05-19",
  "sale_date": "2014-05-17",
  "status": "draft",
  "payment_date": "2014-06-02",
  "paid_date": "",
  "net_price": 12300,
  "tax_price": 2829,
  "gross_price": 15129,
  "client_id": 84,
  "client_company_name": "inFakt Sp. z o.o.",
  "client_street": "Kącik 4",
  "client_city": "Kraków",
  "client_post_code": "30-549",
  "client_tax_code": "9452121681",
  "client_country": "PL",
  "bank_account": "",
  "bank_name": "",
  "vat_exemption_reason": "",
  "services": [
    {
      "id": 179,
      "name": "Produkt 1",
      "tax_symbol": "23",
      "unit": "",
      "quantity": "1.0",
      "unit_net_price": 12300,
      "net_price": 12300,
      "gross_price": 15129,
      "tax_price": 2829,
      "symbol": ""
    }
  ],
  "extensions": {
    "payments": {
      "link": "https://www.infakt.pl/app/gateways/bluemedia/24924df1e55f472f83683591424c315f",
      "avaiable": true
    },
    "shares": {
      "link": "https://www.infakt.pl/app/twoja-faktura/1844249c-9b2c-4f75-9103-743b3c13a62f",
      "avaiable": true,
      "valid_until": "2017-06-20"
    }
  }
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu
404Zasób nie został odnaleziony

Tworzenie

Faktura zawsze utworzy się ze statusem draft.

POST /v3/invoices.json

Tworzenie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{"invoice":{"payment_method":"transfer", "bank_account": "70102010130000010200026526", "client_company_name": "company", "services":[{"name": "Przykładowa Usługa", "gross_price":6623, "tax_symbol": 23 }]}}' \
  https://api.infakt.pl/v3/invoices.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
201Zasób został poprawnie utworzony
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem.

Aktualizacja faktury

Podczas aktualizacji, parametry są identyczne jak podczas tworzenia faktury. W przypadku aktualizacji listy produktów, usuwane są wszystkie istniejące produkty i tworzone nowe, według danych przekazanych w zapytaniu.

PUT /v3/invoices/{id}.json

Aktualizacja

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"invoice":{"payment_method":"cash"}}' \
  https://api.infakt.pl/v3/invoices/42.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem.

Usuwanie faktury

DELETE /v3/invoices/{id}.json

Usuwanie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
    -X DELETE \
    https://api.infakt.pl/v3/invoices/42.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
204Zwracany po poprawnym usunięciu zasobu.
401Brak autoryzacji lub uprawnień do danego zasobu

Następny numer faktury

GET /v3/invoices/next_number.json

Następny numer faktury jest nadawany na podstawie daty wystawienia faktury. W procesie wyboru kolejnego numeru faktury są brane pod uwagę tylko faktury z danego miesiąca.

ParametrTyp danychWymaganyOpis
kindstringNieRodzaj faktury:
  • final – Faktura końcowa
  • advance – Faktura zaliczkowa
  • margin – Faktura marża
  • proforma – Faktura proforma
  • vat – Faktura VAT
datestringNieData wystawienia

Pobranie następnego numeru faktury

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
    https://api.infakt.pl/v3/invoices/next_number.json?kind=vat

Przykładowa odpowiedź

{
  "next_number": "5/06/2014",
  "invoice_date": "2014-06-05",
  "invoice_kind": "vat"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie.
401Brak autoryzacji lub uprawnień do danego zasobu
POST /v3/invoices/{id}/paid.json
ParametrTyp danychWymaganyOpis
paid_datestringNieData opłacenia

Oznaczenie fakury jako zapłacona

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{"paid_date":"2014-06-05"}' \
  https://api.infakt.pl/v3/invoices/42/paid.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
204Zwracany po poprawnym opłaceniu zasobu.
401Brak autoryzacji lub uprawnień do danego zasobu
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem.

Pobranie faktury w formacie pdf

GET /v3/invoices/{id}/pdf.json
ParametrTyp danychWymaganyOpis
document_typestringTakRodzaj dokumentu:
  • original_copy – Orginał i Kopia
  • original – Orginał
  • copy – Kopia
  • original_duplicate – Duplikat orginału
  • copy_duplicate – Duplikat kopii
  • duplicate – Duplikat
  • regular – Bez adnotacji
  • double_regular – 2 Bez adnotacji
localestringNieJęzyk dokumentu: pl – Polski, en – Angielski, pe – polsko – angielski

Pobranie faktury w formacie pdf

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  https://api.infakt.pl/v3/invoices/42/pdf.json?document_type=original&locale=pl
W odpowiedzi zostaje zwrócona faktura w formie pliku PDF. Pobranie faktury jako PDF powoduje zmianę statustu faktury na „Wydrukowano”.

Wysłanie faktury via email

POST /v3/invoices/{id}/deliver_via_email.json

Przy wysyłce dokumentu pocztą elektroniczną, można podać adres email, na który będzie wysłana faktura. W przypadku, gdy nie zostanie podany – faktura zostanie wysłana na domyślny adres email Klienta. Wysłanie faktury e-mailem powoduje zmianę statusu faktury na „Wysłano.”

ParametrTyp danychWymaganyOpis
print_typestringTakRodzaj dokumentu:
  • original – Orginał
  • copy – Kopia
  • original_duplicate – Duplikat orginału
  • copy_duplicate – Duplikat kopii
  • duplicate – Duplikat
  • regular – Bez adnotacji
localestringNieJęzyk dokumentu: pl – Polski, en – Angielski, pe – polsko – angielski
recipientstringNieAdres email odbiorcy
send_copybooleanNieCzy wysłać na adres email właściciela konta?

Wysłanie faktury via email

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{"print_type":"original"}' \
  https://api.infakt.pl/v3/invoices/42/deliver_via_email.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
202Faktura została przekazana do wysłania
422Zwracany wraz z informacją o błędach w przypadku problemów przy wysyłce.

Wysłanie faktury pocztą

POST /v3/invoices/{id}/deliver_via_post.json

Przy wysyłce dokumentu, adres do wysyłki zostanie pobrany z danych klienta.

ParametrTyp danychWymaganyOpis
print_typestringTakRodzaj dokumentu:
  • original – Orginał
  • copy – Kopia
  • original_duplicate – Duplikat orginału
  • copy_duplicate – Duplikat kopii
  • duplicate – Duplikat
  • regular – Bez adnotacji
localestringNieJęzyk dokumentu: pl – Polski, en – Angielski, pe – polsko – angielski

Wysłanie faktury pocztą

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{"print_type":"original"}' \
  https://api.infakt.pl/v3/invoices/42/deliver_via_post.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
202Faktura została przekazana do wysłania
422Zwracany wraz z informacją o błędach w przypadku problemów przy wysyłce.

Szybkie płatności

Funkcja szybkich płatności elektronicznych umożliwia stworzenie dla Faktury VAT adresu URL, po przejściu w który użytkownik może opłacić dany dokument za pomocą systemu płatniczego Blue Media.

Wyświetlenie linku

GET /v3/invoices/{id}/quick_payments.json

Pobranie linku płatności dla Faktury VAT

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  https://api.infakt.pl/v3/invoices/42/quick_payments.json

W przypadku, kiedy Faktura VAT posiada aktywną płatność, w odpowiedzi otrzymamy adres URL kierujący do bramki płatniczej.

Przykładowa odpowiedź

{
  "payment_link": "https://infakt.pl/app/gateways/bluemedia/24924df1e55f472f83683591424c315f"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Wyświetlono adres URL aktywnej płatności
401Brak autoryzacji do danego zasobu

Tworzenie linku

POST /v3/invoices/{id}/quick_payments.json

Tworzenie linku płatności dla Faktury VAT

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.infakt.pl/v3/invoices/42/quick_payments.json

W przypadku, kiedy udało się aktywować szybką płatność dla Faktury VAT, w odpowiedzi otrzymamy adres URL kierujący do bramki płatniczej. W przeciwnym wypadku zostanie wyświetlony komunikat z listą powodów, które uniemożliwiają aktywowanie szybkiej płatności.

Przykładowa odpowiedź

{
  "payment_link": "https://infakt.pl/app/gateways/bluemedia/24924df1e55f472f83683591424c315f"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
201Stworzono adres URL aktywnej płatności
401Brak autoryzacji do danego zasobu
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem

Usuwanie linku

DELETE /v3/invoices/{id}/quick_payments.json

Usuwanie linku płatności dla Faktury VAT

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X DELETE \
  https://api.infakt.pl/v3/invoices/42/quick_payments.json

W przypadku, kiedy Faktura VAT posiada aktywną płatność, wykonanie żądania spowoduje jej usunięcie.

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
204Zwracany po poprawnym usunięciu aktywnej płatności
401Brak autoryzacji do danego zasobu

Funkcja udostępniania linku do faktury umożliwia stworzenie dla Faktury VAT adresu URL, po przejściu na który użytkownik może zobaczyć podgląd faktury oraz wykonać podstawowe akcje, takie jak drukowanie, zaimportowanie do infakt jako koszt, opłacenie za pomocą systemu szybkich płatności.

Wyświetlenie linku

GET /v3/invoices/{id}/share_links.json

Pobranie linku dla Faktury VAT

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  https://api.infakt.pl/v3/invoices/42/share_links.json

W przypadku, kiedy Faktura VAT posiada włączoną opcję udostępniania, w odpowiedzi otrzymamy adres URL kierujący do faktury oraz datę ważności linku.

Przykładowa odpowiedź

{
  "share_link": "http://www.infakt.pl/app/twoja-faktura/1844249c-9b2c-4f75-9103-743b3c13a62f",
  "expiration_date": "2017-07-25"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Dane dotyczące udostępnienia.
401Brak autoryzacji do danego zasobu

Tworzenie linku

POST /v3/invoices/{id}/share_links.json

Tworzenie linku do udostępniania

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.infakt.pl/v3/invoices/42/share_links.json

W przypadku, kiedy udało się włączyć opcję udostępniania dla Faktury VAT, w odpowiedzi otrzymamy adres URL kierujący do faktury oraz datę ważności linku. W przeciwnym wypadku zostanie wyświetlony komunikat z listą powodów, które uniemożliwiają włączenie opcji.

Przykładowa odpowiedź

{
  "share_link": "http://www.infakt.pl/app/twoja-faktura/1844249c-9b2c-4f75-9103-743b3c13a62f",
  "expiration_date": "2017-07-25"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
201Stworzono adres URL dla faktury
401Brak autoryzacji do danego zasobu
403Blokada związana z limitami posiadanego abonamentu
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem

Usuwanie linku

DELETE /v3/invoices/{id}/share_links.json

Usuwanie linku

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X DELETE \
  https://api.infakt.pl/v3/invoices/42/share_links.json

W przypadku, kiedy Faktura VAT posiada włączoną opcję udostępnienia, wykonanie żądania spowoduje jej wyłączenie.

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zwracany po poprawnym wyłączeniu udostępnienia
401Brak autoryzacji do danego zasobu
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem

Przedłużanie ważności linku

POST /v3/invoices/{id}/share_links/prolong.json

Przedłużanie ważności linku

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.infakt.pl/v3/invoices/42/share_links/prolong.json

W przypadku, kiedy Faktura VAT posiada włączoną opcję udostępnienia, wykonanie żądania spowoduje przedłużenie jego ważności o kolejne 30 dni.

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zwracany po poprawnym przedłużeniu ważności linku
401Brak autoryzacji do danego zasobu
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem

Załączniki faktury

Podgląd załączników faktur należących do użytkownika.

Listowanie załączników faktury

GET /v3/invoices/{id}/attachments.json

Akcja listowania zwraca odpowiedź zawierającą tablicę obiektów pod kluczem entities oraz informacje pomocnicze dotyczące stronicowania.

ParametrTyp danychWymaganyOpis
idintegerTylko do odczytuID załącznika
namestringTylko do odczytuNazwa załącznika
content_typestringTylko do odczytuTyp załącznika
download_linkstringTylko do odczytuLink do pobrania załącznika, ważny 10 minut

Dodatkowo, na zbiorze danych można wykonywać nastepującą operacje:

Przykład akcji listowania:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \          
  https://api.infakt.pl/v3/invoices/42/attachments.json

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 10,
      "total_count": 20,
      "next": "https://api.infakt.pl/api/v3/invoices/59/attachments.json?offset=10",
      "previous": "https://api.infakt.pl/api/v3/invoices/59/attachments.json?offset=0"
  },
  "entities": [{
    "id": 16,
    "name": "file.jpg",
    "content_type": "image/jpeg",
    "download_link": "https://confirmation-dev.s3.amazonaws.com/uploads/1d7c33a72-e502-4723-ar3r-5f20f6ee8eaf/original.jpg"
  }, {
    "id": 17,
    "name": "file.png",
    "content_type": "image/png",
    "download_link": "https://confirmation-dev.s3.amazonaws.com/uploads/1d7c33a72-e502-4723-ar3r-5f20f6ee8eaf/original.png"
  },...]
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu
404Zasób nie został odnaleziony

Podgląd załącznika

GET /v3/invoices/{id}/attachments/{id}.json

Przykład akcji podglądu:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \          
  https://api.infakt.pl/v3/invoices/42/attachments/16.json

Przykładowa odpowiedź

{
  "id": 16,
  "name": "file.jpg",
  "content_type": "image/jpeg",
  "download_link": "https://confirmation-dev.s3.amazonaws.com/uploads/1d7c33a72-e502-4723-ar3r-5f20f6ee8eaf/original.jpg"
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu
404Zasób nie został odnalezionyu