Hand in an invoice the client received through a route

Since 0.35.0 (17 Oct 2026). The body is the XML exactly as the route delivered it (UBL, CII or FA(3)); nothing is changed and nothing is sent. The file is stored first, sealed under the client's data key, because in law it is already received; then the route's own validators check it, as for a pass-through send, and the result arrives as a status event (received, then validated or validation_failed, with direction: in) on the client's webhook and on GET /received/{id}/events. A file that fails the rules is kept and reads validation_failed with the errors; it is never dropped. A file that is not an invoice to keep is refused with 422 and nothing is stored, as on POST /invoices/xml: a DOCTYPE (EI-XML-DTD, never parsed), XML that is not well-formed (EI-XML-SYNTAX), or a document that is not an invoice the route knows (EI-XML-TYPE). A check that could not run (a validator down) is retried, and after the last retry the invoice goes on the care list and stays received. A client hands in at most 120 documents a minute and 2,000 a day, whatever key it uses (429, not kept under the Idempotency-Key). The file is served back as a download (Content-Disposition: attachment).

One route document is one received invoice for the client: by rail_id when it is given, by the file's SHA-256 when it is not. The same document again answers 202 with duplicate_of; the same rail_id with other bytes answers 409 received-id-conflict, and nothing is stored. Received invoices are kept apart from the invoices the client sends: they are not in GET /invoices, the series, the metrics or the monthly report, and they never block a send of the same file. A received invoice is deleted with the client's retention once nothing is open on it (its check ended, or a person handled its care row), and is in the client's export under received/. The submit scope; a client key acts for its own client only.