Parcelamento por terceiros
Visão Geral
O processo de parcelamento por sistemas de terceiros é composto por três etapas sequenciais: seleção dos lançamentos disponíveis para parcelamento, simulação do parcelamento e criação efetiva do parcelamento. Cada etapa é executada de forma assíncrona, por meio de requisições independentes.
Seleção de lançamentos
A seleção de lançamentos é a primeira etapa. Ela permite que o sistema terceiro consulte quais débitos e dívidas de um contribuinte estão disponíveis para parcelamento, com base em uma configuração de parcelamento previamente cadastrada no Tributos (Cloud).
O processamento é assíncrono: a requisição de envio retorna imediatamente uma ou mais chaves de processamento, e o resultado deve ser consultado posteriormente por meio de uma rota separada.
A requisição da seleção é realizada pela rota:
POST https://tributos.suite.betha.cloud/parcelamentos/v1/lancamentos-disponiveis
O corpo da requisição deve conter, obrigatoriamente, o ID da configuração de parcelamento e o contribuinte, podendo informar seu id ou CPF/CNPJ. Os demais campos são filtros opcionais que restringem o conjunto de lançamentos retornados.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idConfiguracao | Long | Sim | ID da configuração de parcelamento cadastrada no Tributos (Cloud). |
| idContribuinte | Long | Condicional | Ao menos este ou cpfCnpjContribuinte deve ser informado. |
| cpfCnpjContribuinte | String | Condicional | Ao menos este ou idContribuinte deve ser informado. O sistema valida duplicidade de cadastro ativo. |
| parcelarDebitos | Boolean | Não | Indica se débitos não inscritos em dívida ativa devem ser incluídos. (Padrão: true) |
| parcelarDividas | Boolean | Não | Indica se dívidas inscritas em dívida ativa devem ser incluídas. (Padrão: true) |
| dataVencimentoInicial | Date | Não | Início do intervalo para filtro por data de vencimento dos lançamentos. |
| dataVencimentoFinal | Date | Não | Fim do intervalo para filtro por data de vencimento dos lançamentos. |
| anosLancamento | Array (Integer) | Não | Filtro por ano(s) de lançamento. |
| idsCreditosTributarios | Array (Long) | Não | Filtro por créditos tributários específicos. |
| idsImoveis | Array (Long) | Não | Filtro por imóveis específicos. |
| idsEconomicos | Array (Long) | Não | Filtro por econômicos específicos. |
| statusDividas | Array (String) | Não | Filtro por status das dívidas. Valores: PROCESSO_EXECUCAO, AJUIZADA, PROTESTO, AJUIZADA_PROTESTO, PROCESSO_EXECUCAO_PROTESTO. |
A resposta da requisição é uma lista de chaves (strings), sendo gerada uma chave por tipo de parcelamento processado. Quando a configuração permite parcelar tanto débitos quanto dívidas, duas chaves são retornadas. Cada chave identifica individualmente o processamento assíncrono de um tipo de lançamento.
A combinação entre os campos parcelarDebitos/parcelarDividas e os tipos configurados no cadastro da configuração de parcelamento determina quais tipos serão efetivamente processados. Caso nenhum tipo compatível seja identificado, a requisição retornará uma inconsistência.
Consulta do resultado
Após o envio dos critérios, o resultado de cada chave deve ser consultado individualmente por meio da rota:
GET https://tributos.suite.betha.cloud/parcelamentos/v1/lancamentos-disponiveis/{key}
O campo {key} deve ser substituído por uma das chaves retornadas no POST.
O retorno contém os seguintes campos:
- status: os valores possíveis são: AGUARDANDO_PROCESSAMENTO, PROCESSANDO, SUCESSO, ERRO, CANCELADO
- total: total de registros identificados para processamento. Pode ser nulo enquanto o processamento não for iniciado.
- processado: quantidade de registros já processados. Pode ser nulo enquanto o processamento não for iniciado.
- list: lista de lançamentos disponíveis para parcelamento. Estará preenchida apenas quando o status for SUCESSO.
Cada item da lista representa um lançamento disponível e contém informações como: o contribuinte, o crédito tributário, o referente (imóvel, econômico, nota avulsa, obra, etc.), os valores (lançado, correção, juros, multa e total), os debitos ou dividas vinculados e o tipo de parcelamento ao qual pertence (NAO_INSCRITOS ou INSCRITOS).
A rota retornará nulo caso a chave informada não exista ou o processamento ainda não tenha sido registrado.
Simulação de parcelamentos
Com os IDs dos lançamentos disponíveis obtidos na etapa anterior, é possível iniciar a simulação do parcelamento. A simulação é assíncrona: o serviço de simulação retorna imediatamente um identificador e o processamento ocorre em segundo plano. O sistema deve consultar o resultado pelo identificador retornado até que o status indique a conclusão.
Iniciando a simulação
POST https://tributos.suite.betha.cloud/parcelamentos/v1/simulacao
O corpo da requisição deve conter os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idConfiguracao | Long | Sim | ID da configuração de parcelamento cadastrada no Tributos (Cloud). |
| idContribuinte | Long | Condicional | ID do contribuinte. Obrigatório se cpfCnpjContribuinte não for informado. |
| cpfCnpjContribuinte | String | Condicional | CPF ou CNPJ do contribuinte (apenas dígitos). Obrigatório se idContribuinte não for informado. |
| quantidadeParcelas | Integer | Sim | Quantidade de parcelas desejada. Deve respeitar o limite máximo definido na configuração. |
| idsDebitos | Array (Long) | Condicional | IDs dos débitos (não inscritos) a parcelar. Obrigatório se idsDividas não for informado |
| idsDividas | Array (Long) | Condicional | IDs das dívidas (inscritas) a parcelar. Obrigatório se idsDebitos não for informado. |
Os IDs de débitos e dívidas devem ser obtidos da etapa de seleção de lançamentos. É permitido informar ambas as listas simultaneamente, desde que a configuração de parcelamento aceite os dois tipos de lançamento.
A data para aplicação de acréscimos, data do primeiro vencimento, intervalo entre os vencimentos das parcelas e valor/percentual de entrada são definidos pela configuração de parcelamento. Esses valores não são recebidos como parâmetros da requisição.
A resposta retorna um identificador (string) que deve ser utilizado para consultar o resultado.
Consultando o resultado da simulação
GET https://tributos.suite.betha.cloud/parcelamentos/v1/simulacao/{key}
Onde {key} é o identificador retornado pelo POST.
A resposta contém os seguintes campos:
| Campo | Tipo | Descrição |
|---|---|---|
| id | ObjectId (String) | Identificador da simulação. |
| status | String | Status do processamento. |
| idConfiguracao | Long | ID da configuração utilizada. |
| idContribuinte | Long | ID do contribuinte. |
| quantidadeParcelasGeradas | Integer | Quantidade de parcelas efetivamente geradas. |
| params | Objeto | Parâmetros internos utilizados no cálculo (datas, intervalo, entrada). |
| idsDebitos | Array (Long) | IDs dos débitos incluídos na simulação. |
| idsDividas | Array (Long) | IDs das dívidas incluídas na simulação. |
| mensagem | String | Mensagem de erro, caso o processamento tenha falhado. |
| databaseId | Integer | Identificador do banco de dados. |
| createdBy | String | Identificação do usuário que criou o registro. |
| updatedBy | String | Identificação do usuário que realizou a última atualização. |
| createdIn | LocalDateTime | Data e hora da criação do registro. |
| updatedIn | LocalDateTime | Data e hora da última atualização do registro. |
Valores de status:
- AGUARDANDO_PROCESSAMENTO
- PROCESSANDO
- SUCESSO
- ERRO
- CANCELADO
Parcelas do parcelamento
GET https://tributos.suite.betha.cloud/parcelamentos/v1/simulacao/{key}/parcelas
Retorna a lista paginada de parcelas geradas.
Composição do parcelamento
GET https://tributos.suite.betha.cloud/parcelamentos/v1/simulacao/{key}/composicao
Retorna a lista paginada da composição detalhada da simulação. Cada item corresponde a uma receita de um lançamento incluído.
Criação do parcelamento
Com a simulação concluída com sucesso, é possível efetuar a criação do parcelamento. Nessa etapa, o parcelamento é persistido na base de dados do Tributos (Cloud) e os lançamentos incluídos passam a ter situação de parcelado.
A criação também é assíncrona: o serviço retorna imediatamente um identificador e o processamento ocorre em segundo plano.
Iniciando a criação
POST https://tributos.suite.betha.cloud/parcelamentos/v1/criacao
O corpo da requisição deve conter os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idSimulacao | String | Sim | ID da simulação retornado pelo POST /simulacao. Deve referenciar uma simulação com status SUCESSO. |
| idUsuario | String | Sim | Identificador do usuário responsável pela criação do parcelamento. |
| nomeCompletoUsuario | String | Sim | Nome completo do usuário responsável. |
| cpfCnpjUsuario | String | Sim | CPF ou CNPJ do usuário responsável. |
| nroProcesso | String | Não | Número do processo associado ao parcelamento, se houver. |
A resposta retorna um identificador (string) que deve ser utilizado para consultar o resultado.
Comportamento em caso de reenvio
O serviço verifica se já existe uma criação para a simulação informada antes de iniciar um novo processamento:
- Se a criação existente estiver com status AGUARDANDO_PROCESSAMENTO, PROCESSANDO ou SUCESSO, o mesmo identificador é retornado sem iniciar um novo processamento.
- Se a criação existente estiver com status ERRO, uma nova tentativa é iniciada e um novo identificador é retornado.
Isso garante que chamadas duplicadas acidentais não gerem parcelamentos em duplicidade.
Consultando o parcelamento criado
Endpoint: GET https://tributos.suite.betha.cloud/parcelamentos/v1/criacao/{key}
Onde {key} é o identificador retornado pelo POST.
A resposta contém os seguintes campos:
| Campo | Tipo | Descrição |
|---|---|---|
| id | ObjectId (String) | Identificador da criação. |
| statusParcelamento | String | Status do parcelamento. |
| idSimulacao | ObjectId (String) | ID da simulação utilizada como base. |
| idParcelamento | Long | ID do parcelamento criado na base de dados do Tributos (Cloud). |
| protocoloTermoParcelamento | String | Protocolo do termo de parcelamento gerado. |
| nroProcesso | String | Número do processo informado na criação, se houver. |
| idUsuario | String | Identificador do usuário responsável. |
| nomeCompletoUsuario | String | Nome completo do usuário responsável. |
| cpfCnpjUsuario | String | CPF ou CNPJ do usuário responsável. |
| mensagem | String | Mensagem de erro, caso o processamento tenha falhado. |
| databaseId | Integer | Identificador do banco de dados. |
| createdBy | String | Identificação do usuário que criou o registro. |
| updatedBy | String | Identificação do usuário que realizou a última atualização. |
| createdIn | LocalDateTime | Data e hora da criação do registro. |
| updatedIn | LocalDateTime | Data e hora da última atualização do registro. |
Termo de parcelamento
Após a criação do parcelamento, o sistema emite automaticamente o termo de parcelamento.
O campo protocoloTermoParcelamento retornado pelo GET /criacao/{key} após status SUCESSO corresponde ao protocolo de emissão do termo. Esse protocolo pode ser utilizado como filtro para localizar o documento neste endpoint.
GET https://tributos.suite.betha.cloud/parcelamentos/v1/termos-parcelamentos
Exemplos de parâmetro de filtro:
- ?filter=protocoloEmissao={protocoloTermoParcelamento}
- ?filter=parcelamento.id={idParcelamento}