Recebendo erro de ação crítica. O que fazer?

Você vai identificar o erro de autorização crítica em transferências e escolher o fluxo de confirmação mais adequado para a sua integração.

Ao realizar algumas chamadas, como transferências, você pode receber o erro de “Autorização crítica habilitada”:

{
  "errors": [
    {
      "code": "invalid_action",
      "description": "Sua conta possui autorização crítica habilitada. Para efetuar esta ação informe o código de confirmação."
    }
  ]
}

O que esse erro significa

Toda transferência feita no Asaas, exceto em contas BaaS, precisa ser aprovada via token SMS ou token APP. Quando a conta possui autorização crítica habilitada, a API bloqueia a ação até que o código de confirmação seja informado ou até que a conta utilize uma alternativa de segurança configurada para automatizar esse processo.

Use os campos do erro para decidir o próximo passo:

Escolha o fluxo de confirmação

Você pode tratar a autorização crítica de três formas:

1. Token SMS ou token APP: use quando a transferência puder ser confirmada manualmente por uma pessoa com acesso ao token.
2. Fixação de IPs: use quando a sua integração fizer chamadas a partir de IPs conhecidos e controlados. Com essa configuração, apenas os IPs cadastrados utilizam a API. Caso qualquer outro IP faça a tentativa, a API retorna um erro informando que ele não é considerado seguro.
3. Webhook de autenticação: use quando você precisar de um fluxo mais automático para validar saques ou transferências. Configure o webhook de autenticação conforme descrito na documentação.

Fluxo recomendado de tratamento

1. Execute a chamada de transferência e verifique se a resposta contém code igual a invalid_action.
2. Leia a description do erro para confirmar se a ação exige código de confirmação.
3. Defina o mecanismo de segurança de acordo com o seu cenário:
   • mantenha token SMS ou token APP para operações manuais;
   • fixe IPs quando as chamadas partirem sempre de IPs confiáveis;
   • configure o webhook de autenticação quando precisar automatizar a validação.
4. Configure o mecanismo escolhido seguindo a documentação relacionada.
5. Repita a operação bloqueada somente depois que a confirmação por token, a fixação de IPs ou o webhook de autenticação estiverem configurados corretamente.

Comportamentos críticos e boas práticas

• Ao fixar IPs, garanta que todos os ambientes que chamam a API usem IPs cadastrados. Chamadas feitas por IPs não cadastrados serão bloqueadas.
• Não ignore o erro invalid_action. A transferência não deve ser considerada concluída enquanto a ação crítica estiver pendente.
• Registre o code e a description em logs internos para facilitar diagnóstico, mas não exponha códigos de confirmação em logs, telas ou mensagens de erro.
• Valide o fluxo em ambiente controlado antes de automatizar transferências em produção.
• Revise o mecanismo escolhido sempre que houver mudança de infraestrutura, como troca de servidor, proxy, gateway ou IP de saída.