---
title: "Lotes"
description: "Lotes da API do Digiploma: como criar diplomas, emissões, requisições de registro, históricos escolares ou currículos a partir de um único arquivo."
canonical: "https://docs.lacunasoftware.com/articles/digiploma/api/batches"
locale: "pt-BR"
product: "Digiploma"
last_updated: "2026-10-11"
---

# 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](https://docs.lacunasoftware.com/articles/digiploma/api/degrees)) | Arquivo JSON ou CSV | Emissora e Registradora |
| `Emission` | Emissões ([Apenas emissão](https://docs.lacunasoftware.com/articles/digiploma/api/emissions)) | Arquivo JSON | Emissora, Emissora e Registradora |
| `Registration` | Requisições de registro ([Apenas registro](https://docs.lacunasoftware.com/articles/digiploma/api/registrations)) | Arquivos XML da documentação acadêmica assinados, um por requisição | Registradora, Emissora e Registradora |
| `AcademicTranscript` | [Históricos escolares](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts) | Arquivo JSON | Emissora, Emissora e Registradora |
| `Curriculum` | [Currículos](https://docs.lacunasoftware.com/articles/digiploma/api/curriculums) | 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](https://www.digiploma.com.br/assets/files/json-template5.json), [CSV](https://www.digiploma.com.br/assets/files/csv-template6.csv) |
| `Emission` | [JSON](https://www.digiploma.com.br/assets/files/emission-json-template3.json) |
| `AcademicTranscript` | [JSON](https://www.digiploma.com.br/assets/files/academic-transcript-template2.json) |
| `Curriculum` | [JSON](https://www.digiploma.com.br/assets/files/curriculum-template.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

1. Faça o [upload](https://docs.lacunasoftware.com/articles/digiploma/api#uploads) do arquivo. Para um arquivo JSON, envie o `contentType` `application/json`; para um arquivo CSV,
   `text/csv`.
1. Valide o arquivo (recomendado; veja [Validar um arquivo](https://docs.lacunasoftware.com/articles/digiploma/api/batches#validar-um-arquivo)).
1. Crie o lote com `POST /api/batches`:

```json
{
  "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](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#fluxos-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](https://docs.lacunasoftware.com/articles/digiploma/api/emissions#criar-uma-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](https://docs.lacunasoftware.com/articles/digiploma/api/registrations#registrar-o-diploma), 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](https://docs.lacunasoftware.com/articles/digiploma/api#downloads-e-tickets) 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](https://docs.lacunasoftware.com/articles/digiploma/api#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` |

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

```json
{
  "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 |