Integração com terceiros
Visão Geral
O serviço de integração disponibilizado permite que sejam buscadas informações do nosso banco de dados a fim de criação e atualização de registros criados no Procuradoria (Cloud), onde serão disponibilizados 3 objetos que serão retornados em um array.
Cada serviço deve ser acessado utilizando os endpoints fornecidos neste manual, recebendo como parâmetro a data base da busca pelos registros ou o id da dívida, que filtram os registros que foram criados ou alterados a partir da data ou relativo àquele id.
Cada um desses objetos tem sua parte fundamental no processo dentro do Procuradoria, acessando os endpoints exemplificados abaixo:
Tabela 2 - objetos:
Configuração
Para utilizar a integração é necessário que no primeiro acesso seja criado uma chave pública no sistema Procuradoria (Cloud), acessando o menu Utilitários > Gerenciador de acessos > Aplicações.
|
|---|
|
|---|
Ao confirmar será gerado um código de acesso, este deve ser utilizado no header da requisição RESTI.
|
|---|
Como utilizar
Pegando como exemplo o objeto ExecucoesFiscais, ao realizar uma requisição será necessário enviar no header as informações contidas no exemplo abaixo e no final do manual.
Ao enviar a requisição para o endpoint passado na tabela 2 acima, com os parâmetros conforme demonstrados a seguir, serão retornadas todas as execuções fiscais que foram criadas ou alteradas a partir da dataBase em diante. O resultado terá a estrutura conforme os objetos descritos e terá formato JSON possuindo controle da paginação.
Os parâmetros limit e offset controlam a quantidade de registros seguidos do filtro da dataBase, indicado para realizar o controle das integrações. O controle da requisição deve ser utilizado da seguinte forma - abaixo dois exemplos:
ExecucoesFiscais:
https://procuradoria.suite.betha.cloud/integracoes/v1/execucoes-dividas-terceiros?offset=0&limit=100&filter=dataBase>="2023-01-01T00:00:00.000"EnvioSaldo:
https://procuradoria.test.suite.betha.cloud/integracoes/v1/envio-saldo-terceiros?filter=idDivida=3941085
Em se tratando do objeto **ExecucoesFiscais** será retornado o seguinte JSON:
{
"offset": 0,
"limit": 20,
"total": 1,
"hasNext": false,
"content": [
{
"id": 1,
"idDividas": 1,
"ano": 2023,
"codigoExecucao": 1,
"anoLivro": 1,
"dataVencimento": "2023-01-01",
"descricaoCreditoTributario": "Descrição Crédito Tributario",
"descricaoReceita": "Descrição Crédito Tributario",
"folha": 1,
"idCreditoTributario": 1,
"idReceita": 1,
"livro": 1,
"numeroInscricao": 1,
"dataInscricao": "2023-01-01",
"numeroParcela": 1,
"numeroPosicao": 1,
"valorCorrecao": 9.00,
"valorJuro": 7.00,
"valorMulta": 8.00,
"valorTributo": 66.67,
"dataBase": "2023-01-01"
}
]
}
A documentação a seguir tem como finalidade fornecer orientações e diretrizes para a integração de processos que envolvam execução fiscal, como exportação de dados, recebimentos e atualizações de execuções.
A integração tem como objetivo a interação dos sistemas de Procuradoria, visando o fluxo de informações em cinco pontos chave.
Tipos de retorno
Serão disponibilizados endpoints que aceitam solicitações em formato JSON por meio de uma API REST. Para acessá-los é necessário incluir o token de autorização no cabeçalho de cada requisição. Os parâmetros esperados na requisição estão descritos na tabela 1.
Tabela 1 - Parâmetros
| Campo | Tipo | Descrição |
|---|---|---|
| dataBase | Date | Serão retornados todos os registros criados desde a data base. Este deve ser o parâmetro utilizado para todas as requisições, exceto a de saldo. |
| idDivida | numeric(19) | Serão retornadas as dívidas consultadas. Este deve ser o parâmetro utilizado na requisição do saldo. |
Envio das CDAs, petições iniciais, execuções fiscais e dívidas relacionadas
Se baseando na data base informada, será retornado um array com os registros que foram criados a partir deste parâmetro, conforme modelos apresentados nas tabelas abaixo.
Tabela 2 - Execuções Fiscais:
| Campo | Tipo | Descrição |
|---|---|---|
| codigoExecucao | numeric(19) | Código da execução. |
| processo | varchar(25) | Número do processo da execução fiscal que o tribunal retorna. |
| dataCadastro | Date | Data de cadastro do processo. |
| situacao | bpchar(1) | Situação do processo (valor, descrição): “AJUIZAMENTO”:Aguardando Ajuizamento; “CANCELADO”: Cancelado; “TRAMITACAO”: Em Tramitação; “ENCERRADO”: Encerrado; “SUSPENSO”: Suspenso. |
| idTribunal | numeric(10) | Código de identificação do tribunal. |
| descricaoTribunal | varchar(500) | Descrição/nome do tribunal. |
| idComarca | numeric(10) | Código de identificação da comarca. |
| descricaoComarca | varchar(500) | Descrição/nome da comarca. |
| IdVara | numeric(10) | Código de identificação da vara. |
| descricaoVara | varchar(500) | Descrição/nome da vara. |
| cpfCnpjExecutado | varchar(14) | CPF/CNPJ do executado. |
| nomeExecutado | varchar(500) | Descrição/nome do executado. |
| cpfCnpjAdvogado | varchar(14) | CPF do advogado. |
| nomeAdvogado | varchar(500) | Descrição/nome do advogado. |
| cpfCnpjExequente | varchar(14) | CNPJ do exequente. |
| nomeExequente | varchar(500) | Descrição/nome do exequente. |
| cpfCnpjProcurador | varchar(14) | CPF do procurador. |
| area | varchar(500) | Descrição da área. |
| assunto | varchar(500) | Descrição do assunto. |
| classe | varchar(500) | Descrição da classe. |
| msgForum | varchar(500) | Mensagem retornada pelo tribunal. |
| procedimento | bpchar(2) | Procedimentos: “ES”: Especial; “OR”: Ordinario; “SM”: Sumário; “SS”: Sumaríssimo; |
| segredoJustica | bpchar(1) | Se é um segredo de Justiça: “SIM”: Sim; “NAO”: Não; |
| pedidoUrgencia | bpchar(1) | Se é um pedido de urgência: “SIM”: Sim; “NAO”: Não; |
| valorCausa | numeric(15, 2) | Valor da causa. |
| honorarios | numeric(15, 2) | Valor de honorários. |
| idPeticao | numeric(10) | Código de identificação da Petição. |
| anoPeticao | numeric(10) | Ano da Petição. |
| dataBase | Date | Data base utilizado para a integração. |
Tabela 3 - Execuções Dívidas:
| Campo | Tipo | Descrição |
|---|---|---|
| id | numeric(19) | Código de identificação da dívida. |
| ano | numeric(4) | Ano da dívida. |
| codigoExecucao | numeric(19) | Código da execução. |
| anoLivro | numeric(4) | Ano do livro. |
| dataVencimento | Date | Data de vencimento da dívida. |
| descricaoCreditoTributario | varchar(500) | Descrição do crédito. |
| descricaoReceita | varchar(500) | Descrição do crédito. |
| folha | numeric(9) | Número da folha. |
| idCreditoTributario | numeric(19) | Código de identificação do crédito tributário. |
| idReceita | numeric(19) | Código de identificação da receita. |
| livro | numeric(9) | Número do livro. |
| numeroInscricao | numeric(9) | Número de inscrição da dívida. |
| dataInscricao | Date | Número de inscrição da dívida. |
| dataInscricao | Date | Data de inscrição da dívida. |
| numeroParcela | numeric(5) | Número da parcela da dívida. |
| numeroPosicao | numeric(9) | Número da posição. |
| valorCorrecao | numeric(16,2) | Valor da correção. |
| valorJuros | numeric(16,2) | Valor dos juros. |
| valorMulta | numeric(16,2) | Valor da multa. |
| valorTributo | numeric(16,2) | Valor do tributo. |
| dataBase | Date | Data base utilizado para a integração. |
Tabela 4 - Documentos Dívida:
| Campo | Tipo | Descrição |
|---|---|---|
| anoDocumento | numeric(10) | Ano do documento. |
| idDocumento | numeric(10) | Número do documento. |
| tipoDocumento | varchar(1) | Tipo de documento: "C": Certidão de Dívida Ativa; "P": Petição Inicial. |
| urlDocumento | varchar(500) | URL para download do documento |
| nomePessoa | varchar (500) | Nome do executado da dívida |
| cpfCnpjPessoa | varchar(14) | CPF/CNPJ do executado da dívida. |
| dataCanc | Date | Data de cancelamento do documento. |
| dataEmissao | Date | Data da emissão do documento. |
| dataValidade | Date | Data de validade do documento. |
| valorCorrecao | numeric(14,2) | Valor da correção. |
| valorJuro | numeric(14,2) | Valor dos juros. |
| valorMulta | numeric(14,2) | Valor das multas. |
| valorTributo | numeric(14,2) | Valor do tributo. |
| valorTotal | numeric(14,2) | Valor total do documento. |
| dataBase | Date | Data base utilizado para a integração. |
| inscricaoImobiliaria | varchar(20) | Número da inscrição imobiliária do imóvel. |
| nomeCorresponsavel | varchar(100) | Nome do corresponsável. |
| cpfCnpjCorresponsavel | varchar (50) | CPF/CNPJ do corresponsável. |
| enderecoCorresponsavel | varchar(250) | Endereço do corresponsável. |
Envio de saldo
Se baseando no id da dívida, será retornado um array com os registros que foram criados a partir deste parâmetro, conforme modelos apresentados nas tabelas abaixo.
Tabela 5 - EnvioSaldo
| Campo | Tipo | Descrição |
|---|---|---|
| idDivida | numeric(19) | Código da dívida que será consultada. |
| idReceita | numeric(19) | Código da identificação da receita. |
| valorJuros | numeric(16,2) | Valor dos juros. |
| valorSaldo | numeric(16,2) | Valor do saldo atualizado da dívida. |
| valorMulta | numeric(16,2) | Valor da multa. |
| valorCorrecao | numeric(16,2) | Valor da correção. |
Envio de alteração da situação
Se baseando na data base informada, será retornado um array com os registros que foram criados a partir deste parâmetro, conforme modelos apresentados nas tabelas abaixo.
Tabela 6 - EnvioAlteracao
| Campo | Tipo | Descrição |
|---|---|---|
| idDivida | numeric(19) | Código da dívida que terá situação alterada. |
| situacao | varchar(1) | Situações da dívida: ABERTO; CANCELADA; PAGA; PARCELADO; PRESCRITA; REMIDA; SUSPENSA. |
| valorSaldo | numeric (16,2) | Valor do tributo da dívida. |
| dataBase | Date | Data base utilizado para a integração |
Recebimento do número do processo
Esse serviço é uma entrada de dados, uma requisição POST, em que o sistema terceiro poderá informar um ou mais números do processo da execução, essa rotina irá receber um conjunto de dados, esperando recebê-los como parâmetro, conforme a tabela 7 abaixo, e gravará o número de processo na execução fiscal de código informado e retornará o campo de mensagem preenchido com a situação do processamento individualmente, o campo mensagemRetorno não é necessário ser preenchido pelo sistema terceiro.
Tabela 7 - RecebimentoProcesso
| Campo | Tipo | Descrição |
|---|---|---|
| codigoExecucao | numeric(19) | Código da Execução Fiscal que será alterada. |
| processo | varchar(20) | Número do processo. |
| mensagemRetorno | varchar(100) | Mensagem contendo a situação da execução informada. |
Recebimento das Movimentações do Processo
Serviço que irá disponibilizar uma entrada de dados POST que será utilizada para inserir movimentações nos processos existentes. O sistema Betha irá receber os parâmetros conforme descritos na tabela 8 e devolvido com as informações de cada processamento.
Tabela 8 - RecebimentoMovimentacao
| Campo | Tipo | Descrição |
|---|---|---|
| codigoExecucaoFiscal | numeric(19) | Código da execução que receberá a movimentação.. |
| dataMovimentacao | timestamp(18) | Data da movimentação do processo. |
| codigoMovimentacao | numeric(19) | Código do tipo de movimentação, listagem padrão disponível na tabela 9. |
| comentario | varchar(4000) | Comentário da movimentação. |
| protocolo | varchar(50) | Protocolo da integração. |
Os campos codigoExecucalFiscal, dataMovimentacao e codigoMovimentacao são obrigatórios para o processamento. As informações referentes às movimentações não padrões podem ser obtidas na fonte de dados “tiposMovimentacoes.buscar”. As movimentações padrões do sistema são as demonstradas abaixo, na tabela 9:
Tabela 9 - codigoMovimentacao
| id | descricao | altera_situacao | situacao |
|---|---|---|---|
| 1 | Processo Cadastrado no Sistema | S | T |
| 2 | Petição Inicial Emitida | N | null |
| 3 | Dívida Removida da Execução Fiscal | N | null |
| 4 | Petição Intermediária Cancelada | N | null |
| 5 | Petição Intermediária Reativada | N | null |
| 6 | Execução Fiscal Cancelada pelo Sistema | S | C |
| 7 | Execução Fiscal Reativada pelo Sistema | S | T |
| 8 | Penhora Judicial Deferida | N | null |
| 9 | Penhora Judicial Indeferida | N | null |
| 463 | Ajuizamento Realizado com Sucesso | S | T |
| 464 | Ajuizamento Não Realizado - Inconsistência | N | null |
| 469 | Peticionamento Intermediário Realizado com Sucesso | N | null |
| 470 | Peticionamento Intermediário Não Realizado - Inconsistência | N | null |
| 471 | Petição Intermediária Emitida | N | null |
| 472 | Suspensão cancelada. Situação anterior reativada para o processo | N | null |
| 1423 | Captura Automática de Movimentações | N | null |
| 2294 | Envio Realizado com Sucesso | N | null |
| 2295 | Envio Não Realizado - Inconsistência | N | null |
| 13396 | Integração Terceiros | N | null |
| 15704 | Intimação eletrônica | N | null |
Recebimento do Anexo da Movimentação
Este serviço é uma entrada de dados, uma requisição POST, em que o sistema terceiro poderá informar o arquivo codificado em base64 para que seja vinculado a movimentação do processo no sistema - mencionada no item 5, esse serviço pode ser utilizado tanto com movimentações criadas por terceiros ou não.
É importante ressaltar que:
- o sistema será capaz de processar somente um arquivo em uma única requisição;
- o sistema será capaz de processar somente um objeto por requisição, não aceitando listas ou vários objetos de anexo;
- não será possível inserir um anexo duplicado, de mesmo nome, tipo para a mesma movimentação;
- o nome do arquivo não deve exceder 250 caracteres.
Tabela 10 - RecebimentoMovimentacaoAnexo
| Campo | Tipo | Descrição |
|---|---|---|
| idMovimentacao | numeric(16) | Id da movimentação que terá o anexo vinculado. |
| tipoArquivo | varchar(5) | Extensão do arquivo. |
| nomeArquivo | varchar(250) | Nome do arquivo. |
| arquivo64 | blob | Arquivo codificado em base64 com limite de 10MB. |
Consultando dados de protesto e/ou ajuizamento
Através do serviço resumoDivida, é possível consultar dados de protesto e ajuizamento da divida.
Serão apresentadas informações como data, número de processo, situação, número de CDA, número da petição, entre outras.
Criação e sincronização de custas de execuções fiscais
Este serviço é uma entrada de dados, uma requisição POST, em que o sistema terceiro poderá enviar até 50 custas de execuções fiscais em uma requisição, que serão criadas em lote e sincronizadas no Tributos, caso as configurações estejam nos conformes.
Tabela 11 - ExecucaoFiscalCustaDto
| Campo | Tipo | Descrição |
|---|---|---|
| idExecucoes | numeric(19) | Id da execução fiscal que terá a custa vinculada |
| idCustas | numeric(19) | Id do tipo da custa processual |
| valor | numeric(10,2) | Valor da custa |
| observacao | varchar(500) | Observação relacionada à custa |
Integração de protestos
Regras de Criação (Requisição POST)
Na criação de um novo protesto, o sistema oferece uma facilidade para a associação da pessoa:
- Caso o campo pessoa não seja informado na requisição POST, o sistema irá automaticamente utilizar a pessoa vinculada à Certidão de Dívida Ativa (CDA) correspondente.
Regras de Atualização (Requisição PUT)
Ao atualizar dados de protestos e movimentações, o sistema adota o comportamento de atualização parcial. Isso significa que apenas os campos explicitamente enviados na requisição serão alterados. Campos omitidos não serão modificados, preservando os dados já existentes.
Regras para Movimentação de Protesto
Ao criar ou alterar uma movimentação, existe uma validação de data:
- A data do movimento (dataMovto) não pode ser posterior à data e hora atuais. O sistema não aceitará datas futuras para as movimentações.
Tabela de Campos – Protesto
| Campo | Tipo | Descrição |
|---|---|---|
| id | numeric(19) | Identificador único do protesto. |
| nroCda | numeric(19) | Número da CDA. |
| anoCda | numeric(4) | Ano da CDA. |
| nossoNumero | numeric(19) | Nosso número da cobrança. |
| nroGuia | numeric(19) | Número da guia de arrecadação. |
| anoGuia | numeric(4) | Ano da guia de arrecadação. |
| hashLote | varchar(500) | Hash identificador do lote. |
| hashGeracaoGuia | varchar(500) | Hash da geração da guia. |
| hashGeracaoCda | varchar(500) | Hash da geração da CDA. |
| hashAssinaturaCda | varchar(500) | Hash da assinatura da CDA. |
| hashAssinaturaCdaP7s | varchar(100) | Hash da assinatura CDA no formato P7S. |
| processo | varchar(100) | Identificador do processo. |
| valorTitulo | numeric(14, 2) | Valor original do título. |
| valorProtestado | numeric(14, 2) | Valor protestado. |
| valorCustas | numeric(14, 2) | Valor das custas cartorárias. |
| situacao | varchar(16) | Situação atual do protesto. |
| regraVencimentoProtesto | varchar(2) | Regra de vencimento do protesto. |
| dataCanc | Date | Data do cancelamento. |
| dataProtocolo | Date | Data do protocolo. |
| dataVcto | Date | Data de vencimento. |
| pessoa | object | Pessoa relacionada ao protesto. |
| cartorio | object | Cartório relacionado ao protesto |
| municipio | object | Município do protesto |
| sistemaProtesto | object | Sistema do protesto |
Tabela de Campos – Pessoa
| Campo | Tipo | Descrição |
|---|---|---|
| cpfCnpj | varchar(14) | CPF/CNPJ da pessoa do protesto. |
Tabela de Campos – Cartorio
| Campo | Tipo | Descrição |
|---|---|---|
| identificadorProtesto | numeric(4) | Identificador do cartório para protesto. |
| cpfCnpj | varchar(14) | Identificador único do protesto. |
| nome | varchar(155) | Nome da pessoa dona do cartório. |
Tabela de Campos – Municipio
| Campo | Tipo | Descrição |
|---|---|---|
| id | numeric(19) | Identificador do município. |
| codigoIBGE | numeric(10) | Código do IBGE do município. |
Tabela de Campos – Sistema Protesto
| Campo | Tipo | Descrição |
|---|---|---|
| sigla | varchar(3) | Sigla do sistema protesto. |
Tabela de Campos – Movimentação de protestos
| Campo | Tipo | Descrição |
|---|---|---|
| id | numeric(19) | Identificador único do movimento. |
| idProtesto | numeric(19) | Referência ao protesto. |
| tipoMoeda | numeric(19) | Código do tipo de moeda. |
| valorMovto | numeric(14, 2) | Valor do movimento financeiro. |
| nroCartorio | varchar(10) | Número do cartório. |
| nroProtocolo | varchar(16) | Número do protocolo do movimento. |
| codigoOcorrencia | varchar(5) | Código da ocorrência. |
| ocorrencia | varchar(500) | Descrição da ocorrência. |
| codigoInconsistencia | varchar(5) | Código da inconsistência. |
| inconsistencia | varchar(500) | Descrição da inconsistência. |
| nomeArquivo | varchar(60) | Nome do arquivo de origem do movimento. |
Documentação dos serviços
OBS: É necessário realizar a troca do campo Select a definition para Procuradoria - Integração terceiros.