Integração não é apenas request/response

Uma resposta da API informa o resultado de uma requisição naquele momento, mas nem sempre representa o estado final da operação.

Em integrações financeiras, uma operação pode continuar evoluindo depois da chamada inicial por meio de mudanças de status, processamento assíncrono, eventos, confirmações ou falhas.

📘
Ao concluir esta página, você entenderá por que uma integração não deve depender apenas do request/response e quais mecanismos devem fazer parte da arquitetura para acompanhar todo o ciclo de uma operação.

Quando utilizar

Considere este modelo ao:

desenvolver uma nova integração com a API Asaas;
implementar operações cujo resultado pode mudar após a resposta inicial;
revisar integrações com divergências de status ou falhas silenciosas;
definir como sua aplicação tratará Webhooks, retries e reconciliação;
preparar uma integração para produção.

Antes de começar

Antes de estruturar esse fluxo:

tenha a autenticação e as chamadas básicas à API funcionando;
identifique quais entidades e estados sua aplicação precisa acompanhar;
defina como os IDs do Asaas serão relacionados aos registros internos;
identifique quais atualizações serão recebidas por Webhooks e quais poderão exigir consulta à API.

Como funciona

Uma integração não deve ser modelada apenas como:

requisição → resposta

A resposta da API é uma parte do fluxo. Depois dela, a operação pode continuar evoluindo e exigir que sua aplicação processe novas informações.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Enviar requisição"] --> B["Receber resposta"]
    B --> C["Registrar ID e estado"]
    C --> D{"A operação pode mudar?"}
    D --> DNao(("Não"))
    D --> DSim(("Sim"))
    DNao --> E["Manter estado registrado"]
    DSim --> F["Acompanhar novas informações"]
    F --> G["Webhook ou consulta à API"]
    G --> H["Atualizar estado local"]
    H --> I{"Existe divergência ou falha?"}
    I --> INao(("Não"))
    I --> ISim(("Sim"))
    INao --> J["Continuar acompanhamento"]
    ISim --> K["Reconciliar ou recuperar"]
    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

Nem toda operação seguirá todas essas etapas. O ponto principal é que sua aplicação deve estar preparada para acompanhar a entidade depois da requisição inicial sempre que houver processamento ou mudança de estado posterior.

1. Registre a operação

Ao criar ou alterar uma entidade pela API, não utilize apenas a resposta para atualizar a interface ou liberar o próximo fluxo da aplicação.

Armazene as informações necessárias para continuar acompanhando aquela operação, como:

ID retornado pelo Asaas;
identificador correspondente no seu sistema;
estado conhecido naquele momento;
data e contexto da operação;
informações necessárias para rastrear e diagnosticar o fluxo posteriormente.

O ID retornado pelo Asaas deve ser mantido como referência para consultas, processamento de eventos e reconciliação.

2. Acompanhe mudanças de estado

Depois da chamada inicial, determine se a entidade pode mudar de estado sem uma nova ação da sua aplicação.

Uma cobrança, por exemplo, pode ser criada em um estado e posteriormente receber novas atualizações conforme o processamento financeiro ocorre.

Quando houver mudanças posteriores, sua aplicação deve atualizar o registro local conforme novas informações forem recebidas.

⚠️
Não considere automaticamente o status retornado na criação de uma entidade como seu estado definitivo.

3. Processe eventos

Webhooks devem fazer parte da arquitetura sempre que sua aplicação precisar reagir a alterações que acontecem depois da requisição inicial.

Ao receber um evento:

identifique a entidade relacionada;
persista as informações necessárias antes do processamento;
atualize o estado local conforme o evento recebido;
permita que o processamento seja repetido com segurança;
mantenha informações suficientes para rastrear o evento posteriormente.

A aplicação não deve depender de receber cada evento uma única vez nem assumir que todos os eventos chegarão exatamente no momento esperado.

4. Prepare-se para respostas inconclusivas

Falhas de comunicação podem deixar o resultado de uma operação incerto.

Por exemplo, um timeout não significa necessariamente que a operação deixou de ser processada. A aplicação pode perder a resposta mesmo que o servidor tenha recebido e executado a requisição.

Nesses casos, repetir imediatamente a mesma operação sem qualquer validação pode gerar duplicidades.

Antes de reprocessar, sua aplicação deve conseguir determinar se:

a operação chegou a ser criada;
existe uma entidade correspondente no Asaas;
uma nova tentativa é realmente necessária;
a repetição pode ser executada com segurança.

Esse controle será detalhado no capítulo de Retries e idempotência.

5. Reconcilie divergências

Webhooks são importantes para acompanhar mudanças, mas não devem ser o único mecanismo disponível para identificar inconsistências.

Sua integração deve ter uma estratégia para comparar o estado registrado localmente com o estado disponível no Asaas quando houver indício de divergência.

A reconciliação pode ser necessária quando:

um evento não foi processado;
houve indisponibilidade temporária da sua aplicação;
uma atualização falhou internamente;
o estado local permaneceu sem alteração por um período inesperado;
existe dúvida sobre o resultado de uma operação.

O objetivo é permitir que a aplicação volte para um estado consistente sem depender de intervenção manual em cada ocorrência.

Atenção — erros comuns

Evite arquiteturas que:

consideram a resposta inicial como o estado definitivo da operação;
não armazenam os IDs retornados pela API;
dependem exclusivamente da resposta síncrona;
ignoram eventos relacionados às entidades utilizadas;
repetem requisições após falhas sem verificar o resultado anterior;
não possuem mecanismo de reconciliação;
registram informações insuficientes para investigar uma falha.

⚠️
Uma resposta de sucesso confirma o resultado daquela requisição. Ela não garante, por si só, que nenhuma mudança ocorrerá posteriormente na entidade.

Confirme sua arquitetura

Antes de levar a integração para produção, confirme se sua aplicação consegue responder:

Qual é o fluxo completo de cada operação?
Quais IDs precisam ser armazenados?
Quais estados a aplicação precisa conhecer?
Quais mudanças serão acompanhadas por Webhooks?
O que acontece quando um Webhook não é processado?
Como a aplicação reage a um timeout ou resposta inconclusiva?
Como uma tentativa duplicada é identificada ou evitada?
Como divergências entre o sistema local e o Asaas são detectadas?
Quais informações ficam disponíveis para diagnóstico?

Se essas situações não estiverem previstas, a integração dependerá do cenário ideal para manter o estado consistente.

Boas práticas

mantenha o ID do Asaas relacionado ao identificador interno da operação;
trate estados como parte do domínio da integração, e não apenas como valores exibidos na interface;
implemente Webhooks desde o início em fluxos que dependem de atualizações posteriores;
torne o processamento de eventos tolerante a duplicidades e reprocessamentos;
não associe timeout automaticamente a falha da operação;
tenha uma estratégia de reconciliação para corrigir divergências;
registre contexto suficiente para investigar falhas sem depender apenas de logs isolados.

Próximos passos

Agora que o ciclo de uma operação está definido, aprofunde como representar essas mudanças dentro da aplicação: