Bills, Worklist and Totals

Read the payables overview with totals and gaps, list posting-ready vendor bills filtered by status or hold reason, and read the worklist of held bills.

Three read routes cover the payables inbox. GET /v1/ap/overview returns the state of the inbox without the bills themselves: totals, one block per legal entity, the bill sources and the last posting run. GET /v1/ap/bills returns the bills, held bills first and then by dollars at stake. GET /v1/ap/issues returns only the held bills with why they are held, the dollars at stake and the evidence, largest first. All three need the read scope.

AP finds its invoices by itself: the Spec Money Found's invoice role names, else the workspace's pipeline holding the most documents classified as invoices. New invoices, purchase orders and delivery notes are added to that pipeline once classified, when no run holds them yet and they come from a source the pipeline already reads, or a new source no other Spec reads; POST /v1/ap/intake (scope write, dry_run to only list) adds the ones that arrived before. Payment rules come from files: POST /v1/ap/rules/batches turns uploaded documents (policies, validation rules) into rules, GET /v1/ap/rules lists them, and every invoice is checked against them with the documents it links to; a failed rule holds it with the reason policy_rule and the words it rests on. The overview's gaps array lists what is missing for a complete read: no_invoice_pipeline, contracts_not_set_up / contracts_not_bound (Money Found not set up, or not reading these invoices: prices are not checked against contracts, every other check runs), processing:<role> (invoices still being read), rules_pending (invoices still being checked against the payment rules), no_binding:<role>, unreadable:<role>, ledger_unavailable and contracts_pending. configured is false only when no pipeline holds an invoice, and gaps then holds no_invoice_pipeline. totals.held.at_stake counts the dollars the holds put at stake, never more than the bill itself, while totals.held.amount is the full amount of the held bills.

curl "https://api.talonic.com/v1/ap/bills?status=held&reason=missing_po&limit=50" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "currency": "USD",
  "total": 1,
  "data": [
    {
      "key": "bill-0007",
      "document_id": "7c1e2b94-3a5d-4f08-9b6a-52d8c0e1a4f3",
      "filename": "northwind-inv-20411.pdf",
      "vendor": "Northwind Logistics",
      "invoice_number": "20411",
      "currency": "USD",
      "amount": 18450,
      "amount_base": 18450,
      "status": "held",
      "holds": [
        { "reason": "missing_po", "label": "Purchase order required", "amount": 18450, "explanation": "Freight bills must carry a PO number and this one has none." }
      ],
      "lines": [
        { "description": "Linehaul October", "amount": 18450, "sublist": "expense", "tax": false }
      ]
    }
  ]
}