Kill switch e degradação controlada na API de assinatura
Toda integração eventualmente precisa parar alguma coisa: um método de verificação que passou a falhar, um fornecedor externo instável, um incidente de segurança que exige cortar tudo enquanto se investiga. O jeito improvisado de fazer isso — comentar o código, derrubar o serviço, deixar as chamadas estourarem em timeout — produz sintomas diferentes em cada ponto do fluxo e transforma uma decisão deliberada numa investigação. A API da SignDocs Brasil oferece chaves de desligamento por tenant e por método, com um comportamento único e previsível: 503, com mensagem de indisponibilidade temporária. Este guia mostra quais existem, quanto demoram a valer e — a parte que costuma faltar — como a sua integração deveria reagir a elas.
A ideia: desligar deliberadamente é melhor do que deixar quebrar. Uma chave acionada produz 503 com mensagem de indisponibilidade temporária — sempre igual, em toda a operação — em vez de timeouts, erros variados e sintomas diferentes conforme o ponto do fluxo.
Por que existe um botão de desligar
Considere o cenário real: a comparação facial começa a reprovar em massa às nove da manhã. Alguma coisa mudou — um fornecedor degradado, uma base de referência corrompida, um limiar mexido por engano. A operação precisa parar de tentar biometria agora, e voltar a tentar quando alguém entender o que houve.
Sem um mecanismo próprio, as saídas disponíveis são todas ruins. Derrubar o serviço para tudo, inclusive o que funciona. Comentar o código exige um deploy no pior momento possível. Deixar como está queima cota e frustra signatários em cada tentativa.
Uma chave de desligamento resolve isso com três propriedades que importam: é imediata (não precisa de deploy), é reversível, e produz um comportamento único e reconhecível em vez de uma coleção de sintomas.
As chaves disponíveis
| Chave | Alcance | Quando faz sentido |
|---|---|---|
| Tenant | Tudo — todas as chamadas /v1 e a emissão de tokens, em sandbox e produção |
Incidente de segurança que justifique parar a operação inteira |
| Biometria | Etapas biométricas | Provedor degradado, reprovação em massa, suspeita sobre a base de referência |
| Captura hospedada de vivacidade | Só a captura em página hospedada | Problema específico da página, mantendo a captura no aplicativo do integrador |
| OTP | Envio e verificação de código | Falha de entrega generalizada |
| SMS | Só o canal SMS | Operadora com problema, mantendo o OTP por e-mail de pé |
| Checagem de identidade governamental | Consulta à base oficial | Base instável ou custo fora de controle |
| Aviso de finalidade | A etapa de aviso | Correção de texto ou de versão do aviso |
Repare na granularidade das linhas 3 e 5: desligar a captura hospedada não desliga a biometria, e desligar SMS não desliga o OTP. É o que permite reagir a um problema específico sem derrubar a capacidade inteira — e é a diferença entre um incidente contido e uma parada geral.
O que a API responde
A escolha do código não é arbitrária. 503 significa "indisponível agora, tente depois" — semanticamente correto para algo desligado de propósito e temporariamente, e diferente de tudo o mais que a sua integração pode receber:
- Não é 500. Não houve erro; houve uma decisão.
- Não é 403. A credencial está correta e os escopos também.
- Não é timeout. A resposta é imediata, o que evita segurar conexões e estourar filas do seu lado.
- Não é reprovação de etapa. Uma verificação reprovada volta 200 com o motivo no corpo; um método desligado nem chega a ser executado.
A última distinção é a mais importante para quem instrumenta. São dois eventos diferentes com tratamentos diferentes: "esta pessoa não passou na verificação" e "esta verificação não está disponível". Confundi-los produz relatórios que dizem que a taxa de reprovação explodiu quando, na verdade, alguém desligou o método.
A propagação de 60 segundos
A configuração é cacheada por instância de execução, então uma chave acionada leva até 60 segundos para valer em toda a frota.
Isso importa em dois momentos, e nos dois a expectativa errada causa mais dano que o atraso:
Ao acionar. Ver uma chamada passar dez segundos depois de desligar não significa que o controle falhou. Espere o minuto antes de concluir qualquer coisa — e, num incidente, comunique a janela em vez de acionar a chave duas vezes.
Ao religar. A volta também leva até um minuto. Uma verificação feita imediatamente após reativar pode ainda receber 503, o que costuma ser lido como "não funcionou" e provoca um segundo religamento desnecessário.
Chave de desligamento não é disjuntor
Existem dois mecanismos parecidos operando em camadas diferentes, e vale distingui-los porque a conduta correta difere:
| Chave de desligamento | Disjuntor (circuit breaker) | |
|---|---|---|
| Quem aciona | Uma pessoa, deliberadamente | O próprio sistema, ao detectar falhas seguidas |
| Quando volta | Quando alguém religa | Sozinho, quando o serviço externo se recupera |
| Alcance | Um método, ou o tenant | Um serviço externo específico |
| Como aparece | 503 | Falha de etapa, com código próprio |
O disjuntor existe para que uma dependência externa fora do ar não vire uma fila de chamadas travadas somando trinta segundos de timeout por signatário. Ele age sozinho e some sozinho. Um exemplo concreto aparece no fluxo de checagem de identidade governamental: com o disjuntor aberto, a etapa passa a devolver um código de erro específico em vez de acumular timeouts.
Como a sua integração deveria reagir
Esta é a parte que quase nunca é escrita antes de ser necessária. Um 503 planejado só é útil se o outro lado souber o que fazer com ele.
1. Reconheça o 503 como categoria própria
2. Tenha um caminho alternativo escolhido de antemão
Se a biometria está desligada, o documento espera ou segue com outro perfil de verificação? A resposta depende do documento, e é uma decisão de negócio — que precisa estar tomada antes, porque no meio do incidente ninguém decide bem.
Uma forma prática é classificar por tolerância: documentos que podem esperar entram em fila para reprocessamento; documentos que não podem — porque há alguém aguardando no balcão — seguem com um perfil alternativo previsto, e o registro guarda qual foi usado. O importante é que a escolha seja explícita e fique registrada, não que ela seja sempre a mesma.
3. Não faça retry cego
Um método desligado continua desligado por minutos ou horas. Tentar de novo a cada segundo não adianta e consome o seu próprio limite de requisições. Use intervalos crescentes e um teto, ou espere um sinal humano.
4. Diga a verdade ao usuário final
"Não foi possível confirmar sua identidade" é a mensagem errada — sugere que a pessoa fez algo errado, e ela vai tentar de novo, e vai falhar de novo. "Esta verificação está temporariamente indisponível; avisaremos quando puder concluir" descreve o que houve e evita a repetição inútil.
5. Alarme, sem tratar como incidente seu
Um 503 sustentado merece alarme — mas de uma categoria distinta da falha da sua aplicação, porque a ação é diferente: não há o que corrigir no seu código. O conjunto de sinais a observar está em o que monitorar numa integração.
Quem aciona, e de onde
As chaves ficam na aba de segurança do painel de API. Como todo controle de produção, mexer nelas exige papel MASTER no tenant — um papel DEVELOPER opera com autonomia no sandbox.
Vale conferir isso fora do incidente: descobrir às duas da manhã que a única pessoa com MASTER está inalcançável é uma forma cara de aprender a lição. O mesmo vale para pausar credenciais, tratado em rotação de credenciais.
Escolhendo o controle certo
| Situação | Controle |
|---|---|
| Um método de verificação está falhando | Chave daquele método |
| Uma integração específica está com defeito | Pausar a credencial dela |
| Suspeita de credencial vazada | Pausar → rotacionar → reativar |
| Integração desativada em definitivo | Revogar a credencial |
| Incidente que exige parar tudo | Kill switch do tenant |
| Fornecedor externo instável | Nada — o disjuntor já age sozinho |
A última linha economiza acionamentos desnecessários: nem toda instabilidade externa pede intervenção, porque parte dela já é tratada automaticamente.
Ensaie antes
O valor de um mecanismo de emergência é medido no dia em que ele é usado, e é tarde demais para descobrir que a aplicação transforma 503 em tela branca. Em homologação, com credencial de sandbox, exercite o ciclo completo — e observe não o 503, mas o que o seu sistema faz com ele:
- Que mensagem o usuário final vê?
- Há tentativa automática? Com que intervalo?
- O caso vai para uma fila, para atendimento humano, ou desaparece?
- O alarme dispara — e para quem?
- Quando a chave é religada, o fluxo retoma sozinho ou alguém precisa reprocessar?
Cada uma dessas perguntas tem uma resposta hoje, escolhida por acaso. Vale conhecê-las antes que um incidente as revele.
Perguntas Frequentes
Quais chaves de desligamento existem?
Uma geral, do tenant, que suspende toda a operação; e chaves por método: biometria, captura hospedada de vivacidade, OTP, SMS, checagem de identidade governamental e aviso de finalidade. A geral atinge sandbox e produção juntos.
O que a API responde quando uma chave está acionada?
503, com mensagem de indisponibilidade temporária específica do que foi desligado. Não é 500, não é timeout, não é 403: é uma resposta desenhada para ser reconhecida como "isto está desligado no momento", o que permite à sua integração distinguir desligamento planejado de falha.
Quanto tempo demora para valer?
Até 60 segundos em todas as instâncias — a configuração é cacheada por instância de execução. Num incidente, conte com esse minuto e não conclua que o controle falhou ao ver uma chamada passar logo depois de acioná-lo.
Qual a diferença entre o kill switch e pausar uma credencial?
O alcance. Pausar atinge uma credencial — dá para parar produção mantendo o sandbox de pé. O kill switch do tenant atinge tudo, incluindo a emissão de tokens. Para desligar só um método de verificação, sem parar o resto, use a chave daquele método.
Desligar biometria derruba as assinaturas em andamento?
As sessões continuam existindo, mas a etapa biométrica passa a responder 503 enquanto a chave estiver acionada. Por isso a decisão de desligar um método deve considerar quem está no meio do fluxo — e por que vale ter um perfil alternativo previsto para os documentos que não podem esperar.
Isso é a mesma coisa que o disjuntor (circuit breaker)?
Não. O disjuntor é automático e reage à saúde de um serviço externo — ele abre sozinho quando um fornecedor para de responder e fecha sozinho quando volta. A chave de desligamento é manual e deliberada: alguém decidiu parar. Os dois convivem, e ambos aparecem para a sua integração como falha de etapa, não como erro da requisição.
Como testo o comportamento antes de precisar dele?
Em homologação, com uma credencial de sandbox. O importante não é ver o 503 — é confirmar o que a sua aplicação faz com ele: qual mensagem o usuário final vê, se há tentativa automática, se o caso vai para atendimento humano, e se o alarme dispara.
Decida como a integração se comporta quando algo é desligado
Chaves por método, resposta previsível e reversível. Exercite o comportamento em homologação antes de precisar dele em produção.
Criar credenciais de homologação Fale com o time comercial