Instituições

Uma instituição é uma instituição de ensino superior (IES) cadastrada na organização e identificada pelo código MEC. É para as instituições que são produzidas as listas de diplomas anulados e os arquivos de fiscalização, e cada instituição define como esses documentos, chamados de documentos auxiliares, são assinados.

Criar uma instituição

POST /api/institutes exige o papel Administrador ou Gerente:

{
  "type": "IssuerRegistry",
  "registryData": {
    "nome": "Universidade Exemplo",
    "codigoMEC": 1234,
    "cnpj": "12345678000195",
    "endereco": { … },
    "credenciamento": { … },
    "mantenedora": { … }
  },
  "supportingDocSignatureMode": "Automatic",
  "uploadedCertificate": { "uploadId": "7e2a…", "password": "…" }
}

Campo	Descrição
type	Obrigatório. Issuer (Emissora), Registry (Registradora) ou IssuerRegistry (Emissora e Registradora). Só as instituições que registram diplomas têm listas de diplomas anulados.
issuerData	Para Issuer: os dados da instituição, como em iesEmissora (nome, código MEC, CNPJ, endereço, atos de credenciamento e mantenedora).
registryData	Para Registry e IssuerRegistry: os dados da instituição, como em iesRegistradora. Se for omitido, são usados os dados da registradora salvos nas Configurações da organização.
supportingDocSignatureMode	Obrigatório. Como os documentos auxiliares são assinados: Automatic ou Manual.
uploadedCertificate	Para Automatic: o certificado e-CNPJ ICP-Brasil da instituição, num arquivo PKCS#12 (.pfx) enviado por upload com contentType application/x-pkcs12, e a senha dele. O Digiploma assina os documentos com esse certificado (CertificateIsInvalid se ele não for válido). Depois, o arquivo enviado é excluído.
supportingDocSigner	Para Manual: uma regra de assinatura, com isCompany: true e requiredSignatures 1, com a pessoa que assina os documentos no Lacuna Signer com o e-CNPJ da instituição. Veja Fluxos de assinatura.

O código MEC deve ser único na instância (InstituteCodeAlreadyExists). A resposta não tem corpo: para obter o id da nova instituição, busque-a pelo código MEC com GET /api/institutes?Q={code}. No caso de uma instituição registradora, a primeira lista de diplomas anulados é gerada imediatamente.

Outras operações

Operação	Descrição
GET /api/institutes	Uma página das instituições da organização, ordenadas pelo código MEC. Q busca pelo código MEC ou pelo nome.
GET /api/institutes/{id}	Uma instituição, com os dados dela, o modo de assinatura e o certificado ou o signatário, o número sequencial da última lista de diplomas anulados e a data da próxima, e as configurações de webhook.
PUT /api/institutes/{id}	Altera o type e os dados da instituição (issuerData ou registryData, como na criação). O modo de assinatura e o certificado são alterados na aplicação web; o webhook, com a operação abaixo.
POST /api/institutes/{id}/integrations	Configura o webhook da instituição (veja abaixo).
GET /api/institutes/{id}/events	Os eventos da instituição, dos mais recentes para os mais antigos: a criação e as alterações e a geração das listas e dos arquivos de fiscalização, cada um com type, date e details.

Webhook da instituição

Os eventos das listas de diplomas anulados e dos arquivos de fiscalização vão para o webhook da instituição:

{
  "shouldUseSubscriptionWebhookSettings": false,
  "webhook": { "enabled": true, "url": "https://example.edu.br/digiploma/webhooks", "authType": "Bearer", "token": "…" }
}

Com shouldUseSubscriptionWebhookSettings igual a true, eles vão para o webhook da organização. Se nenhum dos dois estiver configurado, os eventos não são enviados. Veja Configurar o webhook.