Fourteen brands, one provisioning API

At iubenda I owned the team.blue integration: new REST APIs that let a compliance product be sold, tracked and provisioned across fourteen partner brands, each with its own platform, its own checkout and its own idea of what a customer is.

Fourteen is an awkward number. Two partners, and you write two integrations and move on. Fourteen, and you either find the one shape they all fit or you spend the next two years maintaining fourteen of everything.

The thing they disagree about is identity

Every partner agreed on what they were selling. None of them agreed on who they were selling it to. One brand's account is a billing entity, another's is a person, another's is a domain. The provisioning call has to work for all three without the API pretending the differences do not exist.

What worked was refusing to model the partner's customer at all. The API takes an external reference that the partner owns and is responsible for keeping stable, and returns our own identifier. We never try to interpret their side of it. That sounds like giving up, and it is, deliberately. Every attempt to be clever about reconciling identity across fourteen systems is a support ticket waiting for a quiet Friday.

Specs get accepted, then drift

I write the API specification. Engineering accepts it. Then implementation starts and the spec and the code begin drifting apart, usually for good reasons that nobody writes down.

The habit that fixed this was staying in Git after acceptance. I reviewed pull requests through implementation, not to approve the code, which is not my call, but to catch the places where the build had quietly diverged from the agreed contract. Most of the time the code was right and the spec was wrong, and it was cheaper to learn that in a diff than from a partner.

Production logs are a product surface

The integration served a platform used by over 100,000 businesses, which means the failure modes are statistical. Something that breaks for one partner in a thousand calls will break every day.

I monitored and debugged integration performance against production logs and validated the data and workflows there rather than in staging. Staging tells you whether the happy path works. Production tells you what people actually send you, which included, on more than one occasion, fields we had documented as required and never enforced.

The part worth copying

Pick the smallest thing the partners genuinely share, build the contract around exactly that, and push every difference to the edge where one brand's oddity stays one brand's problem. Then stay close enough to the implementation to notice when the contract stops being true.