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