Preparação para produção

Uma integração validada no Sandbox não está automaticamente pronta para operar em produção.

Credenciais, URLs, Webhooks, permissões, volume, monitoramento e comportamento operacional precisam ser revisados no ambiente produtivo antes do go-live.

Quando utilizar

Utilize este checklist ao:

• preparar uma nova integração para o primeiro go-live;
• migrar um fluxo validado no Sandbox para produção;
• habilitar uma nova funcionalidade em uma integração existente;
• revisar uma integração antes de aumentar seu volume de operações;
• estruturar uma validação técnica antes de liberar o fluxo para usuários reais.

Antes de começar

Antes da validação de produção:

• conclua os testes funcionais no Sandbox;
• defina quais fluxos serão liberados no go-live;
• tenha acesso às credenciais e configurações do ambiente de produção;
• identifique os responsáveis pelo acompanhamento da integração;
• defina como a operação será pausada ou recuperada caso ocorra uma falha após a liberação.

Como funciona

A preparação para produção deve validar novamente cada componente no ambiente em que a integração realmente irá operar.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Integração validada no Sandbox"] --> B["Revisar ambiente de produção"]
    B --> C["Validar credenciais e configurações"]
    C --> D["Testar Webhooks e fluxo completo"]
    D --> E["Validar falhas e recuperação"]
    E --> F["Ativar logs e monitoramento"]
    F --> G{"Critérios de go-live atendidos?"}

    G --> GSim(("Sim"))
    G --> GNao(("Não"))

    GSim --> H["Liberar integração"]
    GNao --> I["Corrigir pendências"]
    I --> B

    H --> J["Acompanhar operação inicial"]

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

    class GSim respostaSim
    class GNao respostaNao

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

O objetivo não é repetir todos os testes realizados no Sandbox, mas confirmar que as dependências e configurações necessárias também existem e funcionam corretamente em produção.

1. Revise credenciais e permissões

Antes de realizar qualquer chamada em produção, confirme se a aplicação está utilizando as credenciais correspondentes ao ambiente correto.

Verifique:

• se a API Key utilizada foi gerada em produção;
• se nenhuma credencial de Sandbox permanece configurada;
• se a credencial está armazenada fora do código-fonte;
• se somente os serviços necessários possuem acesso à chave;
• se as permissões disponíveis correspondem às operações executadas pela integração;
• se existe um procedimento definido para substituição ou rotação da credencial.

Evite depender de alterações manuais não documentadas no momento da publicação.

Configurações sensíveis devem estar separadas por ambiente e fazer parte do processo de implantação da aplicação.

2. Confirme URLs e configurações do ambiente

Além das credenciais, revise todas as configurações que mudam entre Sandbox e produção.

Isso inclui, quando aplicável:

• URL base utilizada nas requisições;
• URLs de Webhook;
• permissões;
• identificadores configurados por ambiente;
• variáveis de ambiente;
• parâmetros específicos da integração;
• configurações de serviços externos relacionados ao fluxo.

Não presuma que uma configuração criada no Sandbox também estará disponível em produção.

Cada ambiente deve ser validado separadamente.

3. Valide os Webhooks em produção

O recebimento de Webhooks deve ser testado novamente no ambiente produtivo.

Confirme se:

• a URL correta está cadastrada;
• o endpoint está acessível externamente;
• as validações de segurança estão funcionando;
• o evento é persistido antes do processamento;
• a resposta ocorre dentro do tempo esperado;
• o processamento assíncrono está ativo;
• eventos duplicados podem ser tratados sem repetir efeitos;
• falhas ficam disponíveis para reprocessamento.

Não considere o fluxo validado apenas porque o endpoint funcionou no Sandbox.

Infraestrutura, regras de rede, domínio, proxy, firewall, certificados e serviços intermediários podem ser diferentes em produção.

4. Teste o fluxo de ponta a ponta

Execute pelo menos um fluxo completo utilizando o ambiente produtivo antes de liberar a integração para todo o volume esperado.

O teste deve incluir as etapas relevantes da operação, como:

1. enviar a requisição inicial;
2. armazenar os identificadores retornados;
3. acompanhar o estado da entidade;
4. receber o evento correspondente;
5. processar a atualização;
6. atualizar o registro local;
7. confirmar o resultado final da operação.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Executar operação real controlada"] --> B["Registrar ID e estado inicial"]
    B --> C["Aguardar atualização"]
    C --> D["Receber e processar evento"]
    D --> E["Atualizar sistema local"]
    E --> F{"Resultado está consistente?"}

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

    FSim --> G["Registrar fluxo validado"]
    FNao --> H["Investigar divergência"]
    H --> I["Corrigir configuração ou implementação"]
    I --> A

    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,I recuperacao

    class FSim respostaSim
    class FNao respostaNao

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

Utilize operações controladas e compatíveis com o fluxo que será disponibilizado aos usuários.

O objetivo é verificar a integração como um sistema completo, e não apenas confirmar que um endpoint responde.

5. Teste também cenários de falha

O caminho de sucesso não é suficiente para validar uma integração produtiva.

Inclua cenários em que sua aplicação precise lidar com situações como:

• erro de validação;
• indisponibilidade temporária;
• timeout;
• resposta inconclusiva;
• Webhook duplicado;
• falha no processamento de um evento;
• atraso em uma atualização;
• necessidade de retry;
• divergência entre o estado local e o Asaas.

O objetivo é confirmar que os mecanismos definidos nos capítulos anteriores funcionam também fora do cenário ideal.

6. Ative logs e rastreabilidade antes do go-live

Não espere o primeiro incidente para descobrir quais informações precisam ser registradas.

Antes de liberar a integração, confirme se é possível relacionar uma operação entre os diferentes componentes do sistema.

Registre, quando aplicável:

• identificador interno;
• ID retornado pelo Asaas;
• externalReference;
• data e horário das chamadas;
• resultado das requisições;
• estado conhecido da entidade;
• eventos recebidos;
• resultado do processamento;
• retries executados;
• falhas e reconciliações realizadas.

Evite registrar credenciais, dados sensíveis ou informações desnecessárias para o diagnóstico.

O objetivo é conseguir responder, a partir dos registros disponíveis, o que aconteceu com uma determinada operação.

7. Configure monitoramento e alertas

Logs permitem investigar um problema. Monitoramento permite descobrir que ele está acontecendo.

Defina indicadores para os pontos mais importantes da integração, como:

• aumento de erros nas chamadas à API;
• crescimento de respostas 5xx;
• ocorrências de timeout;
• eventos com erro de processamento;
• eventos acumulados em fila;
• aumento no tempo de processamento;
• operações que permanecem em estados intermediários além do esperado;
• falhas recorrentes em retries;
• divergências encontradas pela reconciliação.

Também defina quando um comportamento deve gerar alerta e quem será responsável por avaliá-lo.

Não dependa exclusivamente da reclamação de um usuário para descobrir uma falha.

8. Revise capacidade e comportamento sob volume

Uma integração que funciona com poucas requisições pode se comportar de maneira diferente quando o volume aumenta.

Antes de ampliar o tráfego, avalie:

• volume esperado de operações;
• concorrência das requisições;
• velocidade de consumo dos Webhooks;
• capacidade das filas e workers;
• tempo médio de processamento;
• estratégia de retry;
• limites aplicáveis aos endpoints utilizados.

O objetivo é evitar que um aumento de volume transforme pequenas falhas em filas crescentes, retries simultâneos ou sobrecarga da própria aplicação.

9. Defina um plano de contingência

Antes do go-live, determine o que será feito se uma falha relevante ocorrer.

O plano deve definir, pelo menos:

• quando interromper temporariamente novas operações;
• como evitar novos efeitos enquanto o problema é investigado;
• como identificar operações afetadas;
• como reprocessar ou reconciliar operações pendentes;
• quem deve ser acionado;
• quais informações devem ser reunidas para investigação;
• quais critérios permitem retomar o fluxo.

O momento de definir esse processo é antes do incidente.

Checklist de go-live

Antes de liberar a integração, valide:

Atenção — erros comuns

Evite entrar em produção:

• assumindo que o comportamento observado no Sandbox será idêntico sem nova validação;
• utilizando uma API Key do ambiente incorreto;
• mantendo URLs de Sandbox em configurações produtivas;
• sem revisar as permissões utilizadas;
• sem cadastrar ou testar os Webhooks de produção;
• validando somente o caminho de sucesso;
• sem mecanismos de retry e prevenção de duplicidade;
• sem logs suficientes para rastrear uma operação;
• sem monitoramento de falhas;
• sem definir quem acompanha os primeiros dias da integração;
• sem um plano de contingência.

Confirme sua arquitetura

Antes do go-live, confirme se sua equipe consegue responder:

• As credenciais utilizadas pertencem ao ambiente de produção?
• As URLs e demais configurações foram revisadas?
• As permissões disponíveis são suficientes e adequadas ao fluxo?
• Os Webhooks de produção foram testados de ponta a ponta?
• A aplicação consegue lidar com eventos duplicados e falhas de processamento?
• Timeouts e respostas inconclusivas são tratados sem gerar retries indevidos?
• Existe proteção contra execuções concorrentes?
• O fluxo foi validado também em cenários de falha?
• Divergências podem ser reconciliadas?
• É possível rastrear uma operação utilizando os logs disponíveis?
• Existem alertas para os principais tipos de falha?
• A equipe sabe o que fazer se uma falha relevante ocorrer após o go-live?

Se alguma dessas respostas ainda depender de uma investigação ou decisão durante um incidente, existe uma pendência de preparação para produção.

Boas práticas

• mantenha configurações explicitamente separadas por ambiente;
• valide credenciais, URLs e Webhooks novamente em produção;
• realize um teste controlado de ponta a ponta antes de aumentar o volume;
• inclua cenários de falha na validação;
• ative logs e monitoramento antes da primeira operação real;
• acompanhe de forma mais próxima o início da operação;
• aumente volume gradualmente quando o fluxo permitir;
• mantenha responsáveis e procedimentos de contingência definidos;
• revise periodicamente a arquitetura conforme a integração evoluir.