Integração de Lançamentos
Visão Geral
O serviço de integração disponibilizado permite que sejam gerados lançamentos no Tributos (Cloud) vinculados a três classificações diferentes de referentes, são eles:
- Econômicos;
- Contribuintes;
- Receitas diversas.
Para lançamentos por econômico ou contribuinte, é necessário sempre informar o valor lançado diretamente.
Para as receitas diversas, seguindo o mesmo funcionamento da funcionalidade no Tributos (Cloud), é possível gerar o lançamento informando diretamente o valor lançado, ou informar os dados necessários para que seja executada uma fórmula de cálculo que defina o valor das receitas do lançamento.
Além disso, ao mesmo tempo em que pode ser gerado o lançamento, também pode ser gerado e retornado o número de baixa, código de barras e o documento/PDF da guia, como poderá ser visto mais abaixo.
Configuração
O primeiro passo para utilizar a ferramenta é fazer a configuração dos tipos de lançamentos que serão gerados pelo serviço, vinculando-os com seus respectivos créditos tributários.
A configuração pode ser acessada por meio do menu Utilitários > Central de configurações > Integração de lançamentos > Sistemas de terceiros.
|
|---|
Nessa tela, deve ser adicionada uma configuração para cada tipo de lançamento a ser gerado, definindo os campos:
- Tipo de lançamento no sistema parceiro: Campo que define uma chave única para o tipo de lançamento a ser gerado.
- Referente: O tipo de referente do lançamento (econômico, contribuinte ou receita diversa).
Para lançamentos de receitas diversas com os valores definidos por fórmula de cálculo, é necessário informar o campo Tipo de serviço. Os tipos de serviço são configurados na configuração de Receitas diversas, também presente na Central de configurações, onde é feito o vínculo entre os créditos tributários e os tipos de serviço (agrupamentos).
Voltando ao serviço de integração, ao ser selecionado um tipo de serviço no cadastro da configuração, o campo crédito é resgatado automaticamente (conforme a configuração de receitas diversas).
Para lançamentos de receitas diversas com os valores informados diretamente (sem execução de fórmula), lançamentos de econômicos ou lançamentos de contribuintes, é necessário informar na configuração de integração os campos:
- Crédito: O crédito tributário do lançamento;
- Receita: A receita para qual o valor principal do lançamento será lançado.
Os seguintes campos também devem ser informados independentemente do tipo de referente:
- Taxa de expediente: opcional, para os lançamentos que possuem um valor de taxa de expediente vinculado ao lançamento do valor principal.
- Convênio: O convênio contendo os dados que serão utilizados no processo de emissão da guia (documento) do lançamento gerado.
- Sistema de origem: Identificação do sistema que originou o lançamento, para ser demonstrado no módulo Atendimento do Tributos (Cloud).
No Json, existe a possibilidade de enviar o indexador ao qual será gerado o lançamento. Não é obrigatório, mas caso não informado irá considerar o indexador que estiver configurado com a opção Moeda do país. Caso não existir um indexador com esta configuração e não for informado no Json, irá apresentar inconsistência.
Receitas diversas por Tipo de serviço (execução de fórmula)
Para o funcionamento da integração de lançamentos referentes as receitas diversas, com valor definido pela execução de fórmula de cálculo, além da configuração da integração, é necessário que haja uma fórmula de cálculo cadastrada no Tributos (Cloud) para o crédito tributário vinculado ao tipo de serviço informado na configuração, e para o ano de lançamento recebido no corpo da requisição de integração.
O serviço de integração permite que sejam passados para a fórmula parâmetros customizados conforme os padrões de campos adicionais do Tributos (Cloud), conforme o exemplo a seguir:
|
|---|
Tendo o cenário acima de campos adicionais no cadastro de receitas diversas, os mesmos valores seriam informados da seguinte forma pelo serviço (no formato JSON):
|
|---|
A chave de cada campo no mapa de camposAdicionais deve ser o título do campo adicional no Tributos (Cloud), exatamente como está no Tributos (com a mesma acentuação e espaçamento)
Já o valor do campo deve ser informado entre aspas duplas, exceto quando se tratar dos campos numéricos (inteiros ou decimais). Para campos de seleção (opções predefinidas), deve ser informado o “título” de cada campo, seguindo as mesmas regras de título já exemplificadas, separando-os por vírgula (caso haja mais de um campo selecionado no campo adicional do tipo Múltipla Opção).
Importante Caso o nome do campo (chave do campo) não estiver exatamente como o título do campo adicional no Tributos (Cloud), será apresentada uma inconsistência, informando que o campo não existe ou que foi alterado.
Gerando o lançamento e emitindo a guia de pagamento
Conforme mencionado acima, ao mesmo tempo em que será gerado o lançamento, também poderá ser gerado e retornando o número de baixa, código de barras e o documento/PDF da guia vinculada ao lançamento gerado, dependendo das informações enviadas. Sendo assim, será executado de forma automática a API de emissão de guias, conforme documentação.
Para isso, foram disponibilizados dois campos que possibilitam a execução da rotina com esses resultados, sendo eles:
emitirGuia: Quando informado True nesse campo, será executado o relatório referente a guia configurada no convênio, com isso, gerando a guia e retornando os atributos nroBaixa e o codigoBarras. Não será retornado o documento PDF (URL do documento). Terá o mesmo efeito que o da execução da API de emissão de guias, mas com o campo emitirDocumento = false (ver documentação de emissão de guias).
gerarDocumento: Quando informado True nesse campo, além de emitir, gerar a guia conforme parâmetro anterior, irá retornar os atributos nroBaixa, codigoBarras e urlDocumento. Este com o valor (https://consultaexecucoes.plataforma.betha.cloud/#/<protocolo_execucao>/resultado) do PDF da guia. Terá o mesmo efeito que da execução da API de emissão de guias, mas com o campo emitirDocumento=true (ver documentação de emissão de guias).
Observação: Não há necessidade utilizar/informar o campo emitirGuia caso for utilizado o campo gerarDocumento = true, pois subetende-se que automaticamente o valor do campo emitirGuia será true.
Número de baixa previamente reservado
Para os casos em que foi reservado um número de baixa específico para o lançamento antes da sua geração, devem ser informados os atributos nroBaixa e codigoBarras no JSON da requisição de geração do lançamento.
Regras básicas sobre a integração do lançamento
- Quando o referente relacionado a 'chaveLancamento' for do tipo ECONÔMICO
- O objeto 'economico' é obrigatório
- Somente podem ser informados os atributos 'codigo', 'cpfCnpj' e/ou 'id'
- Se informar somente o 'id' ou o 'id' e o 'cpfCnpj', ou somente o 'cpfCnpj', obrigatoriamente deverá ser informado o objeto 'pessoa', informando pelo menos um destes atributos: 'codigo', 'nome', 'cpfCnpj' ou 'id'
- Quando o referente relacionado a 'chaveLancamento' for do tipo CONTRIBUINTE
- O objeto 'contribuinte' é obrigatório
- Somente podem ser informados os atributos 'id', 'codigo', 'nome' e/ou 'cpfCnpj'
- Quando o referente relacionado a 'chaveLancamento' for do tipo RECEITA DIVERSA
- O objeto 'contribuinte' ou o 'economico' são obrigatórios
- Se informar o objeto 'contribuinte' somente podem ser informados os atributos 'id', 'codigo', 'nome' e/ou 'cpfCnpj'
- Se informar o objeto 'economico' somente podem ser informados os atributos 'codigo', 'cpfCnpj' e/ou 'id'
- Se informar somente o 'id' ou o 'id' e o 'cpfCnpj', ou somente o 'cpfCnpj', obrigatoriamente deverá ser informar o objeto 'pessoa', informando pelo menos um destes atributos: 'codigo', 'nome', 'cpfCnpj' ou 'id'
- Em casos onde se faz necessário criar lançamentos idênticos em sequencia, o sistema tem uma validação para evitar duplicidades ou inconsistências nas requisições, nestes casos, pode ser enviado no campo observacoesReceitaDiversa alguma informação que diferencie um lançamento do outro, exemplo:
- {"observacoesReceitaDiversa": "Referente ao lançamento de XXX"}
Em relação aos econômicos, para os referentes do tipo ECONÔMICO e RECEITAS DIVERSAS, se no objeto 'economico' for informado somente o cpfCNPJ, irá sempre gerar o lançamento para o econômico que estiver indicado como principal SIM, pois como é permitido ter mais de um econômico para o mesmo CNPJ, essa será a regra. Caso seja necessário gerar o lançamento à um econômico específico, deverá ser informado o ID ou Código