Comunicação síncrona e assíncrona

Nem toda operação é concluída no mesmo instante em que a API responde.

Em alguns casos, a resposta síncrona já representa o resultado necessário para seguir o fluxo. Em outros, ela confirma apenas o processamento inicial da requisição, enquanto o estado definitivo será conhecido posteriormente por meio de um evento ou de uma nova consulta.

Quando utilizar

Considere essa distinção ao:

• implementar operações cujo estado pode mudar depois da resposta inicial;
• definir quando uma ação de negócio pode ser executada;
• utilizar Webhooks para confirmar alterações posteriores;
• modelar fluxos que dependem de bancos, meios de pagamento ou outros processamentos externos;
• tratar operações que podem permanecer temporariamente em processamento.

Antes de começar

Antes de definir se uma operação será tratada de forma síncrona ou assíncrona:

• identifique o que a resposta da API confirma naquela operação;
• verifique se o estado da entidade pode mudar posteriormente;
• identifique os Webhooks relacionados ao fluxo;
• defina quais ações dependem de uma confirmação definitiva;
• determine como sua aplicação tratará períodos em que o resultado ainda estiver em processamento.

Como funciona

O primeiro passo é entender o que a resposta da requisição representa.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Enviar requisição"] --> B["Receber resposta da API"]
    B --> C{"O resultado pode mudar depois?"}

    C --> CSim(("Sim"))
    C --> CNao(("Não"))

    CNao --> D["Utilizar o resultado da resposta"]
    CSim --> E["Registrar o estado atual"]
    E --> F["Aguardar nova informação"]
    F --> G["Receber Webhook ou consultar a API"]
    G --> H["Atualizar o estado local"]
    H --> I{"Estado permite avançar?"}

    I --> ISim(("Sim"))
    I --> INao(("Não"))

    ISim --> J["Executar próxima ação"]
    INao --> K["Continuar acompanhando a operação"]

    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 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,E,F,G,H processo
    class C,I decisao
    class D,J sucesso
    class K processo

    class CSim,ISim respostaSim
    class CNao,INao respostaNao

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

A decisão não depende apenas do código HTTP retornado. O ponto principal é entender se aquela resposta representa o resultado necessário para continuar o fluxo ou apenas um estado intermediário da operação.

1. Identifique o que a resposta síncrona confirma

A resposta síncrona representa o resultado da requisição executada naquele momento.

Ela pode ser suficiente quando a informação necessária para continuar o fluxo já foi determinada na própria chamada.

Por exemplo, após criar uma entidade com sucesso, sua aplicação pode utilizar os dados retornados para:

• armazenar o ID gerado pelo Asaas;
• relacionar a entidade ao registro interno;
• confirmar que os dados enviados foram aceitos;
• continuar etapas que dependem apenas da criação daquele registro.

Nesse cenário, não é necessário aguardar um evento apenas para confirmar novamente que a entidade foi criada.

2. Identifique operações que dependem de confirmação posterior

Em outros fluxos, a resposta inicial não representa o resultado definitivo da operação.

Isso acontece principalmente quando existe processamento posterior, como:

• confirmação de pagamento;
• alteração de status de uma cobrança;
• processamento por bancos ou meios de pagamento;
• análise ou validação posterior;
• estorno ou outra mudança ocorrida depois da chamada inicial.

Nesses casos, a resposta da API informa o estado conhecido naquele momento. Sua aplicação deve continuar acompanhando a entidade até receber a informação necessária para avançar.

3. Aguarde a confirmação antes de executar ações críticas

Quando uma ação depende do resultado definitivo da operação, ela não deve ser executada apenas com base na resposta inicial.

Isso é especialmente importante antes de:

• liberar um produto ou serviço;
• confirmar uma compra;
• atualizar uma operação como concluída;
• baixar estoque;
• enviar uma notificação de conclusão;
• iniciar outro processo financeiro dependente daquele resultado.

Antes dessas ações, confirme se o estado atual realmente permite avançar.

Uma operação que ainda pode mudar deve permanecer em um estado intermediário na sua aplicação até que a confirmação necessária seja recebida.

4. Considere a consistência eventual

Em fluxos assíncronos, o estado da sua aplicação pode ficar temporariamente diferente do estado existente no Asaas.

Esse comportamento é conhecido como consistência eventual.

Por exemplo:

1. uma operação muda de estado no Asaas;
2. o evento correspondente é gerado;
3. sua aplicação recebe o Webhook;
4. o evento é processado;
5. o registro local é atualizado.

Entre a primeira e a última etapa existe uma janela em que os dois sistemas podem apresentar informações diferentes.

Essa diferença temporária não representa necessariamente uma falha.

O problema ocorre quando a aplicação não está preparada para essa condição ou executa uma ação definitiva enquanto o estado ainda pode mudar.

5. Represente estados intermediários na aplicação

Quando a confirmação não é imediata, evite reduzir o fluxo apenas a estados como sucesso e falha.

Sua aplicação pode precisar representar situações como:

• aguardando processamento;
• pendente de confirmação;
• em análise;
• aguardando atualização;
• concluído;
• falhou.

Os estados utilizados internamente devem refletir o comportamento real do fluxo e permitir que o sistema diferencie uma operação concluída de uma operação cujo resultado ainda não é conhecido.

Isso também melhora a experiência do usuário final, que pode receber uma informação adequada enquanto o processamento continua.

6. Defina como a confirmação será recebida

Para cada operação assíncrona, defina qual mecanismo atualizará sua aplicação.

Normalmente, a atualização ocorre por meio de Webhooks.

Consultas à API podem complementar esse fluxo quando for necessário:

• validar o estado atual;
• recuperar uma atualização que não foi processada;
• confirmar uma operação que permaneceu em estado intermediário por mais tempo que o esperado;
• executar uma rotina de reconciliação.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Operação aguardando confirmação"] --> B{"Webhook recebido?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Processar evento"]
    C --> D["Atualizar estado local"]

    BNao --> E{"Tempo esperado foi excedido?"}

    E --> ESim(("Sim"))
    E --> ENao(("Não"))

    ENao --> F["Continuar aguardando"]
    ESim --> G["Consultar estado no Asaas"]
    G --> H["Reconciliar estado local"]

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

    class BSim,ESim respostaSim
    class BNao,ENao respostaNao

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

A consulta não precisa substituir o fluxo de eventos. Ela pode atuar como mecanismo de recuperação quando a confirmação esperada não chegar ou não for processada corretamente.

7. Defina limites para a espera

Operações assíncronas não devem ficar indefinidamente aguardando uma atualização sem qualquer acompanhamento.

Para cada fluxo, determine:

• quanto tempo é esperado para uma mudança de estado;
• quando a operação deve ser considerada fora do comportamento esperado;
• quando uma consulta deve ser realizada;
• quando uma rotina de reconciliação deve atuar;
• quando a situação deve gerar alerta ou investigação.

Esses limites devem considerar o comportamento de cada operação e não precisam ser iguais para todos os fluxos.

Como decidir entre síncrono e assíncrono

Antes de implementar uma operação, responda:

Se uma operação pode mudar depois da resposta inicial, o fluxo deve ser preparado para acompanhar essa evolução em vez de presumir que ela já foi concluída.

Atenção — erros comuns

Evite arquiteturas que:

• tratam toda resposta da API como confirmação definitiva;
• confundem requisição aceita com operação concluída;
• executam ações críticas antes da confirmação necessária;
• atualizam o estado local para concluído antes do resultado definitivo;
• não representam estados intermediários;
• ignoram a janela de consistência eventual;
• dependem de um evento sem definir o que fazer caso ele atrase ou não seja processado.

Confirme sua arquitetura

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

• Quais operações podem ser concluídas com base na resposta síncrona?
• Quais dependem de uma atualização posterior?
• Quais Webhooks representam essas atualizações?
• Quais ações precisam aguardar uma confirmação assíncrona?
• Como uma operação em processamento será representada localmente?
• O que acontece se a confirmação demorar mais que o esperado?
• Quando sua aplicação deve consultar o estado novamente?
• Como o usuário final será informado enquanto a operação ainda estiver em processamento?
• Como uma divergência será identificada e reconciliada?

Se essas respostas não estiverem definidas, a aplicação pode tomar decisões definitivas enquanto a operação ainda estiver em andamento.

Boas práticas

• diferencie o resultado da requisição do resultado completo da operação;
• utilize estados intermediários para representar processamentos ainda não concluídos;
• aguarde a confirmação necessária antes de executar ações críticas;
• utilize Webhooks para acompanhar mudanças posteriores;
• defina mecanismos de consulta e reconciliação para situações excepcionais;
• não dependa de tempos fixos de espera para presumir que uma operação foi concluída;
• informe ao usuário quando uma operação ainda estiver em processamento.

Próximos passos

Depois de definir quais operações dependem de comunicação assíncrona, estruture como esses eventos serão recebidos e processados:

• Webhooks e eventos
• Retries e idempotência