Define the record owner and the meaning of each state
For each customer, product or order, state which system creates it and which fields another system may update. Map stable identifiers, required fields, currency and time-zone handling. Define business states explicitly: paid is different from payment requested; dispatched is different from delivered. Keep a documented mapping so teams can trace a record across systems without relying on display names.
Choose timing and delivery around the workflow
Use immediate requests, webhooks or scheduled synchronization according to provider capabilities and acceptable delay. Ask how a missed event is discovered and whether the provider guarantees ordering. A stock update delayed by a few minutes may be acceptable for one workflow and harmful for another. Specify limits, batch sizes and how to resume after interruption instead of assuming every request is instantaneous.
Make repeated and failed messages safe
A request may succeed remotely while its response is lost. Retrying a payment or document creation without a duplicate-control rule can repeat the action. Use stable event identifiers and supported idempotency mechanisms. Distinguish retryable failures from invalid data or forbidden access. Define limits, backoff and a review queue. Never treat an uncertain result as a definite failure without checking the remote record.
Protect access and make failures traceable
Keep credentials out of browser code and diagnostic screenshots. Separate environments, limit permissions and check access to the specific records involved. Logs should show event identifiers, stages and outcomes while excluding tokens and unnecessary personal data. OWASP’s API guidance identifies authorization and authentication risks; use it as a review reference, not as proof that an integration has passed a security assessment.
Reconcile and rehearse recovery
Compare records or totals between the two systems after a representative test batch. Exercise duplicates, invalid records, delayed updates, revoked access and an outage. Specify who reviews unresolved events and how corrections are made without bypassing audit history. At handover, include mappings, credential ownership, monitoring, API-change responsibilities and a recovery runbook. A connection is ready when the business outcome can be verified.
Review checklist
- Source of truth and allowed update direction.
- Stable identifiers and explicit state mapping.
- Duplicate, out-of-order and uncertain-result handling.
- Least necessary access and redacted logs.
- Reconciliation, recovery and an accountable owner.
Start with one integration flow and sample records. A narrow, verified connection is a better foundation for expansion than several connections whose results cannot be reconciled.