Todos os prazos da API de assinatura em uma página

Numa única assinatura há vários relógios correndo em paralelo, e eles não têm nada a ver uns com os outros: o seu token de acesso, a janela em que o signatário pode assinar, o código enviado por e-mail, a captura de vivacidade, a URL de download. Quase toda dúvida de prazo que chega ao suporte nasce de confundir dois deles — normalmente "meu token expirou, o link do cliente também expirou?", cuja resposta é não, são coisas independentes. Esta é a referência única: o que cada prazo governa, quanto dura, o que é configurável e qual acaba primeiro.

A tabela

O único prazo que você escolhe

De toda a tabela, um campo é seu: expiresInMinutes, aceito na criação da sessão de assinatura e do envelope.

A faixa aceita vai de 5 minutos a 10.080 minutos (7 dias). Fora dela, a criação é recusada com 400 — antes de o signatário existir no fluxo, e não no meio dele.

Como calibrar, sem chutar:

Há um custo em ambos os extremos. Prazo curto demais gera fila de suporte pedindo link novo. Prazo longo demais mantém uma credencial de assinatura circulando por e-mail — e é bom lembrar que o link é a própria autenticação nos perfis mais simples. O padrão de 72 horas é um meio-termo deliberado, não um valor arbitrário.

Os prazos aninhados da biometria

Numa etapa de prova de vida, três relógios correm encaixados:

O menor governa. Na prática, a captura precisa terminar dentro dos 10 minutos que se seguem ao início da etapa — mesmo que a sessão de assinatura ainda tenha seis dias pela frente.

Daí um padrão de uso que falha e parece inexplicável: gerar o link da captura e mandá-lo por e-mail para a pessoa abrir quando puder. Quando ela abre, o token de 10 minutos já morreu. O correto é entregar o link da sessão de assinatura, que tem prazo longo, e deixar que a etapa de vivacidade só comece quando a pessoa efetivamente chegar à tela da câmera.

Um alívio: recarregar a página não queima uma sessão de vivacidade nova. Reiniciar a etapa devolve a mesma sessão, desde que não tenha sido consumida nem vencido — e o reaproveitamento não estende o prazo original, senão bastaria recarregar a cada nove minutos para mantê-la viva para sempre.

Prazos que não estendem

Três casos em que a intuição sugere renovação e não há:

• Reemitir o link não estende a sessão. POST /v1/signing-sessions/{id}/link devolve uma URL nova com o expiresAt original. Serve para recuperar um link perdido ou já consumido — não para ganhar tempo.
• Reenviar o código não estende a sessão. Cria um novo prazo de 10 minutos para o código; a janela de assinatura segue igual.
• Reiniciar a etapa de vivacidade não estende a captura, como acima.

Quando a janela de assinatura realmente vence, não há renovação: cria-se outra sessão — e aí sim há consumo de cota. O runbook do caso está em sessão expirada: reenviar, cancelar ou recriar.

Prazos de URL de download

As URLs devolvidas para baixar arquivos são pré-assinadas e de vida curta — cerca de uma hora no caso da evidência e do carimbo combinado. Duas consequências práticas:

• Não guarde a URL no seu banco. Guarde o identificador (transactionId, envelopeId) e peça uma URL nova quando precisar. Pedir de novo é barato e sempre funciona.
• Não repasse a URL ao cliente final por um canal lento. Se ela chegar por um e-mail lido no dia seguinte, terá expirado. Sirva o arquivo pelo seu próprio backend, ou gere a URL no momento do clique.

Isso vale inclusive para a URL que chega no evento ENVELOPE.ALL_SIGNED: se ela já expirou quando alguém foi usar, o carimbo combinado pode ser pedido de novo, quantas vezes for preciso.

Retenção: prazos de outra natureza

Dois prazos da tabela não governam fluxo, e sim quanto tempo um dado existe:

Imagem biométrica de referência: 90 dias. Depois disso a imagem é apagada e a comparação passa a falhar até haver novo cadastro. O registro do cadastro sobrevive à imagem por mais 30 dias de propósito, para que uma varredura consiga distinguir "venceu" de "nunca cadastrou".

Homologação: 7 dias. Entidades criadas no ambiente de testes desaparecem depois disso. É a causa de uma falha intermitente clássica em suíte automatizada: o teste guarda um transactionId de uma execução anterior e, uma semana depois, ele não existe mais. Crie objetos novos a cada execução — ver como testar sua integração do sandbox ao CI.

Checklist de prazos para a sua integração

1. Renove o token por expiração, não por agenda. Guarde o expires_in devolvido e renove antes do fim; não presuma que um token guardado ontem serve hoje.
2. Escolha expiresInMinutes conscientemente. Aceitar o padrão de 72 horas é uma decisão legítima — desde que seja uma decisão.
3. Não guarde URLs de download. Guarde identificadores e peça a URL na hora.
4. Não mande o link da captura biométrica por e-mail. Mande o link da sessão.
5. Trate TRANSACTION.DEADLINE_APPROACHING. É o aviso de que a janela está acabando, e o gancho natural para lembrar o signatário antes que o link morra — ver webhooks e eventos.
6. Em homologação, não reaproveite ids. Sete dias.

Perguntas Frequentes