Connecting systems
API and systems integrations
Integration looks like technical work, but nearly every problem is an agreement problem. When two systems hold the same record, one of them has to be right — and if that is not written down, the decision gets made daily by accident. So the work starts not by connecting to an interface but by asking which system is the source of truth for each field, and what happens when they disagree.
Discuss an integration scopeIn short: what to settle
Three things decide whether an integration is dependable. The source of truth — which system is right about each field, not in general. The disagreement rule — what happens when values differ: overwrite, skip, or flag for a person. And the owner — who notices that the integration stopped, and who may change it. Without the third, an integration works until the next change on the other side.
When an integration is the right answer
- The same data is entered into two systems by hand today, so errors are a matter of time rather than an exception.
- An event in one system needs to start work in another without a person in between.
- The systems are not being replaced, but their data has to agree — changing platform would be disproportionate.
- You need to know when a transfer failed, rather than learning it from customer calls.
When something simpler is enough
- There is little data and it changes rarely — a periodic export or import can be cheaper and easier to understand.
- Both systems already offer a ready connection that fits the need — then configuring it correctly is enough.
- The process is still changing — automating an unsettled flow means rewriting the integration along with it.
Failure cases and how they are handled
An integration is judged not by how it behaves on a good day but by what happens on a bad one. Below are illustrative cases we define before the work, so they are not improvised later. This is not a price list and not a promise about a particular outcome.
| Failure case | What it means in practice | How it is handled |
|---|---|---|
| Duplicate records | The same customer or order appears twice, usually after a transfer was retried. | Each transfer carries its own identity key, so a retry is recognised and does not create a second record. |
| Data disagreement | Both systems hold the same record with different values and neither is obviously right. | The source of truth is set per field; remaining cases are flagged for a person rather than silently overwritten. |
| The external system does not answer | The interface is unavailable or too slow, so the work cannot complete immediately. | Transfers retry with a growing interval and a bounded count; failures stay in a queue rather than being lost. |
| Request limits | The system permits only so many requests, and heavier load starts being rejected. | Transfers are batched and ordered so the limit is not reached at peak. |
| A changed interface | The other side changes fields or rules, and the integration was not told. | Unexpected structure is rejected with a legible error and recorded, so the problem surfaces before the data is corrupted. |
How the work runs
- 01
Mapping the systems and the source of truth
We record which systems take part, which records travel between them and in which direction, and set the source of truth for each field. This step often reveals that less integration is needed than expected — or that the process has to be agreed first.
- 02
Field mapping and conflict rules
We describe how a field in one system corresponds to another, what happens with empty values, and how conflicts are resolved. The rules are written before the code, because they will be needed either way — otherwise during a dispute.
- 03
Handling failure
Retries, duplicate detection and a queue for failed transfers are implemented. The aim is not to avoid errors but to make sure an error is visible, recoverable, and does not create a second record.
- 04
Monitoring and transferring ownership
Fault reporting is enabled and what each signal means is written down. Alongside it we record who holds access, who may change the integration, and what to do when the other side announces an interface change.
What drives cost and duration
- The number of systems and directions — two-way transfer needs conflict rules, one-way usually does not.
- The quality and documentation of the other side’s interface; without it, most of the time becomes investigation.
- Whether historical data has to be migrated, and what condition it is in.
- The freshness required: once a day, every few minutes, or immediately — this changes the whole solution.
- Whether access and environments can be obtained without lengthy third-party coordination.
Worth considering before we talk
- 01Which systems need connecting, and which one is right when the data differs?
- 02How quickly does data need to appear in the other system?
- 03Who notices today that a transfer failed?
- 04Does historical data need migrating, or is new data enough?
- 05Who will hold access and the right to change the integration after handover?
Let us scope the integration
A note about which systems you want connected and what data should travel between them is enough. Please do not send access tokens or real customer data — a general description is a fine starting point.