Dokumentacja

Ogólne informacje

Punkt dostępowy

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.

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

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.

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

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:

{
  "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"
    }
  ]
}

{
  "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:

{
  "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"
    }
  ]
}

{
  "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:

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.

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.