API Orchestration in Practice: Composing Multi-System APIs into a Business Pipeline
Scenario and Goal
The pipeline: every 10 minutes, pull paid orders from the marketplace, create a sales outbound order in Kingdee Cloud, and once the outbound order is approved, push the shipping status back to the marketplace. Three systems, five API calls, with hard requirements: no lost orders, no duplicates, and full traceability of exceptions.
Step 1: Decompose into Atomic API Calls
| Step | System | API | Idempotency key |
|---|---|---|---|
| 1. Pull orders | Marketplace | Order query (incremental by payment time) | — |
| 2. Existence check | ERP | Query outbound order by external bill no. | Marketplace order no. |
| 3. Create outbound | ERP | Save sales outbound order | Marketplace order no. |
| 4. Approve outbound | ERP | Audit API | Outbound order ID |
| 5. Shipping callback | Marketplace | Shipping write-back | Order no. + waybill no. |
Step 2: Orchestrate Order and Branches
Pull paged orders and process them one by one. If step 2 finds an existing outbound order, skip creation and go straight to the callback — this branch is the heart of idempotency. Records that fail validation (e.g. an unmapped SKU) are parked in an exception queue without blocking the rest. Steps 3 and 4 run serially with exponential backoff retries, escalating to manual handling after three failures.
Step 3: Critical Controls
Use the marketplace order number as the pipeline-wide idempotency key: every step checks current state before acting, so rerunning any step yields the same result. Track each order through a state machine (pulled → created → approved → written back) instead of boolean flags, so retries resume from the checkpoint rather than from the beginning. Respect rate limits on both sides: match page size and schedule frequency to the QPS budget, serialize write calls, and parallelize reads.
Common Pitfalls
Wrapping "fetch increment" and "process increment" in one transaction so a single failure rolls back the whole batch; assuming step 4 succeeded synchronously when approval may be asynchronous — poll before the callback; and ignoring time zones, where a UTC marketplace window against an UTC+8 ERP window silently drops orders.