Invoices and Receipts

A VAT reclaim needs the supplier’s document behind it. PRIMA Bookkeeper collects your invoices and receipts and links each one to the payment it covers. It lists what is missing and files everything into one archive your accountant can read.

Where Documents Come From

You name the sources in the documents block of business.json, and setup writes the first version for you.

Source type	What it reads
folder	Any folder tree, a synced Google Drive or OneDrive folder included
drop	One flat folder you save downloaded invoices into
imap	A mailbox over IMAP, such as Proton Mail through Bridge, iCloud, Fastmail or any IMAP host
gmail	A Gmail mailbox through the Gmail API, with read-only access
graph	A Microsoft 365 or Outlook.com mailbox through Microsoft Graph, with read-only access

Add a mailbox with prima-bookkeeper documents add-mailbox, then set its password or approve access in your own terminal. Each business registers its own Google or Microsoft app, so no shared app reads your mail.

How Mail Stays Private

The engine reads your mail, and your agent does not. Sender discovery reads message headers only. Collection opens only billing mail from the senders it knows as your suppliers. Other mail never reaches your agent or the store. The business’s own addresses go in ownAddresses, so mail you send yourself is never taken for a supplier’s.

What It Keeps and What It Ignores

The engine reads the text of each PDF and sorts it into a kind. Invoices, receipts and credit notes become evidence. The engine counts order confirmations, statements, one-time codes and dispatch notices, and it never uses them as evidence. A scanned image has no text to read, so your agent reads it and submits the figures with documents fields. The engine then checks that the lines add up and that every rate is one the jurisdiction pack knows.

Linking Documents to Payments

match-documents links each payment to a document by supplier, amount and date. A match on all three makes the payment evidenced. When a match differs on amount, such as a currency difference, the payment is probable. That link counts as evidence only after a person confirms it. Each confirmed link teaches the supplier’s profile its legal name, VAT number, rates and currency, and the usual gap between invoice and charge.

Evidence state	Meaning
Evidenced	A document is linked to the payment
Probable	A document may cover the payment and waits for a person to confirm it
Missing	No document covers the payment yet
Not required	The payment needs no document, such as a bank fee or a transfer between your own accounts
Waived	A named person recorded that the payment has no document, with a reason

The Chase List

chase lists the missing documents grouped by supplier and ranked by the VAT at stake. For each supplier it gives the usual route to the invoice, with the portal and the account email. It also names the drop folder to save into. In Claude Code, /invoice-chase works the list with you one supplier at a time.

The tool never logs into a supplier’s website. You download each missing invoice from your own account and save it to the drop folder, and the next collect picks it up. When a supplier issues no document, waive the line with waive --reason none_issued, and that supplier is never chased again.

Filing Into One Archive

file puts every linked document into the archive root under a fixed rule, so you and your agent always know where a document is.

<archive root>/<Class>/<YYYY>/<MM Month>/<YYYY-MM-DD> <Counterparty> <Document number> <Kind>.<ext>

Class	What goes there
Purchases	Supplier invoices and credit notes, and receipts that serve as a supplier’s bill, such as a software subscription receipt
Expenses	Receipts for travel, fuel and meals, such as parking, tolls and diesel
Statements	Bank, merchant and payout statements, under Statements/<Provider>/

Files from the drop folder move into the archive once filed, and files from your other sources are copied, so your originals stay where they were. Every move and copy is written to filing-log.csv at the root so it can be reversed, and index.csv lists every filed document with its bank lines and ledger entries.

The priorYears setting decides where an invoice from an earlier year goes. invoice_year files it under its own year, and current_year_tagged files it under the current year with its own year in the name.

What the Evidence Changes in This Version

In version 0.1.0, the evidence does not yet change what posts. The proposals take their VAT from the rules, and the review gate does not yet read the evidence state. The chase list is how you see the gap, and your agent compares each proposal with its document before it builds the batch.