API Integration Guide
Plan an integration with ERP, CRM or payment systems so that outages, duplicates and timeouts stay harmless instead of costing manual clean-up.
1 Overview
An integration is a dependency on a system you do not control. It will sometimes be slow, unavailable, change a field, or send the same message twice. The connection itself usually works on the first day; the trouble comes later, when something fails and nobody decided in advance what should happen. The decisions below determine whether a failure passes unnoticed or ends in days of correcting records by hand.
Four questions before any code
- Which system is the source of truth for each piece of data? If a customer address can be edited in both the shop and the ERP, someone must decide which one wins.
- In which direction does data flow, and how fresh must it be? Stock levels may need minutes, a catalogue only a nightly run.
- What should your application do while the other system is down for an hour: keep accepting orders and deliver them later, or stop?
- Is there a test environment on the other side, and a person who answers technical questions?
Authentication
Most systems use an API key, or OAuth 2.0 with tokens that expire and have to be renewed. Ask for separate credentials for test and production, stored in the server configuration and never in the code repository. Grant only the permissions needed. Token renewal must happen automatically, and keys or certificates with an expiry date belong in a calendar: an expired credential is a common cause of a sudden outage.
Rate limits
Nearly every API limits the number of requests per minute or day. The first full import and bulk updates reach the limit long before normal operation does. Send outgoing calls through a queue that can be slowed down, bundle records where the API allows it, fetch only what changed since the last run, and wait as long as the other system asks when it reports that the limit was reached.
Retries and idempotency
A timeout does not tell you whether the request failed. It may have been processed while only the answer got lost. So every write operation needs two things. First, automatic retries with growing pauses and a fixed maximum number of attempts, after which the item goes to a list of failed items that a person can see. Only temporary errors are retried; an invalid record fails the same way every time. Second, idempotency: each operation carries a unique key so that a repeated request is recognised and not executed twice. As an illustration: a payment request times out and is repeated. Without a key the customer may be charged twice; with a key the second request returns the first result.
Webhooks
With webhooks the other system calls you when something happens. Handle them in a fixed pattern: verify the signature, store the raw event, answer immediately, and process in a background job. Expect duplicates and events arriving in the wrong order, and ignore events whose ID you have already processed. Webhooks also get lost, so add a regular reconciliation run that compares both systems and fetches what is missing.
Monitoring
Log every request and response with a reference number, without passwords or payment data. Set alerts for a rising error rate, a growing queue and failed authentication. Add a simple screen where non-developers can see failed items, read the reason and trigger a retry.
Typical failure modes
- A user waits on a page while your server waits for a slow external system. Move the call to the background.
- A field is renamed or a new status value appears. Validate incoming data and fail loudly instead of saving nonsense.
- Both systems update the same record and overwrite each other. Define ownership per field.
- Test data reaches the production system. Separate credentials and addresses per environment.
- Nobody notices that the nightly sync stopped three days ago. Alert on missing runs, not only on errors.
What to ask for in an offer
A field-by-field data mapping, the retry and error behaviour per operation, a failed-items view, a reconciliation job, and a named person responsible for alerts after go-live.
2 Who this is for
IT manager
You get a list of what to demand from a vendor before sign-off: separate credentials per environment, retry rules, a reconciliation run and alerts that also fire when a sync silently stops.
Operations lead
You see why orders or invoices end up duplicated or missing between systems, and which features, such as a failed-items view with a retry button, let your team fix cases without a developer.
CTO or tech lead
You can check an integration design against the usual weak points: source of truth per field, idempotency keys on write operations, queue-based throttling, and webhook handling that tolerates duplicates and wrong order.
3 Questions and answers
How long does it take to connect a web application to an ERP or CRM?
It depends less on the number of endpoints than on the clarity of the data mapping and the quality of the other system's documentation and test environment. Reading and displaying data is quick. Writing data in both directions, with error handling, reconciliation and monitoring, is the larger part of the work. Ask for an estimate per data flow, not one figure for the whole integration.
What happens to our orders if the connected system is down?
That is a design decision you should make explicitly. In most cases the application keeps accepting orders, stores them locally and delivers them through a queue once the other system is reachable again. Where a live answer is essential, for example a payment authorisation, the user needs a clear message and a safe way to try again without creating a duplicate.
Is polling or a webhook the better way to receive changes?
Webhooks deliver changes within seconds and cause little load, but individual events can be lost or arrive twice. Polling, meaning asking at intervals what has changed, is slower but dependable. A robust integration uses both: webhooks for speed and a scheduled comparison run as a safety net.
Planning a project like this?
Tell us what you are building. You get a straight answer on scope, approach and effort.