Writing an integration specificationthat people actually read

An integration specification is the document that says how two pieces of software talk to each other: here, an ERP and an online shop. On paper, everyone agrees it should exist. In practice, it is often written once, sent as an attachment, and never opened again. Everyone keeps their own version in their head, and the gaps show up during acceptance testing.

I have written and maintained these documents on client work, and I also build content machines that publish articles with no review before they go live. The two jobs are closer than they look: in both cases, a document has to be precise enough for a tool or another team to act on it without ringing you. What follows is my method: what I put in the document, and what I borrow from my pipelines to keep it read.

01Why most integration specifications go unread

You may have seen this yourself. The first reason is simple: they are written for only one of the two teams. The ERP vendor's document talks about models and fields, the web team's talks about pages and baskets. Nobody recognises themselves in the other side's text.

The second reason is that they are long in the wrong places. Thirty pages on the project background, and three lines on what happens when an order arrives with an unknown product reference. That is exactly the question your developer will be asking on a Tuesday evening.

The third reason is that they stand still while the project moves. This is not a small-project problem. In a talk published by the OpenAPI Initiative, Vasco Veloso starts from the same observation: published API specifications are often incomplete, missing examples or simply outdated, because keeping them in sync is manual work that gets forgotten in the rush to deliver. A wrong document is worse than no document: it proves right whoever read it last.

02What an integration specification should contain

I always split the document into flows, and I suggest you do the same. A flow is one specific exchange: orders from the site to the ERP, stock from the ERP to the site, shipping statuses, product data. Each flow gets its own sheet, always built the same way, so people know where to look.

A flow sheet in eight questions

1. What triggers it? A confirmed order, a set time, a stock change.
2. Who owns the data? One system is the source of truth for each piece of information. If stock exists in both, you have to write down which one wins.
3. Which direction does the flow go, and how often?
4. Which fields are passed, and what do they map to on the other side? That is the mapping table, which I come back to below.
5. What format for dates, amounts and measurements? The UK government's public API standards, for example, recommend ISO 8601 for dates and UTF-8 for text.
6. What happens when something fails? Which message, who is told, is the exchange replayed automatically?
7. How do we check the flow works? One test case per rule, with test data rather than real data.
8. Which version of which interface are we using?

An incomplete sheet does not pass

In my content machines, no article gets written until its brief has been validated by a command. If a source, a question or an angle is missing, it answers "BRIEF REFUSED" with the list of what is missing. I apply the same rule to flow sheets: until each of the eight questions has an answer, the flow is not ready to build. An empty box says "nobody has decided yet", and it is better to see that before the first sprint than during acceptance testing.

The eighth question looks like a detail. It is not. Odoo's documentation, for instance, states that the XML-RPC and JSON-RPC endpoints are deprecated, replaced by a new API, with removal planned in Odoo 22. An integration written without naming the interface it relies on will break one day, and nobody will know why.

On the shop side, I read the platform's documentation before writing the sheet. PrestaShop's explains that its webservice works with an access key whose permissions are set resource by resource, and that it can answer in JSON but still expects XML for writes. These are details, and they are what derail a schedule when you find them late.

03Real time or batch feeds: decide flow by flow

You may be asking this question as if it had one answer for the whole project. I never treat it that way. I ask the same question for every flow: what does late data cost?

If the site shows stock as available when the ERP has none left, the customer orders something you cannot deliver. That flow deserves a real-time call, or at least a very short interval. On the other hand, a product description that changes once a month can quite happily go through an overnight batch feed. Nobody will see the difference, and a file that arrives at a set time is easier to monitor and to replay. Both often live side by side in the same integration, and the specification should say, flow by flow, why one was chosen over the other.

Real time has a cost people forget: you have to handle the other system being unavailable. If the ERP does not respond, what does the site do? Block the order, put it on hold, create it anyway? The answer is a business decision, not a technical one, and it has to be written down.

Replaying without creating duplicates

There is one rule I learnt building my publishing pipelines: every step is logged, so that a rerun picks up where it stopped without creating a second article. An integration has exactly the same need. If an order flow fails halfway and you rerun it, the order must not land in the ERP twice. So in each sheet I ask which identifier tells us an exchange has already been processed.

04The field mapping table, with units

This is the most thankless part of the document, and the part people read most. One row per field, with at least these columns:

• the field name in the source system;
• the field name in the target system;
• the type and format (text, integer, date);
• the unit, for anything that is measured or counted;
• mandatory or not, and what happens if it is missing;
• the transformation rule, if there is one, rounding included.

If you only add one column, make it "unit". I have seen a mix of centimetres and millimetres between two tools distort a whole render. A unit column filled in for every measurement does not guarantee that kind of error never happens. It does force someone to ask the question when writing the row, rather than when the result comes out wrong. The reference data has to be explicit, field by field.

The rounding rule deserves its own row too. At Moonworkers, our payroll software, an oracle written from HMRC's own texts replayed 896 contribution calculations and found four one-penny errors, all caused by a rounding rule. A penny is not much. On an invoice or a tax return, it is a gap someone will have to explain.

05Keeping the specification alive, version after version

On an integration between an ERP and an online shop, I watched the specification change at almost every meeting. That is the normal rhythm of this kind of project: each workshop turns up a case nobody had planned for. The real risk is that the changes live in scattered emails and meeting notes. I moved it forward version by version, so that everyone was talking about the same document.

What I do in practice:

1. One reference document, in one place, that everyone can read.
2. A version number at the top, and a change log just below it: date, what changed, why, who signed it off.
3. After each meeting, I put the decisions into the document the same day, and I send the link to the new version rather than a summary.
4. When a change breaks something that already existed, I flag it clearly and give the teams time to adapt.

That last point matches public guidance: the UK government advises avoiding changes that break previous versions and warning users before retiring a version. Its documentation guide also asks for a section explaining how versioning works and where changes are published.

I add one habit from my machines: the rules live in one file, not in messages. When a reviewer corrects an article, I do not just fix the text, I write the rule into the pipeline's configuration, with a comment saying why it exists. I describe this in my note on an AI content machine with human review. A specification works the same way: a decision made in a meeting that is not in the document does not exist.

06What the specification does not replace

A good specification does not spare you from talking to the teams. It just makes the conversations shorter. When two teams disagree on a rule, the document shows exactly where the disagreement is. It does not settle it for them.

It does not replace acceptance testing either. I can write a perfect rule, but if nobody tests it with real cases before go-live, it remains a hypothesis. That is why each sheet carries its test cases, including the ones that must fail: an order with no reference, negative stock, a date in the wrong format. In my pipelines, deliberately bad articles must always come out red; if one passes, the check itself is broken. My acceptance testing and go-live checklist starts from the same idea.

Finally, the method has a cost. Keeping a document current after every meeting takes time, every week, for the whole project. For a small integration between two standard tools with an existing connector, I would not write anything this complete: one page with the flows, the data owners and the errors is often enough. The full method earns its keep when several teams work in parallel and none of them sees the whole project.

07Where to start on Monday

If your integration project is starting or stalling, this is what I would do first:

1. List the flows on a single page, with the direction, the frequency and the system of record for each.
2. For the riskiest flow, usually orders or stock, write the full sheet with its eight questions, and leave the empty boxes visible.
3. Open the mapping table for that flow and fill in the "unit" column before any other.
4. Put a version number at the top of the document and the first change in the log.

This is part of the work I do in technical and project direction. If your integration looks like this one, we can talk about it.