--- title: "API do Digiploma" description: "Visão geral da API REST do Digiploma: o que ela cobre, como escolher a integração conforme o tipo de organização e onde fica a referência em /swagger." canonical: "https://docs.lacunasoftware.com/articles/digiploma/api" locale: "pt-BR" product: "Digiploma" last_updated: "2026-10-12" --- # API do Digiploma O Digiploma tem uma API REST, com requisições e respostas em JSON, que cobre o que a aplicação web faz: criar diplomas, históricos escolares e currículos, acompanhar as assinaturas, baixar os arquivos, validar os documentos e manter os documentos exigidos pelo MEC. A **referência da API**, com todas as operações e modelos, é publicada por cada instância em `/swagger`; no serviço em nuvem, em [www.digiploma.com.br/swagger](https://www.digiploma.com.br/swagger/). Estas páginas explicam como as operações se combinam. Os exemplos usam `https://www.digiploma.com.br`; numa instância [on-premises](https://docs.lacunasoftware.com/articles/digiploma/on-premises), use o endereço dela. ## Escolha sua integração O que você pode fazer depende do **tipo da sua organização** no Digiploma: | Se a sua instituição… | Tipo de organização | Comece por | |---|---|---| | Emite e registra os próprios diplomas | Emissora e Registradora | [Emissão e registro](https://docs.lacunasoftware.com/articles/digiploma/api/degrees) | | Emite diplomas que outra instituição registra | Emissora | [Apenas emissão](https://docs.lacunasoftware.com/articles/digiploma/api/emissions) | | Registra diplomas emitidos por outras instituições | Registradora | [Apenas registro](https://docs.lacunasoftware.com/articles/digiploma/api/registrations) | As emissoras também podem criar [históricos escolares](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts) e [currículos](https://docs.lacunasoftware.com/articles/digiploma/api/curriculums). Em todos os casos, você vai usar [modelos e fluxos de assinatura](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows) e, provavelmente, [lotes](https://docs.lacunasoftware.com/articles/digiploma/api/batches) e [webhooks](https://docs.lacunasoftware.com/articles/digiploma/api/webhooks). As registradoras também publicam as [listas de diplomas anulados](https://docs.lacunasoftware.com/articles/digiploma/api/cancellation-lists), e as instituições geram [arquivos de fiscalização](https://docs.lacunasoftware.com/articles/digiploma/api/inspection-files) para o MEC. Qualquer pessoa pode [validar um documento](https://docs.lacunasoftware.com/articles/digiploma/api/validation). Uma operação que o tipo da organização não permite falha com `SubscriptionOperationNotAllowed`. As assinaturas são coletadas pelo Lacuna Signer; por isso, antes de criar documentos, a organização precisa ter uma chave de API do Signer definida em **Configurações**. Veja [Integração com o Signer](https://docs.lacunasoftware.com/articles/digiploma/on-premises/signer-setup). ## Autenticação Toda chamada precisa de uma **chave de API**, enviada no header `X-Api-Key`, exceto as operações de [validação pública](https://docs.lacunasoftware.com/articles/digiploma/api/validation), que não precisam de chave: ```text X-Api-Key: your-app|0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0 ``` As chaves de API pertencem a **aplicações**, que o administrador da instância cria em **Sys Admin** → **Aplicações**, escolhendo a organização e os **Papéis** da aplicação. Para obter uma chave, peça ao administrador da instância. Cada chave funciona apenas na organização da sua aplicação: ela só vê e cria documentos dessa organização. A chave é exibida uma única vez, na criação; por isso, guarde-a num gerenciador de segredos. Sem chave, ou com uma chave inválida, a resposta é `401`. Se os papéis da chave não tiverem permissão para a operação, a resposta é `403`. ### Permissões O que uma aplicação pode fazer depende dos papéis dela: | Papel | Pode | |---|---| | **Administrador** | Tudo na organização, inclusive alterar as configurações, o webhook e as aplicações dela. | | **Gerente** | Tudo na organização, exceto alterar as configurações, o webhook e as aplicações dela. | | **Operador** | Criar e atualizar documentos, lotes, modelos e fluxos. Não pode anular diplomas, substituir representações visuais, excluir modelos e fluxos nem gerenciar instituições. | | **Monitor** | Apenas consultar. | Os papéis **Integração de Emissão** e **Integração de Registro** são criados automaticamente para a integração entre duas instâncias do Digiploma; não os atribua às suas aplicações. ## Convenções * Os nomes das propriedades JSON estão em camelCase. Os dados do MEC mantêm os nomes em português do schema XML (XSD) do MEC, como `dadosDiploma` e `iesEmissora`. * As enumerações são escritas pelo nome, como `"Active"`. * Os ids são GUIDs. As datas estão no formato ISO 8601; as datas lidas do banco de dados voltam em UTC. * As mensagens de erro estão em português. ### Paginação As operações que listam itens aceitam estes parâmetros na query string: | Parâmetro | Descrição | |---|---| | `Q` | Texto a pesquisar. Onde ele é procurado depende da operação. | | `Limit` | Quantidade de itens a retornar. Padrão: 10. | | `Offset` | Quantidade de itens a pular (não é um número de página). Padrão: 0. | | `Order` | `Asc` (padrão) ou `Desc`. O campo usado na ordenação depende da operação. | A resposta traz os itens da página e o total de itens encontrados: ```json { "items": [ … ], "totalCount": 1234, "nextCursor": null } ``` `nextCursor` não é usado: pagine com `Offset`. ### Uploads As operações que recebem um arquivo, como o arquivo de um lote ou um modelo, fazem referência a um **upload**: primeiro envie o arquivo, depois use o `id` do upload. Há duas formas de enviá-lo: * `POST /api/uploads`, como `multipart/form-data`, com o arquivo numa parte chamada `file` e o tipo dele num campo de texto chamado `contentType` (e, opcionalmente, o nome em `name`): ```bash curl -X POST https://www.digiploma.com.br/api/uploads -H "X-Api-Key: $API_KEY" \ -F "file=@formandos.json" -F "contentType=application/json" -F "name=formandos.json" ``` A resposta é `{ "id": "…", "name": "formandos.json", "contentType": "application/json", "location": "…" }`. * `POST /api/uploads/bytes`, como JSON, com o arquivo em Base64: `{ "bytes": "…" }`. A resposta é `{ "id": "…", "size": …, "digest": "…" }`. Depois, faça referência ao upload pelo `id`, pelo `name` e pelo `contentType` (obrigatórios), como em: ```json "batchFile": { "id": "5d3b…", "name": "formandos.json", "contentType": "application/json" } ``` Use o upload logo em seguida: os arquivos enviados podem ser excluídos depois de um dia. Os tipos aceitos incluem PDF (`application/pdf`), XML (`application/xml`, `text/xml`), JSON (`application/json`), CSV (`text/csv`) e imagens; quando você envia `name`, a extensão precisa corresponder ao tipo. ### Downloads e tickets A maioria dos arquivos pode ser baixada de três formas: | Operação | Retorna | |---|---| | `…/xml`, por exemplo | O próprio arquivo. | | `…/xml-b64` | Um JSON com o arquivo em Base64: `{ "bytes": "…", "name": "…", "contentType": "…" }`. | | `…/xml-ticket` | Um **ticket**: `{ "location": "…", "filename": "…" }`. | O `location` de um ticket é um endereço temporário para baixar o arquivo **sem a chave de API**, por exemplo para repassar a um navegador. Ele pode ser um caminho relativo à instância, como `/api/degrees/…/xml/file?access_ticket=…`: nesse caso, acrescente o endereço da instância antes dele. Os tickets expiram em pouco tempo (cerca de uma hora); por isso, obtenha o ticket logo antes do download. Condições como "o documento precisa estar assinado" são verificadas no download do arquivo, não quando o ticket é gerado. ## Resultado da criação As operações que criam um único documento (`POST /api/degrees`, `/api/emissions`, `/api/academic-transcripts` e `/api/curriculums`) e `POST /api/emissions/{id}/degree-xml` informam problemas de duas formas: * Problemas encontrados **antes** da geração do documento, como um modelo ausente, um fluxo inválido ou a falta da chave do Signer, retornam um código de status de erro, como em qualquer outra operação. * Problemas encontrados **durante** a geração, como dados rejeitados pelo XSD do MEC, uma duplicidade ou um erro no Signer, retornam **HTTP 200** com `"success": false` e uma descrição em `errors`. ```json { "success": false, "id": null, "errors": "2026-10-11 14:02:11.532 -03:00 … Erro: …" } ``` Sempre verifique `success`. `errors` é um log de processamento em português, feito para pessoas lerem, não para ser interpretado por código. ## Erros | Status | Significado | |---|---| | `400` | A requisição está malformada; por exemplo, falta um campo obrigatório. O corpo lista os campos inválidos em `errors`. | | `401` | A chave de API está ausente ou é inválida. | | `403` | A chave de API não pode executar esta operação ou acessar este item. | | `422` | A requisição viola uma regra de negócio **ou faz referência a um item que não existe**. O corpo é um `ErrorModel`. | ```json { "code": "DegreeNotFound", "message": "Diploma não encontrado", "details": { "id": "9b0f…" } } ``` `code` identifica o erro; `message`, em português, é destinada a pessoas e pode mudar; `details` traz dados sobre o erro, quando houver. Trate os erros pelo `code`. Os códigos estão listados na referência da API (`ErrorCodes`), e novos códigos podem ser acrescentados. Os mais comuns: | Código | Significado | |---|---| | `…NotFound` (como `DegreeNotFound`, `TemplateNotFound`) | O item não existe. | | `SubscriptionOperationNotAllowed` | O tipo da organização não permite a operação. | | `SignerApiKeyNotSet`, `SignerApiKeyError` | A organização não tem chave de API do Signer, ou o Digiploma não conseguiu acessar o Signer com ela. | | `TemplateTypeNotExpected` | O modelo é de outro tipo de documento. | | `DocumentFlow…` | O fluxo de assinatura viola as regras do seu tipo. Veja [Fluxos de assinatura](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#fluxos-de-assinatura). | | `ValidationCodeDuplicated` | Outro documento, que não foi anulado nem cancelado, tem o mesmo código de validação. | | `…NotValid`, `…NotSigned` | O documento não está ativo, ou ainda não foi assinado. | | `…InvalidStatus`, `…CannotBe…` | A operação não é permitida no status atual do item. | | `InvalidCaptcha`, `InvalidOperationCaptchaEnabled` | Veja [Validação pública](https://docs.lacunasoftware.com/articles/digiploma/api/validation#captcha). |