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 disponibilizados serão somente 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.
Através de todas essas operações desenvolvidas na API, o sistema fará a interpretação das informações e retornará os dados requisitados.
IMPORTANTE: Para cada terceiro integrador (ou seja, para cada sistema que utilize da API) e para cada cliente deverá ser desenvolvida sistemática de apuração dos valores de CDA, obedecendo as regras estabelecidas para aquela integração de CDA e ajuizamento, assim como as regras da própria Prefeitura em relação à apresentação de seus débitos e pagamentos e dados legados.
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 |
|---|---|
| "dividaExecutada" | Valor da Dívida da(s) CDA(s) Executadas para o Processo (valor original + encargos) |
| "dividaExecutadaHonorarios" | 10% calculados sobre o valor da dívida executada |
| "dividaExecutadaTotal" | soma dos campos "dividaExecutada" e "dividaExecutadaHonorarios" |
| "valorPago" | Soma (do valor original do débito) das parcelas pagas pertencentes às carteiras executadas |
| "valorPagoTotal" | Soma do valor das parcelas pagas pertencentes às carteiras utilizadas (com encargos) |
| "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. |
| "dataEmissao" | SysDate da emissão do JSON |
CASO 2: DÍVIDAS COM PARCELAMENTO, QUANDO EXISTIR APENAS UM PARCELAMENTO COM TODA A DÍVIDA
| Retorno (cont.) | Descrição |
|---|---|
| "dividaExecutada" | Valor da Dívida da(s) CDA(s) Executadas para o Processo (valor original + encargos) |
| "dividaExecutadaHonorarios" | 10% calculados sobre o valor da dívida executada |
| "dividaExecutadaTotal" | soma dos campos "dividaExecutada" e "dividaExecutadaHonorarios" |
| "acordo" | agrupador das informações do Arcordo/parcelamento realizado |
| "numeroAcordo" | Número do parcelamento/acordo realizado entre o contribuinte e a PM |
| "numeroParcelas" | Número de parcelas que foi negociado o acordo |
| "numeroParcelasPagas" | Número de parcelas pagas do acordo |
| "valorAcordoPago" | Valor pago do acordo |
| "honorariosAcordoPago" | Valor pago de honorários correspondente ao acordo |
| "totalAcordoPago" | Valor total do pagamento do acordo |
| "restanteDebito" | valor restante do débito, referente ao parcelamento/acordo (calculado da data da abertura parcelamento) |
| "restanteDebitoHonorarios" | valor do honorário do débito, referente ao parcelamento/acordo (calculado da data da abertura parcelamento) |
| "restanteDebitoTotal" | soma dos campos "restanteDebito" e "restanteDebitoHonorarios" |
| "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. |
| "dataEmissao" | SysDate da emissão do JSON |
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 101 | Não foi possível obter o endereço do devedor relacionado a carteira [NRO CARTEIRA], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 102 | Não foi possível obter o endereço do devedor do imóvel [COD IMOVEL], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 103 | Não foi possível obter o endereço do devedor da empresa [COD MOBILIARIO], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 104 | Não foi possível obter o endereço do devedor [PESSOA ID], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 001 | O Processo informado [NRO PROCESSO] não existe, favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 002 | Existem [X] Processos com o número informado [NRO PROCESSO], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 003 | Não foram encontradas carteiras vinculadas ao processo informado, favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 004 | A carteira [NRO CARTEIRA] relacionada ao processo solicitado, esta vinculada a um processo mais recente [NRO PROCESSO] |
| ERRO 005 | Nome do contribuinte não localizado na Carteira [NRO CARTEIRA], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 006 | Dados do contribuinte não localizados na carteira [NRO CARTEIRA], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 007 | Não foi possível obter o valor da divida executada para a CarteiraId: [NRO CARTEIRA], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 008 | Erro ao obter dados da Carteira [NRO CARTEIRA], favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 009 | Existem mais de 1 parcelamento vigente para este processo, favor procure a Dívida Ativa e informe o erro encontrado |
| ERRO 010 | Não foi possível obter o valor da divida executada para a carteira de parcelamento, CarteiraId: [NRO CARTEIRA], favor procure a Dívida Ativa 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.
Nenhum comentário