Institutions

An institution (instituição) is a higher education institution (IES) registered in the organization, identified by its MEC code. The institutions are what the lists of annulled diplomas and the inspection files are produced for, and each one says how those documents, called supporting documents (documentos auxiliares), are signed.

Create an institution

POST /api/institutes requires the Administrador or Gerente role:

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

Field	Description
type	Required. Issuer (Emissora), Registry (Registradora) or IssuerRegistry (Emissora e Registradora). Only institutions that register diplomas have lists of annulled diplomas.
issuerData	For Issuer: the institution's data, as in iesEmissora (name, MEC code, CNPJ, address, accreditation acts and the maintaining entity).
registryData	For Registry and IssuerRegistry: the institution's data, as in iesRegistradora. When omitted, the registrar data saved in the organization's Configurações is used.
supportingDocSignatureMode	Required. How the supporting documents are signed: Automatic or Manual.
uploadedCertificate	For Automatic: the institution's e-CNPJ certificate, ICP-Brasil, as a PKCS#12 file (.pfx) uploaded with contentType application/x-pkcs12, and its password. Digiploma signs the documents with it (CertificateIsInvalid if it is not valid). The uploaded file is deleted afterwards.
supportingDocSigner	For Manual: one signature rule, with isCompany: true and requiredSignatures 1, with the person who signs the documents in Lacuna Signer with the institution's e-CNPJ. See Signature flows.

The MEC code must be unique in the instance (InstituteCodeAlreadyExists). The response has no body: to get the new institution's id, search it by its MEC code with GET /api/institutes?Q={code}. For a registering institution, the first list of annulled diplomas is generated right away.

Other operations

Operation	Description
GET /api/institutes	A page of the organization's institutions, sorted by MEC code. Q matches the MEC code or the name.
GET /api/institutes/{id}	An institution, with its data, its signing mode and certificate or signer, the sequence number of its latest list of annulled diplomas and the date of the next one, and its webhook settings.
PUT /api/institutes/{id}	Changes the institution's type and data (issuerData or registryData, as for creation). The signing mode and the certificate are changed in the web application; the webhook, with the operation below.
POST /api/institutes/{id}/integrations	Configures the institution's webhook (see below).
GET /api/institutes/{id}/events	The institution's events, newest first: creation and changes, and the generation of its lists and inspection files, each with type, date and details.

Institution webhook

The events of the lists of annulled diplomas and of the inspection files go to the institution's webhook:

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

With shouldUseSubscriptionWebhookSettings true, they go to the organization's webhook instead. With neither, they are not sent. See Webhooks.