Documentos (documents[])

Lista filha do envelope. Cada item é um arquivo envolvido no processo de assinatura.

A lista é heterogênea de propósito. Ela guarda quatro coisas que, no fim, são todas arquivos do mesmo processo:

O que é	Como se identifica
O documento a assinar	role = original, signerNid = 0
A versão assinada	role = signed
O dossiê de evidências	role = evidence_report, com sourceDocumentNid apontando para o original
A identificação do signatário	role = face_image / document_front / document_back, com signerNid preenchido

signerNid = 0 significa "documento do envelope". signerNid > 0 significa "evidência daquele signatário".

Cada documento aponta para o seu registro

feature + parentNid dizem qual registro aquele arquivo atesta — é o mesmo idioma de Charge e Payment. É isso que permite um envelope carregar contratos de operações diferentes:

#	title	feature	parentNid	type
1	CCB 4471	loan	4471	ccb
2	CCB 4472	loan	4472	ccb
3	Termo de garantia	loan	4471	term

O cliente recebe um convite e assina os três.

parentNid aqui não é o envelope

Nos requisitos, nas autenticações do signatário e nos eventos, parentNid é o nid do envelope.

Nesta tabela é diferente: parentNid é o registro de origem, e o envelope fica em signatureNid. A troca é deliberada, para preservar o par feature + parentNid já usado em Charge e Payment.

Onde o arquivo fica

O binário nunca é gravado na entidade. Ele vive no módulo de armazenamento e chega aqui como file, um espelho do arquivo armazenado.

Isso não é preferência de arquitetura: as URLs que os provedores devolvem expiram — 24 horas na QI Sign para dossiê, imagem facial e foto do documento. Guardar apenas externalUrl significaria perder a evidência de uma assinatura em um dia.

O fluxo é:

1. Saída — o arquivo sai do armazenamento, é convertido para base64 e enviado ao provedor.
2. Entrada — o provedor devolve uma URL temporária; a plataforma baixa o conteúdo, grava um arquivo novo no armazenamento e guarda a URL apenas como rastro.

Só o id é gravado

Você informa apenas fileId. O resto — nome, extensão, contentType, tamanho, URL pública, tipo, origem, grupo e situação — é montado a partir do arquivo armazenado, que é a fonte da verdade.

Na entrada, o FileField é construído lendo o arquivo pelo id no momento do cadastro: o que você mandar no payload além do id é ignorado. Na persistência, tb_signature_document tem uma única coluna para isso, file_id; todas as demais aparecem só na vw_signature_document, que faz JOIN com vw_stored_file.

É o mesmo princípio das referências do resto da plataforma — grava-se o vínculo, não a cópia. As consequências práticas:

• renomear, reclassificar ou mover um arquivo no módulo de armazenamento se reflete no documento sem migração, porque não havia cópia para atualizar;
• não existe o estado de um documento apontar para um arquivo e exibir o nome de outro;
• o JOIN é com a view do armazenamento, não com a tabela, para que type, origin e group já venham resolvidos em code/key/name.

Por que file e não uma referência simples

Uma referência comum carrega nid, code e name — suficiente para um link em tela.

Um documento de assinatura precisa de mais: a extensão e o contentType decidem como o arquivo é enviado ao provedor, o tamanho é validado contra o limite de 10 MB, e a situação diz se o binário ainda existe. Por isso o espelho é o arquivo inteiro, e não só o ponteiro.

Campos

Identificação e posição

Campo	Entrada	Tipo	Para que serve
id	id	string (uuid)	Identificador do documento. Pode ser informado por você no cadastro — é assim que os requisitos referenciam o documento antes de existirem nid.
nid	—	integer	Identificador numérico interno. É por ele que requirements[].documentNid aponta.
signatureNid	—	integer	nid do envelope a que este documento pertence.
signerNid	—	integer	0 para documento do envelope; nid do signatário para evidência de identificação.
sourceDocumentNid	—	integer	Para um dossiê, o nid do documento que ele atesta. 0 nos demais casos.
order	order	integer	Ordem de exibição e de apresentação ao signatário.
refId	refId	string	Id que nós atribuímos ao arquivo dentro do provedor. É o refId da Confia e o document.id da QI Sign. Gerado automaticamente quando não informado; serve de idempotência no reenvio.

Origem

Campo	Entrada	Tipo	Para que serve
feature	feature	object (code/key/name)	Módulo do registro que este documento atesta: loan, authorization_term, billing… Inválido → 1006006.
parentNid	parentNid	integer	nid do registro dentro daquele módulo. Com feature, forma a chave de correlação dos webhooks de esteira.
type	type	object (code/key/name)	Natureza jurídica deste documento: contrato, CCB, aditivo, termo. Padrão contract. Ver SignatureDocumentType. Inválido → 1006002.

Classificação

Campo	Entrada	Tipo	Para que serve
role	role	object (code/key/name)	O papel do arquivo no envelope. Padrão original. Ver SignatureDocumentRole. Inválido → 1006014.
origin	origin	object (code/key/name)	Se o arquivo foi enviado por nós ou coletado pelo provedor. Padrão internal. Ver SignatureDocumentOrigin. Inválido → 1006015.
title	title	string	Nome do documento exibido ao signatário.

Por que origin existe

Quando não enviamos o documento de identificação do signatário, o provedor coleta na hora da assinatura — a QI Sign faz isso por padrão. O arquivo então entra na lista vindo de fora, não de dentro.

Sem origin, não haveria como distinguir "o RG que mandamos" de "o RG que o provedor capturou do celular do signatário" — e é exatamente essa diferença que importa numa contestação.

Conteúdo

Campo	Entrada	Tipo	Para que serve
file	fileId	object (Arquivo)	O arquivo propriamente dito. Na entrada, o id do arquivo no módulo de armazenamento; na saída, o espelho completo — name, extension, key, url, size, type, origin, group, status. É a guarda da evidência.
hash	hash	string | null	Hash do conteúdo, para provar que o arquivo assinado é o mesmo que foi enviado.
hashAlgorithm	hashAlgorithm	string | null	Algoritmo usado (SHA-256).

Provedor e estado

Campo	Entrada	Tipo	Para que serve
externalId	—	string | null	Id do documento no provedor. Correlaciona os eventos de webhook que a Clicksign dispara por documento.
externalUrl	—	string | null	URL temporária devolvida pelo provedor. Expira — só serve para o download que popula file.
status	—	object (Status)	Estado do documento, independente do envelope. Ver SignatureDocumentStatus.

Regras

• Um envelope sem documento com role = original e signerNid = 0 não pode ser enviado → 1006008.
• Documento sem file não tem o que enviar → 1006016.
• Enquanto o envelope está em draft, a lista é substituída por completo a cada alteração. Fora de draft, qualquer alteração devolve 1006025.