[Melhoria] Financeiro: Contratos Financeiros – Novo Campo de Data da Operação na Inclusão de Receitas via API

Agora no Bluesoft ERP, é possível informar a data da operação na inclusão de receitas de contratos financeiros de aluguel através da API.

Objetivo

O objetivo desta melhoria é garantir que receitas futuras de aluguel geradas via integração sejam alocadas na competência contábil e fiscal correta. Dessa forma, a duplicata gerada é considerada na competência adequada pela contabilidade.

O Que Mudou?

Como Era o Processo Antes?

Antes, a API de inclusão de receitas (POST /api/financeiro/contratos/{contratoFinanceiroKey}/receitas) não possuía o campo dataOperacao disponível em seu payload. Por conta da ausência desse campo, o sistema utilizava automaticamente a data de emissão enviada na requisição para preencher a data da operação do lançamento.

Esse cenário impedia que a integração enviasse uma data de operação diferente da emissão. Com isso, as receitas futuras de aluguel frequentemente ficavam com a data de operação desvinculada da competência desejada, gerando impactos contábeis.

Como Irá Funcionar a Partir de Agora?

Para utilizar a nova funcionalidade, o integrador fará o envio da requisição no endpoint POST /api/financeiro/contratos/{contratoFinanceiroKey}/receitas.

1. Novo Campo no Payload: Foi adicionado o campo opcional dataOperacao na estrutura da requisição.
2. Modelos Permitidos: O campo opcional dataOperacao é aceito exclusivamente nos contratos dos tipos:
   • Cobrança de aluguel de imóvel
   • Cobrança de aluguel de equipamento
   • Cobrança de aluguel de quiosque
3. Formato: O campo só aceita datas no formato exato DD/MM/AAAA, sem o envio de horário.
4. Registro na Duplicata: Quando a dataOperacao for informada com sucesso, o sistema a utilizará como referência para a geração e escrituração. O valor será gravado nos campos de data da operação e data de entrada/prestação de serviço da duplicata financeira.
5. Comportamento Padrão (Sem Envio da dataOperação): Caso a requisição seja enviada sem o preenchimento do campo dataOperacao, a API manterá o funcionamento legado, onde a data da operação assume o mesmo valor da data de emissão.

Benefícios da Solução:

• O integrador consegue gerar receitas de aluguel com a data de operação exatamente compatível com a competência contábil pretendida.
• Elimina a inconsistência no reflexo contábil para lançamentos de períodos futuros.

Observações Importantes!

• Permissão Necessária: A rotina exige a permissão “2595 – Incluir Receita”, que permite a inclusão de receitas em contratos financeiros.
• Bloqueio de Período Encerrado: Se a dataOperacao enviada pertencer a uma competência contábil ou fiscal já encerrada na loja, o sistema bloqueará a geração da duplicata e retornará um erro de validação.
• Restrição para Outros Contratos: O modelo “Receita não operacional” não aceita o novo campo. Qualquer envio de data de operação para este modelo será rejeitado com a seguinte mensagem de erro: “Este modelo de contrato não aceita o campo dataOperacao.”.
• Formatos Inválidos: Tentativas de envio em formatos fora do padrão estipulado (como o formato ISO com horário) não serão concluídas e exibirão erro de validação.
• Validações de Regra de Negócio: Todas as exigências anteriores dos modelos de aluguel continuam mantidas, incluindo a obrigatoriedade de tributação, parcelas, valores, e centros de resultado.

Exemplo de JSON da Requisição POST:

{
    "numeroDocumento": {{numeroDocumento}},
    "dataOperacao": "25/12/2026",
    "dataEmissao": "16/08/2026",
    "formaPagamento": "DINHEIRO",
    "parcelas": [
        {
            "descritivo": "TESTE API",
            "valorNominal": 100,
            "desconto": 1,
            "juros": 1,
            "multa": 1,
            "dataVencimento": "30/01/2026"
        }
    ],
    "tributacoes": {
        "valorBaseCalculoPisCofins": 1,
        "pisAliquota": 1.58,
        "cofinsAliquota": 7.26,
        "cstPisCofins": 2
    }
}

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.