Paginacja
Endpointy zwracające listy (GET /documents, GET /clients, GET /products, GET /recurring-rules, GET /recurring-rules/{id}/history, GET /webhooks/{id}/deliveries, GET /documents/{id}/history, GET /warehouse/movements) są paginowane za pomocą parametrów zapytania:
| Parametr | Znaczenie |
|---|---|
currentPage |
numer strony liczony od 1 |
itemsPerPage |
rozmiar strony; wartość domyślna i maksymalna zależą od listy, większe wartości są przycinane do maksimum |
searchQuery |
filtr tekstowy (tam, gdzie jest obsługiwany) |
Domyślny i maksymalny rozmiar strony:
| Lista | Domyślnie | Maksymalnie |
|---|---|---|
GET /documents, GET /clients, GET /products |
10 | 100 |
GET /recurring-rules |
50 | 100 |
GET /recurring-rules/{id}/history |
50 | 200 |
GET /warehouse/movements |
50 | 100 |
GET /documents/{id}/history |
20 | 100 |
GET /webhooks/{id}/deliveries |
20 | 100 |
Wartości dla każdego endpointu podaje też specyfikacja OpenAPI przy parametrze itemsPerPage.
Odpowiedź zawiera stronę wyników oraz pola totalCount i totalPages:
curl -s "https://prod.api.fakturnia.pl/external/v1/documents?currentPage=1&itemsPerPage=50" \
-H "Authorization: Bearer $TOKEN"
{
"success": true,
"data": { "documents": [ /* … */ ], "currentPage": 1, "itemsPerPage": 50, "totalCount": 184, "totalPages": 4, "searchQuery": "" },
"executionTime": 38
}
Iteruj, zwiększając wartość currentPage, aż przekroczysz totalPages. Krótkie, ograniczone listy (GET /warehouse, GET /employees, GET /webhooks, GET /email-accounts) zwracają wszystko naraz. Strumienie aktywności (GET /activity, GET /employees/{id}/activity) używają kursora czasowego before / nextBefore, opisanego w Historii i aktywności.
Filtry listy dokumentów
GET /documents obsługuje dodatkowe filtry, które można łączyć:
| Parametr | Znaczenie |
|---|---|
documentType |
typ dokumentu lub lista typów rozdzielona przecinkami (np. FakturaVAT,FakturaKorygujaca) |
dateFrom |
data wystawienia od, włącznie (YYYY-MM-DD) |
dateTo |
data wystawienia do, włącznie (YYYY-MM-DD) |
buyerNip / buyerVatUE / buyerIdentifier |
dokumenty dla nabywcy o danym identyfikatorze |
excludeIds |
lista ID dokumentów do pominięcia, rozdzielona przecinkami |
onlyUnlinked |
tylko dokumenty bez powiązania z zamówieniem |
curl -s "https://prod.api.fakturnia.pl/external/v1/documents?documentType=FakturaVAT&dateFrom=2026-01-01&dateTo=2026-01-31" \
-H "Authorization: Bearer $TOKEN"
Nieznany documentType albo data w złym formacie zwraca 400 z kodem INVALID_PARAMS. Dopuszczalne typy znajdziesz w słownikach.
Listy podlegają limitom zapytań — przechodź po stronach sekwencyjnie i buforuj wyniki zamiast odpytywać agresywnie.