Report the name and version of the running KSeF connector.

List the invoice metadata of the last thirty days, per subject type.

Takes no arguments, for the same reason synchronise_invoices takes none: a window driven by the caller spends a twenty-per-hour metadata allowance in minutes, and the Ministry reads that pattern as working around a limit. The window ends on the hour, so asking again within the same hour is answered from disk and costs nothing.

Reads only. There is no confirmation to click: a gate on a read teaches the person to approve without looking, and spends the gate that a write needs.

At most fifty invoices are listed individually. Above that the rows are dropped and the answer carries the count and the gross total per currency instead — and message says so in as many words. An empty window is its own answer, restating the NIP, the environment, the subject type and both ends of the period, so "nothing arrived" can be told from "wrong question".

Metadata only. An FA(2)/FA(3) body holds a counterparty's personal data and is third-party input; it never enters this answer.

Write one archived invoice as the PDF the Ministry's own application shows.

ksef_number names an invoice already in the archive. Nothing is fetched: this call spends none of the twenty metadata queries an hour and works with no network at all. An invoice that has not been synchronised yet is refused rather than downloaded, so the answer never depends on a query budget.

The document is produced by the Ministry's own generator, run locally from a build vendored with this package — the same code the verification portal loads into a browser. Fidelity is therefore official rather than approximate, and generator_version names the build, the same string the footer of the document carries.

working_directory overrides the directory declared during onboarding for this one call, under the same rules as the statement: created 0700 if new, refused inside the cache or data root, and reported in warnings when its path looks like a cloud sync folder or its permissions are wider than 0700. A synced directory the taxpayer acknowledged during onboarding is not reported again. The PDF names the counterparty exactly as the statement does.

On production the document carries the QR code and verification link, and verification_url repeats it here. Test and demo invoices have no verification surface, so both are absent rather than pointing at a page that would not resolve.

Requires Node — uvx cannot install it and a Python package cannot depend on it. Without Node this one call fails with a message saying what to install; synchronisation, the CSV statement and the listing are unaffected.

The generator accepts FA(1), FA(2), FA(3), UPO and PEF, but only FA(3) has been exercised end to end. Treat a refusal on an older schema as untested rather than impossible, and report it.

Report the invoices that have arrived since a person was last shown any.

This is the question the free Ministry application cannot answer: it lists what is there, never what is new since somebody last looked. The comparison is against a ledger of KSeF numbers already reported by this tool, kept on disk per subject and per environment, so it survives restarts.

The window is the last ninety days, dated by acceptance in KSeF rather than by the seller's issue date — an invoice issued in March and accepted yesterday is new to the reader, and a window dated by issue date would not contain it. Both ends are fixed, so asking again within the same hour is answered from disk and spends nothing from twenty metadata queries an hour.

received_on per invoice is the day KSeF assigned the number, read off the number itself. It is independent of when this tool fetched anything, and it is not the seller's issue date, which is reported separately.

KSeF has no notion of a closed period and will not stop an invoice from landing in a month already filed, so earlier_month_count counts the new invoices whose number was assigned before the current month. That is a signal to look, never a statement that an invoice belongs to any period — the tax treatment is the reader's decision and this tool does not make it.

Invoices listed individually are recorded as shown, and the next call does not repeat them. Above the threshold the rows are dropped, and then nothing is recorded, because nobody saw them — marked_as_reviewed says which of the two happened. Metadata only: an FA(2)/FA(3) body holds a counterparty's personal data and never enters this answer.

Write one month of purchase invoices as a CSV an accountant can forward.

period is a calendar month spelled YYYY-MM. The month is the unit a period is closed in, and both ends being fixed is what lets the same request be answered from disk instead of spending one of twenty metadata queries an hour a second time.

working_directory overrides the directory declared during onboarding for this one call. Whichever is used is created 0700 if it is new, is refused outright if it lies inside the cache or data root — those are internal storage and deleting statements must never reach the archive — and is reported in warnings when its path looks like a cloud sync folder, unless the taxpayer acknowledged that directory during onboarding.

The file holds ten columns, in this order: KSeF number, the seller's own invoice number, issue date, seller NIP, seller name, gross, net, VAT, currency, and a KOD I verification code. The code is composed from the seller NIP, the issue date and the SHA-256 of the archived invoice body; rows whose body is not in the archive yet say so instead of carrying a blank code.

Addresses, bank accounts, invoice lines and local paths are absent on purpose: this file is written to be attached to an e-mail. The paths are in this answer instead.

Amounts are written exactly as KSeF stated them — no rounding, no float anywhere on the path — with a comma as the decimal separator and a semicolon between fields, which is what a Polish spreadsheet expects. Sums are in this answer, per currency, and never one figure across several of them.

Fetch, decrypt and archive every invoice package KSeF finished since the last run.

Takes no arguments on purpose. The date window, the package size and how many packages to ask for are decided by KSeF and by the hourly allowance, never by the caller: an agent driving them spends a twenty-per-hour budget in two minutes and the Ministry reads the pattern as working around a limit.

Safe to call again. A package still being built, or one fetched but not yet stored, stays recorded on disk with its key, so a second call continues it instead of asking for it twice. An invoice already in the archive is reported under already_held rather than downloaded again.

Reports where the invoices landed and which KSeF numbers arrived. It never returns invoice content: an FA(2)/FA(3) document holds a counterparty's personal data, and reading one means opening the file this tool names.

session_ceilings says how much one session may carry and, in assumed, whether KSeF granted those figures or the conservative fallback is in force because the registry answered about limits in a shape that could not be read. An assumed ceiling is a different event from a granted one, and the message says so in as many words.

correlation names this call in the technical journal on stderr. Quote it when reporting a failure: it is what lets the whole pass be reconstructed without running the synchronisation again out of twenty exports an hour.