Guia de Arquitetura de Integrações
Como modelar integrações resilientes com a API Asaas — controle de estados, eventos, retries e preparo para produção, indo além do request/response.
Integrações com a API Asaas não terminam na resposta de uma requisição. Uma operação pode mudar de estado posteriormente, gerar novos eventos ou exigir recuperação em caso de falha.
Este guia apresenta os principais conceitos para desenvolver integrações resilientes e preparadas para produção, abordando controle de estados, processamento de eventos, comunicação síncrona e assíncrona, retries, idempotência, reconciliação e observabilidade.
Ao concluir este guia, você entenderá como estruturar uma integração considerando todo o ciclo de uma operação, e não apenas o request/response da API.
Quando utilizar
Utilize este guia quando precisar:
- modelar uma nova integração com o Asaas;
- revisar integrações com divergências de status, duplicidades ou falhas silenciosas;
- definir como sua aplicação tratará eventos e mudanças de estado;
- implementar mecanismos de retry e recuperação de falhas;
- preparar uma integração para operar em produção.
Antes de começar
Antes de aplicar os conceitos deste guia:
- tenha a autenticação e as primeiras chamadas à API validadas;
- identifique quais operações dependem de confirmação posterior;
- defina se sua integração utilizará Webhooks, consultas de reconciliação ou os dois mecanismos.
Como funciona
Uma integração deve ser tratada como um fluxo contínuo, e não como uma chamada isolada.
%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart LR
A["Executar operação"] --> B["Registrar estado"]
B --> C["Receber evento"]
C --> D["Atualizar aplicação"]
D --> E{"Falhou?"}
E --> ENao(("Não"))
E --> ESim(("Sim"))
ENao --> F["Fluxo concluído"]
ESim --> G["Recuperar ou reprocessar"]
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
A resposta síncrona da API representa o resultado daquela requisição naquele momento. Dependendo da operação, o estado pode mudar posteriormente por processamento financeiro, análise, confirmação, estorno ou outros eventos.
Por isso, sua aplicação deve estar preparada para registrar o estado atual, processar novas informações e reconciliar eventuais divergências.
Etapas do guia
| Etapa | O que você aprenderá |
|---|---|
| Além do request/response | Por que considerar apenas a resposta da API pode gerar divergências e falhas silenciosas |
| Estados, eventos e consistência | Como representar status, transições e reconciliar o estado da sua aplicação com o Asaas |
| Comunicação síncrona e assíncrona | Quando utilizar a resposta imediata da API e quando aguardar uma confirmação posterior |
| Webhooks e eventos | Como receber, persistir e processar eventos de forma confiável |
| Retries e idempotência | Como repetir operações em caso de falha sem gerar processamento duplicado |
| Preparação para produção | O que validar em credenciais, testes, observabilidade e contingência antes do go-live |
Uma integração validada no Sandbox não está automaticamente pronta para produção. Credenciais, configurações, comportamento dos dados e volume de operações devem ser validados novamente no ambiente produtivo.
Implemente retries sempre com mecanismos de controle e idempotência. Repetir uma requisição sem considerar o resultado anterior pode gerar operações duplicadas.
Próximos passos
Comece entendendo por que uma integração não deve depender apenas da resposta imediata de uma requisição:
- Além do request/response
- Estados, eventos e consistência
Updated 18 minutes ago