Estados, eventos e consistência

As operações podem mudar de estado depois da resposta inicial da API.

Por isso, sua aplicação deve acompanhar o ciclo de vida das entidades e manter os dados locais alinhados com o Asaas por meio de estados, eventos e mecanismos de reconciliação.

Quando utilizar

Considere este modelo ao:

• implementar operações cujo status pode mudar depois da criação;
• utilizar Webhooks para atualizar sua aplicação;
• executar ações que dependem do estado atual de uma entidade;
• tratar eventos duplicados, atrasados ou processados fora da sequência esperada;
• identificar e corrigir divergências entre o estado local e o Asaas.

Antes de começar

Antes de definir esse fluxo:

• identifique quais entidades sua aplicação precisa acompanhar;
• mapeie os estados relevantes de cada entidade;
• defina quais estados permitem avançar, interromper ou repetir uma operação;
• mantenha o ID do Asaas relacionado ao identificador correspondente no seu sistema;
• defina como sua aplicação receberá atualizações e como divergências serão reconciliadas.

Como funciona

A consistência depende de três mecanismos trabalhando em conjunto:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Operação no Asaas"] --> B["Estado atual"]
    B --> C["Evento de atualização"]
    C --> D["Processar evento"]
    D --> E["Atualizar estado local"]
    E --> F{"Estado local está consistente?"}

    F --> FSim(("Sim"))
    F --> FNao(("Não"))

    FSim --> G["Continuar o fluxo"]
    FNao --> H["Reconciliar com o Asaas"]
    H --> E

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

    class FSim respostaSim
    class FNao respostaNao

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

Os eventos mantêm sua aplicação atualizada durante o fluxo normal. A reconciliação funciona como uma camada adicional para corrigir situações em que o estado local deixe de refletir o estado atual no Asaas.

1. Modele os estados da entidade

O estado representa a situação atual de uma entidade em determinado momento.

Cobranças, assinaturas, transferências e outras entidades podem passar por diferentes etapas durante seu ciclo de vida. Por isso, armazenar somente o status retornado no momento da criação não é suficiente.

Para cada entidade utilizada pela integração, identifique:

• quais estados podem ocorrer;
• quais representam o início do fluxo;
• quais são intermediários;
• quais representam uma condição final;
• quais exigem alguma ação da aplicação;
• quais permitem avançar para uma próxima etapa;
• quais ainda podem mudar posteriormente.

O status deve fazer parte da lógica da integração, e não ser tratado apenas como um texto armazenado no banco de dados.

2. Relacione o estado local ao registro no Asaas

Sua aplicação deve conseguir identificar de forma inequívoca qual registro local corresponde à entidade existente no Asaas.

Mantenha, no mínimo:

• o ID retornado pelo Asaas;
• o identificador interno da sua aplicação;
• o estado conhecido atualmente;
• a data da última atualização;
• a origem da atualização;
• informações suficientes para rastrear alterações posteriores.

Esse relacionamento permite processar eventos, realizar consultas e investigar divergências sem depender de buscas imprecisas.

3. Processe eventos como mudanças de estado

Eventos informam alterações relevantes ocorridas durante o ciclo de vida da entidade.

Em fluxos assíncronos, eles permitem que sua aplicação continue acompanhando a operação depois da resposta inicial da API.

Ao processar um evento:

1. identifique a entidade relacionada;
2. recupere o estado atualmente armazenado;
3. avalie a informação recebida;
4. aplique a atualização necessária;
5. registre a mudança;
6. execute ações dependentes desse novo estado somente depois da atualização.

O processamento não deve depender da premissa de que cada evento será recebido uma única vez ou exatamente na sequência esperada.

4. Considere eventos duplicados e atrasados

Sua arquitetura deve tolerar diferentes condições de entrega.

Um evento pode:

• ser recebido mais de uma vez;
• chegar depois de outro evento relacionado;
• ser processado com atraso;
• falhar durante o processamento;
• chegar quando sua aplicação já possui uma informação mais recente.

Por isso, antes de atualizar uma entidade ou executar uma ação, considere o estado atual registrado e o efeito real daquela atualização.

Evite implementar regras baseadas exclusivamente na ordem em que os eventos foram recebidos.

5. Valide transições antes de executar ações

Nem toda mudança de estado deve produzir automaticamente uma nova operação.

Antes de avançar um fluxo, valide se o estado atual permite aquela ação.

Por exemplo, antes de:

• liberar um produto ou serviço;
• executar uma nova tentativa;
• cancelar uma operação;
• iniciar uma transferência;
• atualizar uma situação financeira como concluída;

confirme se o estado conhecido é compatível com essa decisão.

Esse controle reduz o risco de uma atualização atrasada ou duplicada provocar uma ação incorreta.

6. Mantenha o estado local consistente

Uma integração está consistente quando as informações utilizadas pela sua aplicação representam corretamente a situação atual da operação no Asaas.

Quando isso não acontece, podem ocorrer:

• status divergentes;
• decisões com base em informações desatualizadas;
• reprocessamentos desnecessários;
• operações duplicadas;
• intervenções manuais;
• dificuldade para identificar a origem do problema.

Por exemplo, uma cobrança pode ser confirmada no Asaas enquanto sua aplicação continua tratando o registro como pendente caso a atualização correspondente não seja processada.

Nessa situação, o problema não está necessariamente na operação financeira, mas na diferença entre o estado mantido nos dois sistemas.

7. Implemente reconciliação

Mesmo utilizando Webhooks, sua aplicação deve estar preparada para identificar e corrigir divergências.

A reconciliação funciona como uma camada complementar ao processamento normal de eventos.

Uma rotina básica pode:

1. identificar registros pendentes, antigos ou inconsistentes;
2. consultar o estado atual da entidade no Asaas;
3. comparar a resposta com o registro local;
4. corrigir a divergência quando necessário;
5. registrar a alteração realizada;
6. analisar ocorrências recorrentes para identificar problemas estruturais.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart LR
    A["Selecionar operações para validação"] --> B["Consultar estado no Asaas"]
    B --> C["Comparar com estado local"]
    C --> D{"Existe divergência?"}
    D -- "Não" --> E["Manter registro"]
    D -- "Sim" --> F["Atualizar estado local"]
    F --> G["Registrar correção"]
    G --> H["Avaliar causa da divergência"]

    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

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

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

A reconciliação não substitui os Webhooks. Seu objetivo é recuperar inconsistências que não foram corrigidas pelo fluxo normal.

Atenção — erros comuns

Evite arquiteturas que:

• armazenam apenas o status inicial da entidade;
• tratam o status somente como informação visual;
• assumem que eventos sempre chegam na ordem esperada;
• executam ações sem validar o estado atual;
• processam novamente um evento duplicado como se fosse novo;
• dependem exclusivamente de Webhooks para manter a consistência;
• não registram informações suficientes para rastrear mudanças;
• repetem uma operação sem verificar se ela já foi concluída.

Confirme sua arquitetura

Antes do go-live, confirme se sua aplicação consegue responder:

• Quais estados cada entidade pode assumir?
• Quais estados são iniciais, intermediários ou finais?
• Quais estados permitem avançar uma operação?
• Quais exigem tratamento ou intervenção?
• Como o estado local será atualizado?
• Como eventos duplicados serão identificados?
• Como eventos atrasados serão tratados?
• O processamento depende da ordem de recebimento dos eventos?
• Como divergências serão identificadas?
• Quando uma operação poderá ser executada novamente?
• Como uma alteração de estado poderá ser rastreada posteriormente?

Se essas definições não existirem, sua aplicação poderá tomar decisões com base em informações incompletas ou desatualizadas.

Boas práticas

• trate estados como parte da regra de negócio da integração;
• mantenha o ID do Asaas relacionado ao identificador interno;
• registre quando e como cada estado foi atualizado;
• projete o processamento de eventos para tolerar duplicidades;
• não dependa de uma ordem rígida de entrega de eventos;
• valide o estado atual antes de executar ações críticas;
• mantenha histórico suficiente para diagnóstico;
• utilize reconciliação como camada complementar aos Webhooks.

Próximos passos

Agora que sua aplicação consegue controlar mudanças de estado e corrigir divergências, entenda quando depender de uma resposta imediata e quando aguardar atualizações posteriores:

• Comunicação síncrona e assíncrona
• Webhooks e eventos