The verdict in three sentences
Integration project overruns almost never come from code, but from a vague requirements document. In 2026, a precise spec cuts change orders from over 30 % to under 10 % and halves the quote spread between vendors. Document six things: API contracts, authentication, communication mode, idempotency, error handling and availability SLAs.
The requirements to document
Every unspecified requirement becomes a change order. Here are the points that swing the price and must be decided before consultation.
| Requirement | To specify | Impact if omitted |
|---|---|---|
| API contract | OpenAPI/Swagger provided | +20-40 % reverse engineering |
| Authentication | OAuth2, API key, rotation | Vulnerabilities + delay |
| Communication | Webhooks vs polling | Uncontrolled latency |
| Idempotency | Idempotency key, dedup | Duplicates in production |
| Error handling | Retries, backoff, DLQ | Data loss |
| Quotas / rate limits | Thresholds, throttling | Third-party API blocks |
A spec that provides OpenAPI definitions for the APIs involved lets vendors quote accurately instead of padding the price to cover the unknown.
Webhooks, idempotency and SLAs
The technical core of a reliable integration comes down to three notions: receive events (webhooks or polling), never process them twice (idempotency) and guarantee a service level (SLA).
| Parameter | Option A | Option B | 2026 recommendation |
|---|---|---|---|
| Reception | Polling (query) | Webhooks (be notified) | Webhooks if real time |
| Duplicates | No control | Idempotency key | Key mandatory |
| Failures | Drop | Retries + backoff | 3-5 retries + DLQ |
| Flow availability | 99.0 % | 99.5-99.9 % | 99.5 % contractual min |
| Monitoring | None | Alerts + dashboard | Alert < 5 min |
A 99.5 % flow-availability SLA allows about 3.6 h of downtime per month; 99.9 % drops to 43 minutes. Each extra nine costs dearly, so calibrate it to real criticality.
The flow matrix, foundation of the spec
The central deliverable of an integration spec is a matrix listing every flow: source, destination, frequency, volume and criticality. It drives pricing, prioritization and acceptance testing.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
| Flow | Source -> Destination | Frequency | Volume/mo | Criticality |
|---|---|---|---|---|
| Orders | Site -> ERP | Real time | 3,000 | High |
| Stock | ERP -> Site | 15 min | 20,000 | High |
| Contacts | CRM -> App | Nightly | 5,000 | Medium |
| Invoices | ERP -> Accounting | Nightly | 3,000 | Medium |
| Logs | App -> SIEM | Continuous | 200,000 | Low |
Each row comes with acceptance criteria: nominal case, error case, replay, and tested load volume.
Mini case study
Sarah, IT project manager at a distribution SME in Amsterdam, prepares a consultation for 6 integrations. Without a spec, her first three quotes ranged from EUR 14,000 to 34,000, an unmanageable spread. She formalizes a flow matrix, provides the OpenAPI specs and sets a 99.5 % SLA. Result: new quotes tighten to EUR 19,000-24,000 and the change-order budget drops from a 30 % provision to 8 %. On a EUR 21,000 project, she saves roughly EUR 4,600 in avoided change orders.
FAQ
What is an idempotency key? It is a unique identifier attached to each request to ensure a given event (e.g. an order) is processed only once, even if resent. Without it, a retry creates duplicates in production.
Webhooks or polling? Webhooks notify in real time (latency < 30 s) and are preferred for stock or payments; polling queries periodically and suffices for non-urgent data. The wrong choice costs you in latency or server overhead.
What availability SLA to specify? 99.5 % is a good contractual minimum for B2B flows (~3.6 h downtime/month). Moving to 99.9 % (43 min/month) raises infrastructure and monitoring costs, reserved for critical flows.
Does a precise spec really lower the price? It does not lower real cost, but it removes the risk premium vendors add against the unknown. That is how quote spread is halved and change orders kept under 10 %.
What goes in the acceptance criteria? For each flow: the nominal case, error cases (third-party API down, invalid data), replay after outage and a load test at target volume. Without formal acceptance, bugs surface in production.
Let's scope your project. Send us your flow list (source, destination, volume, criticality) and your SLA constraints, and we will help formalize the spec and quote. Detailed quote within 48 h. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionate about digital and entrepreneurship in Africa, Mohamed has been helping Sénégalese businesses with their digital transformation since 2020. Founder of Kolonell, he believes every SME deserves a professional and accessible online présence.
