The technical half of integrating a supplier is well understood, at least by the people doing it: read the docs, write the module, map the fields, handle the errors. The other half is what actually determines when the integration goes live, and almost nobody writes it down, because it does not look like engineering.
A supplier is not an endpoint. It is a company, with a support desk, a release calendar, a queue of other integrators ahead of you, and an engineer on the far side who has their own manager and their own opinion about whether the thing you reported is a bug.
Certification is a conversation
Bringing a new supplier live ends with certification: a per-provider testcase catalog driven through the full flow, with every case's traffic captured. That much is mechanical. What is not mechanical is that certification happens with somebody. Someone on their side reviews the run, decides whether the scenarios were exercised correctly, and signs it off — and that person's availability is a real dependency of your project.
Which means the calendar is shared. Their release train, their freeze period, their team's holidays, the week they are onboarding a bigger partner than you — all of that is in front of your launch date, and none of it appears in your sprint board. The engineering work can be finished on a Tuesday and the integration can go live a month later without anyone having been slow.
The report has to work without a meeting
When you find a defect in the supplier's system — and on an integration of any size you will — a meeting is the most expensive way to communicate it, and often not available anyway: different company, different timezone, a support address rather than a person. The bug report has to be able to do its job while you are asleep.
What that means concretely is that the report carries the whole case, not a summary of it:
- the exact request that was sent, in a form they can run themselves
- the exact response that came back, verbatim, including the parts that look irrelevant
- the timestamp, with the timezone, so they can find the call in their own logs
- what we expected instead, and why — pointing at their documentation, their schema, or their previous behaviour
- what we already ruled out on our side
The last two lines are the ones that decide whether anything happens. "This endpoint is broken" is a complaint, and a complaint gets queued. "Your documentation says this field is optional; when we omit it the response is an error that does not name the field; here is the call" is a defect report with its own reproduction attached, and it can be triaged by someone who has never spoken to you.
Write for a reader who does not know your system
The failure I see most often in engineers' bug reports — including my own earlier ones — is that they are written from inside our architecture. They name our services. They say a job failed, or a worker did not write something, or a mapping was missing. All true, all meaningless to the recipient, who does not know what any of those things are and cannot verify any of them.
The only shared vocabulary between two companies is the traffic between them. So the report is written entirely in that vocabulary: their endpoint, their fields, their response, their identifiers. Anything that happened inside our system is either irrelevant to them or has to be translated into a statement about the call. It is a small discipline and it changes reply rates in a way I have not measured but have certainly noticed.
The evidence pack is a message
We produce an evidence pack for certification — every testcase's request and response, plus the upstream call, crawled into a named folder. Internally that is a QA artifact. Externally it is a communication artifact, and the difference shows up in how it is built.
A pack for us could be a log dump; a pack for them has to be navigable by somebody who has never seen our naming. Folders named after the scenario, not after our internal case ids. One folder, one story: what was asked, what was sent, what came back. The value is that it answers the partner's next three questions before they ask them, and each question they do not have to ask is a round-trip removed from a conversation that may run at one exchange per day.
Escalating without spending the relationship
Sometimes the thing is genuinely blocking and the normal channel is not moving. Escalation is a real tool and it has a real price, because the same partner is the one you need for the next integration, the next incident, and the commercial conversation your company is having in parallel with the one you are having.
What I try to keep true when I escalate: the facts are the same facts I sent the first time, unembellished; the ask is specific and small ("we need a decision on whether this is expected behaviour, so we can either work around it or wait for a fix") rather than an expression of frustration; and the impact is stated in their terms — bookings that cannot complete, not sprints that slipped. Escalate the problem, never the person, and never in a channel where their engineer reads it as an accusation from a stranger.
The estimate has to contain someone else's queue
Here is the asymmetry that shapes every plan. Their sandbox availability, their documentation's accuracy, their support hours, their fix schedule — none of them are yours to control, and all of them are on your critical path. A plan that assumes an answer arrives when you need it is not an estimate, it is a wish.
I do not have a published figure for how long partner turnarounds take. We have never measured it in a way I would put in writing, and I suspect the average would be misleading anyway, because the distribution is what hurts: most answers are quick and the one that is not lands on the week you promised a launch. So the number I do not have is not the point. The point is that an honest estimate has an explicit line in it for somebody else's queue, and that line is not zero.
Engineers, myself included, prefer to model the part we control. The part we do not control is where the schedule actually lives.