{"components":{"schemas":{"envelope":{"additionalProperties":false,"description":"Uniform error envelope returned on every non-2xx response.","properties":{"error":{"additionalProperties":false,"properties":{"code":{"description":"Stable snake_case code agents key on (e.g. \"not_found\", \"forbidden\", \"conflict\").","type":"string"},"details":{"additionalProperties":true,"description":"Optional structured context — the invalid field, the required permission code.","type":"object"},"message":{"description":"Human-readable explanation.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"invoice":{"description":"An invoice header: a number, a party, a period, a total and a state. 🔴 Its lines are materialised ONCE by a generation run and never recalculated on read — an invoice is a statement of what was billed on a particular day, and a document that quietly changes when the underlying data moves is not one.","properties":{"approvedDateTime":{"type":["null","string"]},"approvedUserId":{"type":["null","string"]},"createdDateTime":{"type":["null","string"]},"createdUserId":{"type":["null","string"]},"currencyCode":{"description":"🔴 Per-invoice, not read from the tenant. Restating a historical document in today's default currency is how an invoice stops matching the one that was sent.","type":"string"},"customerId":{"description":"Set on a customer invoice, null on a driver invoice.","type":["null","string"]},"driverId":{"description":"Set on a driver invoice, null on a customer invoice.","type":["null","string"]},"dueDate":{"description":"⚠️ Null means no stated terms rather than due immediately. A driver pay statement usually has none.","type":["null","string"]},"id":{"type":"string"},"invoiceBatchId":{"description":"The generation run that produced it. ⚠️ Null for an invoice raised on its own, which is ordinary.","type":["null","string"]},"invoiceNumber":{"type":"string"},"isLocked":{"description":"🔴 True once approved. Neither the invoice nor its lines may change — an adjustment must be added BEFORE approval.","type":"boolean"},"isNumberOverridden":{"description":"⚠️ True when a caller stated the number rather than letting the scheme issue one. This is why a gapless sequence has a gap, and without it the platform gets blamed for the hole.","type":"boolean"},"issueDate":{"description":"ISO date.","type":"string"},"notes":{"type":["null","string"]},"numberSchemeCode":{"description":"Which scheme issued it. Recorded because \"why does this invoice have this number\" is asked whenever a tenant changes schemes and the sequence appears to jump.","type":["null","string"]},"periodEndDate":{"description":"ISO date.","type":"string"},"periodStartDate":{"description":"ISO date. The billing period this covers.","type":"string"},"sentDateTime":{"description":"⚠️ A different fact from \"a document was rendered\" and from \"an invoice exists\". Three states a tenant asks about separately.","type":["null","string"]},"sideCode":{"description":"`customer` (what you charge) or `driver` (what you owe the person who did the work).","type":"string"},"statusCode":{"description":"draft, approved or cancelled.","type":"string"},"subtotalAmount":{"description":"Decimal string. ⚠️ A string, not a number — JSON numbers are IEEE doubles and money is not.","type":"string"},"taxAmount":{"description":"Decimal string. ⚠️ Summed from the lines, never computed here — the moment invoicing calculates tax, Mesh is in the tax-jurisdiction business.","type":"string"},"totalAmount":{"description":"Decimal string.","type":"string"},"updatedDateTime":{"type":["null","string"]},"updatedUserId":{"type":["null","string"]}},"required":["id","sideCode","statusCode","invoiceNumber","periodStartDate","periodEndDate","issueDate","currencyCode","subtotalAmount","taxAmount","totalAmount","isLocked"],"type":"object"},"invoiceBatch":{"description":"One generation run over a scope and a timeframe. 🔴 An API in its own right — submit it, poll it, then ask it for the invoices it produced. ⭐ A scheduled run creates the same record, so the identifier nobody saw at the time can still be asked for afterwards.","properties":{"completedDateTime":{"type":["null","string"]},"correlationId":{"type":["null","string"]},"createdDateTime":{"type":["null","string"]},"exceptionsRaised":{"type":"integer"},"failureReason":{"type":["null","string"]},"id":{"type":"string"},"invoiceScheduleId":{"type":["null","string"]},"invoicesCreated":{"type":"integer"},"partiesInScope":{"description":"Null until the run has worked out how many there are. ⚠️ Reporting 0 of 0 during that step would read as a finished run that did nothing.","type":["null","integer"]},"partiesProcessed":{"type":"integer"},"periodEndDate":{"type":"string"},"periodStartDate":{"type":"string"},"requestedUserId":{"description":"⚠️ Null when a schedule started the run. Null is the difference between a run somebody asked for and one the clock asked for, not missing data.","type":["null","string"]},"sideCode":{"type":"string"},"startedDateTime":{"type":["null","string"]},"statusCode":{"description":"⚠️ `completed_with_exceptions` is NEITHER success NOR failure — it is what you asked for when you chose to continue past something unexpected. Collapsing it into either neighbour is how a run that skipped two hundred unapproved charges gets read as clean.","type":"string"},"stopWithoutChargesBehaviourCode":{"type":"string"},"unapprovedChargeBehaviourCode":{"description":"🔴 Resolved from the settings cascade at submit time and FROZEN. The setting can change; what this run was told to do cannot.","type":"string"}},"required":["id","sideCode","statusCode","periodStartDate","periodEndDate","partiesProcessed","invoicesCreated","exceptionsRaised"],"type":"object"},"invoiceBatchException":{"description":"🔴 WHAT A GENERATION RUN MET AND DID NOT SWALLOW. One row per occurrence when you chose to continue rather than fault. ⚠️ Silence is the one unacceptable answer — a run that quietly omitted work and produced a total that is wrong is the failure this exists to prevent.","properties":{"createdDateTime":{"type":"string"},"customerId":{"type":["null","string"]},"detail":{"description":"A sentence a person can act on. ⚠️ Required — an exception with a code and no words gets triaged as noise.","type":"string"},"driverId":{"type":["null","string"]},"exceptionCode":{"type":"string"},"excludedAmount":{"description":"⚠️ What was left out, in money. Without it, \"two hundred charges skipped\" says nothing about whether the invoice is four dollars light or forty thousand.","type":["null","string"]},"id":{"type":"string"},"invoiceBatchId":{"type":"string"},"invoiceId":{"description":"🔴 The invoice produced in spite of it, when one was. Null when the run skipped the party entirely. This is the field that answers \"is this total short, and by what?\"","type":["null","string"]},"isResolved":{"type":"boolean"},"resolvedDateTime":{"type":["null","string"]},"resolvedUserId":{"type":["null","string"]},"stopChargeId":{"type":["null","string"]},"stopCostId":{"type":["null","string"]},"stopId":{"type":["null","string"]}},"required":["id","invoiceBatchId","exceptionCode","detail","isResolved","createdDateTime"],"type":"object"},"invoiceDocument":{"description":"🔴 A RERUN PRODUCES VERSION 2, NOT A REPLACEMENT. A driver forgets a Friday stop, the weekly pay invoice is short, he completes it on his phone, the invoice is rerun — and the first file, already emailed, is superseded rather than erased.","properties":{"byteSize":{"type":["null","integer"]},"contentType":{"type":"string"},"createdDateTime":{"type":["null","string"]},"id":{"type":"string"},"invoiceId":{"type":"string"},"renderedDocumentId":{"description":"The renderer's own record of the attempt.","type":["null","string"]},"sentDateTime":{"description":"⚠️ A different fact from the invoice-level one. Version 1 went out on Friday; version 2 may never be sent.","type":["null","string"]},"storageKey":{"type":"string"},"supersedeReason":{"type":["null","string"]},"version":{"description":"⚠️ The version of THIS invoice's document, not of the template.","type":"integer"}},"required":["id","invoiceId","version","storageKey","contentType"],"type":"object"},"invoiceDocumentDownload":{"description":"🔴 A TIME-LIMITED LINK TO THE FILE, NOT THE FILE. The browser fetches from object storage directly — `storage.md` invariant 2 forbids private bytes transiting this service, and a multi-megabyte document through a Worker is paid for twice and times out at about the size a real invoice batch produces.\n\n⚠️ **Treat the URL as a secret.** It carries its own signature, so anyone holding it can fetch the bytes without a token, and it CANNOT be revoked — only expired. Do not log it, do not put it in an email, do not store it.","properties":{"expiresDateTime":{"description":"When it stops working, as an absolute time — so a caller does not have to guess when \"now\" was.","type":"string"},"expiresInSeconds":{"description":"How long the link lives from now.","type":"integer"},"fileName":{"description":"⭐ What the file is called when it lands. The invoice NUMBER, not the storage key — the key carries the internal id on purpose (design ADR 0094).","type":"string"},"url":{"description":"Fetch this with a plain GET and no Authorization header. ⚠️ Single use in practice: ask again rather than keeping one.","type":"string"}},"required":["url","expiresInSeconds","expiresDateTime"],"type":"object"},"invoiceLine":{"description":"🔴 AN INVOICE LINE IS NOT A CHARGE LINE. One row here may stand for 250 charge lines; the link back is carried on the CHARGE, not here. ⭐ And a line need have no underlying work at all — a weekly-minimum make-up line has no charge, no cost and no stop behind it.","properties":{"accountCode":{"description":"The accounting account this line posts to. ⚠️ Carried, never interpreted — accounting integration is a later phase and this is the field it will read.","type":["null","string"]},"amount":{"description":"Decimal string, excluding tax.","type":"string"},"builderCode":{"description":"⚠️ Which rule produced this line. NULL means a person added it by hand — a manual adjustment is first-class and has no builder.","type":["null","string"]},"createdDateTime":{"type":["null","string"]},"createdUserId":{"type":["null","string"]},"description":{"type":"string"},"groupDate":{"description":"The date half of the roll-up group key.","type":["null","string"]},"id":{"type":"string"},"invoiceId":{"type":"string"},"lineNumber":{"description":"Position on the document. Explicit rather than ordering by id, so an adjustment added before approval sits at the bottom regardless of when the surrounding lines were built.","type":"integer"},"quantity":{"description":"Decimal string. ⚠️ A ROLLED-UP LINE HAS QUANTITY 1 and a summed total — the count of jobs behind it is `sourceCount`, because putting 250 here would make quantity × unitAmount contradict `amount` on the face of the document.","type":"string"},"rateTypeCode":{"description":"The charge-type half of the roll-up group key.","type":["null","string"]},"sourceCount":{"description":"🔴 How many jobs a rolled-up line stands for. \"Delivery Charges — 250 stops\" is the difference between a line a customer accepts and one they ring about.","type":["null","integer"]},"taxAmount":{"description":"Decimal string. Summed from the charge lines behind this one; never computed here.","type":["null","string"]},"unitAmount":{"description":"Decimal string, scale 4 — a per-kilogram or per-kilometre rate is routinely sub-cent.","type":["null","string"]}},"required":["id","invoiceId","lineNumber","description","quantity","amount"],"type":"object"},"invoiceLineBuilder":{"description":"🔴 A RULE THAT CONSTRUCTS INVOICE LINES, and the selection is a BITMASK held on the party being billed rather than a mode chosen per run. ⭐ `bit` IS the value to OR together. ⚠️ Only one pair excludes each other; everything else combines freely, which is why *roll up* versus *itemise* is not a two-way switch.","properties":{"bit":{"description":"🔴 The power of two to OR into `builderMask`. 1, 2, 4, 8, 16, 32, 64, 128.","type":"integer"},"code":{"description":"Stable machine code.","type":"string"},"description":{"type":["null","string"]},"hasSource":{"description":"🔴 WHETHER MESH HAS ANYWHERE TO READ THIS BUILDER'S INPUT FROM. False for six of the eight today — nothing attaches a service to a stop, a trip or a run; there is no adjustment-rules table; nothing records a driver's agreed minimum; and one-off adjustments exist as a line a person adds rather than as standing data. ⚠️ Selecting one anyway is allowed and produces a reported exception on every run rather than silence.","type":"boolean"},"id":{"description":"Opaque identifier. ⚠️ Numerically equal to `bit`, but use `bit` for arithmetic — that is what it is for.","type":"string"},"incompatibleWith":{"description":"⭐ Which builders may not be selected alongside this one, and why. Published so a caller can assemble a valid selection without trial and error; the API refuses an illegal combination and a check constraint stops it existing at rest.","items":{"additionalProperties":false,"properties":{"code":{"type":"string"},"reason":{"type":"string"}},"required":["code","reason"],"type":"object"},"type":"array"},"name":{"description":"Human-readable label.","type":"string"},"sideCode":{"description":"Which side this builder produces lines for — `customer` or `driver`. ⚠️ NULL means BOTH: the one-off adjustment builder applies equally to each.","type":["null","string"]},"sortOrder":{"type":"integer"}},"required":["id","code","name","bit","incompatibleWith","hasSource"],"type":"object"},"invoiceNumberScheme":{"description":"🔴 NUMBERING IS AN ALGORITHM YOU CHOOSE, NOT A GAPLESS-OR-NOT SWITCH. ⭐ Gaplessness — an unbroken run with none skipped, which several jurisdictions require by law — is a property of the scheme, not a promise the platform makes everywhere.","properties":{"code":{"type":"string"},"description":{"type":["null","string"]},"id":{"type":"string"},"isGapless":{"description":"Whether this scheme produces an unbroken run within its scope.","type":"boolean"},"name":{"type":"string"},"serialisesScope":{"description":"🔴 WHETHER ISSUING A NUMBER TAKES A LOCK THAT BLOCKS OTHER GENERATION IN THE SAME SCOPE. Per customer is cheap — a batch still generates in parallel across the rest. Per tenant is a SINGLE LOCK ACROSS A WHOLE BATCH, so five thousand invoices issue their numbers one at a time. Published so the cost is chosen knowingly rather than discovered.","type":"boolean"},"sortOrder":{"type":"integer"}},"required":["id","code","name","isGapless","serialisesScope"],"type":"object"},"invoiceSchedule":{"description":"When a tenant wants generation to run on its own. ⭐ A scheduled run creates an ordinary batch, so its identifier can still be asked for afterwards even though nobody saw it at the time.","properties":{"cronExpression":{"description":"Standard five-field cron, interpreted in `timezone`.","type":"string"},"id":{"type":"string"},"isEnabled":{"type":"boolean"},"lastRunDateTime":{"type":["null","string"]},"name":{"type":"string"},"nextRunDateTime":{"type":["null","string"]},"periodDays":{"description":"How far back the run looks from the moment it fires. A weekly Monday run covering the previous seven days is 7.","type":"integer"},"recipients":{"description":"Email addresses told when a run finishes.","items":{"type":"string"},"type":"array"},"sideCode":{"type":"string"},"timezone":{"description":"⚠️ NOT OPTIONAL AND NEVER SILENTLY UTC. A weekly billing run firing at the wrong local hour crosses a period boundary and invoices the wrong week.","type":"string"}},"required":["id","sideCode","name","cronExpression","timezone","periodDays","isEnabled"],"type":"object"},"invoicingSettings":{"description":"How a party wants to be invoiced. ⭐ ONE TABLE, THREE SCOPES, ONE CASCADE — a tenant default, overridden per customer and per driver. Every value is nullable and null means INHERIT, which is what makes the resolution uniform instead of three sets of rules.","properties":{"builderMask":{"description":"🔴 A bitmask over the builder `bit` values. Null means inherit; 0 means BUILD NOTHING, which is a different statement. ⚠️ Rolling up and not rolling up together is refused by the API with a readable error AND by a database check constraint — this column is written directly by migrations and support scripts, which never go through the API.","type":["null","integer"]},"customerId":{"type":["null","string"]},"documentTemplateId":{"description":"🔴 Which template this party’s invoice is rendered with — an id from public-api-document-rendering. ⚠️ **Null means INHERIT**, as everywhere else here: a tenant sets a base per side and overrides it for one customer or one driver. ⚠️ **Null at every level means nothing is configured** and generating a document refuses, because there is no default — a document with nobody’s letterhead is not one a tenant would send.","type":["null","string"]},"driverId":{"type":["null","string"]},"id":{"type":["null","string"]},"invoiceNumberPrefix":{"type":["null","string"]},"invoiceNumberSuffix":{"type":["null","string"]},"isChargeApprovalRequired":{"description":"🔴 Whether priced work must be approved before generation may use it. ⚠️ Applied INSIDE the aggregation query — an unapproved charge never reaches the roll-up, rather than being summed and then removed.","type":["null","boolean"]},"isInvoiceApprovalRequired":{"description":"Whether the invoice itself needs approving. Approval locks, so this decides whether adjustment lines have a window at all.","type":["null","boolean"]},"numberSchemeCode":{"type":["null","string"]},"scopeCode":{"description":"tenant, customer or driver.","type":"string"},"sideCode":{"description":"⚠️ A customer-scope row must be on the customer side and a driver-scope row on the driver side — a customer has no cost side, and a driver is paid rather than charged.","type":"string"},"stopWithoutChargesBehaviourCode":{"description":"⚠️ Not about what a customer may see — about the run. A stop with no charge lines may be deliberately free or may be work nobody billed for, and only a person can tell.","type":["null","string"]},"unapprovedChargeBehaviourCode":{"description":"fault or continue_and_report. Defaults to fault.","type":["null","string"]}},"required":["scopeCode","sideCode"],"type":"object"},"lookup":{"description":"A platform-owned vocabulary entry. ⚠️ READ ONLY — the same for every tenant and not editable through any API. They exist so a caller can discover the legal values of a code field.","properties":{"code":{"description":"Stable machine code. Key your logic on this, not on the id.","type":"string"},"description":{"description":"What the value means.","type":["null","string"]},"id":{"description":"Opaque identifier.","type":"string"},"name":{"description":"Human-readable label.","type":"string"},"sortOrder":{"description":"Display order.","type":"integer"}},"required":["id","code","name"],"type":"object"},"resolvedInvoicingSettings":{"description":"⭐ WHAT A GENERATION RUN WILL ACTUALLY DO FOR THIS PARTY, after the cascade. Every value is non-null; `resolvedFrom` says which scope each one came from, because \"why is this customer being invoiced like that\" is otherwise three queries and a guess.","properties":{"builderCodes":{"description":"The mask spelled out, so a reader does not have to do binary arithmetic.","items":{"type":"string"},"type":"array"},"builderMask":{"type":"integer"},"customerId":{"type":["null","string"]},"documentTemplateId":{"description":"🔴 Which template this party’s invoice is rendered with — an id from public-api-document-rendering. ⚠️ **Null means INHERIT**, as everywhere else here: a tenant sets a base per side and overrides it for one customer or one driver. ⚠️ **Null at every level means nothing is configured** and generating a document refuses, because there is no default — a document with nobody’s letterhead is not one a tenant would send.","type":["null","string"]},"driverId":{"type":["null","string"]},"invoiceNumberPrefix":{"type":["null","string"]},"invoiceNumberSuffix":{"type":["null","string"]},"isChargeApprovalRequired":{"type":"boolean"},"isInvoiceApprovalRequired":{"type":"boolean"},"numberSchemeCode":{"type":"string"},"resolvedFrom":{"additionalProperties":{"type":"string"},"description":"Per setting, the scope it came from — `tenant`, `customer`, `driver`, or `platform-default` when nothing anywhere set it.","type":"object"},"sideCode":{"type":"string"},"stopWithoutChargesBehaviourCode":{"type":"string"},"unapprovedChargeBehaviourCode":{"type":"string"}},"required":["sideCode","builderMask","numberSchemeCode","isChargeApprovalRequired","isInvoiceApprovalRequired","unapprovedChargeBehaviourCode","stopWithoutChargesBehaviourCode","resolvedFrom"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT (Mesh IAM-issued)","description":"Mesh IAM JWT obtained via OAuth2 client_credentials against the Mesh IAM token endpoint for your environment (call get_connection_details on the Mesh MCP server, which returns it along with every API base URL). Validated locally against the IAM JWKS; iss / aud / exp checked (ADR 0025). Locally, DEV_BYPASS_AUTH=1 accepts any non-empty bearer.","scheme":"bearer","type":"http"}}},"info":{"description":"Turn work the platform has already priced into an invoice a human can read, send and dispute — billing a customer for deliveries done, and paying the driver who did them, from one service and one model.\n\n🔴 **An invoice line is not a charge line, and that single fact shapes everything here.** A charge line is one priced fact about one job; an invoice line is a line a human reads. A customer with around 100 drivers each delivering around 250 packages a day, invoiced weekly, has roughly **7,000 charge lines in one period** — one invoice line each is not a document anybody can read, send or dispute. **Rolling many charges into one line is the normal case, not a refinement.**\n\n🔴 **Which rules apply is a property of the party being billed**, not of the run. Eight builders, selected as a bitmask on the customer or the driver. Only roll-up and no-roll-up exclude each other; the other six combine freely — so *roll everything up* versus *itemise everything* is **not** a two-way switch.\n\n🔴 **Six of the eight builders have no source data in Mesh, and the API says so rather than pretending.** Nothing attaches a service to a stop, a trip or a run; there is no adjustment-rules table; nothing records a driver’s agreed weekly minimum. Selecting one produces a **reported exception** on every run rather than silence. Check `hasSource` on `/api/invoice-line-builders`.\n\n🔴 **Silence is the one unacceptable answer.** An unapproved charge in scope, or a stop carrying no charges at all, is governed by an enum you set — defaulting to refusing the run. When you choose to continue instead, every occurrence becomes a row on the batch, carrying the amount that was left out.\n\n🔴 **Approval locks an invoice.** An adjustment line must be added before it; afterwards a correction is a new document version or a credit, never an edit.\n\n⚠️ **Every amount is a decimal string, not a JSON number.** JSON numbers are IEEE doubles and money is not.\n\n⏸ **Nothing is rendered or delivered from here today.** The renderer writes to object storage and no bucket is bound anywhere; all four email sending identities failed on 2026-11-06. Everything up to producing the invoice works.\n\nGenerated from route schemas — never hand-edited. Source: https://github.com/loc-mesh/public-api-invoicing","title":"Invoicing API","version":"1.0.19"},"openapi":"3.1.0","paths":{"/api":{"get":{"description":"What this service is, what it owns, what it deliberately does not own, and the permissions needed to use it. No authentication required.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"Default Response"}},"summary":"Self-describing service root.","tags":["meta"]}},"/api/health":{"get":{"description":"Returns 200 with the canonical health body (design/quality-standards.md §3) once the process has booted. Has no dependencies and never fails unless the API itself is down. Public — no token required.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Liveness payload.","properties":{"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"Always true on success.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment"],"type":"object"}}},"description":"Liveness payload."}},"security":[],"summary":"Liveness check.","tags":["discovery"]}},"/api/health/db":{"get":{"description":"Returns 200 only if the loc-mesh Postgres is reachable. On failure returns 503 with the uniform error envelope. Public — used by the dev portal and readiness gates.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Readiness payload.","properties":{"dependency":{"description":"The dependency this readiness check probes.","type":"string"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"type":"boolean"},"serverTime":{"description":"Database server time, useful for clock-skew checks against the API host.","type":"string"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependency","serverTime"],"type":"object"}}},"description":"Readiness payload."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Database unreachable."}}},"description":"Database unreachable."}},"security":[],"summary":"Readiness — Postgres reachability.","tags":["discovery"]}},"/api/health/ready":{"get":{"description":"Probes every critical dependency in parallel, each with a short per-probe timeout. Returns 200 when every critical dependency is reachable, 503 otherwise. The body shape is identical on both (ADR 0023 carve-out from the uniform error envelope). Public — no token required so readiness gates work before a caller has provisioned credentials. The only critical dependency is the loc-mesh Postgres.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Aggregate readiness payload. Identical shape on 200 and 503.","properties":{"dependencies":{"items":{"additionalProperties":false,"properties":{"critical":{"description":"When true, this dependency being down forces overall ok=false (503).","type":"boolean"},"error":{"description":"Short, leak-free failure reason (present only when ok is false).","type":"string"},"latencyMs":{"description":"How long this probe took, in milliseconds.","type":"integer"},"name":{"description":"Dependency name (e.g. \"postgres\").","type":"string"},"ok":{"description":"Whether this dependency probe succeeded.","type":"boolean"}},"required":["name","critical","ok","latencyMs"],"type":"object"},"type":"array"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"True only if every critical dependency is ok.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependencies"],"type":"object"}}},"description":"Aggregate readiness payload. Identical shape on 200 and 503."},"503":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Aggregate readiness payload. Identical shape on 200 and 503.","properties":{"dependencies":{"items":{"additionalProperties":false,"properties":{"critical":{"description":"When true, this dependency being down forces overall ok=false (503).","type":"boolean"},"error":{"description":"Short, leak-free failure reason (present only when ok is false).","type":"string"},"latencyMs":{"description":"How long this probe took, in milliseconds.","type":"integer"},"name":{"description":"Dependency name (e.g. \"postgres\").","type":"string"},"ok":{"description":"Whether this dependency probe succeeded.","type":"boolean"}},"required":["name","critical","ok","latencyMs"],"type":"object"},"type":"array"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"True only if every critical dependency is ok.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependencies"],"type":"object"}}},"description":"Aggregate readiness payload. Identical shape on 200 and 503."}},"security":[],"summary":"Deep readiness — every critical dependency, probed in parallel.","tags":["discovery"]}},"/api/invoice-batch-exceptions/{exceptionId}/resolve":{"post":{"description":"⚠️ THIS CHANGES NOTHING ABOUT THE INVOICE. It records that a person looked at the exception and acted — or decided no action was needed. The working queue is the unresolved ones; without a way to clear them it fills up and stops being read, which is the same as not reporting at all.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"exceptionId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Resolved."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Mark an exception as dealt with.","tags":["batches"]}},"/api/invoice-batch-statuses":{"get":{"description":"⚠️ `completed_with_exceptions` is NEITHER success NOR failure — it is what you asked for when you chose to continue past something unexpected. Collapsing it into either neighbour is how a run that skipped two hundred unapproved charges gets read as clean.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"How a generation run can end.","tags":["vocabularies"]}},"/api/invoice-batches":{"get":{"parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Defaults to 50; above 200 is clamped.","in":"query","name":"limit","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"in":"query","name":"sideCode","required":false,"schema":{"enum":["customer","driver"],"type":"string"}},{"description":"⚠️ `completed_with_exceptions` is neither success nor failure — it is what you asked for when you chose to continue past something unexpected.","in":"query","name":"statusCode","required":false,"schema":{"enum":["queued","running","completed","completed_with_exceptions","failed","cancelled"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceBatch"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page, or null if this is the last page.","type":["null","string"]}},"required":["items","nextCursor"],"type":"object"}}},"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"List generation runs.","tags":["batches"]},"post":{"description":"Submit a scope and a timeframe; get a batch identifier back; then ask it for the invoices it produced and the exceptions it met.\n\n⚠️ **No named parties means EVERY ELIGIBLE one** — the ordinary weekly run. Eligible is read from the WORK rather than from a party list: a customer with no completed, uncovered stops in the period is not in scope, because generating an empty invoice for every customer a tenant ever had is how a billing run produces four hundred documents nobody wanted.\n\n🔴 **One party faulting does not take down the batch.** Each is generated independently; a fault is recorded against that party and the run carries on, finishing `completed_with_exceptions`. One unapproved charge for one customer aborting a run of four hundred is how a weekly billing run never completes.\n\n⚠️ **The run is synchronous today**, so this call returns when it is finished. The record exists anyway, because a scheduled run makes the same one and nobody sees its identifier at the time.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"correlationId":{"description":"Carried through so the run can be followed across services in the telemetry store.","maxLength":200,"type":["string","null"]},"customerIds":{"description":"Restrict the run to these customers. Customer side only.","items":{"pattern":"^[0-9]+$","type":"string"},"maxItems":1000,"type":"array"},"driverIds":{"description":"Restrict the run to these drivers. Driver side only.","items":{"pattern":"^[0-9]+$","type":"string"},"maxItems":1000,"type":"array"},"dueDate":{"format":"date","type":["string","null"]},"issueDate":{"description":"Defaults to today. Goes on the face of every invoice produced.","format":"date","type":"string"},"periodEndDate":{"description":"Inclusive.","format":"date","type":"string"},"periodStartDate":{"description":"Inclusive. Stops are billed under the date they were COMPLETED, not booked.","format":"date","type":"string"},"sideCode":{"description":"Bill customers, or pay drivers. ⚠️ One side per run — they read different source tables and resolve different settings.","enum":["customer","driver"],"type":"string"}},"required":["sideCode","periodStartDate","periodEndDate"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceBatch"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Submit a generation run.","tags":["batches"]}},"/api/invoice-batches/{batchId}":{"get":{"description":"⚠️ `partiesInScope` IS NULL until the run has worked out how many there are. Reporting 0 of 0 during that step would read as a finished run that did nothing.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"batchId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceBatch"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Poll a generation run.","tags":["batches"]}},"/api/invoice-batches/{batchId}/exceptions":{"get":{"description":"🔴 SILENCE IS THE ONE UNACCEPTABLE ANSWER, and this is the half that makes it impossible. One row per occurrence when you chose to continue rather than fault.\n\n⭐ `excludedAmount` says what was left out in money — without it, \"two hundred charges skipped\" tells you nothing about whether the invoice is four dollars light or forty thousand.\n\n⚠️ A `stop_without_charges` row is an ESCALATION, not a log line. A stop with no charges may be deliberately free or may be work nobody billed for, and only a person can tell. The fix needs no new API: add a charge to the stop through the stops service.","parameters":[{"description":"Only this kind. Legal values from GET /api/invoice-exception-kinds.","in":"query","name":"exceptionCode","required":false,"schema":{"type":"string"}},{"description":"Only the ones nobody has dealt with.","in":"query","name":"unresolvedOnly","required":false,"schema":{"enum":["true","false"],"type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"batchId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceBatchException"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"What the run met and did not swallow.","tags":["batches"]}},"/api/invoice-batches/{batchId}/invoices":{"get":{"description":"The last call of the batch API: submit, poll, then ask for what it made.","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"batchId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoice"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page, or null if this is the last page.","type":["null","string"]}},"required":["items","nextCursor"],"type":"object"}}},"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Every invoice this run produced.","tags":["batches"]}},"/api/invoice-exception-behaviours":{"get":{"description":"🔴 YOU CHOOSE; THE PLATFORM DOES NOT IMPOSE. Both conditions default to refusing the run, because generating an invoice that quietly omits work produces a total that is wrong with nothing saying so.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"What a run does when it meets something unexpected.","tags":["vocabularies"]}},"/api/invoice-exception-kinds":{"get":{"description":"⚠️ A stop with no charges at all is one of them. It may be deliberately free or it may be work nobody billed for, and only a person can tell — which is why it is an escalation rather than a log line.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"The things a run reports rather than swallows.","tags":["vocabularies"]}},"/api/invoice-line-builders":{"get":{"description":"🔴 THE ONE TO READ FIRST. The selection is a BITMASK held on the party being billed, not a mode chosen per run — OR the `bit` values together. ⭐ `incompatibleWith` is published so you can assemble a valid selection without trial and error; only one pair excludes each other, and everything else combines freely, which is why *roll up* versus *itemise* is NOT a two-way switch.\n\n🔴 **Check `hasSource` before selecting.** Six of the eight have nowhere in Mesh to read their input from — nothing attaches a service to a stop, a trip or a run; there is no adjustment-rules table; nothing records a driver's agreed minimum. Selecting one is allowed and produces a reported exception on every run rather than silence.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceLineBuilder"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"The eight rules that construct invoice lines.","tags":["vocabularies"]}},"/api/invoice-number-schemes":{"get":{"description":"🔴 AN ALGORITHM YOU CHOOSE, NOT A GAPLESS-OR-NOT SWITCH. ⭐ `isGapless` says whether the scheme produces an unbroken run within its scope — which several jurisdictions require by law. ⚠️ `serialisesScope` says whether issuing a number takes a lock that blocks other generation: per customer is cheap, per tenant is ONE LOCK ACROSS A WHOLE BATCH, so five thousand invoices issue their numbers one at a time. Published so the cost is chosen knowingly rather than discovered.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceNumberScheme"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"How an invoice can be numbered.","tags":["vocabularies"]}},"/api/invoice-schedules":{"get":{"description":"⭐ A scheduled run creates an ORDINARY batch, so the identifier nobody saw at the time can still be asked for afterwards — which is what makes \"which run produced this invoice, and what did it report\" answerable on Tuesday about Monday's run.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceSchedule"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"When generation runs on its own.","tags":["schedules"]},"post":{"description":"⚠️ Created disabled unless you say otherwise, so a schedule is written and checked before it is armed.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"cronExpression":{"description":"Standard five-field cron, interpreted in `timezone`. ⚠️ Checked for shape — an expression that could never fire is refused, because a schedule that is silently never due looks identical to one nobody enabled.","maxLength":200,"minLength":1,"type":"string"},"isEnabled":{"description":"Defaults to false, so a schedule is written before it is armed.","type":"boolean"},"name":{"maxLength":200,"minLength":1,"type":"string"},"periodDays":{"description":"How far back the run looks from the moment it fires. A weekly Monday run covering the previous seven days is 7.","minimum":1,"type":"integer"},"recipients":{"description":"Told when a run finishes. ⚠️ On PATCH this REPLACES the whole set — a partial update is a sequence of adds and removes a caller cannot express atomically, and the half-applied result is a billing summary sent to somebody who left.","items":{"maxLength":320,"type":"string"},"maxItems":50,"type":"array"},"sideCode":{"enum":["customer","driver"],"type":"string"},"timezone":{"description":"🔴 AN IANA ZONE, AND NOT OPTIONAL. Validated against the runtime's own database. A weekly billing run firing at the wrong local hour crosses a period boundary and invoices the wrong week.","maxLength":100,"minLength":1,"type":"string"}},"required":["sideCode","name","cronExpression","timezone","periodDays"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceSchedule"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Create a schedule.","tags":["schedules"]}},"/api/invoice-schedules/{scheduleId}":{"delete":{"description":"⚠️ Soft delete. The batches it already started keep pointing at it, so \"which schedule produced this run\" stays answerable.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"scheduleId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Delete a schedule.","tags":["schedules"]},"get":{"parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"scheduleId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceSchedule"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Get one schedule.","tags":["schedules"]},"patch":{"description":"⚠️ `recipients` replaces the whole set rather than merging into it.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"scheduleId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"cronExpression":{"description":"Standard five-field cron, interpreted in `timezone`. ⚠️ Checked for shape — an expression that could never fire is refused, because a schedule that is silently never due looks identical to one nobody enabled.","maxLength":200,"minLength":1,"type":"string"},"isEnabled":{"description":"Defaults to false, so a schedule is written before it is armed.","type":"boolean"},"name":{"maxLength":200,"minLength":1,"type":"string"},"periodDays":{"description":"How far back the run looks from the moment it fires. A weekly Monday run covering the previous seven days is 7.","minimum":1,"type":"integer"},"recipients":{"description":"Told when a run finishes. ⚠️ On PATCH this REPLACES the whole set — a partial update is a sequence of adds and removes a caller cannot express atomically, and the half-applied result is a billing summary sent to somebody who left.","items":{"maxLength":320,"type":"string"},"maxItems":50,"type":"array"},"sideCode":{"enum":["customer","driver"],"type":"string"},"timezone":{"description":"🔴 AN IANA ZONE, AND NOT OPTIONAL. Validated against the runtime's own database. A weekly billing run firing at the wrong local hour crosses a period boundary and invoices the wrong week.","maxLength":100,"minLength":1,"type":"string"}},"required":[],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceSchedule"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Update a schedule.","tags":["schedules"]}},"/api/invoice-sides":{"get":{"description":"🔴 Two sides, recorded independently, and the same stop is answered for both. The driver side is the customer model reading cost lines instead of charge lines — the same shape, a different source.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Billing a customer, or paying a driver.","tags":["vocabularies"]}},"/api/invoice-statuses":{"get":{"description":"🔴 Approval LOCKS an invoice — an adjustment must be added before it. After approval a correction is a new document version or a credit, never an edit.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Where an invoice is in its life.","tags":["vocabularies"]}},"/api/invoices":{"get":{"description":"Cursor-paginated, newest first, scoped to the calling tenant. ⭐ Filter by `invoiceBatchId` for every invoice one generation run produced — the last call of the batch API.","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Defaults to 50; above 200 is clamped.","in":"query","name":"limit","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Billing a customer, or paying a driver.","in":"query","name":"sideCode","required":false,"schema":{"enum":["customer","driver"],"type":"string"}},{"in":"query","name":"statusCode","required":false,"schema":{"enum":["draft","approved","cancelled"],"type":"string"}},{"in":"query","name":"customerId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"in":"query","name":"driverId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"in":"query","name":"invoiceBatchId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Exact match.","in":"query","name":"invoiceNumber","required":false,"schema":{"maxLength":200,"type":"string"}},{"description":"Invoices whose period ends on or after this date.","in":"query","name":"periodFrom","required":false,"schema":{"format":"date","type":"string"}},{"description":"Invoices whose period starts on or before this date.","in":"query","name":"periodTo","required":false,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoice"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page, or null if this is the last page.","type":["null","string"]}},"required":["items","nextCursor"],"type":"object"}}},"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"List invoices.","tags":["invoices"]},"post":{"description":"⚠️ IT HAS NO LINES. A one-off invoice is a header plus whatever lines you add — the same path an adjustment takes. Pulling work into it would make it a one-party generation run with a different name; use POST /api/invoice-batches for that.\n\n⭐ The number is issued by the scheme the settings cascade resolves to, unless you state one. 🔴 Stating one sets `isNumberOverridden`, which is the honest record of why a gapless sequence later has a hole in it.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"currencyCode":{"description":"Defaults to the tenant's. 🔴 Stored per invoice — restating a historical document in today's default is how an invoice stops matching the one that was sent.","maxLength":3,"minLength":3,"type":"string"},"customerId":{"description":"Required on a customer invoice.","pattern":"^[0-9]+$","type":["string","null"]},"driverId":{"description":"Required on a driver invoice.","pattern":"^[0-9]+$","type":["string","null"]},"dueDate":{"description":"⚠️ Null means no stated terms rather than due immediately.","format":"date","type":["string","null"]},"invoiceNumber":{"description":"🔴 An explicit override. Sets isNumberOverridden.","maxLength":200,"type":["string","null"]},"issueDate":{"description":"Defaults to today.","format":"date","type":"string"},"notes":{"maxLength":4000,"type":["string","null"]},"periodEndDate":{"format":"date","type":"string"},"periodStartDate":{"format":"date","type":"string"},"sideCode":{"enum":["customer","driver"],"type":"string"}},"required":["sideCode","periodStartDate","periodEndDate"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Raise an invoice by hand.","tags":["invoices"]}},"/api/invoices/{invoiceId}":{"get":{"description":"⚠️ An invoice belonging to another tenant answers 404, not 403 — confirming that an id exists is itself a disclosure.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Get one invoice.","tags":["invoices"]}},"/api/invoices/{invoiceId}/approve":{"post":{"description":"🔴 APPROVAL LOCKS. After this neither the invoice nor its lines may change, and a correction is a new document version or a credit rather than an edit. ⚠️ So an adjustment line has to be added BEFORE.\n\nIdempotent — approving an approved invoice is a no-op rather than a conflict, because a retry after a dropped response must not look like an error.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Approve an invoice, which LOCKS it.","tags":["invoices"]}},"/api/invoices/{invoiceId}/cancel":{"post":{"description":"🔴 CANCELLED, NOT DELETED, AND THE DIFFERENCE IS LOAD-BEARING. The stops this invoice covered keep their coverage rows and its number stays reserved. Deleting it would erase the record that those stops were ever invoiced — which is the exact failure the schema refuses by giving the coverage link no on-delete action.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Cancel an invoice.","tags":["invoices"]}},"/api/invoices/{invoiceId}/documents":{"get":{"description":"🔴 A RERUN IS VERSION 2, NOT A REPLACEMENT. Newest first. The first file was already emailed, and overwriting it would leave the business unable to show what it sent.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceDocument"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Every version of this invoice's rendered file.","tags":["documents"]},"post":{"description":"⏸ **This service does not call the renderer itself yet, and the reason is not in this service.** `public-api-document-rendering` writes to object storage, and no bucket is bound in any environment — no object-storage access key has ever been issued on this platform, the same blocker that holds up the reporting capability's export jobs. A render answers 503 whoever asks for it.\n\n⚠️ **So this records a version a caller rendered.** Supply the storage key the file was written to and, if you have it, the renderer's own attempt id. When storage unblocks, this service calls the renderer directly and fills the same row — the model does not change, only who makes the call.\n\n⚠️ **The version number is assigned, never supplied.** A caller choosing it would eventually choose one that already exists, and the point of the record is that the history of what was sent survives.\n\n⭐ **A document may be recorded against an APPROVED invoice.** Approval locks the invoice and its lines, not its rendering — reissuing the same approved invoice as a fresh PDF is exactly what version 2 is for.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"byteSize":{"minimum":1,"type":["integer","null"]},"contentType":{"description":"Defaults to application/pdf.","maxLength":200,"type":"string"},"renderedDocumentId":{"description":"The render attempt in public-api-document-rendering that produced it.","pattern":"^[0-9]+$","type":["string","null"]},"storageKey":{"description":"⚠️ **Leave this out.** Invoicing owns the namespace and assigns `tenants/{tenantId}/invoices/{invoiceId}/v{n}.pdf` itself (design ADR 0094) — and the version is not known until the row is written, so nothing outside this call can name the key correctly.\n\n🔴 **Supplied, it is refused unless it sits inside your own tenant prefix** (`storage.md` invariant 3).","maxLength":1024,"minLength":1,"type":"string"},"supersedeReason":{"description":"Why this version exists — *\"regenerated after the Friday stop was completed\"*. ⚠️ Ignored on version 1, where the answer is simply that the invoice was created.","maxLength":1000,"type":["string","null"]}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceDocument"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such invoice."}}},"description":"No such invoice."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Record the next version of this invoice's document.","tags":["documents"]}},"/api/invoices/{invoiceId}/documents/generate":{"post":{"description":"⭐ **This is the one call that turns an invoice into a document.** It resolves the template through the invoicing settings cascade, asks the renderer for the bytes, stores them, and records the version — in one request.\n\n🔴 **The template comes from the cascade, not from the request.** Tenant scope sets a base per side — one for customer invoices, one for driver invoices — and a customer or driver row overrides it. ⚠️ **Nothing configured anywhere is refused rather than defaulted**, because a document with nobody's letterhead is not one you would send; the error names the party and the side.\n\n🔴 **Your token is forwarded to the renderer**, which is what keeps tenant isolation structural: no service ever acts as a tenant it cannot prove. ⚠️ **That is also why this is a request rather than a step inside a batch** — a batch run carries no person and no token.\n\n⚠️ **The version number is assigned, never supplied**, and a regenerated invoice is version 2 at a NEW key. The first file was already sent; overwriting it would rewrite what a customer received.\n\n⭐ **A locked invoice can still be rendered.** Approval locks the invoice and its lines, not its rendering — reissuing the same approved invoice as a fresh PDF is exactly what version 2 is for.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"supersedeReason":{"description":"Why this version exists — *\"regenerated after the Friday stop was completed\"*. ⚠️ Ignored on version 1, where the answer is simply that the invoice was created.","maxLength":1000,"type":["string","null"]}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceDocument"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such invoice."}}},"description":"No such invoice."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The rendering service refused or failed."}}},"description":"The rendering service refused or failed."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Object storage is not configured here. Not transient."}}},"description":"Object storage is not configured here. Not transient."}},"security":[{"bearerAuth":[]}],"summary":"Render this invoice and store the next version of its document.","tags":["documents"]}},"/api/invoices/{invoiceId}/documents/{documentId}/download":{"get":{"description":"🔴 **Returns a LINK, never the bytes.** `design/storage.md` invariant 2: private bytes never transit compute. The browser fetches straight from object storage, which is also why a large document does not time out.\n\n⚠️ **The link is a bearer credential for one object.** It carries its own signature, needs no token, and **cannot be revoked** — only expired. It lives 15 minutes, which is sized for *somebody clicks a button*, not for *an email sits in an inbox until Monday*.\n\n⭐ **The file is named for a human** — the invoice number — while the storage key carries the internal id. Those are deliberately different things (design ADR 0094).\n\n⏸ **503 `storage_not_configured`** where no object storage is set, which is honest rather than a generic failure inviting a retry that can never succeed.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"documentId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceDocumentDownload"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No object storage is configured here. Not transient."}}},"description":"No object storage is configured here. Not transient."}},"security":[{"bearerAuth":[]}],"summary":"A time-limited link to this version of the document.","tags":["documents"]}},"/api/invoices/{invoiceId}/documents/{documentId}/sent":{"post":{"description":"⚠️ TWO FACTS, DELIBERATELY SEPARATE. The invoice-level timestamp answers \"has this customer heard from us\"; this one answers \"which file did they get\". Version 1 went out on Friday and version 2 may never be sent at all.\n\n⏸ **Nothing is sent by this call.** Delivery goes through the platform outbox, and all four email sending identities failed on 2026-11-06 — nothing can be delivered from Mesh today. This records the fact for whoever did send it.\n\nIdempotent — the first timestamp stands.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"documentId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Recorded."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Record that this version was sent.","tags":["documents"]}},"/api/invoices/{invoiceId}/lines":{"get":{"description":"In document order. ⚠️ `builderCode` is NULL on a line a person added by hand — a manual adjustment is first-class and has no builder. ⭐ `sourceCount` says how many jobs a rolled-up line stands for.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoiceLine"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"The lines on an invoice.","tags":["invoices"]},"post":{"description":"⭐ THE WORKED EXAMPLE: *\"we are giving this customer $50 off because they have been with us a year\"* is this call with an `amount` of `-50.00`.\n\n🔴 IT MUST HAPPEN BEFORE APPROVAL, because approval locks. A locked invoice answers 422 naming the rule, not 404.\n\n⚠️ The line carries no builder — null is the record that a person put it there, and inventing a `manual` builder would put a value in the selectable bitmask that nobody may select. The invoice totals are re-summed from the lines.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"accountCode":{"description":"Carried for the accounting phase, never interpreted.","maxLength":100,"type":["string","null"]},"amount":{"description":"Decimal string, excluding tax. ⭐ Negative for a credit. A string, not a number — JSON numbers are IEEE doubles and money is not.","pattern":"^-?[0-9]+(\\.[0-9]{1,2})?$","type":"string"},"description":{"description":"What a customer reads. ⚠️ An adjustment with no explanation is the line that gets queried.","maxLength":1000,"minLength":1,"type":"string"},"quantity":{"description":"Defaults to 1.","pattern":"^-?[0-9]+(\\.[0-9]{1,4})?$","type":"string"},"taxAmount":{"description":"⚠️ You supply it. Mesh never computes tax — the moment it does, it is in the tax-jurisdiction business.","pattern":"^-?[0-9]+(\\.[0-9]{1,2})?$","type":["string","null"]},"unitAmount":{"pattern":"^-?[0-9]+(\\.[0-9]{1,4})?$","type":["string","null"]}},"required":["description","amount"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoiceLine"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such invoice."}}},"description":"No such invoice."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Add a line by hand — the adjustment path.","tags":["invoices"]}},"/api/invoices/{invoiceId}/lines/{lineId}":{"delete":{"description":"⚠️ THE CHARGES BEHIND IT ARE RELEASED, not orphaned. Leaving them pointing at a deleted line would make them invisible to the next run — billed for nothing, forever. The invoice totals are re-summed.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"lineId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The invoice is approved and locked."}}},"description":"The invoice is approved and locked."}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from an unapproved invoice.","tags":["invoices"]}},"/api/invoices/{invoiceId}/lines/{lineId}/constituents":{"get":{"description":"⭐ THIS IS WHAT THE INVOICE-LINE IDENTIFIER ON THE CHARGE BUYS. A rolled-up line standing for 250 charges can name every one of them in a single indexed lookup, so a disputed line is EXPLAINABLE rather than an assertion — \"here are the 250 charges and the rule that priced each one\", not \"this line is 250 stops\".\n\n⚠️ Empty on a line a person added by hand and on a line with no underlying work.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"invoiceId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"lineId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"sideCode":{"description":"Which table the constituents came from — charges on a customer invoice, costs on a driver invoice.","type":"string"}},"required":["sideCode","items"],"type":"object"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"The charge or cost lines behind one invoice line.","tags":["invoices"]}},"/api/invoicing-settings":{"get":{"description":"⭐ ONE TABLE, THREE SCOPES, ONE CASCADE — a tenant default, overridden per customer and per driver. Every value is nullable and null means INHERIT. Ordered by precedence, lowest first, which is the order the resolver applies them in.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/invoicingSettings"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Every settings row this tenant has, at every scope.","tags":["settings"]},"put":{"description":"Upsert rather than create — there is exactly one row per scope per side, and setting a preference twice means \"this is what I want\", not \"make a second one\".\n\n🔴 **An illegal builder combination is refused HERE with a sentence naming both builders, AND by a database check constraint.** The duplication is the point: `builderMask` is a configuration column that migrations, backfills and support scripts write to directly, and none of those come through this endpoint.\n\n⚠️ **A customer-scope row must be on the customer side and a driver-scope row on the driver side.** A customer has no cost side, and a driver is paid rather than charged.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"builderMask":{"description":"🔴 OR together the `bit` values from GET /api/invoice-line-builders. Null means inherit; 0 means build nothing, which is a different statement. ⚠️ Rolling up (1) and not rolling up (2) together is refused.","maximum":255,"minimum":0,"type":["integer","null"]},"customerId":{"description":"Required for scope `customer`, refused otherwise.","pattern":"^[0-9]+$","type":["string","null"]},"documentTemplateId":{"description":"🔴 Which template this party’s invoice is rendered with — an id from public-api-document-rendering. ⚠️ **Null means INHERIT**, as everywhere else here: set a base per side at tenant scope, then override it for one customer or one driver. ⚠️ **Null at every level means nothing is configured** and generating a document refuses — there is no default, because a document with nobody’s letterhead is not one a tenant would send.","pattern":"^[0-9]+$","type":["string","null"]},"driverId":{"description":"Required for scope `driver`, refused otherwise.","pattern":"^[0-9]+$","type":["string","null"]},"invoiceNumberPrefix":{"maxLength":50,"type":["string","null"]},"invoiceNumberSuffix":{"maxLength":50,"type":["string","null"]},"isChargeApprovalRequired":{"description":"🔴 Whether priced work must be approved before a run may use it. Defaults to true — the gate exists so an invoice run can tell an approved amount from an unreviewed one, and defaulting it off would make it decorative.","type":["boolean","null"]},"isInvoiceApprovalRequired":{"description":"Whether the invoice itself needs approving. Approval locks, so this decides whether adjustment lines have a window at all.","type":["boolean","null"]},"numberSchemeCode":{"description":"From GET /api/invoice-number-schemes. ⚠️ Check `serialisesScope` before choosing — the per-tenant incrementing scheme is one lock across a whole batch.","type":["string","null"]},"scopeCode":{"enum":["tenant","customer","driver"],"type":"string"},"sideCode":{"enum":["customer","driver"],"type":"string"},"stopWithoutChargesBehaviourCode":{"description":"⚠️ Not about what a customer may see — about the run. Defaults to `fault`.","enum":["fault","continue_and_report",null],"type":["string","null"]},"unapprovedChargeBehaviourCode":{"description":"Defaults to `fault`.","enum":["fault","continue_and_report",null],"type":["string","null"]}},"required":["scopeCode","sideCode"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoicingSettings"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A number already in use, or a state transition that has already happened."}}},"description":"A number already in use, or a state transition that has already happened."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}}},"description":"Well-formed but not acceptable — an illegal builder combination, a locked invoice, a referenced row that does not exist, or a generation run that faulted on something you asked it to fault on."}},"security":[{"bearerAuth":[]}],"summary":"Set the settings for one scope.","tags":["settings"]}},"/api/invoicing-settings-scopes":{"get":{"description":"🔴 `precedence` makes the resolution order DATA rather than something that emerges from whichever query somebody wrote. Lowest first; the last non-null value wins.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection. Used only where the set is small, fixed and platform-owned."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"The levels the settings cascade resolves through.","tags":["vocabularies"]}},"/api/invoicing-settings/resolved":{"get":{"description":"⭐ THE CASCADE, ALREADY APPLIED. Every value is non-null, and `resolvedFrom` says which scope each one came from — `tenant`, `customer`, `driver`, or `platform-default` when nothing anywhere set it.\n\n🔴 This exists because \"why is this customer being invoiced like that\" is otherwise three queries and a guess, and it is the first question anybody asks when an invoice comes out wrong.","parameters":[{"in":"query","name":"sideCode","required":true,"schema":{"enum":["customer","driver"],"type":"string"}},{"in":"query","name":"customerId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"in":"query","name":"driverId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/resolvedInvoicingSettings"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"What a run will actually do for one party.","tags":["settings"]}},"/api/openapi.json":{"get":{"description":"Authoritative request/response shapes for every endpoint. Generated from per-route schemas — cannot drift from the implementation. Public — no token required.","responses":{"200":{"description":"Default Response"}},"security":[],"summary":"Generated OpenAPI 3.1 contract.","tags":["discovery"]}},"/api/version":{"get":{"description":"Body shape per design/quality-standards.md §3. Anonymous — same reason as /api/health.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"buildTime":{"type":"string"},"commit":{"type":"string"},"environment":{"type":"string"},"service":{"type":"string"},"version":{"type":"string"}},"required":["service","version","commit","buildTime","environment"],"type":"object"}}},"description":"Default Response"}},"security":[],"summary":"Service identity + build metadata + environment.","tags":["meta"]}},"/api/whoami":{"get":{"description":"Returns the subject, token type, tenant and scopes resolved entirely from the inbound JWT (never from the request body, query or headers). Useful for verifying a token works and inspecting what it carries. Authenticated — any valid token may call it; an absent or invalid token yields 401.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Identity attached to the request by the bearer-token middleware.","properties":{"scopes":{"description":"Permission codes from the JWT `lm_perms` claim.","items":{"type":"string"},"type":"array"},"service":{"description":"Service identity.","type":"string"},"subject":{"description":"Caller id from the verified token: the JWT `sub` claim, falling back to `client_id` when the token carries no sub (dev-bypass). Never null — an ADR-0023 core field.","type":"string"},"tenant":{"additionalProperties":false,"description":"Tenant scope from the JWT `tenant_id` claim. name/plan are null — this service has no query path to the central tenants table.","properties":{"id":{"description":"JWT `tenant_id` claim. Null if the token carries no tenant scope.","type":["null","integer"]},"name":{"description":"Tenant display name. Null — not enriched by this service.","type":["null","string"]},"plan":{"description":"Tenant plan. Null — not enriched by this service.","type":["null","string"]}},"required":["id","name","plan"],"type":"object"},"tokenType":{"description":"Token kind. Always \"jwt\" for public-api-*.","enum":["jwt","pat","session"],"type":"string"}},"required":["service","subject","tokenType","tenant","scopes"],"type":"object"}}},"description":"Identity attached to the request by the bearer-token middleware."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."}},"security":[{"bearerAuth":[]}],"summary":"Identity resolved from the verified token.","tags":["discovery"]}}},"servers":[{"url":"https://invoicing-api.mesh.locate2u.app"}],"tags":[{"description":"Service identity, health, and self-description. Public (no token required).","name":"discovery"},{"description":"🔴 Generation. Submit a scope and a timeframe, poll it, then ask it for the invoices it produced and the exceptions it met.","name":"batches"},{"description":"Invoices, their lines, approval and cancellation — and the drill-down from a rolled-up line to the charges behind it.","name":"invoices"},{"description":"Every version of an invoice’s rendered file. 🔴 A rerun is version 2, not a replacement.","name":"documents"},{"description":"How a party wants to be invoiced. ⭐ One cascade: tenant, then customer or driver.","name":"settings"},{"description":"When generation runs on its own.","name":"schedules"},{"description":"Platform-owned, closed and read-only. ⭐ Start with the builder catalogue.","name":"vocabularies"},{"description":"Build metadata.","name":"meta"}]}