Laravel Integration Engineering

Very few applications are alone. There is an accounting system that owns the invoice numbers, a payment provider that decides when money is real, a warehouse that has opinions about stock, and increasingly a tax authority that requires documents in a structured form.

Integration is where most of the genuinely hard engineering in a business application lives, and it is almost always underestimated - because the code is straightforward and everything around it is not.

What we connect

Accounting and ERP. SAP, Logo, Netsuite, Xero, Sage and whatever a business has been running since before anybody currently employed there arrived. The recurring problem is not the protocol - it is that both systems believe they own the same record, and nobody has decided which one wins.

Payment providers. Cards, local methods, direct debit mandates, marketplace splits. Each has its own model of what a payment is, and the differences reach the order table rather than stopping at the API client - Stripe is the worked example, and the rest differ in the details rather than the shape.

E-invoicing platforms. Increasingly compulsory and increasingly different per country - ZATCA, XRechnung, Peppol, and whichever accredited provider sits in the middle. An invoice becomes an asynchronous document with a state machine attached.

Banks and files. Statement imports, payment files, reconciliation. The formats are old, badly documented and unforgiving, and the work is matching rather than parsing.

Everything else. Shipping carriers, SMS, identity providers, CRMs, government registries.

The parts that decide whether it works

A boundary you own. Your application talks to your interface; one implementation talks to their API. This costs almost nothing to build and it is what makes replacing a provider a week rather than a quarter - which matters more than it sounds, because providers get acquired, deprecate versions and change pricing.

Idempotency, because everything arrives twice. Webhooks are redelivered. Retries fire after a request that actually succeeded. A network timeout tells you nothing about whether the other side processed it. Every write that crosses the boundary needs a key that makes the second attempt a no-op, and that key belongs in the schema rather than in a developer's intentions.

A decision about failure, per integration. When their system is down: does the user's action fail, queue, or proceed degraded? Charging a card is not sending a marketing email, and treating them the same way is how an outage at a vendor becomes an outage at your company.

Rate limits respected deliberately. Backoff, a queue that spreads work, and a ceiling you set rather than discover. Being throttled because you sent a year of backfill in four minutes is a self-inflicted incident.

A log of what was exchanged. Every request and response, retained for long enough to settle an argument. When the other party says they never received it, this is the difference between a five-minute answer and a fortnight.

Reconciliation is the real work

Two systems that hold the same facts will disagree. Not might - will, because messages are lost, corrections are entered on one side, and somebody edits a record by hand at some point.

An integration that assumes agreement discovers the drift when a customer complains. An integration built properly checks: a scheduled job that compares both sides, a report of differences, and a defined resolution for each kind. It is unglamorous and it is the difference between a connection you trust and one you have to spot-check forever.

How an engagement runs

Send the API documentation of whatever you need to talk to, and credentials for a sandbox if one exists. Most of the sizing happens by reading what the other side actually guarantees instead of what its marketing page says.

The scope that comes back lists each integration, its failure modes, and what reconciliation will have to do about them. It carries a price and it is what the contract points at. If one of the integrations turns out to be a research project rather than a build, that is a separate line in the scope instead of a surprise in month two.

Then the work, in your repository, with reconciliation built at the same time as the happy path.

What you receive

The integration as reviewable pull requests, the interface that isolates the vendor, the queue and retry behaviour with its failure decisions written down, the reconciliation job and its report, and a document describing what is exchanged and what happens when it is not.

Where the work touches invoicing or tax reporting in a specific country, the constraints for that market are part of the scope rather than a discovery - Germany, Saudi Arabia, the UAE, the UK and the Netherlands each have pages describing what changes there.