Picture an e-commerce business that works with a courier company. Orders live on the website, shipments in the courier's panel. Every day someone copies orders across one by one and pastes tracking numbers back. A decision is made: the two systems will be connected. The courier has an API, the developer reads the documentation and says, "a few endpoints, done in two weeks."
Six weeks later the integration is still not live. The code is written, but the test account only arrived in the third week, some fields in the documentation come back under different names, return shipments were never discussed, and nobody wrote down what has to work before anyone can say "done".
This picture is the rule, not the exception. In an API integration the code is often the small part of the job; the rest is waiting between two organisations for information, access and decisions. The seven topics below are the ones that shorten the timeline most when they are settled before work starts.
1. Is the documentation actually current?
The other side's documentation is a starting point, not a contract. Common situations: the documentation is two versions behind, some fields say "optional" but the request is rejected when they are empty, half of the error codes are not explained.
Before you start, check when the documentation was last updated and ask the other side for a technical contact. An email address or a support channel is not enough; you need the name of a person who can answer questions within a few days. Not having that person is the single biggest risk that can add weeks to the plan.
2. Is there a test environment, and when will it open?
Many services offer a test environment, but access goes through an application, a contract or an approval process. Some have no test environment at all; trials happen on the live system, with real records.
Write into the plan that the test account must be open in the first week of the project. If there is no test environment, agree in advance how trials will run on the live system, how trial records will be cancelled, and whether that costs anything. A real shipping label or a real invoice should not be issued while testing.
3. Who grants live access, and with which approval?
Once testing is over, live credentials are needed. These are usually obtained not by the developer but by the business's account owner or manager. Some services run a check with their own team before going live; some ask for a signed form.
Find out at the start who holds this step and how many days it takes. Also agree in whose name, and in which account, the credentials will sit: when the project ends, access should stay with the business, not in one employee's personal account.
4. Do you have samples of real data?
The example requests in documentation are always clean. In real data an address line runs past two hundred characters, a phone number is written with spaces, a product name contains a quotation mark, an order has seventeen lines. A large share of the errors that stretch an integration come from these differences.
Before you start, pull a sample set from your own system of typical and unusual records from the last few months: the longest address, the busiest order, a customer abroad, a discounted product. Mask personal details such as names, phone numbers and addresses in this set; under KVKK and GDPR there is no need for real customer data to travel to a test environment. If the developer works on this set, problems surface in the first week, not in production.
5. Who will describe the flows that go wrong?
Everyone knows what happens when an order is placed. What happens when an order is cancelled, when a customer changes the address, when a shipment comes back, or when the other system rejects a request is usually written down by nobody. When these flows are added later as "this should work too", the timeline slips.
For each main flow, list the cases that go wrong on one page and write a one-sentence decision for each. The answer can be "handled by hand for now"; what matters is that it is a deliberate decision and that it is clear what the first version covers.
6. When something fails, who sees it, and where?
An integration works silently; problems appear silently too. The other system goes down one night, a field changes, a request times out and nobody notices, until a customer asks why their shipment never left.
Three things should be agreed before starting: where failed requests will be logged, who will be told about them (email, a messaging channel or a panel), and how a record will be resent once the error is fixed. Making time for these later is always more expensive than making time at the start.
7. What does "done" mean?
The longest part of an integration project is often the last ten per cent, because the finish line was never drawn. The developer says "the requests work", the operations team says "but not in this case", and the list grows.
Before you start, write the acceptance criteria: which scenarios will be tested with which data, who will test them, and for how many days the integration will be watched together after going live. The list can be short, but it should be written. A written finish line makes every new request that appears later count as a change of scope, planned separately.
Building a realistic timeline
Most of these seven topics are not in the developer's hands; they wait on decisions from the business, the other side and sometimes an accountant or an operations lead. That is why a good integration plan contains two timelines: one for the code and one for the waiting points. When the dates for the test account, the live credentials, the sample data and the acceptance test are written down separately, it is visible from day one where the delay sits.
Topics such as who owns the data on each side and making sure the same record does not arrive twice we covered earlier for CRM and ERP specifically; the focus here is on the questions that set a project's timeline.
In short
An API integration usually runs late because of waiting, not code. Before starting, settle that the documentation is current and there is a technical contact, when the test environment opens, who holds live access, a sample set of real data, decisions for the flows that go wrong, where failures will show up, and written acceptance criteria. Once these seven topics are settled, the timeline no longer falls between a two-week estimate and a two-month reality.
In integration projects we fill in this list together at the proposal stage and give separate timelines for the code and for the waiting points.
Planning a project like this?
Plan it in 10 steps