1. Visão Geral dos Metadados

Atualmente o Conector Local pode gerar documentos baseados em três tipos de metadados diferentes:

• Diploma Digital a partir dos metadados indicados em JSON;

• Documentação Acadêmica a partir dos metadados indicados em JSON;

• Inserir Representação Visual a partir dos metadados indicados em JSON.

A estrutura dos metadados é dividida em duas partes: a seção meta e seção data. A seção meta é comum para todos os tipos de metadados, diferenciando apenas os valores indicados para cada campo.

{
    "meta": {
        "clientId": "institution_id",
        "yourNumber": "",
        "dltId": "ethereum",
        "docType": "visual_rep_degree",
        "mimeType": "application/pdf",
        "clientSignature": "",
        "groupId": "1" 
  } 
} 

Os valores dos campos são preenchidos da seguinte forma:

• clientId: ID da instituição junto ao RAP. Também chamado de institution_id. É enviado para cada instituição no momento da adesão ao serviço.

• yourNumber: código que identifica unicamente cada documento internamente à instituição.

• dltId: identificador da blockchain que será utilizada para registro. Atualmente o id suportado é ethereum. Esse campo é opcional. Caso não seja enviado ou enviado vazio, o documento não será registrado na blockchain.

• docType: Tipo de documento que está sendo processado. Opções são:

  • visual_rep_degree: referente a um documento do tipo representação visual de um diploma digital;

  • academic_doc_mec_degree: referente a um documento do tipo XML que representa uma Documentação Acadêmica de um aluno;

  • digital_degree: Referente a um documento do tipo XML que representa um Diploma Digital de um aluno.

• mimeType: Tipo de documento que está sendo enviado. Exemplo: text/xml para documentos XML ou application/pdf para documentos PDF e PDF/A.

• clientSignature: Campo reservado para uso futuro que deve ser enviado como string vazia.

• isDocSigned: Informa se o documento que está sendo processado será assinado ou não. Esse campo é opcional e por padrão é verdadeiro. No caso da geração de representação visual esse campo deve ser indicado com valor falso (false)

• groupId: Esse campo representa o ID que associa unicamente uma tupla de documentos.

No caso do diploma digital um grupo (groupId) pode ser uma dupla que combina um XML de Documentação Acadêmica + XML de Diploma Digital ou um trio que combina XML de Documentação Acadêmica + XML de Diploma Digital + PDF da Representação Visual (nesse caso os três documentos serão agrupados pelo serviço RAP). O ID de grupo é uma string e pode ser gerado da forma que a instituição achar mais conveniente. TODOS OS DOCUMENTOS QUE COMPÕE UMA TUPLA DEVEM CONTER UM MESMO ID DE GRUPO. A correta geração de IDs únicos e sua indicação por tupla de documentos é condição essencial para correta gestão dos documentos e pode acarretar erros caso não estejam corretamente configurados.

Como exemplo de uso, caso desejássemos gerar um grupo de documentos relacionados ao diploma digital teríamos os seguintes campos meta nos metadados hipotéticos:

• XML da Documentação Acadêmica

{ 
    "meta": { 
        "clientId": "institution_id" , 
        "yourNumber": "AAA" , 
        "dltId": "ethereum" , 
        "docType": "academic_doc_mec_degree" , 
        "mimeType": "tex/xml" , 
        "clientSignature": "" , 
        "isDocSigned": true , 
        "groupId": "1" 
    } 
} 

• XML do Diploma Digital

{ 
    "meta": { 
        "clientId": "institution_id" , 
        "yourNumber": "BBB" , 
        "dltId": "ethereum" , 
        "docType": "digital_degree" , 
        "mimeType": "text/xml" , 
        "clientSignature": "" , 
        "groupId": "1" 
    } 
} 

• PDF da Representação Visual

{ 
    "meta": { 
        "clientId": "institution_id" , 
        "yourNumber": "CCC" , 
        "dltId": "ethereum" , 
        "docType": "visual_rep_degree" , 
        "mimeType": "application/pdf" , 
        "clientSignature": "" , 
        "isDocSigned": false , 
        "groupId": "1" 
    } 
} 

Na tupla de exemplo acima o id de grupo (groupId) é 1 . Percebam que o yourNumber é único para cada documento. Essa tupla de metadados representa o os documentos relacionados ao processamento do Diploma Digital de UM aluno.

O campo data dos metadados são preenchidos de acordo com cada documento/forma de geração.

Vide arquivos de exemplos de preenchimentos** desses campos.

Também foram disponibilizados esquemas JSON** que podem ser utilizados para validar os metadados JSON criado antes de enviar para o Conector local iniciar o processamento.

Algumas considerações sobre o preenchimento dos campos data dos tipos de metadados:

• Diploma Digital a partir dos metadados indicados em JSON;

  • Conjunto de campos solicitados na Nota Técnica No. 13/2019/DIFES/SESU/SESU/MEC, Seção 7.12 - Anulação do Diploma;

  • Campo Versão: versão do XSD utilizado para gerar o XML do Diploma Digital;

• Documentação Acadêmica a partir dos metadados indicados em JSON;

  • Conjunto de campos solicitados na Nota Técnica No. 13/2019/DIFES/SESU/SESU/MEC, Seção 7.12 - Anulação do Diploma;

  • Campo Versão : versão do XSD utilizado para gerar o XML da Documentação Acadêmica.

• Representação Visual a partir dos metadados indicados em JSON.

  • Campo ReferenciaDiploma: mesmo código VDip contido no atributo infoDiploma do XML do Diploma Digital.

1.1. Esquemas para validação dos dados montados no formato JSON

Junto com os exemplos de JSON montados para Documentação Acadêmica, Diploma Digital e Representação Visual, estão os Schemas que podem ser utilizados para validar se o documento correspondente montado está válido e deverá ser processado com sucesso pelo Conector local. É possível confrontar o JSON montado com o Schema utilizando validadores online como o https://www.jsonschemavalidator.net/ Para uma lista completa de validadores de esquema, consultar: https://json-schema.org/implementations.html#validators

2. Preenchimento dos metadados

2.1. Ordem de geração dos documentos

1. Gerar/Assinar Documentação Acadêmica

2. Gerar/Assinar Histórico Escolar Final

3. Gerar/Assinar Diploma Digital

4. (opcional) Processar Representação Visual

5. (opcional) Processar Representação Visual

• O documento subsequente só pode ser gerado após a geração/assinatura e registro do documento anterior;

• A tupla de documentos referentes a um mesmo diploma devem ter o mesmo groupId.

Obs.: Segundo recomendação do MEC, sempre que houver a troca de XSD entre expedição e emissão dos documentos, deve-se alinhar a data de expedição (informada no arquivo XML) para funcionar com a versão do XSD mais atual.

Obs2.: A versão 1.04.1 do normativo criou o elemento Assinantes tanto para a Documentação Acadêmica quanto para o Diploma Digital. O elemento Assinantes é opcional e informa os cargos dos assinantes do nó DadosDiploma (para a Documentação Acadêmica) e do nó DadosRegistro (para o Diploma Digital). Caso esteja presente, deve possuir o CPF e cargo de todas as autoridades assinaram os respectivos nós. Sendo assim, se optarem por preencher esse elemento (que é opcional), cada IES deve gerenciar quem serão os assinantes que irão assinar aquele documento específico já levando em consideração se algum substituto irá substituir um assinante titular.

Obs3.: Os certificados de Pessoa Jurídica que assinam a Documentação Acadêmica e o Diploma Digital devem possuir os mesmo dados informando nos elementos da IES Emissora e da IES Registradora.

Obs4.: A versão 1.04.1 do normativo criou o elemento “ambiente” tanto para a Documentação Acadêmica quanto para o Diploma Digital. Para os documentos oficiais emitidos em produção, o elemento deve ser preenchido com o termo “Produção”.

Obs5.: Os documentos anexos à Documentação Acadêmica, mesmo os que sejam assinados digitalmente, devem estar no formato PDF/A.

3. Preenchimento dos metadados JSON para geração de uma Documentação Acadêmica

3.1. Preencha os metadados JSON para geração de uma Documentação Acadêmica

a. O JSON é composto pela seção meta e pela seção data: i. A seção meta será usada para registro do documento após gerado no serviço RAP e para controle dos documentos; 1. Defina o groupId de forma única para um conjunto de documentos que representam um diploma. Considerando a emissão para um aluno, a Documentação Acadêmica, Diploma Digital e Representação visual correspondentes devem ter o mesmo groupId para o referido aluno.

ii. A seção data será usada para gerar o XML da Documentação acadêmica. Os dados solicitados na seção data foram extraídos da própria norma. iii. Pela Nota Técnica, alguns documentos são necessários na Documentação Acadêmica. Esses documentos devem ser enviados como um base64 de arquivo no formato de preservação PDF/A. Caso não seja enviada nesse formato, o Conector tentará converter. Se a conversão não tiver sucesso, o processo de geração do PDF deve ser alterado para atender esse requisito.

b. Envie o documento para iniciar o seu processamento usando a rota POST /documents da API de Comunicação. Para o processamento de uma documentação acadêmica, o código do tipo é 4.

c. O processo de geração e registro pode ser acompanhado com as rotas GET /documents e GET /documents/{docId}/state i. GET /documents - lista documentos e estados atuais.

ii. GET /documents/{docId}/state - Lista estado atual de um documento

d. Quando o documento estiver no status 4, realize a coleta das assinaturas do XML da Documentação Acadêmica.

e. Após a coleta, o XML da Documentação Acadêmica é registrado e preservado na nuvem da RNP e irá para o status 10.

2. Preencha os metadados JSON para geração do XML do Histórico Escolar Final.

a. O JSON é composto pela seção meta e pela seção data.

i. A seção meta será usada para registro do documento após gerado no serviço RAP e para controle dos documentos.

1. O campo groupId deve ser o mesmo utilizado para gerar a Documentação Acadêmica. O Conector utiliza internamente esse campo para associar um conjunto de documentos relacionados a um diploma.

ii. A seção data será usada para indexar o XML do Histórico Escolar. Os dados necessários para gerar o histórico escolar serão extraídos da Documentação Acadêmica automaticamente pelo Conector.

b. Envie o documento para iniciar o seu processamento usando a rota POST /documents da API de Comunicação. Para o processamento de um histórico escolar final, o código do tipo é 3.

c. O processo de geração e registro pode ser acompanhado com as rotas GET /documents e GET /documents/{docId}/state.

i. GET /documents - lista documentos e estados atuais.

ii. GET /documents/{docId}/state - Lista estado atual de um documento

d. Quando o documento estiver no status 4, realize a coleta das assinaturas do XML do Histórico Escolar Final.

e. Após a coleta o Histórico é Registrado e Preservado na nuvem da RNP e irá para o status 10.

Vídeo demonstrativo - Gerar um XML válido de documentação acadêmica a partir de dados de exemplo:

1. Preencha os metadados JSON para processamento do PDF gerado pela instituição da Representação Visual do Histórico Escolar.

a. O JSON é composto pela seção meta e pela seção data.

i. A seção meta será usada para registro do documento após gerado no serviço RAP e para controle dos documentos.

1. O campo groupId deve ser o mesmo utilizado para gerar a Documentação Acadêmica e o Histórico Final. O Conector utiliza internamente esse campo para associar um conjunto de documentos relacionados a um diploma.

ii. A seção data será usada para indexar a Representação Visual do Histórico Final. O campo ReferenciaHistorico deve ser preenchido com o valor do securityCode retornado pela rota GET /documents/{docId}/.

b. Envie o documento para iniciar o seu processamento usando a rota POST /documents da API de Comunicação. Para o processamento de uma documentação acadêmica, o código do tipo é 13.

c. O processo de geração e registro pode ser acompanhado com as rotas GET /documents e GET /documents/{docId}/state

i. GET /documents - lista documentos e estados atuais.

ii. GET /documents/{docId}/state - Lista estado atual de um documento.

d. O PDF da representação visual do histórico escolar não é assinado digitalmente.

e. A Representação Visual do Histórico Escolar deve ser enviada no formato de preservação PDF/A. Caso não seja enviada nesse formato, o Conector tentará converter. Se a conversão não tiver sucesso, o processo de geração do PDF deve ser alterado para atender esse requisito.

f. Após o processamento da Representação Visual do Histórico Escolar, esta é Registrada e Preservada na nuvem da RNP e irá para o status 10.

3.2. Realização da coleta das assinaturas do XML da Documentação Acadêmica.

Vide passo a passo da coleta das assinaturas na sessão RAPSign

Após a coleta, o XML da Documentação Acadêmica é registrado e preservado na nuvem da RNP.

Vídeo demonstrativo - Teste de depósito registro com documentação acadêmica:

4. Preenchimento dos metadados JSON para geração do Diploma Digital.

4.1. Preencha os metadados JSON para geração do XML do Diploma Digital

a. O JSON é composto pela seção meta e pela seção data; i. A seção meta será usada para registro do documento após gerado no serviço RAP e para controle dos documentos; 1. O campo groupId deve ser o mesmo utilizado para gerar a Documentação Acadêmica. O Conector utiliza internamente esse campo para associar um conjunto de documentos relacionados a um diploma.

ii. A seção data será usada para gerar o XML do Diploma Digital. Os dados solicitados na seção data foram extraídos da própria norma.

b. Envie o documento para iniciar o seu processamento usando a rota POST /documents da API de Comunicação. Para o processamento de uma documentação acadêmica, o código do tipo é 2.

c. O processo de geração e registro pode ser acompanhado com as rotas GET /documents e GET /documents/{docId}/state ;

i. GET /documents - lista documentos e estados atuais.

ii. GET /documents/{docId}/state - Lista estado atual de um documento.

d. Quando o documento estiver no status 4, realize a coleta das assinaturas do XML do Diploma Digital.

e. Após a coleta o Diploma é Registrado e Preservado na nuvem da RNP e irá para o status 10.

Vídeo demonstrativo - Gerar um XML válido de diploma digital a partir de dados de exemplo:

4.2. Realização da coleta das assinaturas do XML do Diploma Digital.

Vide passo a passo da coleta das assinaturas na sessão RAPSign

Após a coleta, o Diploma Digital é registrado e preservado na nuvem da RNP.

Vídeo demonstrativo - Teste de depósito registro com Diploma Digital:

4.3.Exemplo de arquivo JSON da documentação acadêmica preenchido com as especificações de segunda via.

Arquivo JSON: { "meta": { "clientId": "<client_id>", "clientSignature": "<empty>", "docType": "academic_doc_mec_degree", "groupId": "DIGITAL_DEGREE_GROUP_SV-v1.04.1", "mimeType": "application/xml", "yourNumber": "ACADEMIC_DOC_SV-v1.04.1", "isDocSigned": "true" }, "data": { "Versao": "1.04.1", "ambiente": "Produção", "RegistroSegundaViaReq": { "DadosDiploma": { "DataConclusao": "2014-04-28", "Diplomado": { "ID": "17Z79AFB", "Nome": "Levi Chaves Salgado", "NomeSocial": "Djeyson", "Sexo": "M", "Nacionalidade": "brasileiro", "Naturalidade": { "CodigoMunicipio": "2507507", "NomeMunicipio": "João Pessoa", "UF": "PB" }, "CPF": "10285874610", "DataNascimento": "1995-10-01", "OutroDocumentoIdentificacao": { "TipoDocumento": "Carteira Nacional de Habilitação", "Identificador": "08330234514" } }, "DadosCurso": { "NomeCurso": "Ciência da Computação", "CodigoCursoEMEC": "1098272", "Modalidade": "EAD", "Habilitacao": [ { "NomeHabilitacao": "Ciência de dados", "DataHabilitacao": "2022-08-06" } ], "TituloConferido": { "Titulo": "Bacharel" }, "GrauConferido": "Licenciatura", "EnderecoCurso": { "Logradouro": "Campus I - Lot. Cidade Universitaria", "Bairro": "Jardim Cidade Universitária", "CEP": "56051300", "CodigoMunicipio": "2507507", "NomeMunicipio": "João Pessoa", "UF": "PB", "Numero": "s/n", "Complemento": "campus I" }, "Polo": { "Nome": "Polo de João Pessoa", "CodigoEMEC": "214834", "Endereco": { "Logradouro": "Campus I - Lot. Cidade Universitaria", "Bairro": "Jardim Cidade Universitária", "CEP": "58051900", "CodigoMunicipio": "2507507", "NomeMunicipio": "João Pessoa", "UF": "PB", "Numero": "10", "Complemento": "CAB" } }, "Autorizacao": { "InformacoesTramitacaoEMEC": { "NumeroProcesso": "70083", "TipoProcesso": "Solicitação de EMEC", "DataCadastro": "1947-05-14", "DataProtocolo": "1952-01-23" } }, "Reconhecimento": { "Tipo": "Lei Estadual", "Numero": "65424", "Data": "1990-06-01", "VeiculoPublicacao": "Diário oficial do Estado" }, "RenovacaoReconhecimento": { "Tipo": "Lei Federal", "Numero": "61234", "Data": "1991-05-02" } }, "IesEmissora": { "Nome": "Universidade Federal do Brasil", "CodigoMEC": "579", "CNPJ": "24001397250110", "Endereco": { "Logradouro": "Campus I - Lot. Cidade Universitaria", "Bairro": "Jardim Cidade Universitária", "CEP": "58921940", "CodigoMunicipio": "2507507", "NomeMunicipio": "João Pessoa", "UF": "PB", "Numero": "s/n" }, "Credenciamento": { "Tipo": "Lei Estadual", "Numero": "1346", "Data": "1960-12-19" }, "Recredenciamento": { "Tipo": "Portaria", "Numero": "60678", "Data": "2018-01-18" }, "Mantenedora": { "RazaoSocial": "Universidade Federal do Brasil", "CNPJ": "14098297009510", "Endereco": { "Logradouro": "Cidade Universitária", "Bairro": "Castelo Branco", "CEP": "58921940", "CodigoMunicipio": "2507507", "NomeMunicipio": "João Pessoa", "UF": "PB", "Numero": "s/n", "Complemento": "Campus I" } } }, "Assinantes": [ { "Assinante": { "CPF": "39444024997", "Cargo": "Responsável pelo registro" } }, { "Assinante": { "CPF": "21002499495", "Cargo": "Reitor" } } ] }, "DadosPrivadosDiplomado": { "Filiacao": [ { "Genitor": { "Nome": "Marília Novais Quinterno", "Sexo": "F", "NomeSocial": "Marília Quinterno" } }, { "Genitor": { "Nome": "Jaime Vilante Medeiros", "Sexo": "M" } } ], "HistoricoEscolar": { "ElementosHistorico": [ { "Disciplina": { "NomeDisciplina": "Astronomia de posição e mecânica celeste", "CodigoDisciplina": "12345", "PeriodoLetivo": "2019.1", "NotaAteCem": "100.00", "Situacao": { "Aprovado": { "FormaIntegralizacao": "Aproveitado" } }, "CargaHoraria": { "HoraAula": "60" } } }, { "Disciplina": { "NomeDisciplina": "Sensoriamento remoto da atmosfera", "CodigoDisciplina": "54321", "PeriodoLetivo": "2019.2", "Nota": "3.69", "Situacao": "Reprovado", "CargaHoraria": { "HoraAula": "40" }, "Docentes": [ { "Docente": { "Nome": "Arman Aguiar Fontes", "Titulacao": "Mestrado", "Lattes": "http://lattes.cnpq.br/9", "CPF": "51174832778" } } ] } }, { "AtividadeComplementar": { "DataInicio": "2020-01-20", "DataFim": "2020-06-08", "DataRegistro": "2020-01-22", "TipoAtividadeComplementar": "Monitoria acadêmica", "Descricao": "Monitoria acadêmica em ciência de dados", "CargaHorariaEmHoraRelogio": "180.73", "DocentesResponsaveisPelaValidacao": [ { "Docente": { "Nome": "Hannah Coelho Mateus", "Titulacao": "Especialização", "Lattes": "http://lattes.cnpq.br/934542", "CPF": "51174832778" } } ] } }, { "Estagio": { "DataInicio": "2020-07-20", "DataFim": "2020-12-15", "CargaHorariaEmHorasRelogio": "200.30", "Descricao": "Estágio em desenvolvimento de software", "DocentesOrientadores": [ { "Docente": { "Nome": "Dérick Brandão Laureano", "Titulacao": "Tecnólogo", "Lattes": "http://lattes.cnpq.br/7622468", "CPF": "79090401754" } }, { "Docente": { "Nome": "Pietra Granjeiro Farias", "Titulacao": "Especialização", "Lattes": "http://lattes.cnpq.br/0", "CPF": "48163616824" } } ], "Concedente": { "RazaoSocial": "Ledger Serviços em Tecnologia LTDA", "NomeFantasia": "LedgerTec", "CNPJ": "51355751324011" } } }, { "SituacaoDiscente": { "PeriodoLetivo": "2017.2", "Situacao": { "IntercambioInternacional": { "Instituicao": "Universidade de Toronto", "Pais": "Canadá", "NomeProgramaIntercambio": "Ciência sem fronteiras" } } } } ], "DataEmissaoHistorico": "2021-06-17", "SituacaoAtualDiscente": { "PeriodoLetivo": "2022.1", "Situacao": { "Formado": { "DataConclusaoCurso": "2022-07-28", "DataColacaoGrau": "2022-07-30", "DataExpedicaoDiploma": "2022-07-18" } } }, "CargaHorariaCursoIntegralizada": { "HoraRelogio": "980.08" }, "CargaHorariaCurso": { "HoraAula": "1000" } } } } } }

5. Preenchimento dos metadados JSON para processamento do PDF gerado pela instituição da Representação Visual

5.1. Preencha os metadados JSON para processamento do PDF gerado pela Instituição da Representação Visual

a. O JSON é composto pela seção meta e pela seção data; i. A seção meta será usada para registro do documento após gerado no serviço RAP e para controle dos documentos; 1. O campo groupId deve ser o mesmo utilizado para gerar a Documentação Acadêmica e o Diploma Digital. O Conector utiliza internamente esse campo para associar um conjunto de documentos relacionados a um diploma;

ii. A seção data será usada para indexar a Representação Visual. O campo ReferenciaDiploma deve ser preenchido com o valor do securityCode retornado pela rota GET /documents/{docId}/.

b. Envie o documento para iniciar o seu processamento usando a rota POST /documents da API de Comunicação. Para o processamento de uma documentação acadêmica, o código do tipo é 5 ;

c. O processo de registro pode ser acompanhado com as rotas GET /documents e GET /documents/{docId}/state ; i. GET /documents - lista documentos e estados atuais; ii. GET /documents/{docId}/state - Lista todos os estados de um documento;

Vídeo demonstrativo - Associar uma representação visual com um diploma digital:

d. O PDF da representação visual não é assinado digitalmente.

e. A Representação Visual deve ser enviada no formato de preservação PDF/A. Caso não seja enviada nesse formato, o Conector tentará converter. Se a conversão não tiver sucesso, o processo de geração do PDF deve ser alterado para atender esse requisito.

f. Após o processamento da Representação Visual, esta é Registrada e Preservada na nuvem da RNP e irá para o status 10.

6. Validação dos dados JSON antes do início da geração

Foram enviados junto com a documentação Schemas para validação dos arquivos JSON montados para geração da Documentação Acadêmica, Diploma Digital e Representação Visual. Esses esquemas podem ser utilizados para verificar se os dados montados são válidos antes de enviarem para geração. Essa validação pode ser feita por meio de ferramentas online como https://www.jsonschemavalidator.net/ ou outras listadas em https://json-schema.org/implementations.html#validators.

7. Pós-Processamento

Vide link Pós-Processamento

8.0. Assinatura dos Documentos

Para assinatura dos documentos gerados instale e execute a aplicação RAPSign. Os instaladores da aplicação estão disponíveis junto à esta documentação. Na primeira execução da aplicação é necessário configurar a URL do Conector. Para isso, no menu no canto superior direito clique no botão “Configurações”. Preencha o campo “Endereço do serviço" com o IP e porta que o Conector está rodando (ex. http://localhost:80/). Quando um documento estiver no status 4 (“SIGN STARTED”) acesse o RAPSign WEB usando os certificados cadastrados e realize as assinaturas.

Para assinatura dos documentos gerados instale e execute a aplicação RAPSign (vide sessão RAPSing).