Agora no Bluesoft ERP, é possível realizar a inclusão automatizada de despesas vinculadas a contratos financeiros do tipo Consumo de Água por meio de integração via API.
Objetivo
O objetivo desta novidade é automatizar os lançamentos de despesas de consumo de água provenientes das contas das lojas. Isso elimina a dependência de processos manuais, reduz o esforço operacional, agiliza o tempo de processamento e mitiga o risco de divergências entre as contas recebidas e as despesas efetivamente registradas no ERP.
O Que Mudou?
Como Era o Processo Antes?
Antes, embora o ERP permitisse o cadastro do contrato financeiro de Consumo de Água por API, o lançamento da respectiva despesa só podia ser realizado de forma manual por meio da tela do sistema. A API genérica existente para inclusão de despesas atendia estritamente a operações de profissionais liberais/autônomos, pagamento de royalties e aluguel de imóvel. Quando o cliente recebia as contas de água, não havia uma rota pública disponível para automatizar o envio desses dados e gerar a despesa.
Agora, disponibilizamos uma nova rota de API exclusiva para os contratos de Consumo de Água (POST /api/financeiro/contratos/{contratoFinanceiroKey}/despesas/consumo-agua). A solução atende contratos com e sem exigência de nota fiscal, permitindo a geração automática da despesa, a criação de suas duplicatas e a realização da contabilização adequada, tudo por integração.
Benefícios:
- Automação completa do fluxo de contas a pagar de consumo de água.
- Eliminação do retrabalho e dos gargalos causados por lançamentos manuais.
- Integração ágil e centralizada com sistemas externos para a geração de duplicatas.
Como Irá Funcionar a Partir de Agora?
- O integrador deverá realizar a chamada para a nova rota específica utilizando o método
POST /api/financeiro/contratos/{contratoFinanceiroKey}/despesas/consumo-agua. - A requisição será aceita e processada apenas para os contratos do tipo “Consumo de Água” que estejam ativos e vigentes.
- O payload enviado deve conter obrigatoriamente os dados básicos da transação, como
numeroDocumento(positivo numérico de até 9 dígitos),dataEmissao,formaPagamentoe, no mínimo, uma parcela declarada na lista deparcelas. - Exigência de Nota Fiscal: Se o contrato exigir nota fiscal, o integrador deverá enviar obrigatoriamente o bloco
notaFiscal, englobando os camposserieNotaFiscal,dataEntrada,tipoClasseConsumoKey,cfopKeye umachaveAcessoválida (44 caracteres). Em seguida, o ERP gerará a Nota Fiscal Modelo 29. Se o contrato não exigir nota fiscal, o envio excessivo desses dados causará a recusa integral da operação. - Rateio Contábil: A rota não permite incluir despesas para contratos que possuam rateio contábil entre filiais habilitado. Nessa situação, a requisição é recusada antes da criação de despesa, nota fiscal, duplicata ou lançamento contábil.
- Centro de Resultado: Quando configurado como obrigatório pelos parâmetros contábeis da loja, o integrador deverá informar ao menos um centro de resultado válido. As porcentagens dos centros e dos canais de venda devem totalizar 100%.
- Quitação Imediata: O integrador tem a opção de preencher o campo
dataQuitacaoDuplicatapara gerar a despesa e quitá-la instantaneamente. A quitação imediata só é aplicável para o caso de despesas com uma parcela única, para despesas com mais de uma parcela, a operação deverá respeitar as regras de quitação definidas pelo ERP. - Retorno: Concluindo o processamento com sucesso (Status
201 Created), o sistema irá retornar a chave da despesa (despesaKey), as chaves das duplicatas, o status das duplicatas geradas e, caso aplicável, a chave da nota fiscal.
Observações / Validações
- Permissões de Acesso: O usuário da API precisará ter atrelada a si a nova permissão
4728 - API - Incluir despesas - consumo de água. - Bloqueio no Rateio do Contrato: O lançamento da despesa via API será rejeitado pelo sistema caso a opção de “Permite Rateio” contábil esteja habilitada nativamente na configuração do contrato dentro do ERP.
- Dados Fiscais: Quaisquer dados de impostos (PIS, COFINS e ICMS) enviados pela API vão prevalecer sobre as parametrizações do contrato exclusivamente para aquela despesa corrente, não alterando o seu cadastro base.
- Resiliência (Rollback): Qualquer falha sistêmica durante a tentativa de quitação imediata cancelará integralmente a operação (desfazendo a despesa, a nota fiscal e as duplicatas pendentes), impedindo registros parciais.
Exemplo de JSON da Requisição POST:
// POST {{baseURL}}/api/financeiro/contratos/{{contratoFinanceiroKey}}/despesas/consumo-agua
{
"numeroDocumento": {{numeroDocumentoUnico}},
"dataEmissao": "17/09/2026",
"formaPagamento": "PIX",
"parcelas": [
{
"descritivo": "Despesa de consumo de agua com nota fiscal",
"valorNominal": 100.0,
"desconto": 0.0,
"juros": 0.0,
"multa": 0.0,
"dataVencimento": "17/10/2026"
}
],
"impostos": {
"baseCalculoIssRetido": 0.0,
"baseCalculoInssRetido": 0.0,
"baseCalculoIrrfRetido": 0.0,
"pis": {
"cst": -1,
"aliquota": 0.0
},
"cofins": {
"cst": -1,
"aliquota": 0.0
},
"baseCalculoCsrf": 0.0,
"aliquotaInss": 0.0,
"aliquotaIrrf": 0.0,
"aliquotaIssRetido": 0.0,
"aliquotaCsll": 0.0,
"valorIrrfRetido": 0.0,
"valorInssRetido": 0.0,
"valorIssRetido": 0.0
},
"notaFiscal": {
"serieNotaFiscal": "1",
"subSerieNotaFiscal": "1",
"dataEntrada": "17/09/2026",
"codigoVerificacao": "{{codigoVerificacao}}",
"chaveAcesso": "{{chaveAcessoValida44Caracteres}}",
"tipoClasseConsumoKey": 10,
"cfopKey": 1556,
"valorDespesasNaoTributadas": 0.0,
"valorDespesasAcessorias": 0.0,
"baseCalculoPisCofins": 100.0,
"valorBaseIcms": 0.0,
"icmKey": 12
},
"centroResultados": [
{
"centroResultadoKey": 124,
"valor": 100.0,
"porcentagem": 100.0,
"canaisDeVenda": []
}
],
"centroResultadosGerenciais": [],
"dataQuitacaoDuplicata": "17/09/2026"
}Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.
Para saber mais sobre a utilização das APIs do ERP, clique aqui.