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.plNiniejsza 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/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 HTTPX-inFakt-ApiKey
.Kodowanie znaków
Każdy string przekazywany do API musi być kodowany w UTF-8.Parametry
Dla requestówPOST
, 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
Wyszukiwanie odbywa się poprzez wywołanie akcji listowania odpowiedniego zasobu z parametremq
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ść
_lt
– mniejsze niż_gt
– więszke niż_lteq
– mniejsze lub równe_gteq
– większe lub równe
Przykłady:
Aby wyszukać fakturę o numerze1/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
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
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ówoffset
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 parametrufields
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ą parametruorder
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 odpowiedzi | Opis |
---|---|
200 OK | Zapytanie zostało wykonane poprawnie |
201 Created | Zasób został poprawnie utworzony. |
202 Accepted | Zapytanie zostało zakceptowane do przetworzenia, np. podczas wysyłki dokumentów. |
204 No Content | Zwracany po poprawnym usunięciu zasobu. |
400 Bad Request | Któryś z parametrów przyjął nieprawidłową wartość. |
401 Unauthorized | Brak autoryzacji lub uprawnień do danego zasobu. |
402 Payment Required | Wystę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 Forbidden | Zwracany w przypadku braku uprawnień do danej akcji (np. posiadanie nieodpowiedniego planu) lub nałożenia blokady na adres IP. |
404 Not Found | Zasób nie został odnaleziony. |
406 Not Acceptable | Zwracany w przypadku użycia niepoprawnego typu danych w adresie zasobu. |
422 Unprocessable Entity | Zwracany 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.Limit | Wartość |
---|---|
Liczba zapytań (metoda GET) z jednego adresu IP | 300 zapytań/60 s. |
Liczba zapytań (pozostałe metody) z jednego adresu IP | 150 zapytań/60 s. |
Proaktywna ochrona | dynamiczna do 1 adresu IP lub całej podsieci |