API integration is an agreement between systems about data, permissions and failure. A connection that works in a demonstration can still create duplicate orders, stale stock or invisible errors in daily operation. The business brief therefore needs more than a list of endpoints.
Begin with the event you want to support. When a sales order is approved, should the warehouse reserve stock, create a picking task or merely receive a notification? Those are different business commitments. Decide which system owns each record and which system may change its state.
Establish a source of truth
For a hypothetical distributor, the ERP may own product identifiers and invoicing while a warehouse system owns physical movements. An ecommerce channel owns the customer's order request, but not necessarily the final stock allocation.
Write this ownership down field by field where ambiguity is likely. Product names can be copied for display, while the permanent identifier should stay stable. An integration should not overwrite a manually corrected address unless that change is explicitly part of the contract.
Specify the contract
An OpenAPI document can describe request and response shapes, but business meaning must accompany the technical specification. Explain units, time zones, optional fields, enumerated states and identifier formats.
| Contract item | Example decision |
|---|---|
| Quantity | Individual units or cartons, with conversion defined |
| Timestamp | UTC storage and business-zone display |
| Status | Accepted, reserved and shipped are separate states |
| Identity | Stable external ID plus the owning system |
| Error | Retryable outage versus rejected business rule |
Have both system owners review realistic payloads. A technically valid quantity of zero may still be invalid for a specific operation.
Make failure part of the workflow
Distinguish a request rejected before processing from a request whose response was lost after processing. The second case requires a status check or idempotent retry. Otherwise a network interruption can create the same order twice.
Define retry limits, a queue for failed messages and an owner who can resolve them. A dashboard showing hundreds of errors is not a recovery process. Staff need the business identifier, reason and safe next action without exposed credentials or unnecessary customer details.
Test more than connectivity
Acceptance should cover a normal operation, a duplicate request, an unavailable destination, an invalid identifier and a changed schema. Use representative volumes and payload sizes instead of assuming one small sample predicts production performance.
Test permission boundaries too. A service account intended to read catalogue data should not inherit administrative write access. Rotate integration credentials through an agreed process and ensure operational staff can identify when an expired credential is blocking work.
Release with reconciliation
During rollout, compare records across systems. For example, count approved orders that have a matching warehouse reservation and inspect the exceptions. This catches failures that a healthy HTTP response cannot reveal.
Keep the original manual recovery route available until the integration is trusted. Decide how historical records are loaded, how new events are cut over and how duplicate imports are avoided. A practical integration proposal includes the contract, reconciliation report, failure owner and rollback plan alongside the endpoint implementation.
Primary references
Related reading
For help applying these choices to your operation, explore our business systems or discuss the workflow.