Lotes

Um lote cria vários documentos a partir de um único arquivo: diplomas, emissões, requisições de registro, históricos escolares ou currículos. O lote é criado de forma síncrona, depois que o arquivo é validado, e os documentos são gerados em segundo plano.

Tipos de lote

`type`	Cria	Entrada	Tipo de organização
`EmissionRegistration` (padrão)	Diplomas, cada um com seu histórico escolar final (Emissão e registro)	Arquivo JSON ou CSV	Emissora e Registradora
`Emission`	Emissões (Apenas emissão)	Arquivo JSON	Emissora, Emissora e Registradora
`Registration`	Requisições de registro (Apenas registro)	Arquivos XML da documentação acadêmica assinados, um por requisição	Registradora, Emissora e Registradora
`AcademicTranscript`	Históricos escolares	Arquivo JSON	Emissora, Emissora e Registradora
`Curriculum`	Currículos	Arquivo JSON	Emissora, Emissora e Registradora

Envie sempre o type: quando ele é omitido, o padrão é EmissionRegistration.

Formatos de arquivo

Um arquivo JSON é um array com um objeto por documento, com os mesmos dados da requisição de criação individual daquele tipo de documento. Arquivos de exemplo:

`type`	Exemplo
`EmissionRegistration`	JSON, CSV
`Emission`	JSON
`AcademicTranscript`	JSON
`Curriculum`	JSON

O arquivo CSV, aceito apenas para diplomas, tem uma linha por diploma e uma linha de cabeçalho com os nomes das informações, na forma de caminhos separados por ponto, como Diploma.Diplomado.Nome. Elementos repetidos recebem um sufixo numerado, como em Diploma.Curso.Habilitacao_1.NomeHabilitacao. O separador é o declarado numa primeira linha SEP=, (como o Excel grava) ou, se ela não existir, a vírgula ou o ponto e vírgula, o que for mais frequente no cabeçalho. A codificação padrão é ISO-8859-1 (Latin-1); um arquivo com BOM (byte order mark) é lido como UTF-8.

Nos arquivos JSON, a vírgula decimal é aceita, e os espaços no início e no fim dos textos são removidos. As entradas JSON são validadas contra o schema XML (XSD) do MEC; as linhas CSV são validadas apenas contra as regras dos dados.

Criar um lote

Faça o upload do arquivo. Para um arquivo JSON, envie o contentType application/json; para um arquivo CSV, text/csv.
Valide o arquivo (recomendado; veja Validar um arquivo).
Crie o lote com POST /api/batches:

{
  "type": "EmissionRegistration",
  "fileType": "Csv",
  "batchFile": { "id": "5d3b…", "name": "formandos-2026-1.csv", "contentType": "text/csv" },
  "templateId": "0f8b…",
  "academicTranscriptTemplateId": "6a1d…",
  "documentFlowId": "c2f0…",
  "newFolderName": "Formandos 2026-1"
}

Campo	Descrição
`type`	O tipo do lote.
`fileType`	`Json` ou `Csv`. `Csv` só vale para `EmissionRegistration` (`BatchTypeRequiresJson`).
`batchFile`	O arquivo enviado por upload. Não é usado em `Registration`. (`degreesFile` é um nome obsoleto do mesmo campo.)
`templateId`	O modelo de diploma: obrigatório para `EmissionRegistration`, opcional para `Emission`.
`academicTranscriptTemplateId`	O modelo de histórico escolar: obrigatório para `EmissionRegistration`, `Emission` e `AcademicTranscript`.
`curriculumTemplateId`	O modelo de currículo: obrigatório para `Curriculum`.
`documentFlowId` / `documentFlow`	Os signatários, obrigatórios: um fluxo de assinatura salvo, de tipo correspondente ao do lote, ou as etapas na própria requisição.
`newFolderName` / `signerFolderId`	A pasta do Signer para os documentos: uma pasta nova com esse nome ou uma pasta existente.
`academicTranscriptType`	Para `AcademicTranscript`: `Partial`, `Final` ou `Copy`.
`emission`	Para `Emission`: `registrationType` e, para `Subscription`, `registryId`, como em Apenas emissão. Também pode anexar, em `files`, a documentação comprobatória e o ato de designação de cada entrada, como uploads (com a posição da entrada, a partir de 0, em `index`).
`registration`	Para `Registration`: `academicDocumentationFiles`, a lista de arquivos XML enviados por upload (pelo menos um).

A resposta é o id do lote: { "id": "…" }.

O arquivo inteiro é validado durante essa chamada, o que pode demorar num arquivo grande. Se qualquer entrada for inválida, o lote não é criado, e a chamada falha com DegreesFileIsInvalid, AcademicTranscriptFileIsInvalid, CurriculumFileIsInvalid ou BatchRegistrationInvalidFiles, sem detalhes por entrada. Para encontrar os problemas, valide o arquivo antes.

Nos lotes Registration, os arquivos XML e as assinaturas deles são validados e as requisições são criadas, mas nada é enviado ao Signer: a coleta de assinaturas começa quando cada requisição é registrada, com o fluxo e a pasta do lote.

Acompanhar o lote

Os documentos são gerados em segundo plano, em grupos de 50. GET /api/batches/{id} retorna o andamento do lote:

Campo	Descrição
`status`	`Created` (aguardando), `Started` (em geração) ou `Completed`.
`totalDegrees`	O número de entradas do arquivo (em todos os tipos de lote, apesar do nome).
`totalDegreesCreated`	O número de documentos criados até o momento.
`totalDegreesWithError`	O número de entradas que falharam até o momento.

Consulte o lote periodicamente (polling) até que o status seja Completed. Não há webhooks de lote, mas cada documento criado envia o próprio webhook de criação, como DegreeCreated.

Uma entrada pode falhar na geração mesmo depois de o arquivo ter sido validado, por exemplo quando já existe outro documento com o mesmo código de validação ou quando o Signer recusa um grupo de documentos. As entradas que falham não são criadas, e os motivos ficam apenas no log do lote: GET /api/batches/{id}/log-ticket retorna um ticket para baixá-lo como arquivo de texto, em português, com uma linha por passo do processamento, o número da entrada e o CPF do aluno. O log só existe depois que o lote fica Completed (antes disso, BatchLogFileNotFound).

Para listar o que um lote criou, use GET /api/batches/{id}/degrees, …/emissions, …/registrations, …/academic-transcripts ou …/curriculums, com os parâmetros de paginação. Um lote EmissionRegistration lista os diplomas e os históricos deles.

GET /api/batches retorna uma página dos lotes da organização, ordenados pela data de criação.

Validar um arquivo

Antes de criar um lote, valide o arquivo com a operação do tipo dele. Ela retorna o resultado de cada entrada e não cria nada:

`type`	Operação
`EmissionRegistration`	`POST /api/batches/degrees-file` (JSON ou CSV)
`Emission`	`POST /api/batches/emissions-file`
`AcademicTranscript`	`POST /api/batches/academic-transcripts-file` (com `academicTranscriptType`)
`Curriculum`	`POST /api/batches/curriculums-file`

{ "id": "5d3b…", "name": "formandos-2026-1.csv", "contentType": "text/csv", "fileType": "Csv" }

{
  "isValid": false,
  "totalErrors": 2,
  "generalError": null,
  "result": [
    { "entryNumber": 1, "isValid": true, "errors": [], "structureErrors": [], "information": { … } },
    { "entryNumber": 2, "isValid": false, "errors": [ "Diploma.Diplomado.CPF: …" ], "structureErrors": [ … ], "information": { … } }
  ]
}

A resposta é sempre HTTP 200. Problemas do arquivo como um todo, como um arquivo CSV sem cabeçalho, vêm em generalError, sem result. Cada item de result traz o número da entrada no arquivo (a partir de 1), os erros nos dados (errors, no formato "campo: mensagem", em português), os erros contra o XSD do MEC (structureErrors) e os dados lidos do arquivo (information).

Referência das operações

Operação	Descrição
`POST /api/batches`	Criar um lote
`GET /api/batches`	Listar os lotes
`GET /api/batches/{id}`	Obter um lote
`GET /api/batches/{id}/log-ticket`	Baixar o log do lote
`GET /api/batches/{id}/degrees`, `…/emissions`, `…/registrations`, `…/academic-transcripts`, `…/curriculums`	Listar os documentos de um lote
`POST /api/batches/degrees-file`	Validar um arquivo de diplomas
`POST /api/batches/emissions-file`	Validar um arquivo de emissões
`POST /api/batches/academic-transcripts-file`	Validar um arquivo de históricos escolares
`POST /api/batches/curriculums-file`	Validar um arquivo de currículos

Ver em Markdown

Tipos de lote​

Formatos de arquivo​

Criar um lote​

Acompanhar o lote​

Validar um arquivo​

Referência das operações​