Integration is not just request/response

An API response reports the result of a request at that moment, but it does not always represent the final state of the operation.

In financial integrations, an operation may keep evolving after the initial call through status changes, asynchronous processing, events, confirmations, or failures.

When to use

Consider this model when:

• building a new integration with the Asaas API;
• implementing operations whose result may change after the initial response;
• reviewing integrations with status mismatches or silent failures;
• defining how your application will handle Webhooks, retries, and reconciliation;
• preparing an integration for production.

Before you start

Before structuring this flow:

• have authentication and basic API calls working;
• identify which entities and states your application needs to track;
• define how Asaas IDs will be linked to internal records;
• identify which updates will be received via Webhooks and which may require querying the API.

How it works

An integration should not be modeled only as:

request → response

The API response is one part of the flow. After it, the operation may keep evolving and require your application to process new information.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Send request"] --> B["Receive response"]
    B --> C["Record ID and state"]
    C --> D{"Can the operation change?"}
    D --> DNao(("No"))
    D --> DSim(("Yes"))
    DNao --> E["Keep recorded state"]
    DSim --> F["Track new information"]
    F --> G["Webhook or API query"]
    G --> H["Update local state"]
    H --> I{"Is there a mismatch or failure?"}
    I --> INao(("No"))
    I --> ISim(("Yes"))
    INao --> J["Continue tracking"]
    ISim --> K["Reconcile or recover"]
    K --> H

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef processo fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef recuperacao fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C,F,G,H processo
    class D,I decisao
    class E,J sucesso
    class K recuperacao

    class DSim,ISim respostaSim
    class DNao,INao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px

Not every operation will go through all these steps. The main point is that your application must be prepared to track the entity after the initial request whenever there is later processing or a later state change.

1. Record the operation

When creating or changing an entity through the API, do not use only the response to update the interface or release the next step of the application flow.

Store the information needed to keep tracking that operation, such as:

• the ID returned by Asaas;
• the corresponding identifier in your system;
• the state known at that moment;
• the date and context of the operation;
• the information needed to trace and diagnose the flow later.

The ID returned by Asaas must be kept as a reference for queries, event processing, and reconciliation.

2. Track state changes

After the initial call, determine whether the entity can change state without a new action from your application.

A charge, for example, may be created in one state and later receive new updates as financial processing takes place.

When there are later changes, your application must update the local record as new information is received.

3. Process events

Webhooks should be part of the architecture whenever your application needs to react to changes that happen after the initial request.

When receiving an event:

• identify the related entity;
• persist the necessary information before processing;
• update the local state according to the event received;
• allow processing to be safely repeated;
• keep enough information to trace the event later.

The application must not depend on receiving each event only once, nor assume that all events will arrive exactly when expected.

4. Prepare for inconclusive responses

Communication failures can leave the result of an operation uncertain.

For example, a timeout does not necessarily mean the operation was not processed. The application may lose the response even though the server received and executed the request.

In these cases, immediately repeating the same operation without any validation can create duplicates.

Before reprocessing, your application must be able to determine whether:

• the operation was actually created;
• there is a corresponding entity in Asaas;
• a new attempt is really necessary;
• the repetition can be executed safely.

This control is detailed in the Retries and idempotency chapter.

5. Reconcile mismatches

Webhooks are important for tracking changes, but they should not be the only mechanism available to identify inconsistencies.

Your integration must have a strategy to compare the state recorded locally with the state available in Asaas when there is a sign of a mismatch.

Reconciliation may be necessary when:

• an event was not processed;
• your application was temporarily unavailable;
• an update failed internally;
• the local state remained unchanged for an unexpected period;
• there is doubt about the result of an operation.

The goal is to allow the application to return to a consistent state without depending on manual intervention for each occurrence.

Attention — common mistakes

Avoid architectures that:

• treat the initial response as the definitive state of the operation;
• do not store the IDs returned by the API;
• depend exclusively on the synchronous response;
• ignore events related to the entities used;
• repeat requests after failures without checking the previous result;
• have no reconciliation mechanism;
• record insufficient information to investigate a failure.

Confirm your architecture

Before taking the integration to production, confirm that your application can answer:

• What is the complete flow of each operation?
• Which IDs need to be stored?
• Which states does the application need to know?
• Which changes will be tracked via Webhooks?
• What happens when a Webhook is not processed?
• How does the application react to a timeout or inconclusive response?
• How is a duplicate attempt identified or prevented?
• How are mismatches between the local system and Asaas detected?
• What information is available for diagnosis?

If these situations are not accounted for, the integration will depend on the ideal scenario to keep the state consistent.

Best practices

• keep the Asaas ID linked to the internal identifier of the operation;
• treat states as part of the integration's domain, not just as values displayed in the interface;
• implement Webhooks from the start in flows that depend on later updates;
• make event processing tolerant to duplicates and reprocessing;
• do not automatically equate a timeout with a failed operation;
• have a reconciliation strategy to fix mismatches;
• record enough context to investigate failures without relying only on isolated logs.

Next steps

Now that the lifecycle of an operation is defined, dive deeper into how to represent these changes within the application:

• States, events, and consistency
• Synchronous and asynchronous communication