API and system integration

For the shipping example, describe each state the operator can see: waiting for submission, accepted by the carrier, dispatched, cancelled or needing attention. Document which identifier links the two systems and which events may move a record between states. A transport response may mean only that a request arrived; the business may still need a later confirmation. Keep that distinction visible instead of turning every successful network response into a completed shipment.

Extend the illustrative contact change with field versions and origin. The portal changes the email while a salesperson changes the phone. The integration should preserve both changes when the agreed ownership allows them. If two systems change the same field from the same earlier version, retain both candidates and route the conflict according to an explicit rule. A timestamp alone may not express authority, particularly when devices or imports report different clocks.

Test a worker stopping after it receives an event, after durable acceptance and while processing the business change. In each case, inspect both the inbox state and the business record after restart. If an external side effect is involved, acknowledge that the remote system may have accepted it before the local result was saved. Use supported idempotency or a reconciliation lookup where available; do not claim that a local status flag alone guarantees exactly-once delivery.

Start acceptance with read-only comparisons against familiar warehouse reports. Ask operators to investigate a missing item, an unknown variant and an export with an unexpected quantity unit. Only after those cases are understood should the project introduce supported writes. A write adapter needs permission checks, a durable reference and confirmation from the old system. The new API should report pending work honestly instead of presenting a successful upload as a completed order.