Integra Contador: MIT

Endpoints da WebApiAlcance para o MIT - Módulo de Inclusão de Tributos da integração Serpro Integra Contador. O MIT é o módulo em que o contribuinte informa e encerra a apuração de tributos (a "confissão" que alimenta a DCTFWeb). Estes endpoints cobrem o encerramento de uma apuração, a consulta da situação desse encerramento, a consulta de uma apuração específica e a listagem de apurações de um período.

Todas as rotas são um proxy autenticado sobre a API do Serpro: a WebApi valida o payload, injeta o contratante e o autor (fixos via .env), repassa a chamada ao Serpro e devolve a resposta dentro do envelope padrão da plataforma.

Base path

/api/v1/integra-contador/mit

O router mit é montado sob o prefixo /integra-contador/mit da integração Serpro. Todos os endpoints usam o método POST e recebem o mesmo envelope de entrada (dados + contribuinte).

Escopos necessários

• integra_contador:write - todos os endpoints MIT

Atenção: a ação do escopo é derivada do método HTTP, não da semântica da operação. Como todos os endpoints MIT são POST (inclusive as consultas), todos exigem integra_contador:write - não basta integra_contador:read. O recurso integra_contador vem do 1º segmento da rota e é compartilhado com SN, DCTFWeb e Radar.

Envelope

Toda requisição carrega apenas dois campos de topo (OnlyContribuintePayload):

{
  "dados": { },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

• dados - objeto com os campos específicos de cada endpoint (validados por schema; erro de validação retorna 422 com hint e example).
• contribuinte - identificação da parte (tipo: 2 = CNPJ; numero: somente dígitos). Os campos contratante e autor não são enviados pelo cliente - são fixos via .env.

Toda resposta segue o envelope padrão:

{ "success": true, "message": "...", "data": { } }

Endpoints

POST /integra-contador/mit/encerrar-apuracao

Encerra a apuração do MIT para o período informado. É a operação que efetiva (confessa) os tributos apurados no mês/ano, disparando o processamento no Serpro via MITService.encerrar_apuracao.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição, no envelope OnlyContribuintePayload (dados + contribuinte). O campo dados é validado por MITEncerrarApuracaoDados, com anoApuracao e mesApuracao obrigatórios.

Request

{
  "dados": { "anoApuracao": 2025, "mesApuracao": 8 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Apuração encerrada com sucesso!",
  "data": {
    "idApuracao": "abc123-uuid",
    "anoApuracao": 2025,
    "mesApuracao": 8,
    "situacaoApuracao": 3
  }
}

Escopo: integra_contador:write

POST /integra-contador/mit/situacao-encerramento

Consulta a situação do encerramento de uma apuração - usado para acompanhar o processamento após um encerrar-apuracao. Encaminha para MITService.consultar_situacao_encerramento.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição, no envelope OnlyContribuintePayload (dados + contribuinte). O campo dados é validado por MITSituacaoEncerramentoDados, com anoApuracao e mesApuracao obrigatórios.

Request

{
  "dados": { "anoApuracao": 2025, "mesApuracao": 8 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Situação do encerramento recuperada com sucesso!",
  "data": {
    "anoApuracao": 2025,
    "mesApuracao": 8,
    "situacaoApuracao": 3,
    "situacaoEncerramento": "Encerrada"
  }
}

Escopo: integra_contador:write

POST /integra-contador/mit/consultar-apuracao

Consulta os detalhes de uma apuração específica pelo seu identificador (idApuracao). Encaminha para MITService.consultar_apuracao.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição, no envelope OnlyContribuintePayload (dados + contribuinte). O campo dados é validado por MITConsultarApuracaoDados, com idApuracao obrigatório.

Request

{
  "dados": { "idApuracao": "abc123-uuid" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Apuração recuperada com sucesso!",
  "data": {
    "idApuracao": "abc123-uuid",
    "anoApuracao": 2025,
    "mesApuracao": 8,
    "situacaoApuracao": 3
  }
}

Escopo: integra_contador:write

POST /integra-contador/mit/listar-apuracoes

Lista as apurações do MIT para um ano, com filtros opcionais por mês e situação. Encaminha para MITService.listar_apuracoes.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição, no envelope OnlyContribuintePayload (dados + contribuinte). O campo dados é validado por MITListarApuracoesDados: anoApuracao é obrigatório; mesApuracao e situacaoApuracao são opcionais.

Request

{
  "dados": { "anoApuracao": 2025, "mesApuracao": 8, "situacaoApuracao": 3 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Apurações recuperadas com sucesso!",
  "data": [
    {
      "idApuracao": "abc123-uuid",
      "anoApuracao": 2025,
      "mesApuracao": 8,
      "situacaoApuracao": 3
    }
  ]
}

Escopo: integra_contador:write

Schemas

MITEncerrarApuracaoDados

MITSituacaoEncerramentoDados

MITConsultarApuracaoDados

MITListarApuracoesDados

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• Erros de validação do campo dados retornam 422 Unprocessable Entity com detail contendo errors, um hint sobre os campos obrigatórios ausentes e um example de payload válido.
• O contribuinte é a única identificação enviada pelo cliente; contratante e autor da chamada ao Serpro são fixos via .env e injetados pela WebApi.
• O escopo integra_contador é compartilhado com Integra Contador: SN, Integra Contador: DCTFWeb e Radar - não existe escopo dedicado ao MIT.
• O MIT alimenta a apuração usada pela DCTFWeb: após encerrar-apuracao, acompanhe o processamento com situacao-encerramento.