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. Estas páginas explicam como as operações se combinam. Os exemplos usam https://www.digiploma.com.br; numa instância 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
Emite diplomas que outra instituição registra	Emissora	Apenas emissão
Registra diplomas emitidos por outras instituições	Registradora	Apenas registro

As emissoras também podem criar históricos escolares e currículos. Em todos os casos, você vai usar modelos e fluxos de assinatura e, provavelmente, lotes e webhooks. As registradoras também publicam as listas de diplomas anulados, e as instituições geram arquivos de fiscalização para o MEC. Qualquer pessoa pode validar um documento. 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.

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, que não precisam de chave:

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:

{ "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):

  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:

"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.

{ "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.

{ "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.
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.