Pobieranie faktur
POST /invoices/{environment}
Wyszukuje faktury w KSeF dla podanego zakresu dat. Wymaga aktywnej sesji KSeF (wcześniejsze wywołanie POST /auth/{environment}).
Parametry ścieżki
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
environment | string | ✅ | test, demo lub prod |
Request Body
{
"dateFrom": "2026-01-01 00:00:00",
"dateTo": "2026-01-31 23:59:59",
"subjectType": "sales",
"pageSize": 10,
"pageNr": 1
}
| Pole | Typ | Wymagany | Domyślnie | Opis |
|---|---|---|---|---|
dateFrom | string | ✅ | — | Data początkowa (yyyy-MM-dd lub yyyy-MM-dd HH:mm:ss) |
dateTo | string | ✅ | — | Data końcowa (yyyy-MM-dd lub yyyy-MM-dd HH:mm:ss) |
subjectType | string | ❌ | sales | Typ listy faktur: sales, purchases, thirdParty |
pageSize | integer | ❌ | 10 | Liczba faktur na stronę (1–100) |
pageNr | integer | ❌ | 1 | Numer strony (od 1) |
Typy podmiotów (subjectType)
| Wartość | Odpowiednik KSeF | Opis |
|---|---|---|
sales | Subject1 | Faktury, na których Twoja firma jest sprzedawcą (domyślnie) |
purchases | Subject2 | Faktury, na których Twoja firma jest nabywcą |
thirdParty | Subject3 | Faktury, w których Twoja firma jest podmiotem trzecim |
Odpowiedź 200
{
"invoices": [
{
"ksefNumber": "1234567890-20260101-ABCDEF-12",
"invoiceNumber": "FV/2026/01/001",
"sellerNip": "9570429696",
"sellerName": "Firma XYZ",
"buyerNip": "1234567890",
"buyerName": "Klient ABC",
"netAmount": "1000.00",
"vatAmount": "230.00",
"grossAmount": "1230.00",
"currency": "PLN",
"invoiceType": "VAT",
"issueDate": "2026-01-15 00:00:00"
}
],
"pageNr": 1,
"pageSize": 10,
"hasMore": false
}
| Pole | Typ | Opis |
|---|---|---|
invoices | array | Lista podsumowań faktur |
pageNr | integer | Bieżący numer strony |
pageSize | integer | Liczba faktur na stronę |
hasMore | boolean | Czy dostępne są kolejne strony |
Pola podsumowania faktury:
| Pole | Typ | Opis |
|---|---|---|
ksefNumber | string | Numer KSeF faktury |
invoiceNumber | string | Numer faktury (element P_2) |
sellerNip | string | NIP sprzedawcy |
sellerName | string | Nazwa firmy sprzedawcy |
buyerNip | string | NIP nabywcy |
buyerName | string | Nazwa firmy nabywcy |
netAmount | string | Kwota netto |
vatAmount | string | Kwota VAT |
grossAmount | string | Kwota brutto |
currency | string | Kod waluty (np. PLN) |
invoiceType | string | Typ faktury |
issueDate | string | Data wystawienia |
Synchronizacja DB
Podczas pobierania faktur z KSeF, ksef-proxy automatycznie wykonuje synchronizację danych:
- Faktury zaliczkowe (ROZ ↔ ZAL) — wykrywane i wiązane przez
advance_groups/advance_group_invoices - Faktury korygujące (KOR) — wiązane z fakturami oryginalnymi przez
invoice_corrections - Metadane synchronizacji —
invoice_sync_metaaktualizowane o znacznik czasu ostatniej synchronizacji i liczbę nieprzeczytanych
Kody błędów
| Kod | Opis |
|---|---|
| 400 | Błędne parametry (brak dat, zły format) |
| 401 | Brak autoryzacji |
| 404 | Brak aktywnej sesji KSeF |
| 502 | Błąd KSeF |