Pular para o conteúdo principal

Service Layer - Encerramento mensal

Documentação de Integração: Service Layer – Encerramento Mensal e Movimentações (Tributos)​

Este documento descreve os endpoints essenciais para a gestão de guias, movimentações de dívidas e o encerramento mensal de saldos. As rotas aqui descritas são o caminho oficial para integrações e migrações do sistema Desktop para a Cloud.

Acesse ao Swagger Oficial: Swagger Plataforma Betha - Service Layer Tributos

1. Regras de Negócio e Comportamento da API​

Antes de iniciar o uso dos endpoints, os técnicos devem estar cientes das seguintes regras críticas:

1- A Regra de Ouro (Movimentações): Sempre que houver qualquer alteração na situação de uma dívida ou débito através da Service Layer (ex: cancelamento, pagamento), é obrigatório gerar o registro da movimentação correspondente. Se isso não for feito, o processo de encerramento mensal não reconhecerá a alteração, e o saldo do mês seguinte começará errado.

2 - Processamento Assíncrono e em Lote: * Todos os endpoints de criação listados abaixo recebem requisições em lotes (arrays).

  • O processamento não é imediato. A API retorna o identificador de um lote (idLote), que deve ser consultado posteriormente para verificar se o processamento foi concluído com sucesso ou se houve falhas.

  1. Regra de Estorno: Em movimentações de estorno, os valores inseridos na Service Layer devem ser rigorosamente idênticos aos valores da manutenção original.

  2. Campo de Integração: Toda requisição exige o campo idIntegracao (String). Este é o seu identificador único para controle e rastreabilidade daquele registro específico.

2. Especificação dos Serviços (Endpoints)​

Abaixo estão detalhados os 5 serviços principais relacionados ao Encerramento Mensal.

2.1. Encerramento Mensal Dívidas - Receitas

  • Endpoint: POST /api/encerramentoMensalDividasReceitas
  • Objetivo: Inserção e controle dos saldos das dívidas por receita no momento do fechamento do mês.
  • Uso Principal: Ele garante que o saldo inscrito e o saldo atual por receita estejam sincronizados no fechamento.

Exemplo de Payload:

JSON

[
  {
    "idIntegracao": "MIGRA_DIV_REC_01",
    "encerramentoMensalDividasReceitas": {
      "idEncerramentoMensal": 1,
      "mesEncerramento": 1,
      "anoEncerramento": 2018,
      "dhMovimentacao": "2018-01-01 10:00:00",
      "usuarioEncerramento": "SISTEMA_MIGRA",
      "dtFinalMes": "2018-01-31",
      "idDividas": 1,
      "codigoDivida": 1,
      "anoDivida": 2018,
      "idCreditosTributarios": 1,
      "idReceitas": 1,
      "idPessoas": 1,
      "codigoPessoa": 1,
      "situacaoDivida": "ABERTO",
      "vlInscrito": 100.00,
      "vlSaldo": 100.00,
      "vlCorrecao": 0,
      "vlJuros": 0,
      "vlMulta": 0,
      "vlCorrecaoMes": 0,
      "vlJurosMes": 0,
      "vlMultaMes": 0,
      "registroHomologado": true
    }
  }
]

2.2. Encerramento Mensal Lançamento - Receita

  • Endpoint: POST /api/encerramentoMensalLancamentoReceita
  • Objetivo: Registra o saldo de um lançamento por receita no último dia do mês. Somente os movimentos de encerramento devem ser considerados para compor estes valores.

Exemplo de Payload:

[
  {
    "idIntegracao": "MIGRA_LANC_REC_01",
    "encerramentoMensalLancamentoReceita": {
      "idEncerramentoMensal": 1,
      "mesEncerramento": 1,
      "anoEncerramento": 2018,
      "dataHoraMovimentacao": "2018-01-01 10:00:00",
      "usuarioEncerramento": "SISTEMA",
      "dataFinalMes": "2018-01-31",
      "idLancamento": 1,
      "ano": 2018,
      "idCreditoTributario": 1,
      "idReceita": 1,
      "idContribuinte": 1,
      "codigoContribuinte": 1,
      "situacao": "A",
      "valorLancado": 100.00,
      "valorSaldo": 100.00,
      "valorCorrecao": 0,
      "valorJuros": 0,
      "valorMulta": 0,
      "valorCorrecaoMes": 0,
      "valorJurosMes": 0,
      "valorMultaMes": 0,
      "registroHomologado": true
    }
  }
]

2.3. Movimentação de Dívidas - Receitas

  • Endpoint: POST /api/dividasMovtosReceitas
  • Objetivo: Estabelece a relação detalhada entre as movimentações que ocorreram em uma dívida e as receitas envolvidas.

Exemplo de Payload:

[
  {
    "idIntegracao": "MOV_DIV_REC_01",
    "dividasMovtosReceitas": {
      "idDividasMovtos": 1,
      "mesEncerramento": 1,
      "anoEncerramento": 2018,
      "dtEfeito": "2018-01-01",
      "dhMovimentacao": "2018-01-01 10:00:00",
      "idDividas": 1,
      "codigoDivida": 1,
      "anoDivida": 2018,
      "idCreditosTributarios": 1,
      "idReceitas": 1,
      "idPessoas": 1,
      "codigoPessoa": 1,
      "situacaoDivida": "ABERTO",
      "vlInscrito": 100.00,
      "vlSaldo": 100.00,
      "vlCorrecao": 0,
      "vlJuros": 0,
      "vlMulta": 0,
      "vlTributoMovto": 100.00,
      "vlCorrecaoMovto": 0,
      "vlJurosMovto": 0,
      "vlMultaMovto": 0,
      "idHomologManutencao": "1"
    }
  }
]

2.4. Movimentação de Guias

  • Endpoint: POST /api/guiasMovtos
  • Objetivo: Registra uma movimentação sobre débitos/parcelas, como cálculos, cancelamentos ou pagamentos. Todo evento externo deve acionar este endpoint.

Exemplo de Payload:

[
  {
    "idIntegracao": "GUIA_MOV_01",
    "guiasMovtos": {
      "tiposMovimentacoesDebito": "CALCULO",
      "dhMovimentacao": "2018-01-01 10:00:00",
      "dhEstorno": "2018-01-01 10:00:00",
      "idGuia": 1,
      "anoGuia": 2018,
      "idCreditoTributario": 1,
      "idPessoa": 1,
      "codigoPessoa": 1,
      "tipoReferente": "CONTRIBUINTE",
      "idReferente": 1,
      "codigoReferente": "CODIGO1",
      "situacaoGuia": "ABERTO",
      "idPagamento": 1,
      "idParcelamento": 1,
      "idHomologRequerimento": "1",
      "idDividas": 1
    }
  }
]

2.5. Movimentação de Guias - Receitas (Detalhe Financeiro)

  • Endpoint: POST /api/guiasMovtosReceitas
  • Objetivo: Trabalha em conjunto com o guiasMovtos. Enquanto a guia registra "o que aconteceu", este serviço detalha "como isso afetou os valores" divididos por receita.

Exemplo de Payload:

[
  {
    "idIntegracao": "GUIA_MOV_REC_01",
    "guiasMovtosReceitas": {
      "idGuiasMovtos": 1,
      "tiposMovimentacoesDebito": "CALCULO",
      "mesEncerramento": 1,
      "anoEncerramento": 2018,
      "dtEfeito": "2018-01-01",
      "dhMovimentacao": "2018-01-01 10:00:00",
      "idGuia": 1,
      "anoGuia": 2018,
      "idCreditoTributario": 1,
      "idReceita": 1,
      "idPessoa": 1,
      "codigoPessoa": 1,
      "tipoReferente": "CONTRIBUINTE",
      "idReferente": 1,
      "codigoReferente": "REF1",
      "situacaoGuia": "ABERTO",
      "vlTributo": 100.00,
      "vlCorrecao": 0,
      "vlJuros": 0,
      "vlMulta": 0,
      "vlTributoMovto": 100.00,
      "vlCorrecaoMovto": 0,
      "vlJurosMovto": 0,
      "vlMultaMovto": 0,
      "idPagamento": 1,
      "idParcelamento": 1,
      "idHomologRequerimento": "1",
      "idGuiasRecManutencao": 1,
      "idDivida": 1
    }
  }
]

3. Dicas de Consultas (GET) na Service Layer​

Quando precisarem consultar (filtrar e ordenar) dados nestas entidades para auditoria ou validação, devem atentar aos principais campos disponíveis no Service Layer:

  • Saldos Finais: Diferencie os valores totais (valorSaldo, vlSaldo) dos valores gerados apenas no mês de referência (ex: valorCorrecaoMes, vlJurosMes). Para fins de encerramento, "Acréscimos do mês" considera apenas a variação do período atual.

  • Usuário: O campo usuário aceita o nome do operador do sistema ou um identificador de máquina (ex: SISTEMA, INTEGRACAO ).

  • Filtros Mais Comuns: Ao consultar saldos, indexe suas buscas por idLancamento, idDebito, idContribuinte, idReceita, dataEfeito e situacao. Isso garantirá a melhor performance no retorno dos dados.

4. Operações de Manutenção e Correção (PUT, PATCH e DELETE)​

Embora o método POST seja utilizado para o envio de novos registros (criação e migração em lote), a documentação do Swagger também disponibiliza os métodos PUT, PATCH e DELETE para todas os serviços mencionados (DividasMovtosReceitas, EncerramentoMensalDividasReceitas, GuiasMovtos, GuiasMovtosReceitas e EncerramentoMensalLancamentoReceita).

Esses métodos são fundamentais para a manutenção corretiva do dia a dia e para desfazer operações indevidas.

🟡 PUT (Atualização Completa)

  • Como funciona: Substitui integralmente um registro existente.
  • Uso no Swagger: O endpoint exigirá o ID do registro na URL (ex: PUT /api/guiasMovtos/{id}). O corpo da requisição (Payload) deve conter o objeto inteiro novamente, mesmo os campos que não sofreram alteração.
  • Aplicação Prática: Correção de um registro de Encerramento Mensal que foi migrado com o ano ou a receita tributária incorreta.

🟠 PATCH (Atualização Parcial)

  • Como funciona: Atualiza apenas campos específicos de um registro, preservando os demais.
  • Uso no Swagger: Também exige o ID na URL (ex: PATCH /api/encerramentoMensalLancamentoReceita/{id}). O Payload deve conter apenas as propriedades que precisam ser modificadas.
  • Aplicação Prática: Alterar apenas o campo situacaoDivida ou atualizar a flag registroHomologado de false para true, sem precisar reenviar todos os valores financeiros do registro.

🔴 DELETE (Exclusão)

  • Como funciona: Remove permanentemente um registro do banco de dados.

  • Aplicação Prática: * Limpeza de movimentações geradas por engano.

    • Atenção no Encerramento: Quando ocorre a operação de Desfazer Encerramento, os registros daquele mês correspondente precisam ser excluídos para que o saldo do mês anterior volte a ser o saldo vigente oficial.

Aviso Técnico de Segurança: > O uso de PUT, PATCH e, especialmente, DELETE em tabelas de Movimentações GuiasMovtos ou GuiasMovtosReceitas deve ser feito com extrema cautela. Alterar ou apagar um evento do passado (como um pagamento ou estorno) sem a devida compensação contábil fará com que o Saldo Inicial do Encerramento Mensal do mês seguinte fique inconsistente com a realidade do Contribuinte.