Integrations fail at the seams

The connector is not the integration

Most integration work is sold as a line on a diagram: Salesforce to billing, warehouse to storefront, payments to the ledger. The line looks thin. In production it is a set of meanings that do not quite match, a retry policy that creates duplicates, and a person in operations who has a spreadsheet because they do not trust either side.

If your business still has a human bridging two tools, you do not have a missing API. You have an unresolved seam: a status, an identifier, a timing assumption, or an exception that nobody wanted to design.

The four seams that actually break

• Identity. What is the same customer in both systems? Email is not an identifier. Neither is name. If you cannot point to the join key, you will create doubles.
• Meaning. “Paid,” “closed,” and “complete” are not portable. Each system uses those words for a different moment in the business.
• Time. One side is eventually consistent. The other expects an answer now. Someone will poll, timeout, and try again.
• Failure. A 500 is easy. A 200 with a partial body, a webhook delayed by an hour, or a “success” that will be reversed tomorrow is the real work.

Make the handoff observable

An integration that cannot explain itself will be replaced by a human. That is not a metaphor. Operations will open both UIs and type. The system has already lost.

For every important handoff, someone who is not an engineer should be able to answer: what was sent, what was acknowledged, what is waiting, and what needs a person. That usually means a record of the attempt, a visible status, and a way to replay without creating a second truth.

If the only log is in a vendor dashboard you lose access to next year, you do not own the integration.

Automate the repeatable path. Keep a door for the exception.

The aim is not to remove humans from every case. The aim is to stop humans from doing the same correct case two hundred times a week, and to give them a controlled place to handle the case the systems cannot agree on.

A good integration has a quarantine. Records that cannot be matched, amounts that do not reconcile, statuses that were not in the contract — they land somewhere a person can see, with enough context to decide, and they do not silently enter the ledger.

• Define the contract in examples, not only in field names. Include the ugly ones.
• Prefer your own store of what you sent and received over trusting the other system as history.
• Make replay a first-class action, with the same idempotency as the original.
• Agree who owns a mismatch. “The API” is not an owner.

This is the work hiding inside “just connect it”

When a business asks us to connect the tools they already use, we spend the first conversations on the seams, not the logo list. Which identifier is true? Which status means money has moved? What happens when the other side is down during your busiest hour?

If you already know those answers, the build is straightforward. If you do not, writing them down is the highest-leverage hour you can spend. The integration will fail at exactly the place you skipped.