Signatários (signers[])

Lista filha do envelope. Cada item é uma pessoa envolvida no processo — assinando ou não.

O signatário diz quem é a pessoa, como falar com ela e como ela comprova a identidade — tudo isso vale para o envelope inteiro. O que varia por documento, e a evidência técnica de cada ato, ficam nos requisitos.

Observador é signatário

Quem apenas recebe cópia não ganha tabela própria: é um signatário com action = receive_copy e nenhum requisito. É o carbonCopies da DocuSign e o observador da Clicksign.

Uma tabela separada duplicaria nome, documento, e-mail, canal de notificação e status para não acrescentar nada.

Ordem de assinatura

Dois campos controlam a ordem, e eles não são a mesma coisa:

Campo	O que controla
group	Quem assina antes de quem. O grupo 2 só é notificado quando o grupo 1 termina.
order	A ordem dentro do grupo, para exibição. Todos do mesmo grupo assinam em paralelo.

Um contrato em que o cliente assina primeiro e depois as duas testemunhas: cliente no grupo 1, testemunhas no grupo 2 com order 1 e 2. Só order não expressaria isso — sugeriria que as testemunhas assinam uma após a outra.

Quando flow = parallel, os grupos são ignorados e todos são notificados de uma vez.

Campos

Identificação

Campo	Entrada	Tipo	Para que serve
id	id	string (uuid)	Identificador do signatário. Pode ser informado por você no cadastro — é assim que os requisitos o referenciam antes de existirem nid.
nid	—	integer	Identificador numérico interno. É por ele que requirements[].signerNid e documents[].signerNid apontam. Também é enviado como id do signatário à QI Sign, que exige unicidade dentro do envelope.
group	group	integer	Grupo de assinatura. Ver acima.
order	order	integer	Ordem dentro do grupo.
name	name	string	Nome completo. Aparece no documento e no dossiê.
personType	personType	object (code/key/name)	Pessoa física ou jurídica (natural_person, legal_entity). Ver Pessoas. Inválido → 1006030.
documentType	documentType	object (code/key/name)	Tipo do documento de identificação (cpf, cnpj). Ver Pessoas. Inválido → 1006009.
documentNumber	documentNumber	string	Número do documento, somente dígitos. Obrigatório no envio → 1006010. É a chave de identificação em todos os provedores e o que permite buscar "quais envelopes este CPF precisa assinar".
email	email	string | null	E-mail.
phone	phone	string | null	Telefone em E.164.
birthDate	birthDate	string (date) | null	Data de nascimento. Exigida por alguns provedores na validação biométrica.

Por que personType e não um booleano

A plataforma inteira representa "física ou jurídica" pelo domínio PersonType, nunca por um isLegalEntity. O signatário segue a mesma regra.

Um booleano responde uma pergunta só, e sempre pela negativa de um dos lados: false significa "não é jurídica", não "é física". O domínio nomeia os dois casos, é o mesmo tipo usado no titular do termo de autorização e no cadastro, e comporta um terceiro valor no dia em que existir.

É também o que casa com documentType: natural_person anda com cpf, legal_entity com cnpj. Signatário pessoa jurídica é o recipient do tipo Seal da DocuSign, em que quem assina é a organização e não um indivíduo.

Contato obrigatório

Ao menos um entre email e phone precisa estar preenchido, ou o envio falha com 1006011. Sem contato, não há como notificar nem enviar token — nenhum provedor aceita.

Notificação

Campo	Entrada	Tipo	Para que serve
deliveryChannel	deliveryChannel	object (code/key/name)	Canal por onde o documento chega. Padrão email. Ver SignatureDeliveryChannel. Inválido → 1006013.
authDeliveryChannel	authDeliveryChannel	object	Canal por onde o token de autenticação chega.

Por que dois canais

A QI Sign separa document_submission_method de authentication_submission_method: o contrato pode chegar por e-mail enquanto o código de verificação chega por SMS — o que é justamente o ponto de um segundo fator.

Provedor que não faz essa distinção usa só o deliveryChannel.

Ação e autenticação

Duas propriedades que descrevem a pessoa no envelope e valem para todos os documentos dele.

Campo	Entrada	Tipo	Para que serve
action	action	object (code/key/name)	O que a pessoa faz: assinar, aprovar, testemunhar, receber cópia. Padrão sign. Ver SignatureSignerAction. Inválido → 1006012.
authenticationType	authenticationType	object (code/key/name)	Como comprova a identidade. Ver SignatureAuthenticationType. Inválido → 1006018.

Por que aqui e não no requisito

Uma pessoa tem uma identidade só. Quem se identifica por biometria facial se identifica assim em todos os documentos daquele envelope; quem entrou para aprovar, aprova tudo.

A qualificação jurídica é o oposto: varia por documento, e por isso fica no requisito.

Fazer a mesma pessoa provar quem é de um jeito no contrato e de outro no anexo não descreve nenhum processo real de assinatura — e abriria espaço para configurar, por engano, um documento com exigência mais fraca que o outro.

Autenticação e acesso

Campo	Entrada	Tipo	Para que serve
authCode	authCode	string | null	Código de autenticação pré-definido por nós, em vez de gerado pelo provedor. É o AuthCode da Unico Sign e o access code da DocuSign: o operador combina o código com o cliente por outro canal.
embedded	embedded	boolean	Este signatário assina dentro da nossa aplicação, em widget embarcado, em vez de por link. Controle individual — o envelope tem o seu próprio.
embeddedUrl	—	string | null	URL do widget embarcado, devolvida pelo provedor.
signUrl	—	string | null	Link de assinatura individual. É o que se reenvia quando o cliente diz que não recebeu o e-mail.

Estado

Campo	Entrada	Tipo	Para que serve
status	—	object (Status)	Estado do signatário. Ver SignatureSignerStatus.
externalId	—	string | null	Id do signatário no provedor. Correlaciona os eventos de webhook.
externalStatus	—	string | null	Texto do status cru do provedor ("Não Assinado").
tryCount	—	integer	Quantas vezes o signatário tentou se autenticar. É o numberOfTries da Confia. Tentativas em excesso costumam preceder uma recusa — serve de sinal para a operação intervir antes de o envelope travar.
expiresAt	expiresAt	string (date-time) | null	Prazo individual deste signatário, distinto do prazo do envelope. A Confia define expiração por parte: um avalista pode ter menos tempo que o devedor.
signedAt	—	string (date-time) | null	Momento da assinatura.
refusedAt	—	string (date-time) | null	Momento da recusa.
refusalReason	—	string | null	Motivo declarado da recusa.

Biometria (biometry)

Resumo do resultado biométrico devolvido pelo provedor. Fica no signatário para permitir filtro e exibição em tela sem abrir outro registro.

Campo	Tipo	Para que serve
faceAvailable	boolean	O provedor conseguiu localizar e validar um rosto na captura. false quer dizer "não deu para avaliar", não "reprovou".
faceScore	decimal | null	Score da validação facial. Escala do provedor.
faceMatchScore	decimal | null	Score da comparação entre a selfie e a foto do documento. É o que responde "a pessoa que assinou é a do RG?".
faceProvider	object (code/key/name)	Quem executou a validação facial. Nem sempre é o provedor de assinatura — a Clicksign pode acionar SERPRO, e a QI Sign usa motor próprio. Ver SignatureBiometryProvider.
livenessResult	object (code/key/name)	Resultado da prova de vida. Ver SignatureLivenessResult.
fraudBaseFlag	boolean	O rosto foi encontrado em base de fraude conhecida.
documentTemplate	string | null	Template reconhecido do documento apresentado (cnh_front).

Resumo aqui, detalhe em outro módulo

Este bloco é resumo. As imagens, o OCR do documento, as validações biográficas e o resultado por capacidade pertencem à verificação de identidade, um processo que acontece também fora de qualquer envelope — no onboarding, por exemplo, antes de existir contrato.

Esse módulo ainda não existe, e por isso o signatário não guarda nenhum vínculo com ele. Quando existir, é aqui que entra a referência — e com ela a possibilidade de reaproveitar uma verificação já feita em vez de pedir selfie de novo.

A evidência técnica não está aqui

IP, geolocalização, dispositivo e timestamp do ato de assinar ficam em requirements[].authenticity, por par signatário × documento.

Com fluxo sequencial, ou com o cliente voltando dias depois para terminar, a mesma pessoa assina cada documento de um lugar e num momento diferente. Um IP só no signatário mentiria sobre pelo menos um documento.

Extensão

Campo	Entrada	Tipo	Para que serve
validations	validations	array de { key, label, value }	Validações externas executadas pelo provedor sobre o signatário. É onde entra o externalsValidations da Confia (cpf = REGULAR). Chave/valor livres porque cada provedor valida coisas diferentes; label é o rótulo de exibição.
data	data	array de { key, label, value }	Dados do signatário que não têm campo próprio: endereço, chave Pix, código interno do provedor. Cada plataforma manda um conjunto diferente e mutável — modelar colunas para isso envelheceria mal. label é o rótulo de exibição.

Por que existe o label

Toda lista livre do módulo é { key, label, value }. A chave é o que o sistema lê; o rótulo é o que a tela mostra.

Sem ele, exibir uma dessas listas obrigaria a inventar um texto a partir de pix_key ou nsu — e esse texto acabaria hardcoded na interface, longe de quem cadastrou o dado.