Skip to content

Querying Invoices

Use auth.invoices when you need invoice metadata outside a sending session. Metadata queries are filter-driven and paginated by KSeF.

Build a filter

Keep filters narrow. Date ranges, role, and invoice type make queries faster and reduce pagination work.

from datetime import datetime, timedelta, timezone

from ksef2.domain.models import InvoicesFilter

filters = InvoicesFilter(
    role="seller",
    date_type="issue_date",
    date_from=datetime.now(tz=timezone.utc) - timedelta(days=7),
    date_to=datetime.now(tz=timezone.utc),
    amount_type="brutto",
    invoicing_mode="online",
    invoice_types=["vat"],
)

Query one page or all pages

from ksef2.domain.models import InvoiceMetadataParams

page = auth.invoices.query_metadata(
    filters=filters,
    params=InvoiceMetadataParams(sort_order="asc"),
)

for invoice in page.invoices:
    print(invoice.ksef_number, invoice.invoice_number)

for page in auth.invoices.query_metadata_pages(filters=filters):
    print(len(page.invoices), page.has_more)

for invoice in auth.invoices.all_metadata(filters=filters):
    print(invoice.ksef_number, invoice.invoice_number)

Wait for a newly sent invoice

KSeF processing is asynchronous. After sending an invoice, poll metadata when your next step depends on the invoice becoming visible in retrieval APIs.

result = auth.invoices.wait_for_invoices(
    filters=filters,
    timeout=120.0,
    poll_interval=2.0,
)

for invoice in result.invoices:
    print(invoice.ksef_number)

Recommended flow

Decide which subject role you are querying as.
Build a narrow InvoicesFilter.
Fetch one page for interactive screens or use iterators for background jobs.
Persist KSeF numbers needed for later downloads.

Next workflows