Order lifecycle & statuses

Concepts

Every order is identified by a request_id and moves through a small set of statuses. You read them from GET /order_status/{request_id} and GET /order_status/list.

Rendering diagram…

Solid arrows happen automatically or through the API; dashed arrows involve an operator or a retry.

Status reference

Status	Meaning	What you do
Waiting	Accepted, waiting to be processed.	Wait.
Processing	Extraction, validation and resolution are running (seconds to a few minutes).	Wait.
Processed	Clean extraction: every line resolved to a known article, customer identified, totals consistent.	Sendable. Review or auto-send per your model.
Attention	Landed, but something needs a human: an unknown article, an unidentified customer, an unreadable quantity, a mismatch between document and master data. result is present.	Route to a person. Sendable only as an explicit override.
Failed	Terminal processing error (last_error says why).	POST /order/retry/{id} once; then alert.
Queued (retry)	Transient failure (temporary upstream outage, timeout); AIOTIC will retry automatically (next_retry_at, retry_count).	Wait.
Modified	An operator edited fields in the AIOTIC app.	Sendable.
Sending	Locked while AIOTIC calls your ERP receive endpoint.	Wait; a concurrent send returns 409.
Sent	Your ERP accepted the order; erp_ref holds your order number. Final.	Nothing — the order is in your ERP.
Reprocessed	This order was retried; a new order with a new request_id continues the work. Final for this id.	Track the new id.
Canceled	Cancelled by an operator in the app. Final.	Nothing.

Sendable = PROCESSED, MODIFIED, ATTENTION. Landed (safe to read result) = PROCESSED, ATTENTION, MODIFIED, plus FAILED (no result).

Rules that never change

• A send is never implicit. Parsing, editing or polling never triggers a call to your ERP.
• SENT cannot be sent again. A retry of a send only happens after a failure rolled the status back.
• A retry of processing creates a new order. The old id becomes REPROCESSED and keeps its history.
• Corrections are non-destructive: the AI's original reading is kept next to the operator's edits; you receive the merged result.
• ATTENTION is a normal outcome, not an error. The product prefers flagging over guessing.

Reading the payload

result holds the purchase-order model. Fields that tell you why an order is in ATTENTION:

• result.items[].article_number is null → the line could not be resolved to your catalog.
• result.customer.customer_id is null → the sender could not be matched to a customer record.
• result.items[].quantity_state == "Unrecognised" → a quantity was present but unreadable; quantity is null.
• state (free-form) carries validation details used by the app.

Timing expectations

Step	Typical
Upload → PROCESSING	seconds
PROCESSING → landed	20 s – 3 min depending on page count
SENDING → SENT	as fast as your endpoint answers (timeout 30 s)

Poll with backoff (2 s, 3 s, 5 s, … capped at 15 s). The SDK's orders.wait() does this.