An API integration looks like a simple job: one system sends a request, the other answers. In the demo everything works the first time. The trouble starts later — when an external service answers late, an order arrives twice, and the data in the CRM and the warehouse stops matching.
Connecting one system — a payment provider, a delivery service or a CRM — usually takes 1–3 weeks and costs from RUB 200,000. Linking several systems with data synchronisation takes 1.5–3 months and costs from RUB 1.3 million. The gap between those numbers is exactly the risks described below.
Where to start
The first step is not choosing a technology but describing the exchange. Before development, a few questions need answers.
Which system owns each kind of data? Prices live in the accounting system, customers in the CRM, delivery statuses with the delivery service. If one kind of data has two owners, discrepancies are inevitable.
What data moves, and in which direction? Orders from the website to the CRM, stock levels from the warehouse to the website, payments to accounting. Each direction is a separate flow with its own rules.
How fast must the data arrive? A payment should change the order status at once. Stock levels can update every few minutes. Reports once a day. This decides the exchange method.
What happens when something goes wrong? Who learns about the failure, what happens to the data that did not get through, and how it is sent again.
The answers add up to an exchange diagram. It is a short document, but it saves weeks: developers do not guess the logic, and the client sees in advance what will happen to their data.
Risk 1: documentation
The quality of the other side’s documentation is the first thing that decides how long an integration takes. Good documentation describes the methods, formats, errors and request limits, and comes with a test environment. With it, the connection goes to plan.
It can be different:
- the documentation is outdated and does not match how the API really behaves;
- there is no test environment, so checks have to run on live data;
- error codes are not described, and the vendor’s support takes days to reply.
What helps: ask for documentation and test access before the estimate, not after the contract is signed. If they do not exist, plan time for exploring the API and say so honestly in the estimate.
Risk 2: errors and retries
Sooner or later the external system will be unavailable — for a minute, for an hour, during an update. The question is not whether it happens but what happens to your data when it does.
A reliable integration includes:
- retries — if the service does not answer, the request is sent again after a while;
- duplicate protection — sending again does not create a second order or a second payment;
- an exchange log — you can see what data was sent, when, and with what result;
- monitoring — the team learns about a failure before customers do.
Without these, the integration works until the first serious failure, and then managers spend a week reconciling orders by hand.
Risk 3: data synchronisation
When systems exchange data both ways, the trickiest risk appears: drift. A customer was changed in the CRM while someone was editing the same customer on the website. Stock was written off in the warehouse, but the website does not know yet. An order was cancelled, but the payment has already gone through.
Simple rules reduce the risk:
- each kind of data has one owner system; the others only receive changes;
- each record has a shared identifier across all systems;
- conflicts are resolved by a rule written down in advance, not “however it turns out”;
- data is reconciled automatically from time to time, and discrepancies go into a report.
When there is a lot of data and it changes often, it can make sense to put an intermediate service between the systems that receives, checks and distributes changes. It costs more at the start but is easier to maintain.
Risk 4: life after launch
An integration is not a one-off job. Other systems get updated: API versions, fields, authorisation rules and request limits change. Vendors usually warn in advance, but someone has to read the warning and update the integration.
What to plan for:
- isolation — calls to each external system are kept in a separate module, so changes to its API do not affect the rest;
- monitoring keeps running after launch, not only in the first days;
- an owner for the integrations — on your side or with the contractor under a support agreement.
Our work comes with a 6-month warranty: we fix bugs in the integration we built at our own cost. Updates for changes in other systems are ongoing support, and it is better to agree on that in advance.
How to choose the integration method
The method depends on how fast the data is needed and what the systems themselves can do:
| Method | When it fits |
|---|---|
| Direct API requests | an answer is needed now: payment, stock check, delivery quote |
| Notifications from the external system | the system reports an event itself: payment received, status changed |
| Scheduled export | a lot of data, a delay of minutes or hours is acceptable |
| Intermediate service | several systems, data flowing in different directions |
One project often uses several methods at once. What matters is not to mix them for the same data flow.
A short checklist before you start
- Each kind of data has an owner system.
- There is documentation and test access to the external APIs.
- It is written down what happens on an error and who learns about it.
- It is clear how fast the data must arrive.
- It is agreed who supports the integration after launch.
More about how we design and build integrations is on the API integration page.
A good integration is barely noticed. Orders simply arrive, stock levels simply match. All the work is in keeping it that way on the day something goes wrong.
