---
title: "How to integrate systems through an API: contracts, statuses and recovery · Lyntev"
description: "Prepare an API integration covering data ownership, contracts, permissions, pagination and failure handling. Includes a fictional payload and acceptance criteria."
url: "https://lyntev.com/en/guides/integrate-systems-api"
language: "en-GB"
date_published: "2026-11-21T17:20:13.047Z"
date_modified: "2026-11-21T17:20:13.047Z"
---

1. [Home](<https://lyntev.com/en>)
2. [Practical guides](<https://lyntev.com/en/guides>)
3. How to integrate systems through an API: contracts, statuses and recovery

# 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](<https://lyntev.com/en/company>). Updated on 17 November 2026.
About 5 minutes to read.

[Start reading](<https://lyntev.com/en/guides/integrate-systems-api#leitura>)[Download worksheet](<https://lyntev.com/recursos/en/integrar-sistemas-por-api.txt>)

**A request that stays connected**The same reference follows the request and prevents duplicates.

Translation published on 21 November 2026. [Original Portuguese guide](<https://lyntev.com/guias/integrar-sistemas-por-api>); source revision 17 November 2026.

By the end, you can:

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

In this guide

1. [Choose the authoritative source for each field](<https://lyntev.com/en/guides/integrate-systems-api#origem-e-destino>)
2. [Write the contract before connecting credentials](<https://lyntev.com/en/guides/integrate-systems-api#contrato-explicito>)
3. [Use a fictional request with an expected result](<https://lyntev.com/en/guides/integrate-systems-api#payload-preenchido>)
4. [Authorise the operation and the specific record](<https://lyntev.com/en/guides/integrate-systems-api#permissoes-e-segredos>)
5. [Combine events with a way to check the complete set](<https://lyntev.com/en/guides/integrate-systems-api#eventos-e-listagens>)
6. [Distinguish a temporary failure from an invalid request](<https://lyntev.com/en/guides/integrate-systems-api#falhas-e-repeticao>)
7. [Approve statuses and recovery using concrete evidence](<https://lyntev.com/en/guides/integrate-systems-api#aceitacao-operacional>)
8. [Sources and criteria](<https://lyntev.com/en/guides/integrate-systems-api#fontes>)

## 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 field | Authoritative source | Destination |
| --- | --- | --- |
| order\_id | Sales system | External job reference |
| service\_code | Approved catalogue | Job type |
| requested\_date | Confirmed request | Preference, subject to planning |
| work\_status | Operational system | Progress 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.

- [OpenAPI: describing the capabilities of an HTTP interface](<https://spec.openapis.org/oas/latest.html>)

## 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.

- [OWASP: object-level access control](<https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization/>)

## 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.

- [Stripe: event authenticity, order and redelivery](<https://docs.stripe.com/webhooks>)
- [GitHub: example of paginated responses](<https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api>)

## 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.

- [Stripe: idempotency contract](<https://docs.stripe.com/api/idempotent_requests>)
- [Cloudflare: message delivery and duplicates](<https://developers.cloudflare.com/queues/reference/delivery-guarantees/>)

## 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

| Test | Acceptance evidence |
| --- | --- |
| Same event twice | One business operation and a reused result |
| Lost response | Reconciliation finds the result without duplication |
| Earlier revision arrives later | Current state preserved according to policy |
| Several data pages | All expected references checked |
| Access to another account | Operation 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.

- [OpenAPI Initiative: descrição de interfaces HTTP](<https://spec.openapis.org/oas/latest.html>)
- [OWASP: autorização ao nível do objeto numa API](<https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization/>)
- [Stripe: receção e verificação de webhooks](<https://docs.stripe.com/webhooks>)
- [GitHub: percorrer respostas paginadas de uma API](<https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api>)
- [Stripe: pedidos idempotentes](<https://docs.stripe.com/api/idempotent_requests>)
- [Cloudflare: garantias de entrega de filas](<https://developers.cloudflare.com/queues/reference/delivery-guarantees/>)

## Continue to your next decision.

- [Specific connection between a form and CRM](<https://lyntev.com/en/guides/connect-website-form-crm>)
- [Automate customer reminders](<https://lyntev.com/en/guides/automate-customer-reminders>)
- [Process automation with Lyntev](<https://lyntev.com/en/process-automation>)

[Explore the guide library](<https://lyntev.com/en/guides>)

## Would you like to apply this to your business?

Send us your worksheet or explain what you need to improve. We help you choose the next step for your project.

- [Lyntev assistant Immediate answers about services, prices and timescales, with a cost estimate. Read the assistant guide](<https://lyntev.com/en/help/ai-assistant>)
- [WhatsApp +351 928 412 891. The message is only sent when you confirm it in WhatsApp. Write on WhatsApp](<https://wa.me/351928412891?text=Hello!%20I%20came%20from%20the%20Lyntev%20website%20and%20would%20like%20to%20discuss%20a%20project.>)
- [Form Describe what you need and receive the reply by email. Complete the form](<https://lyntev.com/en/contact>)
- [Email contacto@lyntev.com Send an email](<mailto:contacto@lyntev.com?subject=Request%20for%20information>)

![Wellinton Oliveira](<https://lyntev.com/media/autores/wellinton-oliveira.webp>)

Written by

[Wellinton Oliveira](<https://lyntev.com/en/company>)

CEO of Lyntev

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