Modelos e fluxos de assinatura

Antes de criar documentos, a organização normalmente cadastra dois tipos de recurso, que reutiliza em várias requisições:

• Modelos, que definem a representação visual de cada documento: o RVDD do diploma, o RVHE do histórico escolar e o RVCE do currículo.
• Fluxos de assinatura, que definem quem assina cada documento. Salvar um fluxo é opcional, já que toda requisição de criação também aceita os signatários na própria requisição, mas cada requisição precisa de um ou de outro.

Modelos

type	Usado para	Requisitos do PDF
Degree	O RVDD do diploma	Um formulário PDF com exatamente duas páginas (frente e verso), em paisagem.
AcademicTranscript	O RVHE do histórico escolar	Um PDF com uma página, em retrato, com o cabeçalho da instituição (nome, endereço, atos regulatórios e, opcionalmente, o logotipo), conforme o art. 17 da Portaria MEC 1095/2018.
Curriculum	O RVCE do currículo	Um PDF com uma página, em retrato.

Exemplos: modelo de diploma, modelo de histórico escolar e modelo de currículo.

Como o modelo de diploma é preenchido

O modelo de diploma é um formulário PDF. O Digiploma preenche os campos de texto com os dados do diploma e depois achata o formulário (flatten):

• Um campo com o nome de uma informação, como Diploma.Diplomado.Nome, recebe o valor dela.
• Num campo cujo texto contém tags entre chaves, como Conferido a {Diploma.Diplomado.Nome}, cada tag é substituída. Um mesmo campo pode misturar texto e várias tags.

Os nomes das informações são os mesmos das colunas do arquivo CSV de lote, como Diploma.Diplomado.CPF ou Registro.LivroRegistro.NumeroRegistro, além de valores derivados, como Diploma.DataConclusaoExtenso. A página de criação de modelos, no Digiploma, lista todos eles.

Dois nomes de campo são especiais:

• VerificationCode recebe o endereço e o código de validação. Sem esse campo, eles são impressos no canto inferior direito da primeira página.
• QrCode marca onde fica o QR code que leva à página de validação. Sem esse campo, o QR code é colocado no canto inferior direito da última página.

Um modelo de diploma também pode ter uma versão para papel timbrado: um segundo formulário PDF, com os mesmos campos e sem imagem de fundo, para imprimir o diploma em papel timbrado. Ele também precisa ter exatamente duas páginas. Nesse caso, cada diploma ganha um segundo RVDD, baixado com GET /api/degrees/{id}/letterhead-visual-representation-ticket.

Como os modelos de histórico e de currículo são usados

Nos históricos escolares e nos currículos, o PDF é um fundo aplicado a todas as páginas de um documento que o próprio Digiploma diagrama, com as tabelas de dados do aluno, do curso, das disciplinas etc. As margens (marginTopInCentimeters etc.) mantêm o conteúdo afastado do cabeçalho: a margem superior deve corresponder à altura do cabeçalho no PDF. Os campos de texto podem usar tags como {Historico.IesEmissora.Nome} ou {Curriculo.IesEmissora.CNPJ}. Um QR code que leva à página de validação é colocado no canto inferior esquerdo da última página.

O endereço de validação

Por padrão, o QR code e o endereço impresso apontam para a página de validação da instância, /validar/{code}. Para usar uma página de validação própria, defina baseUrl (por exemplo, https://diplomas.example.edu.br) e, opcionalmente, validationPath, em que {code} é substituído pelo código de validação (por exemplo, /diploma/{code}).

Criar um modelo

1. Faça o upload do PDF.

2. Se quiser, visualize o modelo preenchido com dados de demonstração: POST /api/templates/preview-ticket recebe o upload (id, contentType) e as configurações do modelo (type, margens, baseUrl, validationPath) e retorna um ticket para baixar o PDF preenchido.

3. Crie o modelo com POST /api/templates:

   {
     "name": "Diploma de graduação 2026",
     "type": "Degree",
     "upload": { "id": "5d3b…", "name": "diploma.pdf", "contentType": "application/pdf" },
     "letterheadUpload": { "id": "8a1f…", "name": "diploma-timbrado.pdf", "contentType": "application/pdf" }
   }

Campo	Descrição
name	Obrigatório, até 200 caracteres.
type	Degree (padrão), AcademicTranscript ou Curriculum.
upload	O PDF. O contentType precisa ser application/pdf (ContentTypeNotSupported).
letterheadUpload	Só para Degree: a versão para papel timbrado.
baseUrl, validationPath	O endereço de validação (veja acima).
marginTopInCentimeters, marginBottomInCentimeters, marginLeftInCentimeters, marginRightInCentimeters	Não se aplicam a Degree. Na página A4, as margens superior e inferior somadas não podem passar de 27,5 cm, e as margens esquerda e direita somadas precisam ficar abaixo de 21 cm (InvalidTemplateDimensions).
settings.academicTranscript	Só para AcademicTranscript: exibir o reconhecimento do curso junto com a renovação, ocultar o documento de identidade de alunos brasileiros e definir títulos personalizados para as tabelas de dados.

Um PDF com o número de páginas ou a orientação errados falha com InvalidNumberOfPages ou InvalidPageOrientation.

Outras operações

Operação	Descrição
GET /api/templates	Uma página de modelos. Filtra por Type; Q busca no nome.
GET /api/templates/{id}	Um modelo, com as configurações, e tickets para baixar o PDF (file) e a versão para papel timbrado (letterheadFile).
PUT /api/templates/{id}	Altera o nome, o endereço de validação, as margens e as configurações. O PDF e o tipo não podem ser alterados: crie um novo modelo.
DELETE /api/templates/{id}	Exclui um modelo. Falha com TemplateIsLinked enquanto uma emissão usar o modelo. Os documentos já criados mantêm a representação visual.

Fluxos de assinatura

Um fluxo de assinatura lista os signatários de cada etapa de um documento. Cada tipo de documento usa algumas das etapas:

type do fluxo	Usado em	Etapas
EmissionRegistration	Emissão e registro	issuingFlow, registrationFlow, storageFlow, academicTranscriptFlow
Emission	Apenas emissão	issuingFlow, academicTranscriptFlow
Registration	Apenas registro	registrationFlow, storageFlow
AcademicTranscript	Históricos escolares	academicTranscriptFlow
Curriculum	Currículos	curriculumFlow

As etapas listadas precisam ser preenchidas, e as demais precisam ficar vazias.

Regras de cada etapa

Cada etapa é uma lista de regras. Uma regra é a assinatura de uma pessoa, com certificado e-CPF, ou a assinatura da instituição, com certificado e-CNPJ (isCompany: true):

Etapa	O que assina	Regras
issuingFlow (Emissão)	DadosDiploma, no XML do diploma e no XML da documentação acadêmica	Pelo menos um representante da emissora (e-CPF) e a emissora (e-CNPJ). A primeira regra e-CNPJ também assina o XML da documentação acadêmica inteiro.
registrationFlow (Registro)	DadosRegistro, no XML do diploma	Apenas representantes da registradora (e-CPF).
storageFlow (Armazenamento)	O XML do diploma inteiro	Exatamente uma regra, do e-CNPJ da registradora, com requiredSignatures = 1.
academicTranscriptFlow	O XML do histórico escolar	Pelo menos uma regra e-CNPJ. Os representantes (e-CPF) assinam primeiro; depois, a primeira regra e-CNPJ.
curriculumFlow	O XML do currículo	Exatamente uma regra e-CNPJ. Os coordenadores de curso (e-CPF) assinam primeiro.

Um fluxo que viola essas regras falha com um erro DocumentFlow…, como DocumentFlowStorageInstitutionSignatureRequired.

{
  "name": "Diplomas — graduação",
  "type": "EmissionRegistration",
  "issuingFlow": [
    { "order": 1, "isCompany": false, "requiredSignatures": 1,
      "signers": [ { "name": "Reitora", "email": "reitoria@ies.edu.br", "cpf": "12345678909" } ] },
    { "order": 2, "isCompany": true, "companyIdentifier": "12345678000195", "requiredSignatures": 1,
      "signers": [ { "name": "Secretaria Geral", "email": "secretaria@ies.edu.br", "cpf": "98765432100" } ] }
  ],
  "registrationFlow": [ … ],
  "storageFlow": [ … ],
  "academicTranscriptFlow": [ … ]
}

Campo da regra	Descrição
order	Numa etapa, as regras com o mesmo order são assinadas em paralelo; valores diferentes são assinados em sequência. As etapas se sucedem na ordem da tabela acima.
isCompany	true para uma assinatura institucional (e-CNPJ), false para uma pessoa (e-CPF).
companyIdentifier	Com isCompany, o CNPJ que o certificado precisa ter.
signers	As pessoas que assinam, cada uma com name, email e cpf (todos obrigatórios). Numa regra institucional, a pessoa que assina com o certificado e-CNPJ.
requiredSignatures	Quando uma regra lista vários signatários, quantos deles precisam assinar.
ruleName	O nome de uma regra com vários signatários.

Os certificados precisam ser do tipo A3, a menos que a instância desative essa exigência. Os históricos escolares parciais aceitam certificados A1.

Operações

Operação	Descrição
POST /api/flows	Cria um fluxo, com name, type e as etapas.
POST /api/flows/validate	Verifica um fluxo contra as regras do seu type, sem salvá-lo.
GET /api/flows	Uma página de fluxos. Filtra por type; Q busca no nome.
GET /api/flows/{id}	Um fluxo, com as etapas.
PUT /api/flows/{id}	Substitui um fluxo.
DELETE /api/flows/{id}	Exclui um fluxo.

Lotes e documentos guardam uma cópia do fluxo com que foram criados: alterar ou excluir um fluxo não os afeta.

Numa requisição de criação, envie documentFlowId com o id de um fluxo salvo, ou documentFlow com as etapas na própria requisição (sem name e type). Quando os dois são enviados, vale o documentFlow.