Polling & notifications

Driving orders via the API

There is no push notification for status changes in the public API today (the AIOTIC app is updated through a channel that is not part of the public API; the optional processing webhook fires only once, before review). Polling is the mechanism, and it is cheap if done right.

One order

GET/order_status/{request_id}integration key

Poll with backoff — 2 s, then ×1.6, capped at 15 s — until the status is landed (PROCESSED, ATTENTION, FAILED, MODIFIED) or terminal:

status = client.orders.wait(request_id, timeout=600)     # exactly that loop
if status.status == "PROCESSED":
    ...
elif status.status == "ATTENTION":
    ...

result is populated once landed; erp_ref after a send; last_error, retry_count, next_retry_at during retries.

Many orders: the transition watcher

GET/order_status/list?page=1&size=200integration key

The list is newest first. A watcher polls the first page or two every 15–30 s, remembers the last status it saw per request_id, and emits a transition whenever it changes. The SDK ships one:

from aiotic.watch import OrderWatcher, SqliteWatchState

def on_change(t):
    print(t.request_id, t.from_status, "→", t.to)
    if t.to == "ATTENTION": notify_team(t.order)
    if t.to == "SENT":      mark_done_in_erp(t.order.erp_ref)

OrderWatcher(client, on_transition=on_change, state=SqliteWatchState("watch.db"), interval=20, pages=2).run_forever()

aiotic orders watch runs the same loop and prints JSON lines — useful to pipe into a queue.

Costs: two requests every 20 s, regardless of volume. Orders older than the pages you look at are assumed settled; raise pages for very high volumes.

Split e-mails

GET/order/group/{email_group_id}integration key

Returns every child order of one source e-mail with their statuses — one call instead of N.

Files and artifacts

GET/order/{request_id}/{filename}integration key

Download an original upload (by file name as listed in attachments) or latest_result.json (the extracted order as a file). GET /order/{request_id}/{filename}/preview returns the same file with an inline Content-Disposition for showing inside your UI.

Choosing an interval

Need	Interval
Show live status in your UI	per-order wait() while the user looks; 5 s
Book PROCESSED orders automatically	watcher, 20–30 s
Nightly reporting	list pages once

Do not poll a single order faster than every 2 s, and stop polling terminal orders.