How to integrate systems through an API: contracts, statuses and recovery

Integrating systems through an API enables data exchange and operations through defined interfaces. The work is complete when every value’s source, each operation’s status and recovery after failures can be explained. This guide prepares a verifiable connection between two systems, with a small example and criteria for accepting delivery.

By Lyntev. Updated on .
About 5 minutes to read.

A request that stays connectedThe same reference follows the request and prevents duplicates.

Translation published on . Original Portuguese guide; source revision .

By the end, you can:

  • Specify inputs, outputs and statuses
  • Distinguish events from full synchronisation
  • Test repeated events, access and recovery

Choose the authoritative source for each field

Describe the journey in business terms: “an order confirmed in the sales system creates a job in the operational system”. Identify the common reference and data direction. If both systems can change the same date, decide which takes precedence and how conflicts reach review.

Map by field, rather than just by application. The sales system may own the order and the operational system its execution status. Avoid generic two-way synchronisation that sends every change back to its origin. Define which changes matter and when the current status must be queried.

Choose the authoritative source for each field
Example fieldAuthoritative sourceDestination
order_idSales systemExternal job reference
service_codeApproved catalogueJob type
requested_dateConfirmed requestPreference, subject to planning
work_statusOperational systemProgress information

Write the contract before connecting credentials

Record operations, fields, types, permitted values, responses and errors. OpenAPI defines a way to describe HTTP interfaces for people and tools. If the supplier provides that description, check the version and examples; otherwise document the connection’s minimum contract. Documentation does not replace testing the real operation.

Define what absent, empty and null mean. An omitted property may mean “do not change”, while null may mean “clear”, depending on the API. Also specify date formats, units, limits and calculated fields. These decisions prevent synchronisation deleting information merely because one system did not send it.

Use a fictional request with an expected result

In the example, order ORD-104 is confirmed and should create a job. The event has its own identifier and an order revision. The requested date is a preference, rather than an automatic reservation. The names and format below are a teaching proposal; they must be adapted to the APIs actually contracted.

Expected processing validates the event, looks up the external reference, creates or updates the permitted draft and saves the job identifier. Repeating the same event should return the recorded result. A later revision may change authorised fields; an old revision arriving afterwards must not replace the latest state.

Fictional contract: input and result shown togetherJSON
{
  "entrada": {
    "schema_version": 1,
    "event_id": "evt-demo-104-3",
    "event_type": "order.confirmed",
    "order": {
      "order_id": "ORD-104",
      "revision": 3,
      "service_code": "MANUTENCAO",
      "requested_date": "2026-11-25"
    }
  },
  "resultado": {
    "event_id": "evt-demo-104-3",
    "processing_status": "completed",
    "work_id": "TRAB-208",
    "work_status": "draft"
  }
}

Authorise the operation and the specific record

Keep credentials in the server component and grant only the necessary operations. Separate test and production environments and define how to rotate credentials without losing control of the connection. Technical logs should support investigation by reference without copying secrets or excessive personal data.

Authentication identifies who makes the request; authorisation decides whether they may act on that record. OWASP highlights the need to check object access when an API receives its identifier. Test a reference belonging to another fictional account: a valid credential should not consequently expose every record.

Combine events with a way to check the complete set

A webhook reports an event; a query obtains data according to the API contract. Verify notification authenticity using the supplier’s mechanism before trusting the content. Stripe documents signature verification, repeated deliveries and no guarantee of delivery order, for example. Confirm your supplier’s behaviour instead of assuming it is the same.

Periodic reconciliation compares references and statuses to find differences left by a lost event. When querying lists, follow pagination: the first response may contain only some records, as GitHub documentation shows. Record the cursor or continuation point and handle changes during reading according to the API’s guarantees.

Distinguish a temporary failure from an invalid request

An interrupted connection may leave the result uncertain: the destination may have saved before the response was lost. Use the provided reference and idempotency mechanism, checking scope and expiry. Stripe documents this mechanism; that does not mean every API accepts the same key or offers the same guarantees.

Limit attempts, respect the supplier’s waiting instructions and send persistent failures for review. A queue may deliver a message again, as in the at-least-once delivery model documented by Cloudflare. Consumers therefore also need to recognise repeats. An invalid field is not corrected by indefinitely repeating the same request.

Approve statuses and recovery using concrete evidence

In acceptance testing, confirm ORD-104 generates a single TRAB-208 even after repetition, and that completed refers to integration processing while draft refers to the job. These are statuses of different entities. Then simulate a failure, resume and compare records on both sides.

Include an old version, an out-of-order event, a usage limit, a revoked credential and a multipage list. Assign responsibility for alerts and contract changes. When an API announces deprecation, its update must repeat these tests before replacing the connection the team uses.

Approve statuses and recovery using concrete evidence
TestAcceptance evidence
Same event twiceOne business operation and a reused result
Lost responseReconciliation finds the result without duplication
Earlier revision arrives laterCurrent state preserved according to policy
Several data pagesAll expected references checked
Access to another accountOperation rejected without changing data

Worksheet for your project

Business journey and expected result:
Systems, environments and responsible people:
Fields and authoritative source for each:
Contract, version, input, output and errors:
Common reference, event and revision:
Permissions and technical-log retention:
Event authenticity:
Pagination, continuation and reconciliation:
Idempotency, attempts and persistent failures:
Processing and business statuses:
Test cases and evidence from both sides:
Alerts, maintenance and recovery procedure:

Sources and criteria

Content prepared with AI assistance and research using technical sources, with checks of the relevant examples and calculations. The references support the guide’s decisions; examples identified as fictitious let you try out the method.

Wellinton Oliveira

Written by

CEO of Lyntev

Technology with context, original analysis and sources you can consult.