Building ERP Integrations That Don't Break

In October, we had to rebuild integrations with three different ERP systems because the vendors shipped API changes that broke existing code.

SAP changed a response schema. Oracle modified an authentication endpoint. NetSuite updated rate limiting.

We fixed all three in about four hours total. Most companies would have been down for days.

The difference: we built with integration failure in mind from the start.

Why ERP Integrations Break

ERP systems are living systems. The vendors update them constantly. Sometimes they just fix bugs. Sometimes they add features. Sometimes they're supporting new compliance requirements.

When they update, they often update their APIs. They deprecate endpoints. They change authentication. They modify response formats.

The instinct is to build integrations that are tightly coupled to the current API. You write code that assumes the API response has exactly these fields in exactly this structure. You build it to the current API version.

That works until the API changes.

Then you're scrambling.

The Three Layers

The pattern we use has three layers: provider API, abstraction layer, application code.

Provider API: The actual SAP API, Oracle API, whatever. This changes. We assume it will change.

Abstraction layer: We write a shim between the provider API and our application. This shim normalizes the provider's response into our internal format. When the provider changes their API, we change the shim. Application code never changes.

Application code: Our code works against the abstraction, not against the provider API directly. Application code almost never changes because it's working against a stable interface.

The key: the abstraction layer is designed to be changed. It's expected to change when the provider updates.

Concrete Example

We integrate with SAP for purchase order data. SAP's API returns:

{
  "d": {
    "results": [
      {
        "PO_NUMBER": "PO-001",
        "VENDOR_ID": "V123",
        "AMOUNT": "1000.50",
        "CURRENCY": "USD",
        "STATUS": "RELEASED"
      }
    ]
  }
}

Our abstraction layer transforms this into:

{
  "orders": [
    {
      "id": "PO-001",
      "vendor": "V123",
      "amount": 1000.50,
      "currency": "USD",
      "status": "released"
    }
  ]
}

Our application code works with the second format.

When SAP updates their API and changes the response structure, we update the abstraction layer. Application code doesn't change.

The Anti-Pattern

I see this fail a lot. Teams build direct integrations. The code makes HTTP calls to the provider API. It parses the response. It uses the data directly.

When the provider updates, that code breaks.

Then they debug it. They fix the parsing. They redeploy. Meanwhile, they're down.

The root cause: no isolation between provider and application.

Version Management

We also version our abstractions.

When SAP ships a breaking change to their API, we don't immediately update our abstraction. We support both versions: the old API version (with the old abstraction) and the new one (with the new abstraction).

Our application code can request a specific version of the abstraction.

So we can migrate gradually. We don't have to deploy everything at once.

In practice: SAP ships a change. We add support for the new version to our abstraction layer. We test it. We have a week to migrate our code. Then we deprecate the old version.

Most of the time, the migration is automatic. Our code is written generically enough that it doesn't care which version it's using.

Failure Modes

We also build for failure modes.

When you call an external API:

• It might be slow.
• It might be down.
• It might return an error you don't recognize.
• It might return data in an unexpected format.
• It might be a different version than you expect.

We build the abstraction layer expecting all of these.

Timeouts: we set aggressive timeouts and retry with exponential backoff.

Downtime: we queue requests and process them when the provider recovers.

Errors: we log them and alert. We also have fallback behavior: if we can't reach SAP right now, what's the best thing to do with the current request?

Unexpected data: we validate the response against a schema. If it doesn't match, we log it, alert, and don't proceed. We don't try to be clever.

Real Example: October Incident

SAP updated their API in early October. Response structure changed slightly. A field that was a string became an object with sub-fields.

Our parsing code broke. It tried to access .AMOUNT on what was now an object instead of a string.

But we found out within 15 minutes because our validation layer caught it. The abstraction layer had a schema for what SAP returns. The new response didn't match that schema. We logged an alert.

We updated the abstraction layer (took 30 minutes). We deployed (took 5 minutes). We were back online within an hour.

Meanwhile, we had queued up the requests that came in during that window. They processed automatically once we fixed the abstraction.

Most companies would have been manually debugging this for days.

Documentation

One more thing: we treat the abstraction layer as a contract.

We document it as if it's a public API. We track changes. We have a changelog. When we update the abstraction, we document why.

This forces us to think carefully about changes. If we're going to break the abstraction, we have to document it. That friction prevents unnecessary changes.

Monitoring and Alerting

The last piece: we instrument everything.

For each call to the provider API:

• How long did it take?
• Did it succeed?
• What was the response?
• Did the response match our schema?

We track these in time-series metrics. If response time suddenly jumps, we know. If success rate drops, we know. If responses start deviating from the schema, we know.

Most integration failures aren't surprises. They're gradual degradations that people miss until it's too late.

With proper instrumentation, you catch them immediately.

What We Ship to Clients

At Arvension, we're building "ERP Integration as a Service." We manage the provider APIs. Clients talk to our abstraction layer.

When SAP updates their API, we handle it. Our clients don't have to do anything.

They pay a monthly fee based on the number of integrations and the volume of data flowing through.

We make money by making integrations reliable. That alignment makes us think differently about this problem than vendors do.

The Pattern

The general pattern for any external dependency:

One: identify all the ways it can fail.

Two: build an abstraction layer between your code and the dependency.

Three: make the abstraction handle failures gracefully.

Four: instrument so you see failures immediately.

Five: version your abstraction so you can migrate gradually.

This is a bit more work upfront. But it's 10x less painful when the dependency inevitably changes.

By October next year, most reliable integrations will be built this way. The companies still doing tight coupling will be the ones constantly dealing with integration failures.