Dois tokens, dois públicos: Bearer do integrador e token de embed do signatário

Quase toda API tem uma credencial só: o seu token, em toda chamada. A API de assinatura tem duas, e a diferença não é organizacional — é de público. O seu token de aplicação representa a empresa que pediu a assinatura; o token de embed representa a pessoa que vai assinar. São interesses distintos e, em alguns momentos, opostos: o remetente não deveria conseguir avançar as etapas em nome de quem assina. Daí a consequência que aparece como bug: algumas rotas recusam o seu Bearer com 401, e o erro é indistinguível de credencial errada. Este guia traz o mapa completo e o que fazer quando um link de assinatura já foi consumido.

Duas credenciais, dois interesses

O seu token de aplicação, obtido em POST /oauth2/token, representa a empresa que pediu a assinatura. Ele vale para o tenant inteiro, atravessa todas as transações e vive 15 minutos — independentemente do que acontece com qualquer sessão específica.

O token de embed representa a pessoa que vai assinar. Ele nasce preso a uma sessão, morre com ela e não serve para mais nada.

A separação existe porque os dois papéis não são a mesma pessoa e, em alguns momentos, têm interesses opostos. Se o token de aplicação pudesse avançar as etapas de uma sessão, quem enviou o documento poderia concluir a assinatura em nome de quem deveria assinar — e a evidência registraria, com todos os carimbos de tempo em ordem, um ato que a pessoa nunca praticou. Restringir as rotas de avanço ao token do signatário é o que mantém essa fronteira de pé.

Dito de outro modo: o 401 que incomoda é a fronteira funcionando.

O mapa das seis rotas

E as rotas vizinhas, que usam o seu Bearer normalmente:

De onde vem o token de embed

Ele começa como o clientSecret devolvido na criação da sessão:

O link entregue à pessoa é a url com o segredo anexado como parâmetro cs. A página de assinatura lê esse parâmetro, obtém o token de embed e passa a usá-lo nas chamadas de advance.

Na prática, você raramente manipula esse token: entrega o link e acompanha por /status ou por webhook. Ele só aparece explicitamente em dois casos — integração headless, que conduz as etapas por conta própria, e modo embarcado, em que o segredo é passado ao componente de checkout.

Uma consequência que vale registrar: o clientSecret é uma credencial, ainda que de vida curta e escopo mínimo. Ele não deveria aparecer em log de aplicação, em URL registrada por um proxy, nem em mensagem encaminhável para quem não é o signatário.

Uso único: o link que já foi usado

O link de assinatura vale uma vez. Depois que a pessoa conclui — ou que o token embutido é consumido de outra forma —, reabrir a mesma URL devolve:

Isso costuma soar como problema até se pensar na alternativa: um link reutilizável seria uma credencial permanente circulando por e-mail, capaz de reabrir a sessão de outra pessoa. O uso único é o que impede isso.

O efeito colateral é real, porém. A pessoa fecha a aba sem querer, o e-mail é encaminhado e alguém abre antes, o aplicativo de mensagens pré-carrega o link. Nada disso deveria custar uma transação nova — e não custa:

Três propriedades desta rota, cada uma respondendo a uma pergunta previsível:

• Não consome cota. Reemitir um link não é enviar um documento novo, e o plano não é debitado outra vez.
• Não estende o prazo. O expiresAt devolvido é o da sessão original. Relinkar não é uma forma de esticar o prazo indefinidamente — se a sessão venceu, o caminho é outro.
• Só em sessões ACTIVE. Uma sessão concluída ou cancelada responde 409 Session cannot be linked in status: <status>. Faz sentido: um link para uma sessão encerrada não autenticaria coisa alguma.

Vale para sessões avulsas e para sessões dentro de um envelope, indistintamente.

O que fazer quando a sessão já terminou

Se o pedido é "o cliente quer ver o que assinou", relinkar é a ferramenta errada. O que ele quer é o documento:

Depurando um 401

1. A rota está na lista das seis? Se sim, ela nunca vai aceitar o seu Bearer. Para consultar, troque GET /{id} por GET /{id}/status.
2. A mensagem diz Embed token has been consumed? O link foi usado. Emita outro com /link, sem custo.
3. É uma rota de Bearer mesmo assim? Verifique a validade do token — ele dura 900 segundos e integrações que o guardam entre execuções longas o usam vencido.
4. É 403, e não 401? Então a credencial foi aceita e o problema é de permissão: consulte o mapa de escopos, onde um escopo inválido descartado em silêncio é a causa mais comum.

Para os prazos que governam cada token e cada sessão, veja todos os prazos da API em uma página. Para o fluxo embarcado, em que o segredo é passado ao componente de checkout, assinatura incorporada. E para o runbook de sessões vencidas, sessão expirada: reenviar, cancelar ou recriar.

Perguntas Frequentes