---
title: "Históricos escolares"
description: "Emissão de históricos escolares digitais pela API do Digiploma: XML assinado e RVHE, nos tipos parcial, final e segunda via."
canonical: "https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts"
locale: "pt-BR"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Históricos escolares

O **histórico escolar digital**, definido pela Portaria MEC nº 1.095/2018, é um arquivo XML assinado acompanhado da sua representação
visual, a **RVHE**, um PDF gerado a partir de um modelo. O Digiploma gera os dois, coleta as assinaturas no Lacuna Signer e publica o
histórico para validação.

Um histórico **final** também é gerado automaticamente com cada diploma, nos modos [emitir e registrar](https://docs.lacunasoftware.com/articles/digiploma/api/degrees) e
[apenas emitir](https://docs.lacunasoftware.com/articles/digiploma/api/emissions). Use esta API para emitir os demais históricos, ou um histórico final avulso.

## Tipos

| `type` | Significado |
|---|---|
| `Partial` | Emitido a qualquer momento enquanto o aluno está matriculado, como comprovante da parte do currículo já integralizada. |
| `Final` | Emitido quando o vínculo do aluno com a instituição termina, para o diploma ou para uma transferência externa. |
| `Copy` | Segunda via, em formato digital, de um histórico emitido originalmente em papel. O código do currículo e os dados de ingresso passam a ser opcionais. |

Um histórico parcial é recusado enquanto o aluno tiver, no mesmo curso, um histórico final que não esteja anulado. Além disso, quando
qualquer histórico de um aluno e curso é assinado, o Digiploma **anula automaticamente os históricos parciais mais antigos** desse aluno e
curso, com o motivo *"Histórico escolar cancelado automaticamente pois um histórico escolar final ou um novo histórico escolar parcial foi
emitido"*.

## Antes de começar

* A organização precisa ser emissora (tipo **Emissora** ou **Emissora e Registradora**). Caso contrário, a chamada falha com
  `SubscriptionOperationNotAllowed`.
* A chave de API do Signer precisa estar definida nas **Configurações** da organização (`SignerApiKeyNotSet`).
* É preciso ter um [modelo](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#modelos) de histórico escolar: um PDF de uma página, em orientação retrato, com o
  cabeçalho da instituição.
* É preciso ter os signatários: um [fluxo de assinatura](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#fluxos-de-assinatura) salvo, do tipo
  `AcademicTranscript`, ou os signatários informados diretamente em cada requisição.

## Criar um histórico escolar

`POST /api/academic-transcripts` cria um histórico. Para criar vários a partir de um arquivo JSON, use um [lote](https://docs.lacunasoftware.com/articles/digiploma/api/batches).

```json
{
  "type": "Partial",
  "academicTranscriptTemplateId": "6a1d9e44-…",
  "documentFlow": {
    "academicTranscriptFlow": [
      { "order": 1, "requiredSignatures": 1, "isCompany": false,
        "signers": [ { "name": "Maria Souza", "email": "maria@ies.edu.br", "cpf": "12345678909" } ] },
      { "order": 2, "requiredSignatures": 1, "isCompany": true, "companyIdentifier": "12345678000195",
        "signers": [ { "name": "João Lima", "email": "joao@ies.edu.br", "cpf": "98765432100" } ] }
    ]
  },
  "academicTranscript": {
    "aluno": { … },
    "dadosCurso": { … },
    "iesEmissora": { … },
    "historicoEscolar": { "codigoCurriculo": "…", "elementosHistorico": [ … ], "situacaoAtualDiscente": { … }, … }
  }
}
```

| Campo | Obrigatório | Descrição |
|---|---|---|
| `type` | Sim | `Partial`, `Final` ou `Copy`. |
| `academicTranscriptTemplateId` | Sim | O modelo de histórico escolar. |
| `academicTranscript` | Sim | Os dados do MEC: o aluno (`aluno`), o curso (`dadosCurso`), a instituição emissora (`iesEmissora`) e o próprio histórico (`historicoEscolar`). Quando omitidos, `historicoEscolar.dataEmissaoHistorico` e `horaEmissaoHistorico` recebem a data e a hora atuais. |
| `documentFlowId` | Um dos dois | Um fluxo de assinatura salvo, do tipo `AcademicTranscript`. |
| `documentFlow` | Um dos dois | Os signatários, informados na própria requisição. Só `academicTranscriptFlow` pode ser preenchido. Tem precedência sobre `documentFlowId`. |
| `newFolderName` | Não | Cria no Signer uma pasta com esse nome para o documento. Tem precedência sobre `signerFolderId`. |
| `signerFolderId` | Não | Uma pasta já existente no Signer. |

Há um exemplo completo dos dados no [arquivo JSON de exemplo](https://www.digiploma.com.br/assets/files/academic-transcript-template2.json).
Os dados são validados pelo esquema XML do MEC.

**Signatários.** O fluxo precisa de pelo menos uma assinatura institucional (`isCompany: true`, com certificado e-CNPJ); caso contrário, a
chamada falha com `DocumentFlowIssuerInstitutionSignatureRequired`. Os representantes (e-CPF) assinam primeiro, na ordem dos valores de
`order`, numa etapa chamada *Secretaria acadêmica*; a instituição assina por último, numa etapa chamada *Instituição*. Só a primeira regra
institucional é usada. Históricos finais e segundas vias exigem certificados A3, a menos que a instância desative essa exigência.

**A resposta** é `{success, academicTranscriptId, errors}`:

> **Aviso: Verifique success, não só o código de status HTTP**
>
> Falhas que acontecem durante a geração do histórico retornam **HTTP 200** com `"success": false` e o log de processamento, em português, em
> `errors`. Isso inclui um código de validação duplicado e um histórico parcial recusado porque já existe um histórico final. Veja
> [Resultado da criação](https://docs.lacunasoftware.com/articles/digiploma/api#resultado-da-criação).

O **código de validação** é calculado a partir do aluno, do curso, da instituição e da data e hora de emissão (até o minuto), no formato
`{código MEC da emissora}.{12 caracteres hexadecimais}`. Dois históricos do mesmo aluno e curso emitidos no mesmo minuto recebem o mesmo
código, e o segundo é recusado como duplicado.

## Status

| `status` | Significado |
|---|---|
| `Created` | Criado; aguardando assinaturas. |
| `Active` | Assinado: o histórico é válido. |
| `CanceledTemporarily` | Anulado temporariamente. Pode ser restaurado. |
| `Canceled` | Anulado. |

## Anular ou restaurar

**`POST /api/academic-transcripts/{id}/cancellation`** anula um histórico, com um motivo (`reason`) de até 500 caracteres:

```json
{ "reason": "Emitido com dados incorretos" }
```

Se o histórico ainda não foi assinado, o documento dele é excluído do Signer e o histórico nunca mais pode ser restaurado. Se o histórico
já estiver anulado, a chamada falha com `AcademicTranscriptAlreadyCanceled`.

**`POST /api/academic-transcripts/{id}/status`** muda o status, com um motivo (`reason`) obrigatório:

| `status` | Permitido quando |
|---|---|
| `Canceled` | O histórico ainda não está anulado. Mesmo efeito de `/cancellation`. |
| `CanceledTemporarily` | O histórico está assinado. |
| `Active` (restaurar) | O histórico está `CanceledTemporarily` e assinado (`AcademicTranscriptNotSignedCannotBeRestored`). |

Qualquer outra mudança falha com `AcademicTranscriptInvalidStatus`. As duas operações exigem a permissão `UpdateAcademicTranscript`.

## Baixar os arquivos

| Documento | Base64 | Ticket | Download direto | Disponível quando |
|---|---|---|---|---|
| XML assinado | `GET /{id}/xml-b64` | `GET /{id}/xml-ticket` | `GET /{id}/xml` | O histórico está `Active` (`AcademicTranscriptNotValid`). Com ticket, a verificação é feita no momento do download. |
| RVHE | `GET /{id}/visual-representation-b64` | `GET /{id}/visual-representation-ticket` | — | Sempre. |

Todos os caminhos são relativos a `/api/academic-transcripts`. Veja [Downloads e tickets](https://docs.lacunasoftware.com/articles/digiploma/api#downloads-e-tickets).

## Substituir a representação visual

`POST /api/academic-transcripts/{id}/visual-representation` substitui o RVHE de um histórico que não esteja anulado, a partir de outro modelo
de histórico escolar (`templateId`) ou de um PDF em orientação retrato enviado por [upload](https://docs.lacunasoftware.com/articles/digiploma/api#uploads) (`uploadId`). O XML assinado
não é alterado. A operação exige a permissão `UpdateDocumentVisualRepresentation` (papéis **Administrador** e **Gerente**).

## Consultar e pesquisar

* `GET /api/academic-transcripts/{id}` retorna o histórico, com `degreeId` quando ele foi gerado junto com um diploma.
* `GET /api/academic-transcripts/{id}/history` retorna as mudanças de status, da mais recente para a mais antiga.
* `GET /api/academic-transcripts` retorna uma página de históricos. Além dos [parâmetros de paginação](https://docs.lacunasoftware.com/articles/digiploma/api#paginação), filtra por
  `Status`, `BatchId`, data de criação (de `StartDateUtc`, inclusive, até `EndDateUtc`, exclusive), `IsSigned=true` (históricos
  assinados, inclusive os anulados) e `Q` (CPF, nome ou nome social do aluno, ou curso). Os resultados são ordenados pela data de
  atualização.

## Validar um histórico escolar

* `GET /api/academic-transcripts/codes/{code}` valida um histórico da sua própria organização, com a chave de API.
* `GET /api/academic-transcripts/{code}/validation` é a validação **pública**. Veja [Validação pública](https://docs.lacunasoftware.com/articles/digiploma/api/validation).

## Webhooks

| Evento | Quando |
|---|---|
| `AcademicTranscriptCreated` | O histórico foi criado (não é enviado quando ele é gerado com `POST /api/degrees/{id}/academic-transcript`). |
| `AcademicTranscriptConcluded` | O histórico foi assinado **ou restaurado**. |
| `AcademicTranscriptCanceled` | O histórico foi anulado, inclusive na anulação automática dos históricos parciais mais antigos. |
| `AcademicTranscriptCanceledTemporarily` | O histórico foi anulado temporariamente. |

Veja os dados de cada evento em [Webhooks](https://docs.lacunasoftware.com/articles/digiploma/api/webhooks).

## Referência das operações

| Operação | Descrição |
|---|---|
| `POST /api/academic-transcripts` | Criar um histórico |
| `GET /api/academic-transcripts` | Listar históricos |
| `GET /api/academic-transcripts/{id}` | Consultar um histórico |
| `GET /api/academic-transcripts/{id}/history` | Consultar as mudanças de status |
| `POST /api/academic-transcripts/{id}/cancellation` | Anular um histórico |
| `POST /api/academic-transcripts/{id}/status` | Anular, anular temporariamente ou restaurar um histórico |
| `GET /api/academic-transcripts/{id}/xml`, `…/xml-b64`, `…/xml-ticket` | Baixar o XML assinado |
| `GET /api/academic-transcripts/{id}/visual-representation-b64`, `…/visual-representation-ticket` | Baixar o RVHE |
| `POST /api/academic-transcripts/{id}/visual-representation` | Substituir o RVHE |
| `GET /api/academic-transcripts/codes/{code}` | Validar um histórico da sua organização |
| `GET /api/academic-transcripts/{code}/validation`, `…/validation/visual-representation`, `…/validation/xml` | [Validação pública](https://docs.lacunasoftware.com/articles/digiploma/api/validation) |