Checklist de go-live: o que muda de homologação para produção

A passagem de homologação para produção parece uma troca de URL e de credencial, e essa é a leitura que produz o primeiro incidente. Mudam mais coisas do que parece: a biometria deixa de ser simulada, as evidências passam a ter valor probatório, os e-mails chegam a pessoas de verdade, os dados param de expirar em sete dias e a cota deixa de ter um valor padrão — ela passa a ser a que foi contratada. Este é o checklist do que conferir antes de virar a chave, organizado pelo que costuma quebrar primeiro.

O que realmente muda

A última linha é a única que todo mundo lembra, e é a menos perigosa das nove.

1. Biometria: o item que merece mais atenção

Se a sua política usa verificação biométrica, este é o maior salto entre os ambientes — e o único em que a integração pode ter passado meses sem nunca exercitar o caminho que vai encontrar no primeiro dia.

Em homologação, as verificações biométricas são simuladas e aprovam por padrão. Em produção elas acontecem de verdade: pessoas reais, luz de escritório às seis da tarde, óculos, câmera de celular antigo, fotos de referência tiradas há três anos. A reprovação deixa de ser um caso de borda e passa a ser um evento cotidiano.

Antes de virar a chave:

• Exercite a reprovação no sandbox, com valores próximos do limiar e não apenas com falhas grosseiras: é na fronteira da barra que as capturas reais caem.
• Confirme que a sua integração lê errorCode, errorDetail e retryable. Uma verificação reprovada volta 200, e quem trata só o status HTTP vai contabilizar reprovação como sucesso.
• Decida o que acontece quando as tentativas acabam. Alguém vai esgotá-las no primeiro dia.
• Inspecione as fotos de referência antes de cadastrar, se a sua operação usa base própria.

2. Credenciais e papéis

• Credenciais de produção não são autosserviço — elas vêm com o plano.
• Confira quem tem papel MASTER e se essa pessoa está alcançável fora do horário comercial. Só MASTER cria, altera, pausa, rotaciona ou revoga credencial de produção.
• Separe as credenciais por aplicação e função, em vez de uma chave para tudo. Uma credencial de leitura vazada é um incidente; a mesma com escopos de escrita é outro tamanho de problema.
• Nomeie cada credencial no painel, e guarde o segredo no primeiro momento: ele é exibido uma vez e não pode ser recuperado.
• Agende a rotação. A cadência mínima é anual, e o procedimento está em rotação de credenciais sem downtime.

3. Cota: o número que você ainda não conhece

Produção não tem cota padrão. Ela vem do plano contratado, dimensionada pelo volume e pelos métodos que a operação usa — e as cotas são por método, então é possível esgotar biometria com documentos sobrando.

Os números do sandbox não servem de referência para dimensionar nada: eles existem para permitir testar.

• Assine o evento QUOTA.WARNING e trate-o como alarme. É o último aviso antes de as chamadas passarem a ser recusadas.
• Saiba que não há endpoint público de consulta de cota — o acompanhamento é pela aba Uso do painel ou pelo evento.
• Olhe a Previsão de Uso na primeira semana. É o único lugar que avisa que você vai estourar antes de estourar.
• Projete repetição. Segundas tentativas consomem cota; projetar zero repetição subestima o consumo de forma sistemática.

4. Webhooks: recadastrar, e conferir que chegam

Os ambientes são separados em tudo, inclusive nos webhooks. Os endpoints registrados em homologação não existem em produção — e este é um dos esquecimentos mais comuns, porque o sintoma é silencioso: as assinaturas funcionam normalmente e nenhum evento chega.

• Cadastre os endpoints de produção e selecione os eventos.
• Assine, no mínimo, os desfechos (TRANSACTION.COMPLETED, FAILED, EXPIRED, ENVELOPE.ALL_SIGNED), mais DEADLINE_APPROACHING e QUOTA.WARNING.
• Não assine STEP.STARTED, STEP.COMPLETED ou STEP.FAILED: os três foram retirados e nunca chegaram a ser emitidos.
• Confirme que o seu receptor devolve 2xx rápido e reprocessa com segurança — ver webhooks em fila.
• Guarde o segredo de assinatura e lembre que rotacioná-lo não tem janela de sobreposição.

5. Prazos e persistência

Em homologação as entidades vivem 7 dias; em produção elas persistem, porque a verificação pública de uma assinatura depende de o registro continuar existindo.

• Reveja rotinas que toleravam dados sumindo — e as que dependiam da limpeza automática.
• Escolha expiresInMinutes conscientemente, em vez de aceitar o padrão de 72 horas por omissão. A faixa vai de 5 minutos a 7 dias, e o valor certo depende de como o link chega ao signatário.
• Não guarde URLs de download: elas são de vida curta. Guarde identificadores e peça a URL na hora.
• O panorama completo está em todos os prazos da API.

6. Mensagens que agora chegam a pessoas

Convites, códigos e lembretes passam a sair para caixas reais. Confira o remetente, o texto e — o item que sempre aparece — se não sobrou nenhum endereço de teste embutido no código continuando a receber cópias de tudo.

Vale também um teste de ponta a ponta com um destinatário real interno, incluindo a conferência de que a mensagem não caiu em spam. Convite que não chega é indistinguível, do lado do integrador, de signatário que não quis assinar — e o indicador que revela isso é a taxa de conclusão, não uma taxa de erro.

7. Dados reais, pela primeira vez

A regra se inverte: o que era proibido em homologação passa a ser o objeto da operação. Vale conferir que o caminho inverso está fechado:

• Log explícito da URL base resolvida no start-up de cada serviço.
• Homologação nunca como fallback de produção em wrapper de retry.
• Cache de token chaveado por ambiente, para não usar token de um ambiente no outro.
• Segredos prefixados por ambiente no cofre.

Os cinco vazamentos típicos, com as correções, estão em homologação sem dado pessoal real.

8. Observabilidade ligada antes, não depois

Instrumentar depois do primeiro incidente significa investigá-lo sem dados. O conjunto mínimo:

• Taxa de conclusão por janela de tempo — a métrica que capta o que nenhum erro HTTP capta.
• Contagem por errorCode, e taxa de retryable: false.
• RateLimit-Remaining, para alarmar antes do primeiro 429.
• Idade do último evento de webhook recebido.
• Reconciliação periódica entre a API e o seu banco.

O detalhamento está em o que monitorar numa integração.

9. O plano de parada

O último item, e o mais fácil de adiar. Antes do primeiro documento real, decida — e escreva — como a operação é interrompida:

Lembre que qualquer um deles leva até 60 segundos para valer em toda a frota, e que produção exige MASTER. Os detalhes estão em kill switch e degradação controlada.

A lista, em uma tela

1. Credenciais de produção criadas, nomeadas, segredo guardado, escopos mínimos.
2. Papel MASTER identificado e alcançável.
3. Cota conhecida, QUOTA.WARNING assinado e alarmando.
4. Webhooks de produção cadastrados e testados de ponta a ponta.
5. Caminho de reprovação biométrica exercitado, se houver biometria.
6. errorCode, errorDetail e retryable tratados no código.
7. expiresInMinutes escolhido conscientemente.
8. E-mails conferidos, sem destinatários de teste embutidos.
9. URL base logada no start-up; homologação fora de qualquer fallback.
10. Observabilidade ligada.
11. Plano de parada escrito, com quem aciona o quê.
12. Primeiro documento real enviado para alguém de dentro da casa.

O item 12 é o mais barato da lista e o que mais evita constrangimento: o primeiro documento de produção deveria ir para um colega, não para um cliente.

Perguntas Frequentes