API

Wstęp

Niniejsza dokumentacja odnosi się do API w wersji 3 (APIv3). Aby swobodnie korzystać z funkcjonalności udostępnianych przez interfejs API, zalecamy uważne zapoznanie się z treścią dokumentacji oraz zasadami korzystania z usług inFakt zawartymi w Regulaminie

Polityka zmian

W ramach procesu rozwijania aplikacji, zasoby dostępne dla użytkowników API mogą ulegać zmianom. Za każdym razem, zmiany, które mają wpływ na funkcjonalność API będą komunikowane za pośrednictwem strony zmian api jak również - w przypadku istotnych zmian - wcześniej komunikowane dostępnymi kanałami kontaktu z użytkownikami API.

API w wersji 3

API w wersji 3 wprowadza wiele ulepszeń dotyczących zarówno uporządkowania istniejących już zasobów, jak również udostępnienie nowych. Poniżej przedstawiamy listę najważniejszych zmian w stosunku do API w wersji 2:

REST

Nowa wersja API jest zgodna z architekturą REST.

Autentykacja

W odróżnieniu od APIv2, gdzie autoryzacja odbywała się przy użyciu protokołu oAuth, w APIv3 autentykacja następuje poprzez użycie unikalnego klucza API. Korzystając z panelu zarządzania aplikacjami w ustawieniach konta użytkownik ma możliwość wygenerowania oraz zarządzania kluczami dostępu. Klucz dla Aplikacji iOS generowany jest automatycznie podczas korzystania z Aplikacji. Klucz przekazywany jest za pomocą nagłówka HTTP X-inFakt-ApiKey lub parametru api_key.

Zmiana adresacji zasobów

Chcąc uporządkować sposób dostępu do zasobów API, zmieniliśmy adresację tak, aby była spójna i bardziej intuicyjna dla Użytkowników.

  • Klienci:
    • /api/v2/clients/*    /v3/clients.json
  • Faktury:
    • /api/v2/invoices/*    /v3/invoices.json
    • /api/v2/invoices/deliver?type=post    /v3/invoices/ID/deliver_via_post.json
    • /api/v2/invoices/deliver?type=mail    /v3/invoices/ID/deliver_via_email.json
    • /api/v2/invoices/pdf    /v3/invoices/ID/pdf.json
  • Księga przychodów i rozchodów:
    • /api/v2/reports/kpir    /v3/books.json
  • Podatek dochodowy:
    • /api/v2/reports/pit5    /v3/income_taxes.json
  • Podatek VAT:
    • /api/v2/reports/vat7    /v3/vat_taxes.json
  • Składki ZUS:
    • /api/v2/reports/zus    /v3/insurance_fees.json
  • Podstawy zwolnienia z VAT:
    • /api/v2/vat_exemptions    /v3/vat_exemptions.json

Nowe zasoby

  • Faktury korygujące:
    • /v3/corrective_invoices.json
  • Konta bankowe:
    • /v3/bank_accounts.json
  • Kraje:
    • /v3/countries.json
  • Produkty:
    • /v3/products.json
  • Podatek VAT-UE:
    • /v3/vat_eu_taxes.json
  • Stawki VAT:
    • /v3/vat_rates.json

Optymalizacja

  • Za pomocą parametru fields można ograniczyć pola, które zostaną pobrane.
  • Możliwość zastosowania nagłówka ETag dla zasobów:
    • clients
    • books
    • insurance_fees
    • bank_accounts
    • countries
    • products
    • vat_rates

Nowe funkcje formatowania danych

W nowej wersji API wprowadziliśmy także możliwość dodatkowego formatowania zwracanych danych:

Sortowanie

Odpowiedź serwera zawierającą dane można sortować używając parametru order. Więcej informacji.

Stronicowanie

Odpowiedź serwera zawierającą dane można stronicować używając parametrów limit oraz offset. Więcej informacji.

Częściowe odpowiedzi

Nowe API udostępnia również możliwość zawężania ilości danych zwracanych przez serwer (ang, Partial Responses). Więcej informacji.

Interaktywna dokumentacja

Aby maksymalnie ułatwić korzystanie z API, udostępniliśmy interaktywne narzędzie, dzięki któremu można zacząć korzystać z API przy pomocy przeglądarki internetowej. Więcej informacji.

Status APIv2

Aktualnie obowiązującą wersją API jest wersja 3. W związku z tym, poprzednie wersje API zostają automatycznie uznane za przestarzałe i nie będą dłużej rozwijane przez zespół inFakt.