Downloading invoices

POST /invoices/{environment}

Searches invoices in KSeF for a given date range. Requires an active KSeF session (prior call to POST /auth/{environment}).

Path Parameters

Parameter	Type	Required	Description
environment	string	✅	test, demo or prod

Request Body

{
  "dateFrom": "2026-01-01 00:00:00",
  "dateTo": "2026-01-31 23:59:59",
  "subjectType": "sales",
  "pageSize": 10,
  "pageNr": 1
}

Field	Type	Required	Default	Description
dateFrom	string	✅	—	Start date (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)
dateTo	string	✅	—	End date (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)
subjectType	string	❌	sales	Invoice list type: sales, purchases, thirdParty
pageSize	integer	❌	10	Invoices per page (1–100)
pageNr	integer	❌	1	Page number (1-based)

Subject Types

Value	KSeF equivalent	Description
sales	Subject1	Invoices where your company is the seller (default)
purchases	Subject2	Invoices where your company is the buyer
thirdParty	Subject3	Invoices where your company is a third party

Response 200

{
  "invoices": [
    {
      "ksefNumber": "1234567890-20260101-ABCDEF-12",
      "invoiceNumber": "FV/2026/01/001",
      "sellerNip": "9570429696",
      "sellerName": "Firma XYZ",
      "buyerNip": "1234567890",
      "buyerName": "Client 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
}

Field	Type	Description
invoices	array	List of invoice summaries
pageNr	integer	Current page number
pageSize	integer	Number of invoices per page
hasMore	boolean	Whether more pages are available

Invoice summary fields:

Field	Type	Description
ksefNumber	string	KSeF invoice number
invoiceNumber	string	Invoice number (P_2 element)
sellerNip	string	Seller NIP number
sellerName	string	Seller company name
buyerNip	string	Buyer NIP number
buyerName	string	Buyer company name
netAmount	string	Net amount
vatAmount	string	VAT amount
grossAmount	string	Gross amount
currency	string	Currency code (e.g. PLN)
invoiceType	string	Invoice type
issueDate	string	Issue date

DB Synchronization

When invoices are fetched from KSeF, ksef-proxy automatically performs data synchronization:

• Advance invoices (ROZ ↔ ZAL) — detected and linked via advance_groups / advance_group_invoices
• Correction invoices (KOR) — linked to original invoices via invoice_corrections
• Sync metadata — invoice_sync_meta is updated with the last sync timestamp and unread count

Error Codes

Code	Description
400	Invalid parameters (missing dates, wrong format)
401	Unauthorized
404	No active KSeF session
502	KSeF error