Integration Architecture Guide

Integrations with the Asaas API do not end with the response to a request. An operation may change state later, generate new events, or require recovery in case of failure.

This guide presents the main concepts for building resilient, production-ready integrations, covering state control, event processing, synchronous and asynchronous communication, retries, idempotency, reconciliation, and observability.

When to use

Use this guide when you need to:

• model a new integration with Asaas;
• review integrations with status mismatches, duplicates, or silent failures;
• define how your application will handle events and state changes;
• implement retry and failure recovery mechanisms;
• prepare an integration to operate in production.

Before you start

Before applying the concepts in this guide:

• have authentication and your first API calls validated;
• identify which operations depend on later confirmation;
• define whether your integration will use Webhooks, reconciliation queries, or both mechanisms.

How it works

An integration should be treated as a continuous flow, not as an isolated call.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart LR
    A["Execute operation"] --> B["Record state"]
    B --> C["Receive event"]
    C --> D["Update application"]
    D --> E{"Failed?"}
    E --> ENao(("No"))
    E --> ESim(("Yes"))
    ENao --> F["Flow completed"]
    ESim --> G["Recover or reprocess"]
    G --> B

    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,D processo
    class E decisao
    class F sucesso
    class G recuperacao

    class ESim respostaSim
    class ENao respostaNao

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

The synchronous API response represents the result of that request at that moment. Depending on the operation, the state may change later due to financial processing, review, confirmation, refund, or other events.

That is why your application must be prepared to record the current state, process new information, and reconcile any mismatches.

Guide steps

Next steps

Start by understanding why an integration should not depend only on the immediate response to a request:

• Beyond request/response
• States, events, and consistency