Guia de Migração: Matrículas e Movimentações de matrículas — Service Layer V1 → V2

Público: integradores, equipes de conversão de dados e desenvolvedores que consomem o Service Layer de Educação.

1. Visão Geral

O que foi migrado

Os seguintes recursos do Service Layer V1 ( api-educacao-service ) foram migrados para o V2 (api-service-layer).

Recurso V2	Equivalente V1	Operações V2
`matricula`	`MatriculaConvertService → /api/matriculas`	GET, POST, PUT, DELETE
`matricula-atividade`	Conversão de matrícula atividade	GET, POST, PUT, DELETE
`matricula-eja-modular`	`MatriculaEjaModularConvertService`	GET, POST, PUT, DELETE
`matricula-movimentacao`	`MatriculaMovimentacaoConversaoService` + serviços de movimentação	GET, POST (somente inserção — sem PUT/DELETE no V2)

Movimentações passivas unificadas (6 tipos): CANCELAMENTO, TRANSFERENCIA, DEIXOU_DE_FREQUENTAR, FALECIMENTO, READMISSAO, RECLASSIFICACAO — todas via POST /v2/api/matricula-movimentacao com campo discriminador tipo .

Status da descontinuação do V1

O V2 está disponível e validado para os recursos acima. O V1 ( /conversao/api/... ) permanece em operação até comunicado formal de descontinuação (avisaremos com antecedência a data em que ele será desligado).

Importante: Integradores priorizarem a migração para a V2 em novas integrações e adapte integrações existentes conforme este guia.

2. Service Layer: matricula (matrícula padrão)

Endpoints

Operação	V1 (deprecado)	V2 (usar)
Listar	`GET /conversao/api/matriculas`	`GET /service-layer/v2/api/matricula`
Consultar	-	`GET /service-layer/v2/api/matricula/{id}`
Criar	`POST /conversao/api/matriculas`	`POST /service-layer/v2/api/matricula`
Atualizar	`PUT /conversao/api/matriculas`	`PUT /service-layer/v2/api/matricula`
Remover	`DELETE /conversao/api/matriculas` ou `PUT .../remover`	`DELETE /service-layer/v2/api/matricula`

Schema Swagger V2: MatriculaVagaEtapa (campo vaga obrigatório).

Regras de negócio

Regra	Descrição
R01	`aluno` obrigatório
R02	`tipo` obrigatório — valores: `EDUCACAO_BASICA, COMPLEMENTAR, AEE, ATIVIDADE_COMPLEMENTAR, PROGRESSAO_PARCIAL, ACELERACAO, EJA`
R03	`situacao` obrigatória
MVE-VAGA	`vaga` obrigatória — V2 persiste em `matriculas + matriculas_vagas_etapas`

Regra	Descrição
Auto-enturmação	Se `turma` informada e não há enturmação ativa: cria enturmação, incrementa `turmas.qtd_alunos` , situação → `CURSANDO`
Saldos de vaga	Se situação requer vaga: ocupa `saldos_vagas` no POST; libera no DELETE
Multiturno	Se `turno = INTEGRAL` e `turnoFrequenta` informado: ocupa saldo multiturno
DELETE	Remove movimentações, reclassificações, itens de rematrícula, avaliações sem nota, enturmações; ajusta saldos

Diferenças de contrato V1 → V2

Campo / comportamento	V1	V2
Polimorfismo `type`	`MATRICULA_VAGA_ETAPA`, `MATRICULA_DISCIPLINA`, etc.	Ignorado — V2 usa sempre `MatriculaVagaEtapa`
Campo `vaga`	Opcional em alguns fluxos V1	Obrigatório
Wrapper do payload	`{ "matricula": { ... } }` em alguns endpoints	Campos flat em `conteudo`
Retorno do lote	Podia incluir `idEnturmacao`	Apenas `idGerado` da matrícula
`PUT`	Reprocessa efeitos via `persistInNewTransaction`	Atualização direta — não reprocessa auto-enturmação/saldos automaticamente

Impactos para integradores

Incluir vaga em toda criação de matrícula padrão — sem vaga, a matrícula pode não aparecer corretamente na UI.
Remover dependência do campo type polimórfico do V1.
Não depender de idEnturmacao no retorno do lote — buscar enturmação via consulta ou outro endpoint.
Cuidado com PUT: alterar turma ou situação via PUT pode não reproduzir todos os efeitos colaterais do V1; preferir fluxos explícitos de movimentação quando a situação mudar.

Exemplos HTTP

POST — Criar matrícula

Request V2:

 POST {BASE_URL}/service-layer/v2/api/matricula
 Authorization: Bearer {token}
 Content-Type: application/json

 [
   {
     "idIntegracao": "mat-post-001",
     "conteudo": {
      "aluno": { "id": "{idAluno}" },
     "anoLetivo": { "id": "{idAnoLetivo}" },
     "estabelecimento": { "id": "{idEstabelecimento}" },
     "vaga": { "id": "{idVaga}" },
     "tipo": "EDUCACAO_BASICA",
     "situacao": "MATRICULADO",
     "turno": "MATUTINO",
     "data": "2025-02-20"
     }
   }
 ]

Response (lote enfileirado):

{ "id": "lote-mongo-id", "situacao": "AGUARDANDO_EXECUCAO" }

Equivalente V1 (deprecado):

POST {BASE_URL}/conversao/api/matriculas

 {
   "idIntegracao": "mat-post-001",
    "matricula": {
    "type": "MATRICULA_VAGA_ETAPA",
    "aluno": { "id": "{idAluno}" },
    "anoLetivo": { "id": "{idAnoLetivo}" },
    "estabelecimento": { "id": "{idEstabelecimento}" },
    "tipo": "EDUCACAO_BASICA",
    "situacao": "MATRICULADO",
    "turno": "MATUTINO",
    "data": "2025-02-20"
   }
 }

O que mudou	Detalhe
Envelope	Objeto → array; `matricula` → `conteudo`
`vaga`	Agora obrigatório no V2
`type`	Remover — ignorado no V2

POST — Criar matrícula com turma (auto-enturmação)

Adicionar ao conteudo:

 "turma": { "id": "{idTurma}" }

Efeitos: enturmação criada, turmas.qtd_alunos incrementado, situação → CURSANDO, saldos de turma atualizados (cenários SV-01 a SV-06 nos testes).

GET — Consultar matrícula

 GET {BASE_URL}/service-layer/v2/api/matricula/{id}

Response (campos principais):

  {
     "id": 450999001,
     "aluno": { "id": 123 },
     "anoLetivo": { "id": 456 },
     "estabelecimento": { "id": 789 },
      "vaga": { "id": 101 },
      "tipo": "EDUCACAO_BASICA",
     "situacao": "MATRICULADO",
     "turno": "MATUTINO",
     "data": "2025-02-20",
     "observacao": null
  }

PUT — Atualizar observação

      PUT {BASE_URL}/service-layer/v2/api/matricula

 [
    {
         "idIntegracao": "mat-put-001",
         "conteudo": {
         "id": 450999001,
         "aluno": { "id": "{idAluno}" },
         "anoLetivo": { "id": "{idAnoLetivo}" },
         "estabelecimento": { "id": "{idEstabelecimento}" },
         "vaga": { "id": "{idVaga}" },
          "tipo": "EDUCACAO_BASICA",
         "situacao": "MATRICULADO",
         "turno": "MATUTINO",
         "data": "2025-02-20",
         "observacao": "Texto atualizado via PUT"
       }
     }
  ]

Limitação conhecida: PUT cobre atualização de campos simples; não garante reprocessamento de enturmação/saldos como o V1.

DELETE — Remover matrícula

 DELETE {BASE_URL}/service-layer/v2/api/matricula

 [
   {
     "idIntegracao": "mat-del-001",
     "conteudo": { "id": 450999001 }
   }
 ]

Efeitos (MVE-DEL): remove registros em matriculas e matriculas_vagas_etapas ; libera saldos de vaga/turma/multiturno; remove enturmações e dependências.

POST — Negativo: sem vaga (MVE-VAGA) Omitir vaga do conteudo → lote finaliza com erro de validação.

3. Service Layer: matricula-atividade

Operação	V2
Listar / Consultar	`GET /v2/api/matricula-atividade, GET /v2/api/matricula-atividade/{id}`
Criar	`POST /v2/api/matricula-atividade`
Atualizar	`PUT /v2/api/matricula-atividade`
Remover	`DELETE /v2/api/matricula-atividade`

Regras de negócio

Regra	Descrição
R02	`atividade` obrigatória — referência à atividade complementar vinculada à turma
R04	`tipo` deve ser `AEE` ou `ATIVIDADE_COMPLEMENTAR`
Auto-enturmação	Com `turma` informada: cria enturmação na turma de atividade
CRUD completo	Todas as operações disponíveis no V2

Diferenças V1 → V2

Payload flat em conteudo (sem wrapper matricula).
Mesmo padrão de lote assíncrono do V2.

Exemplo POST

      POST {BASE_URL}/service-layer/v2/api/matricula-atividade

   [
     {
         "idIntegracao": "mat-atividade-001",
         "conteudo": {
         "aluno": { "id": "{idAluno}" },
         "anoLetivo": { "id": "{idAnoLetivo}" },
         "estabelecimento": { "id": "{idEstabelecimento}" },
         "atividade": { "id": "{idAtividade}" },
         "turma": { "id": "{idTurmaAtividade}" },
         "tipo": "ATIVIDADE_COMPLEMENTAR",
         "situacao": "MATRICULADO",
         "turno": "MATUTINO",
         "data": "2025-02-20"
     }
    }
   ]

Exemplo DELETE

 DELETE {BASE_URL}/service-layer/v2/api/matricula-atividade

 [
   {
      "idIntegracao": "mat-atividade-del-001",
       "conteudo": { "id": "{idMatriculaAtividade}" }
   }
 ]

4. Service Layer: matricula-eja-modular

Endpoints

Operação	V1	V2
CRUD	`POST/PUT/DELETE /conversao/api/matricula-eja-modular`	`POST/PUT/DELETE /v2/api/matricula-eja-modular`

Regras de negócio

Regra	Descrição
Agregado pai/filho	Cria/atualiza `Matricula` (pai, tipo EJA) + `MatriculaDisciplina` (filho)
R03/R04	Situações `MOVIMENTADO` e `RECLASSIFICADO` rejeitadas no create/update
R06	`aluno` obrigatório
R07	`disciplina` obrigatória
Default	`tipo = EJA, situacao = MATRICULADO` se nula
Enturmação	Auto-enturmação após persistência; PUT com nova `turma` reconcilia enturmação
DELETE parcial	Se pai tem múltiplos filhos: remove só a disciplina (R08 / MVEJA-DEL-02)
DELETE total	Se pai tem um único filho: remove agregado completo (MVEJA-DEL-01)
Multiturno	Com `turno = INTEGRAL`: ocupa `turmas_saldos` conforme turno da matrícula

Diferenças V1 → V2

Aspecto	V1	V2
Payload	Conversão via representation	Campos flat: aluno, disciplina, turno, turma, pai?
Wrapper	Podia usar estrutura aninhada	Sem wrapper matricula

Exemplo POST

  POST {BASE_URL}/service-layer/v2/api/matricula-eja-modular

  [
     {
          "idIntegracao": "eja-post-001",
          "conteudo": {
          "aluno": { "id": "{idAluno}" },
          "anoLetivo": { "id": "{idAnoLetivo}" },
          "estabelecimento": { "id": "{idEstabelecimento}" },
          "disciplina": { "id": "{idDisciplina}" },
          "turno": "MATUTINO",
         "turma": { "id": "{idTurmaEja}" },
  "data": "2025-02-20",
  "situacao": "MATRICULADO"
      }
    }
  ]

Exemplo PUT — Trocar turma

Incluir id da matrícula filho e nova turma no conteudo; o V2 reconcilia a enturmação ativa.

5. Service Layer: matricula-movimentacao — criação de matrícula

Este endpoint permite criar matrícula já com situação alterada, incluindo movimentação ou reclassificação no mesmo lote — contrato herdado do V1 (MatriculaConversaoRepresentation.COMPLETO).

Endpoints

Operação	V1	V2
Criar matrícula + movimentação	POST /conversao/api/matricula-movimentacao	POST /v2/api/matricula-movimentacao
Remover matrícula criada via movimentação	DELETE /conversao/api/matricula-movimentacao	DELETE /v2/api/matricula (usar service matricula)

Operações V2 em matricula-movimentacao: apenas GET e POST (LoteType restrito a INSERIR). Movimentações passivas em matrícula existente também usam POST neste endpoint.

Nota: o Swagger V2 não expõe DELETE em matricula-movimentacao. Para remover matrículas, usar DELETE /v2/api/matricula.

Estrutura do payload (wrapper preservado)

 [
     {
         "idIntegracao": "mat-mov-001",
         "conteudo": {
         "matricula": {
          "aluno": { "id": "{idAluno}" },
         "anoLetivo": { "id": "{idAnoLetivo}" },
         "estabelecimento": { "id": "{idEstabelecimento}" },
         "tipo": "EDUCACAO_BASICA",
         "situacao": "CURSANDO",
         "data": "2025-02-20"
       },
       "turma": { "id": "{idTurma}" },
       "movimentacao": {
         "tipo": "TRANSFERENCIA",
         "motivo": { "id": "{idMotivo}" },
         "data": "2025-03-01",
         "estabelecimentoDestino": { "id": "{idEstabDestino}" }
     }
   }
  }
 ]

Regras de negócio

Regra	Descrição
R04	Situação default `MATRICULADO` se nula em novo registro
R05	Situações "simples" não exigem movimentação: `APROVADO`, `APROVADO_CONSELHO`, `APROVADO_DEPENDENCIA`, `EM_EXAME`, `REPROVADO`, `REPROVADO_FREQUENCIA`, `CURSANDO`
R03	Situações alteradoras (`TRANSFERIDO`, `CANCELAMENTO`, etc.) exigem `movimentacao` ou `reclassificacao`
R02	Turma obrigatória para situação alteradora (exceto EJA modular)
R01	Tipo do `motivo` deve coincidir com o tipo da movimentação (exceto `FALECIMENTO`)
Reclassificação	Usar bloco `reclassificacao` (não `movimentacao`) com `turmaDestino`, `tipo` e `justificativa`

Exemplo — Matrícula CURSANDO sem movimentação

 {
     "matricula": {
     "aluno": { "id": "{idAluno}" },
     "anoLetivo": { "id": "{idAnoLetivo}" },
     "estabelecimento": { "id": "{idEstabelecimento}" },
     "tipo": "EDUCACAO_BASICA",
      "situacao": "CURSANDO",
     "data": "2025-02-20"
  },
  "turma": { "id": "{idTurma}" }
 }

Gap conhecido — remoção (R07)

No V1, DELETE /matricula-movimentacao removia matrícula com cascata (movimentações, avaliações, enturmações). No V2, não há DELETE em matricula-movimentacao — usar DELETE /v2/api/matricula.

6. Movimentações passivas - 6 tipos

Endpoint recomendado (unificado)

   POST {BASE_URL}/service-layer/v2/api/matricula-movimentacao

Discriminador: campo tipo no conteudo.

Atenção: o Swagger lista REMANEJAMENTO_INTERNO no enum, mas esse tipo não está implementado no MatriculaMovimentacaoProcessor — requisições com esse valor falharão em runtime.

Campos comuns a todos os tipos

Campo	Obrigatório	Descrição
`tipo`	Sim	Discriminador da movimentação
`matricula`	Sim	`{ "id": N }` — matrícula existente
`anoLetivo`	Recomendado	`{ "id": N }`
`estabelecimento`	Recomendado	`{ "id": N }`
`data`	Recomendado	Data da movimentação (`YYYY-MM-DD`)
`observacoes`	Não	Texto livre
`motivo`	Conforme tipo	`{ "id": N }` — não se aplica a `FALECIMENTO` e `RECLASSIFICACAO`

Importante: situacaoMatricula não deve ser enviado — o servidor define com base no tipo.

Cancelamento

Aspecto	Valor
Situação resultante	`CANCELAMENTO`
Campos extras	`motivo`

Aspecto	Valor
Efeitos	Desenturmação (`enturmacoes.dt_fim`), saldos turma/vaga, histórico, tabela `cancelamentos`

Exemplo:

 [
   {
       "idIntegracao": "cancel-001",
        "conteudo": {
       "tipo": "CANCELAMENTO",
       "matricula": { "id": "{idMatricula}" },
       "anoLetivo": { "id": "{idAnoLetivo}" },
       "estabelecimento": { "id": "{idEstabelecimento}" },
       "motivo": { "id": "{idMotivoCancelamento}" },
       "data": "2025-03-10",
       "observacoes": "Cancelamento via V2"
    }
  }
 ]   

Transferência

Aspecto	Valor
Situação resultante	`TRANSFERIDO`
Campos extras	`motivo`, `estabelecimentoDestino`, `nomeEstabelecimentoDestino`, `municipio`
Efeitos	Tabela `transferencias`, desenturmação, saldos, histórico

Exemplo:

 {
      "tipo": "TRANSFERENCIA",
      "matricula": { "id": "{idMatricula}" },
      "anoLetivo": { "id": "{idAnoLetivo}" },
      "estabelecimento": { "id": "{idEstabelecimento}" },
      "motivo": { "id": "{idMotivoTransferencia}" },
      "estabelecimentoDestino": { "id": "{idEstabDestino}" },
      "nomeEstabelecimentoDestino": "ESCOLA DESTINO",
      "data": "2025-03-15"
  }

Deixou de frequentar

Aspecto	Valor
Situação resultante	`DEIXOU_FREQUENTAR`
Campos extras	`motivo`
Atenção ao enum	Usar `DEIXOU_DE_FREQUENTAR` no campo `tipo` — não `DEIXOU_FREQUENTAR`

Exemplo:

 {
     "tipo": "DEIXOU_DE_FREQUENTAR",
     "matricula": { "id": "{idMatricula}" },
      "motivo": { "id": "{idMotivo}" },
     "data": "2025-03-20"
 }

Falecimento

Aspecto	Valor
Situação resultante	`FALECIDO`
Campos extras	`cancelouOutrasMatriculas` (boolean, obrigatório no V1)
Efeito `cancelouOutrasMatriculas=true`	Aplica falecimento a todas as matrículas ativas do aluno no ano letivo
Efeito adicional	Atualiza `pessoas_fisicas_obito.data_obito`

Exemplo — falecimento isolado:

 {
     "tipo": "FALECIMENTO",
      "matricula": { "id": "{idMatricula}" },
      "anoLetivo": { "id": "{idAnoLetivo}" },
      "estabelecimento": { "id": "{idEstabelecimento}" },
      "data": "2025-04-05",
      "cancelouOutrasMatriculas": false
 }

Exemplo — cancelar outras matrículas do aluno:

{
      "tipo": "FALECIMENTO",
      "matricula": { "id": "{idMatricula}" },
      "data": "2025-04-05",
      "cancelouOutrasMatriculas": true
}

Readmissão

Aspecto	Valor
Situação resultante	`CURSANDO` (se havia enturmação inativa) ou `MATRICULADO`
Campos extras	`motivo` (opcional conforme cadastro)
Efeitos	Reenturmação da última enturmação elegível, reocupação de saldos

Exemplo:

{
      "tipo": "READMISSAO",
      "matricula": { "id": "{idMatricula}" },
      "anoLetivo": { "id": "{idAnoLetivo}" },
      "estabelecimento": { "id": "{idEstabelecimento}" },
      "motivo": { "id": "{idMotivo}" },
      "data": "2025-04-10"
 }

Gap READM-02: V1 rejeita readmissão em matrícula ainda ativa/enturmada; V2 pode aceitar. Validar cenário antes de migrar integrações críticas.

Reclassificação

Aspecto	Valor
Situação resultante	`RECLASSIFICADO_AVANCO` ou `RECLASSIFICADO_ACELERACAO`
Campos extras	`tipoReclassificacao` (`AVANCO` \| `ACELERACAO`), `matriculaDestino`, `nomeEstabelecimentoDestino`
Pré-condição	A matrícula de destino deve existir — criar via `POST /v2/api/matricula` antes
Sem motivo	`RECLASSIFICACAO` não utiliza `motivo` (tipo não cadastrável)

Fluxo recomendado:

POST /v2/api/matricula → obter idMatriculaDestino
POST /v2/api/matricula-movimentacao na matrícula origem

Exemplo:

  {
     "tipo": "RECLASSIFICACAO",
     "matricula": { "id": "{idMatriculaOrigem}" },
     "matriculaDestino": { "id": "{idMatriculaDestino}" },
     "tipoReclassificacao": "AVANCO",
     "anoLetivo": { "id": "{idAnoLetivo}" },
     "estabelecimento": { "id": "{idEstabelecimento}" },
     "data": "2025-05-10",
     "nomeEstabelecimentoDestino": "ESCOLA DESTINO"
   }

Fluxo comum das movimentações passivas

Recarrega matrícula (instância gerenciada JPA).
Define nova situação na matrícula.
Captura enturmações ativas → associa à movimentação (mov_enturmacoes).
Persiste movimentação + tabela filha (cancelamentos, transferencias, etc.).
Desenturma ativas (dt_fim = data da movimentação).
Libera saldos de vaga/turma/multiturno se aplicável.
Gera histórico cadastral (tp_historico = MOVIMENTACAO).
Libera saldos de vaga/turma/multiturno se aplicável.
Gera histórico cadastral (tp_historico = MOVIMENTACAO).

DELETE de movimentação

O DELETE de movimentação remove apenas o registro — não reverte situação da matrícula, enturmações ou saldos (mesmo comportamento do V1).

7. Guia prático de migração para integradores

Checklist de migração para a API V2

Mapeamento rápido V1 → V2

V1	V2
`POST /conversao/api/matriculas`	`POST /v2/api/matricula`
`POST /conversao/api/matricula-eja-modular`	`POST /v2/api/matricula-eja-modular`
`POST /conversao/api/matricula-movimentacao`	`POST /v2/api/matricula-movimentacao`

V1	V2
`POST /conversao/api/sincrona/.../movimentar`	`POST /v2/api/matricula-movimentacao`
`GET /conversao/api/lotes/{id}`	`GET /v2/api/lotes/{id}`

1. Visão Geral​

2. Service Layer: matricula (matrícula padrão)​

Regras de negócio​

Diferenças de contrato V1 → V2​

Impactos para integradores​

Exemplos HTTP​

3. Service Layer: matricula-atividade​

4. Service Layer: matricula-eja-modular​

5. Service Layer: matricula-movimentacao — criação de matrícula​

6. Movimentações passivas - 6 tipos​

Cancelamento​

Transferência​

Deixou de frequentar​

Falecimento​

Readmissão​

Reclassificação​

7. Guia prático de migração para integradores​

Checklist de migração para a API V2​

1. Visão Geral

2. Service Layer: matricula (matrícula padrão)

Regras de negócio

Diferenças de contrato V1 → V2

Impactos para integradores

Exemplos HTTP

3. Service Layer: matricula-atividade

4. Service Layer: matricula-eja-modular

5. Service Layer: matricula-movimentacao — criação de matrícula

6. Movimentações passivas - 6 tipos

Cancelamento

Transferência

Deixou de frequentar

Falecimento

Readmissão

Reclassificação

7. Guia prático de migração para integradores

Checklist de migração para a API V2