Integrating Interfaces and APIs: Data Contracts, Synchronisation and Operations

The shop-and-ERP example runs through the whole article. The same decisions apply to connections between CRM, accounting or bespoke software.

01An API connection is not yet a process integration

An API is a contract: it defines which operations a system offers, which data is exchanged and which error responses are possible. An interface is the more general term for any connection between systems – an API is its precise, usually standardised form.

The common mistake starts earlier: one system calling the other is not yet an integration. A reachable endpoint does not answer which system is the master for the order, what happens on an error in the target, whether the same order can arrive twice, or who notices in operation when the data flow stops.

An integration therefore has to be designed as an end-to-end process. Only once data ownership, sequence, error handling and operation are defined has a connection become a business process.

02The integration form follows the process

Four integration forms cover most requirements: the synchronous API call, the webhook, the queue and batch processing. None of them is superior across the board.

The decision follows the process, not the technology. If the caller needs an immediate answer – the shop when calculating prices in the basket, say – the synchronous call is the right form. If the ERP should be informed of every order at once without the shop waiting for a reply, a webhook fits. If outages on either side must be bridged, a queue buffers. Accounting data transferred in a nightly bundle is a legitimate batch case.

Webhooks deserve particular attention because their contractual position is often misunderstood. Delivery guarantees, retry windows and event ordering are not properties of the webhook mechanism but of the individual provider. Stripe documents that endpoints can receive the same event more than once and does not guarantee that events arrive in order of creation; timestamps are not a reliable ordering criterion, and Stripe explicitly advises against using the created field to determine event order (Stripe). A webhook endpoint first checks the authenticity of the message, stores the event durably – in an inbox or queue, for instance – and only then acknowledges receipt with 2xx. Business processing follows asynchronously; a duplicate is normal input there, not an incident. Anyone who acknowledges receipt without first securing the event loses it in a crash immediately after the acknowledgement.

03Defining data ownership, identities and mapping

Before any technical implementation, it has to be settled per data object which system is its master. In the example: the shop owns the basket, the ERP owns stock, documents and the item master. Conflicting write rights on the same object are a typical source of permanently divergent data.

Several decisions follow from this:

• System and external identities. The shop knows its order number, the ERP its document number. The assignment is kept as a mapping of its own, not by overwriting one of the two numbers.
• Status semantics. What does the status in the source system mean in the target system? A “paid” in the shop may only cover a deposit in the ERP.
• Missing fields, units and deletions. A missing optional field is information; a missing mandatory field is a contract violation. The contract defines what a missing field, a null value and an empty value each mean. Deletions are agreed: delete permanently, mark as deleted, or do not transfer.
• Synchronisation loops. If a system reports back every change it has adopted, a loop can result. What matters is write ownership and rules not to re-transmit changes that were triggered by the system itself or already adopted; marking the origin of a change helps, but is not a control on its own.

A mapping record may look like this:

{  "external_id": "order_20260741",  "local_id": "ERP-DOC-41872",  "entity": "order",  "source_system": "shop",  "mapped_at": "2026-10-26T09:14:00Z"}

When creating a new record, the target ID does not yet exist before the first write call. The integration therefore stores the operation before the call under a stable identifier of the logical operation and assigns the target ID only after the creation is confirmed. If the response is lost, the restart rules in section 7 apply.

04Describing data contracts and changing them in a controlled way

A data contract describes which fields are exchanged with which types, obligations and value ranges. For HTTP APIs, the OpenAPI Specification is the common description format (OpenAPI Initiative). The contract is the basis for three checks: validating incoming data against the schema, checking outgoing data before sending, and detecting when the other side changes.

A schema-compliant message can still be invalid in business terms – an order for an item without stock satisfies every data type. The contract therefore has to document business rules alongside structure: valid status transitions, mandatory field combinations, handling of empty values.

Whether a change is compatible depends on direction, contract and consumer behaviour. New optional fields are only unproblematic if consumers tolerate unknown fields. New values in existing enumerations can overwhelm clients with closed case distinctions – especially in responses a consumer does not control. Removed fields, changed types, new mandatory fields or changed semantics are breaking changes. Whether a break actually takes effect is checked against the actual consumers: if one partner uses the field, it is in use. A version number alone does not answer that. Breaking changes come with announced deadlines and transition periods in which both variants work.

05Adapters separate system details from process logic

The robust structure of an integration does not depend on whether two or ten systems are connected. Each external system gets its own adapter that translates its data model, authentication and error messages. In between sit mapping and process steps in a layer of their own that need not know any shop or ERP details.

The separation pays off at the first change: a new ERP or a changed shop data model mainly affects the respective adapter. The process logic – what happens to an order when the ERP rejects it – usually remains untouched.

A gateway or message broker is not an end in itself. With few participants and clear flows, adapters and a process layer are sufficient. A broker is justified by requirements such as several independent consumers of the same event, strongly fluctuating loads or independent release cycles of the teams involved.

06Distinguishing initial load from ongoing synchronisation

Two procedures are often mixed up although they have different requirements: the initial load of the existing data and the ongoing synchronisation.

The initial load transfers existing data volumes – item master, stock, open orders. It works with pagination and stores checkpoints so that an abort does not start from scratch. It has to cope with a changing data set: orders keep being placed during the load. The handover to ongoing processing is defined as well: for a gap-free transition, the data set and the subsequent changes have to be aligned, for example through a consistent snapshot with an associated change position according to the source API's contract. A marker set only at the end of the load is not enough: it can skip changes made in the meantime. If the API offers no such support, an explicitly bounded fallback strategy with a subsequent reconciliation is needed. Pagination and checkpoints alone do not guarantee a gap-free data set.

Ongoing synchronisation processes changes. It has to handle duplicates, late events and events without a predecessor. Which delivery guarantees apply is determined by the individual provider: with Stripe, events can arrive more than once and out of creation order (Stripe). If an event arrives without its predecessor, the adapter can read the current state through the API instead of rejecting the operation as faulty. That does not, however, replace a distinct business event with defined follow-up steps: for replicating the state of an object the current state is enough; for a process step to be triggered, the event itself or an explicitly agreed fallback rule is needed.

Regardless of the form of transmission, a regular reconciliation belongs to it: comparing the data of both systems – counts, totals, samples of deviating records – also finds gaps that produced no error message. Otherwise, missing webhooks only become visible through business symptoms, such as orders without a follow-up document. Reconciliation is not an admission of failure; it is part of operation.

07Modelling errors and partial success explicitly

Three error categories require different responses:

• Technical error. The target system is unreachable, responds with 5xx or aborts. That initially describes the observed disruption, not necessarily the execution result – even after a 5xx the change may already have taken place. Automatic retries require a transient error and either proven non-execution or contractually assured idempotency; they are time-limited, with back-off, and follow the target's Retry-After rules where documented.
• Business rejection. The target understood the call and rejected it – missing stock, an invalid status. A repeated identical call is rejected as well as long as the cause persists. RFC 9457 defines application/problem+json as a format for machine-readable error details; application-specific information can be added as extensions (RFC 9457).
• Unknown outcome. The call was sent, the response was lost. That is not a proven failure, and a blind retry may execute the action twice.

The category decides the next step. Technical errors belong in the time-limited retry only under these conditions. Business rejections do not belong in the retry but in a clarification list with a named owner: an order without stock is not resolved by the fifth identical call but by a business decision. Unknown outcomes are clarified before any retry – through the target API's idempotency function, where documented, or through a unique external reference in the target system. Operations that remain open after the retry window has expired move to a separate holding area and are counted; they are the metric “pending operations” in section 10.

When integrating independent APIs, there is usually no shared atomic transaction. A multi-step flow – accept the order, book the stock, confirm to the shop – can be partially successful. Each step therefore gets its own state, and resumption after an abort starts from the first unconfirmed step. Idempotency keys for write calls, handling lost responses and reconciling with the target system before a retry are described in detail in the article Integrating AI Agents into Production; the rules apply to every system connection, with or without a language model.

08Checking identity and permissions at system boundaries

Authentication and authorisation are different checks. The first establishes who or what is calling; the second, what this caller may do on this resource. The target system has to check access itself; the integration application complements this control by limiting its own credentials, permissions and the forwarding of identities.

For authorisation between systems, OAuth 2.0 is the established framework (RFC 6749); for system-to-system connections in which a confidential client acts on its own behalf, the client credentials flow is suitable, provided the target platform offers it. The accompanying security guidance recommends restricting an access token's permissions to the necessary minimum, prohibits the resource owner password credentials grant, advises against the implicit grant and recommends sender-constrained access tokens, for instance via mutual TLS or DPoP (RFC 9700). API keys in query parameters or permanently valid tokens are accordingly to be avoided. Client secrets and tokens live in the platform's secret store – not in source code, not in logs, not in the frontend.

In addition:

• Permissions follow the principle of least privilege. The shop adapter that only sends orders needs no write access to item masters. The OWASP API Security Top 10 list broken object level authorisation in first place (OWASP, API1:2023).
• Webhook endpoints verify the signature. The message is authenticated against the sender, following the procedure defined by the provider – often an HMAC over the unmodified message body – before any field is processed.

09Testing contracts, error cases and restart

Tests of an integration check more than the success paths. Three levels are to be kept apart:

• Contract tests. Send and receive messages at the edge of the contract: missing mandatory fields, wrong types, unknown fields of a newer version, new values in an enumeration. These tests run against the adapters without involving the counterpart systems.
• Integration tests with test data. The shop–ERP reconciliation is checked with agreed test data – orders, stock changes, price changes – and the expected values are compared in both systems.
• Business end-to-end acceptance. The complete process including the error cases that are certain to occur in operation.

The error cases include at least: the same event twice; an event before its predecessor; an abort of the initial load with restart at the checkpoint while the source data set has changed in the meantime; a reconciliation that must find a deliberately created gap; two shop orders that are to be mapped to the same ERP document number; a new mandatory field on the other side. Added to these are the cases that affect every writing API connection – a target that stops responding mid-flow, and a lost response after a successful write call (section 7). No integration test that only covers the normal case checks the properties that count in operation.

10Operation needs business-level evidence and named owners

An integration is only in operation when its state can be assessed without studying logs. Technical metrics such as error rates and latency are necessary but not sufficient. The more meaningful measures are business-level:

• Backlog. How many changes are waiting to be processed, and how old is the oldest?
• Pending operations. Orders in the shop without a document in the ERP – the central business metric of the example.
• Unresolved discrepancies. Records that do not match in the reconciliation of both systems without an error being present.

A correlation ID accompanies every change through all systems and links shop event, adapter processing and ERP document. Without it, every incident investigation is a reconstruction.

At least as important as monitoring are named responsibilities: who is informed when the other side changes its API, and who adapts the adapter? Who handles incidents outside business hours? Who decides on retrying stuck operations? Answering these questions before go-live is part of the integration – not an afterthought.

Sources

• IETF: RFC 9457, Problem Details for HTTP APIs (opens in a new tab)
• IETF: RFC 6749, The OAuth 2.0 Authorization Framework (opens in a new tab)
• IETF: RFC 9700, Best Current Practice for OAuth 2.0 Security (opens in a new tab) (BCP 240)
• OpenAPI Initiative: OpenAPI Specification v3.2.1 (opens in a new tab)
• Stripe: Receive Stripe events in your webhook endpoint (opens in a new tab) (duplicate events, event ordering, retries)
• Stripe: Idempotent requests (opens in a new tab) (API reference)
• OWASP: API Security Top 10 (2023) (opens in a new tab), API1:2023 Broken Object Level Authorization

All sources retrieved on 26 October 2026.

Technical implementation with Seovantis

If connections between existing systems are to be implemented, we take over the technical implementation. Seovantis implements software modules, APIs and interfaces for existing business applications – between shop, inventory management, CRM, ERP or bespoke software, for instance.

Depending on the project, this includes connecting existing APIs, adapters and data transfer with an agreed reconciliation, backend components for state and execution, and tests and acceptance criteria. The check before handover follows the agreed requirements.

Related article: Integrating AI Agents into Production: Tool Calling, State Management and Secure API Execution