FAQ

Appendix

Contract

Does AIOTIC retry a send if my endpoint is down? No. A failed send rolls the order back to its previous status; an operator (or your code) sends again. Your idempotency on request_id makes that safe.

Can I return 200 with success: false? Yes. The body decides. Many integrators do exactly that so their monitoring separates transport errors from business rejections.

What if customer_id is null in the payload? An operator explicitly sent an unidentified order (override of ATTENTION). Decide your policy: reject with a clear message, or book to a "walk-in" debtor and flag it.

Why does total_price not match the sum of lines? It is the printed document total, which often includes VAT, or was recalculated after e-mail instructions changed lines (then additional_information notes the original). Do not book it; let your ERP compute totals.

What is supplier for? It is you. It makes the payload self-describing (and useful for multi-company setups). Ignore it otherwise.

Master data

Why does AIOTIC sync my data instead of reading it live from my ERP? Performance and consistency: matching runs against normalised, enriched data that sits next to the processing, independent of your ERP's speed, availability or API style; and the synchronised data is what AIOTIC benchmarks and improves against for your tenant. See Reference data.

Do I really need to sync products? The article numbers are on the document. Yes. The product table is the definition of a valid article number. Without it AIOTIC cannot tell a mis-read PR0D-001 from a real code, and every order would need a human.

How often should I sync? On change. Use events or an updated_at poll; reconcile nightly/weekly. Never schedule full dumps.

Can I sync from a script inside the ERP? Yes — that is what the sync key is for. Use one PUT per changed record.

Can two customers share a VAT number? Yes (branches, group companies). Keep city and, if applicable, the branch in the name accurate; AIOTIC uses the branch printed on the document to pick the right one.

Orders

How do I get notified when an order is ready? Poll — see Polling & notifications. The processing webhook fires once when extraction finishes; signed status webhooks are proposed.

Can I correct a field through the API? Not yet (Headless limits). Corrections happen in the AIOTIC app or on your side after receiving the payload.

A customer sent the same PO twice. What happens? Two orders with different request_ids. Detect duplicates in your receive endpoint by (customer_id, order_number) and reject the second with a clear message (the SDK's NoDuplicateOrder).

An e-mail with three POs arrived. What do I get? If the tenant has order splitting enabled: three orders sharing an email_group_id. Otherwise one merged order — ask for splitting to be enabled.

What does Unrecognised mean on a line? A quantity was there but unreadable (handwritten, smudged). quantity is null and the order is in ATTENTION so someone types it in.

Keys & security

Can I use one key for everything? The integration key works everywhere, but keep it in one service and give sync jobs the sync key. See Security checklist.

Is there IP allow-listing? On your side, yes — ask for the tenant's egress addresses. On AIOTIC's side, keys are the control.

SDK

I do not use Python. The contracts are language-neutral; this guide shows curl for everything and C# for the receive endpoint. The Python SDK doubles as an executable specification — read aiotic/receive.py and aiotic/sync/engine.py for the logic worth porting. Other languages are planned.

Can I use the SDK with Flask/Django? Yes. ErpReceiver.handle(), Pipeline.run() and SyncEngine.apply() are plain Python; only the routers are FastAPI.