Submit a document order

Some teams still work in buysheets, and some sellers still want them. The document workflow accepts a file, interprets it, and asks you to confirm the interpretation before anything commits. It is slower than the catalog path on purpose; use it when a file is genuinely how the trade exists.

The file comes first: register the upload, PUT the bytes, then reference the upload_id here. An upload that has not received its bytes, or whose bytes contradicted its declared format, cannot be referenced.

POST /v1/orders
{ "seller": "acme", "workflow": "document",
  "external_order_id": "q4-buysheet-007",
  "buyer_metadata": { "advertiser": "Northwind Coffee" },
  "document": { "upload_id": "up_3fc2", "format": "xlsx" },
  "notify_url": "https://yourapp.example.com/webhooks/vamos" }

• The pipeline parses the file (rules first, models second) and emits parsed_io and validation_result artifacts, then parks at needs_confirmation.
• Review the parsed interpretation, then POST /orders/{id}/confirm with confirm or reject and a reason (persisted either way).
• Documents the platform generates back to you are hash-bound renderings of the authoritative JSON: verify the sha256, trust the JSON. Field parity is guaranteed; if a column exists on the sheet, it exists in the payload.
• A file that cannot be interpreted fails fast with PARSE_FAILED and the specific rows at issue, not a silent partial read.

Document orders versus attachments

Two different things use the same files, and picking the wrong one costs you a confirmation round-trip:

• A document order is the file as the order. The platform parses it, the structured order is a derivative of the parse, and you confirm the interpretation before anything commits. Use it when the file is genuinely how the trade exists.
• attachments[] on a catalog order is the file beside the order. Your line_items are authoritative, the file is never parsed, and nothing extra gates. Use it when you have structured lines and the seller's desk also wants the paper.

So if your system produces both a buysheet and structured lines, send the lines and attach the buysheet. You get the catalog path's speed and your counterparty still gets its paper. If a buysheet and your lines disagree, your lines win: the disagreement is a warning, never a rejection.

The two are not interchangeable on one order. attachments is valid only under workflow: "catalog"; on a document or proposal order it returns 422 INVALID_INPUT.