Invoices

Invoices and the accountant workflow over them: matching to a purchase order, PO reconciliation, tax validation, booking proposal, allocations, and hand-over to accounting.

📄️Get invoices with pagination

Retrieve a paginated list of all invoices, newest first unless sort_by says otherwise. Every ordering ends on the unique id, so pages stay disjoint for a client stitching them together.

📄️Create a new invoice

Create a new invoice with required file attachment. The file must be a PDF, an image (PNG, JPEG, TIFF, WebP) or an e-invoice XML; its content is validated, not just its name.

📄️Delete an invoice

Soft delete an invoice that is not approved.

📄️Get invoice details by code

Retrieve a specific invoice, the purchase orders it settles, and its related journal entries by business code.

📄️Update invoice

Update invoice payment and accounting status flags.

📄️Get additional invoice data

Retrieve payment terms, bank details, and other additional data.

📄️Complete additional data step

Mark the additional data collection step as complete and save payment/bank details.

📄️Replace the invoice's allocation set

Submit the full intended allocation set: target POs (same supplier), per-PO line assignments, and the buyer-entered shares of shared VAT, charges, and allowances. Validates same-supplier scope, complete line assignment, and per-bucket coverage against the document totals before persisting atomically.

📄️Get booking proposal for an invoice

Retrieve the accountant's booking proposal for an invoice.

📄️Update booking proposal

Update the booking proposal for an invoice (edits by accountant).

📄️Create invoice connection

Creates a directed connection from the path invoice (source) to the target invoice code in the body.

📄️Delete invoice connection

Deletes a connection if the path invoice is either source or target.

📄️Get corrections for an invoice

Retrieve all corrections made during invoice review.

📄️Check whether a candidate PO already carries a logical duplicate

Read-only Layer 2 comparison of an invoice against a candidate PO. Flag-gated; returns negative when the invoice_duplicate_guard flag is off for the tenant. No side effects. Object-level authorization applies: a caller who may not access the invoice is masked as 404, mirroring the matching read endpoints.

📄️Manually mark an invoice as a duplicate of another

Parks the invoice in DUPLICATE status, links it DUPLICATE_OF the named original, skips journal entry and PO advancement, and notifies the Buyer. Works regardless of the invoice_duplicate_guard flag. Requires the invoices.mark-duplicate write grant (Buyer, Accountant, Admin); the service further restricts to invoices the caller can access, and refuses the park once the invoice's workflow has progressed into accounting (READY_FOR_EXPORT_PREPARATION onward) or already ended (409).

📄️Replace invoice process marks

Replaces all process marks on an invoice. Empty marks clears them. Relational marks require matching connections (see ADR-0018).

📄️Get matching result for an invoice

Retrieve the matching result including confidence score and matched PO.

📄️Get PO candidates for an invoice

Returns the stored purchase-order candidates for an invoice, narrowed to what this caller may act on. A caller holding the ACCOUNTANT role receives the stored set as it is. Every other caller receives only the orders they requested or buy, and also loses any candidate whose purchase order no longer resolves. A row withheld here is a row that caller could not have selected, so an absent row does not mean the matcher found no candidate. The stored set itself is drawn from a tenant-wide search only for an invoice that reached no personal inbox; for one that did, the search is scoped to that recipient's own orders, and only an order the document or a card charge named is stored past that scope.

📄️Manually select a PO for an invoice

Manually match an invoice to a specific purchase order.

📄️Get PO reconciliation results

Retrieve the reconciliation comparison between invoice and purchase order with field-level comparisons. Returns supplier, product, and amount field comparisons with invoice vs PO values, match status, confidence scores, and overall reconciliation status.

📄️Confirm PO reconciliation

Confirm that the invoice matches the PO (with optional notes for mismatches).

📄️Correct PO reconciliation field

Correct an incorrectly matched PO field during reconciliation.

📄️Amend PO reconciliation discrepancy notes

Update one or more buyer-discrepancy comments on a previously confirmed PO reconciliation. Allowed only while the invoice has not been sent to accounting; does NOT change workflow status. At least one note field must be provided.

📄️Reprocess an invoice

Re-trigger document extraction for an existing invoice.

📄️Get tax validation results

Retrieve the §14 UStG validation results for an invoice with extracted fields metadata. Returns validation results along with pre-extracted field data including AI confidence scores, PO comparisons, and missing field counts.

📄️Confirm tax validation

Confirm that all tax validation fields are correct.

📄️Correct tax validation field

Correct an incorrectly extracted field during tax validation.

📄️Transfer invoice to FI (DATEV)

Submits invoice to DATEV UO, advances workflow to READY_FOR_DATEV, and optionally marks accountant task as done.

📄️Get workflow state for an invoice

Retrieve the current workflow state and available actions. Workflow auto-advances through validation steps unless issues are found.

📄️Record the accountant's verification of a buyer review step

Records that the calling accountant has independently verified the invoice's formal check or order match. Writes no workflow status. Idempotent: re-posting a step already verified keeps the first verification's actor and timestamp. Both steps must be verified before the invoice can be transferred to the FI tool.