Skip to main content

Invoice Checks

Check an invoice against a contract price model, list earlier checks, and read the audit-proof restatement of a checked invoice as data, HTML or PDF file.

An invoice check reads an invoice document with the extraction model, recomputes each billed price from the contract (each invoice month priced by the version in force then) and stores the comparison. Every invoice line gets a verdict. match means the billed price equals the contract price, underbilled and overbilled carry an effect in the comparison's currency (contract price minus billed price, times quantity; positive means the biller billed less than the contract allows), and not_comparable means the line could not be compared, with a reason.

A gap carries a tier that says how firmly it stands. owed is a gap built only on independent sources. estimated rests on an invoice-printed index. potential covers a suspected amendment or a charge the contract prices that the invoice leaves off. assumed rests on an assumption. Index values the invoice prints are kept as invoice-sourced values and flagged as not independent, so a check never presents the biller's own numbers as independent evidence.

POST/v1/price-baseline/models/{id}/compare

Body fields

invoice_document_id*uuidInvoice document of the workspace.

Key response fields (201)

iduuidComparison id. Feeds the proof-invoice routes and the comparison_id parameter of the workbook.
model_id / invoice_document_iduuidThe model and the invoice document.
invoiceobjectWhat the extraction read: invoice_number, document_kind (bill, final, instalment, credit_note, cancellation), issuer, period, master data, readings, payments, totals, lines, stated_indices.
prices[]arrayThe recomputed component prices for the invoice period.
comparison.lines[]arrayPer line: baseline_price, billed_price, effect, verdict, reason, independent, tier, unbilled, weights.
comparison.totalsobjectunderbilled, overbilled, compared_lines, not_comparable_lines.
comparison.completenessobjectpartial, truncated, lines_net, printed_net, reconciliation (ok, gap, unknown), gap. partial is true when lines may be missing.
comparison.amendment_suspects[]string[]Base values that look superseded; held out of the totals.
underbilled / overbilled / currencynumber / number / stringTotals and the ISO 4217 code of every amount.
engine_versioninteger | nullPricing engine version the comparison was computed under.

cURL: Check an invoice

curl -X POST "https://api.talonic.com/v1/price-baseline/models/7b1f0a52-3c9d-4e08-a6d4-51c2e8f7b3a9/compare" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_document_id": "c91d47e0-52ab-4f63-8e1b-0a7d3c6f2b48"}'

Response: 201 Stored comparison (excerpt)

{
  "id": "e04a9b17-6d28-47c5-b3f1-9c5e2a8d7016",
  "model_id": "7b1f0a52-3c9d-4e08-a6d4-51c2e8f7b3a9",
  "invoice_document_id": "c91d47e0-52ab-4f63-8e1b-0a7d3c6f2b48",
  "currency": "EUR",
  "underbilled": 0,
  "overbilled": 2092.8,
  "comparison": {
    "currency": "EUR",
    "lines": [
      {
        "line": { "label": "Arbeitspreis Q1", "component": "AP", "quantity": 480000, "unit_price": 7.62 },
        "baseline_price": 7.184,
        "billed_price": 7.62,
        "unit": "ct/kWh",
        "effect": -2092.8,
        "verdict": "overbilled",
        "independent": true,
        "tier": "owed"
      }
    ],
    "totals": { "underbilled": 0, "overbilled": 2092.8, "compared_lines": 1, "not_comparable_lines": 0 }
  },
  "engine_version": 12,
  "created_at": "2025-04-02T08:31:07.000Z"
}
GET/v1/price-baseline/models/{id}/comparisons

Path parameters

id*uuidModel id.

Audit-Proof Restatement

The audit-proof restatement answers "what is the invoice the contract supports for this period". It restates a checked invoice line by line from the stored comparison: every line at the contract's price, and each input with its source, which is a contract passage, a publisher line with its URL, or the biller's invoice. It lists the checks that say what still keeps it from being audit-proof and carries a sha256 hash over the amounts. No model call is made, so the restatement is free and repeatable. The {id} of these routes is a comparison id, not a model id.

GET/v1/price-baseline/comparisons/{id}/proof-invoice

Path parameters

id*uuidComparison id.

Response fields

invoice.lines[]arrayPer line: label, component, period, quantity, unit_price, price_unit, amount (what the contract supports), billed_amount, delta (amount minus billed_amount; positive means the biller billed too little), formula, inputs[], verdict, unbilled, independent.
invoice.totalsobjectnet, billed_net, delta, tax_rate, tax, gross.
invoice.checks[]arrayEach with key, label, passed and detail. The keys are lines_priced, indices_published, no_assumptions, contract_values_quoted, quantities_evidenced, periods_priced, no_open_questions and engine_current.
invoice.audit_proofbooleanWhether the restatement passes the checks.
invoice.sources[]arrayNumbered sources (S1, S2, ...): kind (contract, published, invoice, assumed), what, document, url, quote, verified.
invoice.hashstringsha256 over the lines, their inputs and the engine version.
htmlstringSelf-contained HTML rendering of invoice.
GET/v1/price-baseline/comparisons/{id}/proof-invoice.pdf

Path parameters

id*uuidComparison id.

cURL: Download the audit-proof PDF

curl -OJ "https://api.talonic.com/v1/price-baseline/comparisons/e04a9b17-6d28-47c5-b3f1-9c5e2a8d7016/proof-invoice.pdf" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
The PDF route can answer with HTML. When the deployment cannot render PDFs, the same document is sent with content type text/html and the same attachment name. Check the Content-Type header of the response before treating the file as a PDF.

Frequently asked questions

What do underbilled and overbilled mean?+
The verdict compares the billed price with the contract price. effect is the contract price minus the billed price, times quantity, in the comparison currency. A positive effect means the biller billed less than the contract allows (underbilled); a negative effect means it billed more (overbilled).
What is the difference between the tiers owed, estimated, potential and assumed?+
owed rests only on independent sources. estimated uses an index the invoice itself prints. potential is a suspected amendment, or a charge the contract prices that the invoice leaves off, and is held out of the totals. assumed rests on an assumption made in the workspace.
Does checking the same invoice twice call the model twice?+
No. The same invoice read against the same contract versions is read once, and a repeat check reuses the stored extract. The comparison is recomputed from the stored extract and the current index values.
Why is audit_proof false?+
One or more of the eight checks failed, for example an input rests on an assumption (no_assumptions), an index was printed on the invoice instead of published (indices_published), or the workbook still has open questions (no_open_questions). The failing check names the reason in its detail.

Related

Price Models
Register, Prices and Workbook
Assumptions
Contract Pricing Overview