List the files in the inbox folder (PDFs, images, e-Fatura CSVs), newest first: kind (document, not_an_invoice, efatura_export), whether a PDF reads like an invoice, its status in the ledger (new, extracted, filed) and whether it is an exact copy of another inbox file.

Read everything in the inbox and return the plan, without writing anything: expense rows ready for add_expense (with the file name for file_document and any checks to resolve), sales ready for add_income (your invoice paired with its AT document), documents to read yourself, copies, non-invoices, e-Fatura exports.

Read one invoice or receipt (PDF or photo). Returns the document fields, which layer read them (qr / parser: / text), a booking proposal (VAT code, region, ECB rate, payment account, business share, document label, file name) and a ready expense row. If a PDF does not read like an invoice or receipt, its text is withheld unless read_anyway=true, so unrelated documents are not exposed.

Parse an e-Fatura CSV export into documents, each with a booking proposal.

Add one expense row to the year's expenses tab. row keys: date (YYYY-MM-DD), expense, supplier, country, supplier_vat, invoice_no, currency, amount, vat_included, fx, nif, code, business_pct, document, file, account. Refuses duplicates and quarters already filed. Call with dry_run=true first.

Read every document already in the year's folders into the ledger, so later copies are recognised. Run it once per year (and again after moving files by hand).

Move a document from the inbox into its tax-year folder under the proposed name (or name). If the same file or the same invoice is already filed, the inbox copy is deleted instead. Never overwrites and never deletes outside the inbox. e-Fatura CSV exports go to the year folder. Dry run first.

What is still missing for a year: rows flagged MISSING, rows whose file is not in the folder, rows without a date, amount or invoice number, files in the folder no row books (and receipts that duplicate a booked payment), and months missing in monthly subscriptions. For income: sales without an AT document yet, missing files and unbooked files.

Read one sale: your own invoice and/or the AT document issued on the Portal (recibo verde, fatura or fatura-recibo). Returns the income row (client, tax id, recibo no. and date, amount, rate, IVA, withholding, VAT case), the file names to file both under, and checks that the two documents belong together.

Add one sale to the year's income tab. row keys: invoice_date (YYYY-MM-DD), client, country, client_tax_id, invoice_no, recibo_no, recibo_date, currency, amount, fx, net_eur, vat_rate, vat_eur, withheld, vat_case, invoice_file, recibo_file, account. Refuses duplicates and filed quarters. Dry run first.

The IRS and Segurança Social totals at the top of the income tab, per quarter and for the year: gross income by invoice date (IRS), income by recibo date (Segurança Social quarterly declaration), and business expenses.

Compare an e-Fatura CSV export with the expenses tab: invoices not in the sheet, rows whose amount, VAT or invoice number differ (or that lack fields e-Fatura has), and Portuguese rows e-Fatura lacks.

The Declaração Periódica boxes for a quarter (Q1-Q4) as the sheet shows them, including the credit carried over (box 61) and the result boxes 90-96, and whether the quarter is already filed.

After the user submits a quarter: freeze its declaration values, grey them and lock (warning-only) the quarter's block column, expense rows and income rows. If the submitted return PDF is in the year folder (or given), its boxes are compared with the sheet; apply_pdf_values=true copies the PDF's values over the frozen ones, since the submitted return is the source of truth. Dry run first.

The purchase and sales VAT codes the sheet understands, and which return boxes each one fills.

Create a tax year's books: a local .xlsx workbook (default) or tabs in a Google Sheet, per the config. Expenses and income tables with the Declaração Periódica block (what to type each quarter, with the credit carried over), quarter sums, IRS / Segurança Social totals, formulas, dropdowns and formats. The opening credit (Q1 box 61) defaults to the previous year's Q4 box 96. Refuses to overwrite.