Response contract

Receiving orders

AIOTIC reads exactly one thing from your answer: the success field.

Field	Type	Required	Effect in AIOTIC
success	boolean	yes	true → order becomes Sent. false → status rolls back, operator sees error.
order_number	string	on success	Stored as erp_ref, shown in the app, returned to API callers in data.order_number. Use your real sales-order number.
error	string	on failure	Shown verbatim to the operator. Make it actionable: "Unknown article number PROD-999 on line 3" beats "validation failed".

Anything else in the body is passed through untouched to POST /erp/send callers (data), so you may add diagnostic fields.

What AIOTIC does with each outcome

Your response	HTTP status	AIOTIC
{"success": true, "order_number": "SO-1"}	any 2xx (or even 5xx)	SENT, erp_ref = "SO-1"
{"success": false, "error": "…"}	any	rollback to previous status; API caller gets 422 with your text; operator sees your text
JSON without success	any	treated as success (legacy behaviour — always send the field)
Non-JSON (HTML error page, empty body)	any	rollback; API caller gets 500 "ERP server error"; operator sees a generic message
No answer within the timeout (30 s default)	—	rollback; 500; operator can retry

HTTP status is not the signal

Some ERPs answer business errors with 500. AIOTIC deliberately ignores the status and trusts success. Do the same in your tests: an accepted order with a 500 is still SENT.

Choosing between rejection and failure

Situation	Answer
Unknown article, blocked customer, credit limit, missing mandatory field	success: false with the reason — the operator can fix it in AIOTIC and send again
Duplicate: same request_id seen before	success: true with the same order_number (idempotent replay)
Duplicate: different request_id, same customer PO number	Your policy. Usually success: false "already booked as SO-…" so a human decides
ERP down, database timeout	success: false with a generic message (or let it 5xx). Both roll back; the operator retries later

Timing

Respond fast. AIOTIC holds the order in Sending and the operator waits on the button. If your ERP is slow to create orders, accept synchronously (validate, persist a queued record, return a provisional number) and finish asynchronously — as long as success: true really means "this will be booked".

Test cases you should have

1. valid order → success: true + number, order visible in ERP
2. same payload again → same number, nothing new in ERP
3. unknown article → success: false, clear text
4. wrong X-API-KEY → 401, nothing written
5. malformed JSON → 4xx with success: false
6. ERP unavailable → success: false, nothing half-written