Requisitos (requirements[])

Lista filha do envelope. É o elo do modelo: cada item liga um signatário a um documento, dizendo com que título ele participa daquele arquivo, se precisa rubricá-lo, e registrando se aquele par já foi cumprido.

Uma linha se lê assim:

O signatário A, na qualidade de avalista, participa do documento B rubricando todas as páginas com iniciais — e ainda não cumpriu.

Uma linha por documento

Um requisito por par (signatário, documento). João como devedor no contrato e caucionante no termo de garantia:

#	signer	document	role	initialsType
1	João	Contrato	debtor	typed_initials
2	João	Termo de garantia	collateral_provider	none

O que NÃO está aqui

Duas coisas são da pessoa e valem para o envelope inteiro, não por documento:

Propriedade	Onde fica
Método de autenticação	signers[].authenticationType
Ação — assinar, aprovar, testemunhar, receber cópia	signers[].action

Uma pessoa tem uma identidade só, e o papel dela no envelope também é um só: quem entrou como testemunha é testemunha em tudo.

O que muda de documento para documento é a qualificação — e é isso, mais o cumprimento e a evidência do ato, que o requisito guarda.

Por que o requisito existe

Além da qualificação e da rubrica por documento, ele responde uma pergunta que nenhuma outra entidade responde:

Entidade	O que o status dela diz
documents[].status	se aquele documento já foi fechado
signers[].status	se aquela pessoa terminou tudo
requirements[].status	se aquela pessoa cumpriu aquele documento

"O João assinou a CCB 4471, mas ainda não o termo de garantia" só existe no requisito. É o detalhe por trás do status partially_signed do envelope — e é o que o operador precisa para saber o que cobrar do cliente.

Geração automática

Enviar requirements vazio ou ausente faz a plataforma gerar o padrão: o produto cartesiano dos signatários que atuam pelos documentos assináveis, todos com role = party.

Um envelope com 2 signatários e 2 contratos vira 4 requisitos sem você informar nenhum:

#	signer	document	role
1	João	CCB 4471	party
2	João	CCB 4472	party
3	Maria	CCB 4471	party
4	Maria	CCB 4472	party

Assim o caso comum — todo mundo assina tudo como parte — não exige montar a lista à mão, e os requisitos continuam existindo para registrar o progresso e a evidência de cada ato.

Quem entra na geração

Regra	Efeito
Documentos	só os assináveis: role = original e signerNid = 0. Dossiês, anexos e imagens de identificação ficam de fora.
Signatários	todos, exceto os com action = receive_copy — observador não tem o que cumprir. Entrega certificada entra, porque o envelope só fecha quando ele visualiza.

A lista nunca é complementada

Se você informar um requisito, a geração não acontece: a lista enviada é usada como está.

Isso é deliberado. Complementar uma lista parcial produziria envelopes com metade dos requisitos escolhidos por você e metade inventados pela plataforma — e ninguém conseguiria dizer, olhando o resultado, qual é qual. Para configurar exceção, informe a lista inteira.

Vale também no update: limpar requirements num envelope em rascunho regenera o padrão.

Campos

Campo	Entrada	Tipo	Para que serve
id	id	string (uuid)	Identificador do requisito.
nid	—	integer	Identificador numérico interno.
signatureNid	—	integer	nid do envelope.
signerNid	signerNid	integer	nid do signatário. Usado em alterações de envelope já gravado. Signatário inexistente → 1006021.
documentNid	documentNid	integer	nid do documento. Documento inexistente → 1006022.
signerId	signerId	string (uuid)	Só no cadastro. O id que você atribuiu ao signatário no mesmo payload. A plataforma resolve o nid correspondente.
documentId	documentId	string (uuid)	Só no cadastro. O id que você atribuiu ao documento no mesmo payload.
role	role	object (code/key/name)	Qualificação jurídica: com que título a pessoa assina aquele documento. É a única propriedade do signatário que varia por documento. Padrão party. Ver SignatureSignerRole. Inválido → 1006017.
initialsType	initialsType	object (code/key/name)	Se precisa rubricar, e de que forma. Padrão none. Ver SignatureInitialsType. Inválido → 1006019.
initialsPages	initialsPages	string | null	Quais páginas rubricar: "all" ou lista ("1,3,7"). Ignorado quando initialsType = none. A rubrica é por página; o modelo não guarda coordenada de marca.
status	—	object (Status)	Se o requisito já foi cumprido. Ver SignatureRequirementStatus.
fulfilledAt	—	string (date-time) | null	Momento do cumprimento.
authenticity	authenticity	object	Evidência técnica do ato. Ver abaixo.
externalId	—	string | null	Id do requisito no provedor, quando ele o expõe como recurso próprio (Clicksign).

Por que role está aqui e não no signatário

Porque o mesmo signatário pode ter qualificações diferentes em documentos diferentes do envelope. Quem assina o contrato principal como devedor pode assinar o termo de garantia como caucionante.

A qualificação é o que vai impresso no documento ao lado da assinatura — ela pertence à relação entre a pessoa e aquele papel específico.

---

Autenticidade

Evidências técnicas do ato de assinar aquele documento. É o que sustenta a assinatura numa contestação.

Campo	Tipo	Para que serve
timestamp	string (date-time) | null	Momento exato registrado pelo provedor, em UTC.
ipAddress	string | null	IP de onde partiu a assinatura.
sessionId	string | null	Identificador da sessão de assinatura.
userAgent	string | null	Navegador e sistema operacional usados.
deviceId	string | null	Identificador do dispositivo.
fingerprint	string | null	Impressão digital do navegador/dispositivo.
latitude	decimal | null	Latitude no momento da assinatura.
longitude	decimal | null	Longitude. A Confia devolve as duas juntas em latLong.
location	string | null	Local declarado (cidade/UF), quando informado pelo signatário.
channel	object (code/key/name)	Canal em que a assinatura ocorreu. Ver SignatureDeliveryChannel.
data	array de { key, label, value }	Evidências adicionais específicas do provedor. label é o rótulo de exibição.

Por que por par, e não por signatário

Com flow = sequential, ou com o cliente voltando dias depois para terminar, a mesma pessoa assina cada documento de um lugar e num momento diferente — a CCB de casa na segunda, o termo do escritório na quarta.

Um IP só no signatário seria falso para pelo menos um dos documentos. É também assim que os provedores registram: a auditoria da Confia é por parte com ip e latLong por evento, e a Clicksign dispara evento por documento.

Não confundir com os eventos

SignatureEvent também guarda IP e geolocalização — mas é a trilha: todo acesso, toda tentativa, toda recusa.

authenticity é o snapshot do ato que valeu. Mesma relação que existe entre o status de um registro e o seu log de auditoria.