Arquivos de fiscalização

Quando o MEC supervisiona uma instituição, a instituição fornece um arquivo de fiscalização: um arquivo XML assinado, no layout ArquivoFiscalizacao do MEC, com os diplomas que ela emitiu ou registrou num período. O Digiploma gera e assina esse arquivo sob demanda, para uma instituição.

Há dois tipos de arquivo:

type	Conteúdo de cada entrada de diploma
Issuer	Código de validação, CPF do diplomado, código e-MEC do curso, datas de emissão e de registro, e as URLs do XML do diploma e do RVDD (e, opcionalmente, do XML da documentação acadêmica).
Registry	Código de validação, CPF do diplomado, códigos e-MEC da emissora e do curso, dados do livro de registro e id da documentação acadêmica.

Criar um arquivo de fiscalização

POST /api/inspection-files exige a permissão CreateInspectionFile:

{ "type": "Issuer", "iesCode": 1234, "startDate": "2026-01-01T00:00:00-03:00", "endDate": "2026-06-30T23:59:59-03:00", "includeAcademicRegistryUrl": false }

Campo	Obrigatório	Descrição
type	Sim	Issuer ou Registry. Precisa corresponder ao tipo da instituição (InspectionTypeUnavailableForThisOrganization).
iesCode	Sim	O código MEC da instituição.
startDate, endDate	Sim	O período. endDate não pode ser anterior a startDate (EndDateMustBeGreaterOrEqual).
includeAcademicRegistryUrl	Não	Só para Issuer: inclui também a URL do XML da documentação acadêmica, quando o MEC solicitar.

O período seleciona os diplomas, com os dois arquivos XML assinados, cuja última atualização esteja dentro dele, com startDate e endDate inclusive.

A geração é assíncrona: a chamada retorna o arquivo com status Started. Acompanhe a geração com GET /api/inspection-files/{id} ou com os webhooks descritos abaixo.

As URLs de um arquivo Issuer são links para baixar os arquivos de cada diploma sem autenticação. Por padrão, elas expiram depois de 14 dias; por isso, gere o arquivo quando o MEC o solicitar.

Status

status	Significado
Started	Em geração.
Created	Gerado e aguardando a assinatura no Signer (assinatura manual).
Signed	Assinado e pronto para download.
Error	A geração falhou. errorReason informa o motivo.

A geração falha com EmptyInspectionFile quando nenhum diploma se enquadra no período. Ela também pode falhar com UnavailableEmissionAndRegistrationDates ou UnavailableRegistrationBook quando alguns diplomas ainda não têm as suas entradas no livro de registro: nesse caso, o Digiploma agenda a criação dessas entradas, e você deve solicitar um novo arquivo algumas horas depois.

O arquivo é assinado da mesma forma que as listas de diplomas anulados: automaticamente, com o certificado e-CNPJ da instituição, ou manualmente, no Lacuna Signer, de acordo com as configurações da instituição.

Operações

Operação	Descrição
POST /api/inspection-files	Criar um arquivo de fiscalização.
GET /api/inspection-files?InstituteId={id} ou ?IesCode={code}	Uma página dos arquivos de fiscalização da instituição, ordenados pela data de atualização. Um dos dois filtros é obrigatório (InstituteFilterRequired).
GET /api/inspection-files/{id}	Um arquivo de fiscalização.
GET /api/inspection-files/{id}/xml-ticket	Um ticket para baixar o XML. Falha com InspectionFileGenerationNotConcluded enquanto o arquivo está Started.

Um arquivo de fiscalização tem id, iesCode, iesName, type, startDate, endDate, status, errorReason, creationDate, updateDate e, na assinatura manual, signerDocumentId e signerDocumentUrl.

Webhooks

Evento	Quando
InspectionFileCreated	O arquivo foi gerado e enviado para o Signer (assinatura manual).
InspectionFileSigned	O arquivo foi assinado.
InspectionFileGenerationError	A geração falhou. details traz o motivo.

Os dados do evento também trazem o número de diplomas do arquivo (inspectedDegreesNumber). Não dependa dos eventos InspectionFileStarted e InspectionFileGenerated, que aparecem na referência da API: eles não marcam o início e o fim da geração. Veja Webhooks.