Integração API Extrato Judicial
Objetivo:
Documentação da API que fornece Extrato de atualização de Débitos Judiciais com base a autenticação e apresentação de Processo Judicial.
Os endpoints retornarão dois sets de infromações para o terceiro:
- Informações em JSON correspondentes ao solicitado;
- Formulário PDF (necessita de homologação da Prefeitura) para consumo e entrega a interessados.
A homologação do documento fornecido e seus dados específicos são de responsabilidade da Prefeitura Municipal em questão, sendo que os dados sensíveis serão aqueles autorizados pela Prefeitura para exibição.
Conceito:
Para funcionamento da ferramenta, é preciso que os números de Processo Cadastrados no STM sejam equivalentes aos requisitados pelo terceiro.
As permissões para acesso aos serviços é dada pela CEBI, com expressa autorização da Prefeitura (Chamado Técnico e/ou documentação apropriada).
Pode acontecer, em alguns casos, do número cadastrado no Sistema Tributário STM não serem os mesmos requisitados pela integração, nesse caso haverá tratamento de erro indicando a situação.
Para os casos onde o Processo for identificado no sistema, o STM fará diversas verificações de status:
- Verificação das carteiras correspondentes ao Processo Judicial;
- Verificação do Processo Administrativo equivalente ao Processo Judicial solicitado;
- Verificar qual é o cadastro correspondente e responder responsivamente se trata de um CCM, Inscrição de IPTU ou Documento, conforme o caso;
- Verificação se o processo solicitado é o último processo cadastrado na carteira;
- Verificação do tipo de Integração realizado com parceiro;
- Verificação do Processo Administrativo equivalente ao Processo Identificado;
- Os valores das dívidas processadas (se houver registro), ou o valor calculado das dívidas para a data do processo judicial;
- As baixas, cancelamentos, e outras situações de carteiras referentes às carteiras executadas;
- Os parcelamentos e reparcelamentos efetivados com base às dívidas;
- A situação das parcelas desse parcelamento;
- Caso o parcelamento tenha vários processos na sua composição, fará a identificação e extração da informação correspondente (principal baixas, pagamentos, etc.) somente ao Processo Requisitado;
- Verificará o endereço prioritário para o tipo de contribuinte necessário (se é Imóvel, se é CCM ou se é Pessoa) para exibição no relatório e nos dados disponibilizados.
Foi estabelecida rotina para que o sistema identifique de forma automática a situação completa da dívida e seus desdobramentos, para informação de resposta das APIs.
Quando há mais de um processo judicial cadastrado na carteira pesquisada, apenas o último (mais recente) será considerado como ativo.
Conflitos cadastrais não retornarão informações, ou seja, se não houver certeza dos valores a apresentar, a API não apresentará informações e retornará erro (verificar tabela de erros).
O terceiro fará conexão com o serviço através da obtenção de um token, seguido de uma requisição POST relacionada.
Autenticação:
Esse tópico trata da autenticação no servidor de Login do ambiente Cebi, realizada através de chamadas HTTP.
No modelo proposto, o Usuário de Integração Envia Credenciais, que passam pelo sistema Integrador (CEBI) - o qual valida as credenciais - e por sua vez retorna com o token (expirável) para que as informações de integração sejam validadas pela integração desejada (Extrato Judicial).
Endpoints:
| URL | Método |
|---|---|
| /login/connect/token | POST |
A primeira parte da URL depende do cliente e será disponiblizada para cada implantação conforme demanda à Infraestrutura.
Conteúdo:
Headers:
Content-Type: application/x-www-form-urlencoded
| Campo | Conteúdo |
|---|---|
| grant_type | client_credentials |
| client_id | Será informado pela CEBI |
| client_secret | Será informado pela CEBI |
| scope | Cebi.Api |
Emissão de Extrato:
Após obtenção das credenciais, o serivço de API retornará com informações de Extrato:
-
Informações do Devedor e Dívdia (consolidada) em JSON:
-
Documento em PDF, desenvolvido em Web, para impressão com as informações (que deve ser aprovada e homologada pela Dívida Ativa do município).
Processo Judicial - Retorno JSON
Uma vez com as credenciais obtidas/autenticadas, as informações de Extrato devem ser solicitadas em:
| URL | Método |
|---|---|
| /Integracao_stm/ProcessosJudiciais/Extrato | POST |
O Número do processo judicial - CNJ, deverá ser enviada no Parâmetro da requisição o número do processo.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| NumeroProcesso | Alfanumérico | Número cadastrado no sistema, exemplo '1500930-19.2023.8.26.0363' |
Importante: O número deve ser solicitado com traços e pontos, da forma que está cadastrado no sistema. Processos antigos podem ter formato diferenciado, o que impossibilita a padronização dos campos.
Em caso de sucesso, o retorno será status code 200:
| Retorno | Descrição |
|---|---|
| "numeroProcesso" | Extraído do BD do cliente, idêntico ao solicitado na requisição (conferência) |
| "anoProcesso" | Ano do Processo Judicial, exemplo "2016" |
| "vara" | Informação da Vara cadastrada no sistema. |
| "ccm" | Se o contribuinte for mobiliário, será o número do CCM conrome cadasrro do órgão. Exemplo: 00.000 |
| "inscricao" | Se o contribuinte for um imóvel, o número da Inscrição Cadastral do Imóvel. Exemplo: 51-53-71-0178-001 |
| "documento" | Número do CPF ou do CNPJ da pessoa (fornecido com máscara) |
| "nome" | nome do contribuinte cadastrado no sistema |
| "tributo" | Tributos que fazem parte do Processo, ex: "IPTU-2011" |
| "endereco" | Agrupador do endereço do devedor (principal) |
| "logradouro" | Logradouro do devedor |
| "numero" | Número do devedor |
| "complemento" | Complemento do devedor |
| "bairro" | Bairro do Devedor |
| "cidade" | Cidade do Devedor |
| "uf" | UF do Devedor |
| "cep" | CEP do Devedor |
As informações do devedor referem-se àquelas cadastradas no sistema no momento da pesquisa.
Para identificação do devedor (caso haja mais de uma pessoa cadastrada no sistema), será observada a seguinte regra:
-
Se houver Parcelamento nas carteiras do Processo, o devedor apurado será aquele que parcelou (confessou) a dívida.
-
Se não houver parcelamento, contudo houver mais de um devedor, deverá ser apurado pela seguinte ordem:
a. Pessoa ligada ao CCM;
b. Pessoa proprietária do Imóvel;
c. Pessoa que tem documento cadastrado, caso haja mais de uma pessoa nessa situação, o que tiver sido cadastrado por ÚLTIMO (maior PFJ_SEQ).
A apuração dos débitos será da seguinte forma:
CASO 1: DÍVIDAS SEM PARCELAMENTO
| Retorno (cont.) | Descrição |
|---|---|
| "dataExecução" | Data informada da Execução Fiscal dd/mm/yyyy |
| "dividaExecutada" | Soma das carteiras de dívida calculadas, na data de Execução Fiscal (valor original + encargos) |
| "valorPago" | Soma (do valor original do débito) das parcelas pagas pertencentes às carteiras executadas |
| "ValorDevidoAtualizado" | Valor da dívida Atualizada para a data atual (somados multa, juros e correção) |
| "valorDevidoAtualizadoHonorarios" | Honorários Advocatícios atualizados |
| "valorDevidoAtualizadoTotal" | Valor devido atualizado total, devido pelo contribuinte. |
CASO 2: DÍVIDAS COM PARCELAMENTO, QUANDO EXISTIR APENAS UM PARCELAMENTO COM TODA A DÍVIDA
| Retorno (cont.) | Descrição |
|---|---|
| "dataExecução" | Data informada da Execução Fiscal dd/mm/yyyy |
| "dividaExecutada" | Soma das carteiras de dívida calculadas na data de Execução Fiscal |
| "numeroAcordo" | Número do parcelamento/acordo realizado entre o contribuinte e a PM |
| "numeroParcelas" | Número de parcelas que foi negociado o acordo |
| "valorAcordo" | Valor da dívida negociada no acordo (exceto honorários) |
| "honorariosAcordo" | Valor do honorário negociado no acordo |
| "totalAcordo" | Valor total negociado no acordo |
| "valorAcordoPago" | Valor pago do acordo |
| "honorariosAcordoPago" | Valor pago de honorários correspondente ao acordo |
| "totalAcordoPago" | Valor total do pagamento do acordo |
| "ValorDevidoAtualizado" | Valor da dívida Atualizada para a data atual (somados multa, juros e correção) |
| "valorDevidoAtualizadoHonorarios" | Honorários Advocatícios remanescentes do acordo |
| "valorDevidoAtualizadoTotal" | Valor devido atualizado total, devido pelo contribuinte. |
Processo Judicial - Retorno PDF
Com as credenciais autenticadas, a certidão deverá ser solicitada em:
| URL | Método |
|---|---|
| /Integracao_stm/ProcessosJudiciais/ExtratoPdf | POST |
O Número do processo judicial - CNJ, deverá ser enviada no Parâmetro da requisição o número do processo.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| NumeroProcesso | Alfanumérico | Número cadastrado no sistema, exemplo '1500930-19.2023.8.26.0363' |
Importante: O número deve ser solicitado com traços e pontos, da forma que está cadastrado no sistema. Processos antigos podem ter formato diferenciado, o que impossibilita a padronização dos campos.
Mensagens de Erro
Em caso de erro, retornará 404 e a descrição do erro como mensagem, conforme o problema identificado, para ambas as requisições realizadas.
TABELA DE ERROS
| Código | Descrição |
|---|---|
| ERRO 001 | O Processo informado 'numeroProcesso' não existe, favor contate o administrador e informe o erro encontrado |
| ERRO 002 | Não foram encontradas carteiras vinculadas ao processo informado, favor contate o administrador e informe o erro encontrado |
| ERRO 003 | Nome do contribuinte não localizado na carteira 'CarteiraId' |
| ERRO 004 | Dados do contribuinte não localizados na carteira 'CarteiraId', favor contate o administrador e informe o erro encontrado |
| ERRO 005 | Erro ao obter dados da Carteira 'CarteiraId', favor contate o administrador e informe o erro encontrado |
| ERRO 006 | Existe mais de 1 parcelamento vigente para este processo, favor contate o administrador e informe o erro encontrado |
| ERRO 007 | Existem 13 Processos com o número informado 'numeroProcesso', favor contate o administrador e informe o erro encontrado |
| ERRO 008 | A carteira CarteiraId relacionada ao processo solicitado, esta vinculada a um processo mais recente 'Numero/Ano' |
| ERRO 010 | Não foi possível obter o endereço do devedor relacionado a carteira 'CarteiraId', favor contate o administrador e informe o erro encontrado |
| ERRO 011 | Não foi possível obter o endereço do devedor do imóvel 'ImobiliarioId', favor contate o administrador e informe o erro encontrado |
| ERRO 012 | Não foi possível obter o endereço do devedor da empresa 'MobiliarioId', favor contate o administrador e informe o erro encontrado |
| ERRO 013 | Não foi possível obter o endereço do devedor 'PessoaFisJurId', favor contate o administrador e informe o erro encontrado |
4. Considerações:
Os relatórios e informações são extraídas com base às carteiras e acordos processados no sistema. O desenvolvimento trabalha na expectativa de enviar informações apuradas e barrar a entrega no caso de divergências ou necessidade de intervenção.
A API devido a sua natureza é dependente de recursos de infraestrutura alheios ao desenvolvimento, de responsabilidade do cliente e/ou compartilhada, conforme contrato de prestação de serviços.
As informações disponibilizadas são as constantes do cadastro, ou seja, qualquer mudança no cadastro que seja relevante nas rotinas pode alterar os resultados, portanto, as informações podem variar de requisição a requisição baseado nesse fato.