Dokumentacja

Ogólne informacje

Wstęp

inFakt API oparty jest o architekturę REST i umożliwia dostęp do zasobów serwisu inFakt.pl za pomocą interfejsu JSON. Dzięki temu możliwe staje się stworzenie zewnętrznych aplikacji integrujących się z kontem użytkownika inFakt.pl

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

Punkt dostępowy

Punkt dostępowy API znajduje się pod adresem:https://api.infakt.pl/v3Należy zwrócić uwagę, że dostęp odbywa się szyfrowanym połączeniem https z wykorzystaniem protokołu TLS 1.2 oraz TLS 1.3 – wcześniejsze wersje protokołu nie są wspierane. Pełna lista szyfrów (ang. ciphers) znajduje się tutaj – lista ta może ulegać zmianom.

Uwierzytelnianie

Klucz dostępu do API można wygenerować po zalogowaniu do aplikacji WWW korzystając z ustawień konta. Klucz powinien być przekazywany za pomocą nagłówka HTTP X-inFakt-ApiKey.

Kodowanie znaków

Każdy string przekazywany do API musi być kodowany w UTF-8.

Parametry

Dla requestów POST, PATCH, PUT i DELETE parametry nie zawarte w URLu powinny być zakodowane JSONem, a zapytanie powinno posiadać nagłówek Content-Type: application/json.

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"client":{"company_name":"Infakt Biuro Rachunkowe Sp. z o.o."}}' \
  https://api.infakt.pl/v3/clients/1.json
Wyszukiwanie odbywa się poprzez wywołanie akcji listowania odpowiedniego zasobu z parametrem q zawierającym treść zapytania w formacie:/invoices.json?q[NAZWA_PARAMETRU_eq]=SZUKANA_WARTOŚĆWażne, aby w tym miejscu zwrócić uwagę na modyfikator _eq dołączony do nazwy wyszukiwanego parametru. Nazwa parametru dla każdego pola znajduje się w sekcji Definicja odpowiedniego zasobu (pierwsza kolumna).

Modyfikatory:

Do wartości tekstowych można użyć:
  • _eq – zwraca rekordy w których pole równa się podanej wartości
  • _cont – zwraca rekordy w których pole zawiera podaną wartość
Do dat można użyć:
  • _lt – mniejsze niż
  • _gt – więszke niż
  • _lteq – mniejsze lub równe
  • _gteq – większe lub równe
Ważna informacja: Nie do wszytskich parametrów można zastosować podane modyfikatory.

Przykłady:

Aby wyszukać fakturę o numerze 1/09/2013, do zapytania listującego faktury należy dodać parametr q[number_eq]=1/09/2013.
  • GET /v3/invoices.json?q[number_eq]=1/09/2013
Aby wyszukać klienta po NIP, do zapytania listującego faktury należy dodać parametr q[nip_eq]=SZUKANY_NIP.

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: API_KEY" \
  -H "Content-Type: application/json" \
  -X GET \
  -d '{"q": {"nip_eq": "SZUKANY_NIP"} }' \
  https://api.infakt.pl/v3/clients.json
Aby wyszukać faktury bez daty opłacenia

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: API_KEY" \
  -H "Content-Type: application/json" \
  -X GET \
  -d '{"q": {"paid_date_null": true} }' \
  https://api.infakt.pl/v3/invoices.json

Stronicowanie

Niektóre zapytania listujące kolekcje zasobów zwracają ograniczoną ilość danych i mogą być stronicowane. W tym celu należy użyć parametrów offset i limit

Przykłady:

  • GET /v3/clients.json?offset=10&limit=50
  • GET /v3/products.json?offset=0&limit=100

Częściowe odpowiedzi

Domyślnie, serwer zwraca pełną reprezentację zasobu. Dla lepszej wydajności, można zwrócić się do serwera, aby wysłał tylko te pola, których naprawdę potrzebujesz i uzyskać częściową odpowiedź.Aby ubiegać się o częściową odpowiedź, użyj parametru fields celem określenia pól, które mają zostać zwrócone. Możesz użyć tego parametru dla każdej akcji Listowania oraz Podglądu.

Przykłady:

GET /v3/bank_accounts.json?fields=bank_name

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 4,
      "total_count": 4,
      "next": "https://api.infakt.pl/api/v3/bank_accounts.json?fields=bank_name&offset=10",
      "previous": "https://api.infakt.pl/api/v3/bank_accounts.json?fields=bank_name&offset=0"
  },
  "entities": [
    {
      "id": 4,
      "bank_name": "Bank4"
    },
    {
      "id": 3,
      "bank_name": "Bank3"
    },
    {
      "id": 2,
      "bank_name": "Bank2"
    },
    {
      "id": 1,
      "bank_name": "Bank1"
    }
  ]
}
GET /v3/invoices.json?fields=number,services(name,tax_symbol)

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 15,
      "next": "https://api.infakt.pl/api/v3/invoices.json?fields=number,services(name,tax_symbol)&offset=10",
      "previous": "https://api.infakt.pl/api/v3/invoices.json?fields=number,services(name,tax_symbol)&offset=0"
  },
  "entities": [
    {
      "id": 5,
      "number": "4/05/2022",
      "services": [
        {
          "id": 5,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    },
    {
      "id": 3,
      "number": "3/05/2022",
      "services": [
        {
          "id": 3,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    },
    {
      "id": 2,
      "number": "2/05/2022",
      "services": [
        {
          "id": 2,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    }
  ]
}

Sortowanie

Sortowanie odbywa się za pomocą parametru order

Przykłady:

GET /v3/products.json?fields=name&offset=10&limit=5&order=name%20asc

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 467,
      "next": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=15&limit=5&order=name%20asc"
      "previous": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=5&limit=5&order=name%20asc"
  },
  "entities": [
    {
      "id": 391,
      "name": "Air Electric System"
    },
    {
      "id": 327,
      "name": "Air Filter"
    },
    {
      "id": 353,
      "name": "Air GPS Filter"
    }
  ]
}
GET /v3/products.json?fields=name&offset=10&limit=5&order=name%20desc

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 467,
      "next": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=15&limit=5&order=name%20desc"
      "previous": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=5&limit=5&order=name%20desc"
  },
  "entities": [
    {
      "id": 137,
      "name": "Video Filter"
    },
    {
      "id": 351,
      "name": "Video Controller"
    },
    {
      "id": 369,
      "name": "Video Compressor"
    }
  ]
}

Kody błędów

Rezultat wykonanego zapytania można określić na podstawie kodu błędu HTTP. W aplikacji klienckiej w przypadku odpowiedzi z kodem błędu należy uwzględnić odpowiednie zachowanie swojej aplikacji. Przykładowo w sytuacji błędu z rodziny 50x lub 429 warto zaplanować ponowienie operacji po pewnym czasie. W InFakt API używane są następujące kody:
Kod odpowiedziOpis
200 OKZapytanie zostało wykonane poprawnie
201 CreatedZasób został poprawnie utworzony.
202 AcceptedZapytanie zostało zakceptowane do przetworzenia, np. podczas wysyłki dokumentów.
204 No ContentZwracany po poprawnym usunięciu zasobu.
400 Bad RequestKtóryś z parametrów przyjął nieprawidłową wartość.
401 UnauthorizedBrak autoryzacji lub uprawnień do danego zasobu.
402 Payment RequiredWystępuje, gdy w ramach posiadanego planu przekroczono limit dokumentów lub nie ma dostępu do funkcjonalności. Należy zmienić pakiet na wyższy, który zawiera funkcjonalność API lub posiada odpowiedni limit dokumentów.
403 ForbiddenZwracany w przypadku braku uprawnień do danej akcji (np. posiadanie nieodpowiedniego planu) lub nałożenia blokady na adres IP.
404 Not FoundZasób nie został odnaleziony.
406 Not AcceptableZwracany w przypadku użycia niepoprawnego typu danych w adresie zasobu.
422 Unprocessable EntityZwracany wraz z informacją o błędach w przypadku problemów z zasobem.
429 Too Many Requests
503 Service Unavailable		Zwracany w przypadku osiągnięcia limitu zapytań z jednego adresu IP.

Limity

W celu zapewnienia sprawiedliwego dostępu do API dla wszystkich naszych użytkowników wprowadziliśmy limity zapytań. W momencie przekroczenia limitu zwracany będzie odpowiednie kod błędu zgodnie z tabelą wymienioną w punkcie Kody błędów. Jednocześnie informujemy, że nie ma możliwości zmiany tego w żadnym zakresie. Zastrzegamy sobie również prawo do zmiany tych limitów oraz wprowadzania nowych.
LimitWartość
Liczba zapytań (metoda GET) z jednego adresu IP300 zapytań/60 s.
Liczba zapytań (pozostałe metody) z jednego adresu IP150 zapytań/60 s.
Proaktywna ochronadynamiczna do 1 adresu IP lub całej podsieci

Interaktywna dokumentacja

Dla użytkowników korzystających z API została udostępniona interaktywna dokumentacja, dzięki której można przetestować zapytania do API z poziomu przeglądarki.Aby korzystać z interaktywnej dokumentacji, należy posiadać klucz dostępu, który można wygenerować tutaj a następnie wprowadzić go do odpowiedniego pola pod adresem:http://api.infakt.pl/api/v3/doc/index.htmlDla użytkowników został również stworzony projekt w GitHubie zawierający pliki, które można wgrać do Postmana. Po zaimportowaniu należy wygenerować również klucz dostępu, a następnie wprowadzić go do odpowiedniej zmiennej.