Proposal: headless API additions

Appendix

PROPOSAL — not available

Nothing on this page exists in the API today. It documents what the AIOTIC team is considering to close the gaps listed in Headless limits today, so integrators can plan and give feedback. Contracts may change before release; the changelog announces what ships.

P1 — Submit corrections

PUT /order/{request_id}/corrections
{ "changes": [
    { "field": "customer.customer_id", "value": "58931" },
    { "field": "items[2].article_number", "value": "PROD-002" },
    { "field": "items[0].quantity", "value": 12 }
] }
→ 200 { "request_id": "…", "status": "MODIFIED", "applied": 3 }

Same semantics as corrections in the app: non-destructive (originals kept), merged into the hand-off payload, status → MODIFIED. Allowed from PROCESSED, ATTENTION, MODIFIED. 409 otherwise. Field paths follow the PurchaseOrder model.

P2 — Cancel

POST /order/{request_id}/cancel   { "reason": "duplicate of PO-4710" }
→ 200 { "request_id": "…", "status": "CANCELED" }

From any non-terminal, non-SENDING status.

P3 — Signed event webhooks

Per-transition events to a tenant-configured URL:

POST <your events URL>
Content-Type: application/json
X-AIOTIC-Event: order.processed
X-AIOTIC-Delivery: 1b2c…            (unique per attempt)
X-AIOTIC-Signature: t=1741000000,v1=<hex hmac-sha256(secret, "<t>." + body)>

{ "id": "evt_…", "type": "order.processed", "created_at": "…", "tenant": "acme",
  "data": { "request_id": "…", "status": "PROCESSED", "previous_status": "PROCESSING", "order_number": "PO-4711", "erp_ref": null } }

Types: order.queued, order.processed, order.attention, order.failed, order.retry_pending, order.modified, order.sent, order.send_failed, order.canceled, email.rejected. Retries with exponential backoff for 24 h on non-2xx; GET /events?since= for replay. The SDK's verify_hmac_signature already implements the signature check.

P4 — Batch upserts

POST /customer/batch          { "items": [ { "number": "58931", ...fields } ] }        ≤ 1000
POST /product/batch           { "items": [ { "item_number": "…", "language_code": "nl", "description": "…" } ] }
POST /customer-product/batch  { "items": [ { "customer_number": "…", "customer_item_number": "…", "item_number": "…", "language_code": "nl" } ] }
→ 200 { "results": [ { "key": "58931", "status": "upserted" | "error", "error": "…" } ] }

Per-item results, no all-or-nothing. Same keys as the single-record endpoints.

P5 — Change detection on reads

• updated_at on customers, products, mappings and orders; ?updated_since=<ISO> on every list endpoint.
• ETag / If-None-Match on single-record reads.
• ?status= and ?since= filters on GET /order_status/list.

P6 — Scoped keys and rate limits

Keys with scopes (orders:read, orders:send, masterdata:write, …) manageable by tenant admins; documented per-tenant rate limit with 429 + Retry-After.

Feedback

Which of these unblocks your integration? Tell your AIOTIC contact. Ordering will follow real demand.