The short answer
Integration problems are rarely about protocols. They are about two systems holding different versions of the same thing and nobody having decided which is correct.
Settle that first, per type of record, and most of the remaining work is mechanical.
Decide where the truth lives
| Record | Question to settle |
|---|---|
| Customer details | Which system may change them |
| Prices | Which one is authoritative |
| Stock or availability | Which is trusted at the moment of sale |
| Orders or jobs | Where they are created |
| Documents | Which copy is the real one |
Allowing two systems to edit the same record without a rule produces conflicts that resolve differently each time, and nobody can explain the result afterwards.
Plan for the other side being down
- Queue outbound changes rather than failing the user action.
- Retry with increasing gaps, not continuously.
- Show clearly when displayed data may be stale.
- Alert someone who can chase the other system.
- Reconcile after recovery instead of assuming it caught up.
Point five is the one that is skipped, and it is where silent data gaps come from. Recovery is not the same as having caught up.
Prefer fewer connections
- Every connection is something to maintain and monitor
- Each adds a way for a change elsewhere to break your system
- Two systems exchanging data both ways is harder than one direction
- A shared reference is frequently simpler than synchronising copies
- Some connections exist because nobody removed them
Reviewing existing connections occasionally is worth the hour. Integrations built for a process that has since changed are a common source of confusing behaviour.
Test the awkward paths
Test what happens when the other system is slow, returns an error, returns unexpected data, or is upgraded. Those are normal events rather than edge cases.
Have a way to replay a failed exchange, because you will need it and building it during an incident is unpleasant.