Dokumentacja

Ogólne informacje

Punkt dostępowy

Punkt dostępowy API znajduje się pod adresem:

https://api.infakt.pl/v3

Należ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.
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. Jednocześnie zastrzegamy sobie 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.html

Dla 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.

Ograniczenia

API w wersji V3 posiada następujące ograniczenia:

  • W przypadku używania numeracji automatycznej podczas wystawiania faktur za pomocą API konieczne jest realizowanie zapytań w sposób sekwencyjny. Jednoczesne zlecenie wystawienia kilku faktur może spowodować wystawienie ich z tym samym numerem.
  • Limitowana ilość zapytań z jednego adresu IP, w takim przypadku serwer odpowiada statusem HTTP 503 lub 429.