userExternalId: escolhendo um identificador que você não vai querer trocar

Entre os campos obrigatórios de uma transação, userExternalId é o mais fácil de preencher no automático e o mais caro de corrigir depois. Ele aceita qualquer texto, ninguém valida o formato, e o valor que você mandar no primeiro dia funciona. O que a documentação não deixa óbvio é o papel que ele exerce: é por ele que a API agrupa tudo o que uma pessoa fez e é ele que endereça o cadastro biométrico dela. Trocá-lo mais tarde não renomeia coisa alguma — cria um segundo usuário, vazio, ao lado do primeiro. Este guia mostra o que ele governa e como escolher um valor com o qual você vai conseguir conviver.

Um campo obrigatório que ninguém valida

Toda criação de transação ou sessão exige signer.userExternalId:

Sem ele, a criação falha com signer.userExternalId is required. Com qualquer valor, ela passa: não há restrição de formato, de tamanho ou de conjunto de caracteres. É essa combinação — obrigatório, mas irrestrito — que faz o campo ser preenchido no reflexo, com o que estiver à mão.

O que ele realmente governa

1. O histórico da pessoa

A plataforma agrupa as transações por esse identificador. É a resposta para "o que essa pessoa já assinou na minha conta" — usada em suporte, em auditoria interna e em qualquer tela que mostre o histórico de um cliente.

Dois valores diferentes para a mesma pessoa produzem dois históricos, e nada na API indica que eles se referem ao mesmo indivíduo.

2. O cadastro biométrico

Este é o vínculo mais concreto, porque o identificador está no próprio caminho da rota:

O cadastro da foto de referência é endereçado por ele. Mudar o identificador de uma pessoa desconecta o cadastro biométrico dela — a consulta responde 404 e a próxima assinatura com comparação facial falha por falta de referência, num ponto do fluxo que não tem nada a ver com a mudança que causou o problema.

O que acontece quando o valor muda

Nada é migrado. Vale ser literal sobre a sequência, porque a intuição sugere renomeação e não é isso que acontece:

Não há endpoint de fusão nem de renomeação. A correção é reprocessar do seu lado: descobrir o valor antigo, recadastrar a biometria sob o novo, e manter em algum lugar a informação de que os dois identificadores são a mesma pessoa. Todo esse trabalho é evitável com dez minutos de decisão no início.

Duas identidades, e por que ambas existem

Uma dúvida frequente é por que a API pede dois identificadores — este e o CPF ou CNPJ, que também é obrigatório. Eles respondem a perguntas diferentes:

Isso explica por que usar o CPF como userExternalId costuma ser a escolha errada, embora funcione. O CPF já é indexado separadamente como identificador da pessoa natural, então repeti-lo aqui não acrescenta capacidade de busca alguma — só espalha um dado pessoal por mais um campo, que aparece em log de aplicação, no caminho da URL das rotas de cadastro biométrico e no seu próprio banco. Ganha-se nada e amplia-se a superfície.

Escolhas ruins, e por quê

A penúltima linha merece atenção porque é um erro sutil: usar o identificador do documento no campo do signatário não gera erro nenhum na API. Tudo funciona, e o histórico simplesmente nunca se forma.

A escolha que envelhece bem

Três propriedades a buscar:

• Imutável por construção. Chave primária de banco não muda porque a pessoa mudou de e-mail — é justamente para isso que ela existe.
• Legível em investigação. Quando o suporte lê cliente-8812 num registro, sabe onde procurar. Com um UUID opaco, precisa de uma consulta a mais só para saber de que tabela veio.
• Sem dado pessoal. O identificador aparece em caminho de URL e em log; um valor que não carrega dado pessoal simplifica a vida.

O prefixo resolve um problema real quando várias tabelas alimentam a mesma integração: sem ele, o cliente 8812 e o fornecedor 8812 colidiriam no mesmo identificador — e a API os trataria, corretamente do ponto de vista dela, como a mesma pessoa.

Decisões de borda

A mesma pessoa em dois papéis. Se ela é cliente e também fornecedor, e o seu sistema mantém dois cadastros, use dois identificadores — os históricos ficam separados, o que costuma ser o desejado. Se quiser o histórico unificado, use um. As duas escolhas são legítimas; o que causa problema é oscilar entre elas ao longo do tempo.

Signatário que não é seu cliente. O avalista, o representante da outra parte, a testemunha — pessoas que não têm cadastro no seu sistema. Crie um cadastro mínimo e use a chave dele, ou adote um prefixo próprio (externo-…) com um identificador que você controle. O que não funciona é improvisar um valor diferente a cada vez: aí a mesma pessoa, que pode voltar a assinar, nunca acumula histórico.

Migração de outra plataforma. Reaproveitar o identificador da plataforma antiga é tentador e amarra você a ela. Se o mapeamento existe do seu lado, use o seu próprio identificador desde o começo.

Antes da primeira transação em produção

1. Escolha a fonte do valor — qual tabela, qual coluna — e escreva isso na documentação interna da integração.
2. Prefixe por origem se mais de uma tabela alimenta a integração.
3. Confirme que a coluna é imutável. Se a área de negócio consegue renumerar aquilo, não serve.
4. Não derive de dado pessoal. Nem e-mail, nem telefone, nem CPF.
5. Se usar biometria, teste o ciclo completo: cadastrar sob o identificador, consultar e assinar. É onde um identificador instável se revela primeiro — ver os prazos do cadastro biométrico.

Para o modelo em que esse identificador se encaixa, veja transação, sessão ou envelope: qual usar.

Perguntas Frequentes