Agora no Bluesoft ERP, é possível cadastrar contratos financeiros do tipo Tomada de Serviço de Prestador Municipal diretamente via API pública, permitindo a integração e automação no cadastro de contratos de despesa vinculados a serviços tomados de prestadores municipais.

O objetivo desta novidade é expandir as integrações do módulo Financeiro, permitindo que sistemas externos cadastrem automaticamente contratos de despesa no ERP com as mesmas validações, regras operacionais, fiscais e contábeis já aplicadas na interface do sistema.

O Que Mudou?

Como Era o Processo Antes?

Antes, o cadastro de contratos financeiros do tipo Tomada de Serviço de Prestador Municipal estava disponível apenas manualmente pela interface do ERP (no caminho Financeiro > Contratos Financeiros > Consultar). A ausência de uma API pública específica limitava a automação de integrações externas que precisavam criar esse tipo de contrato de despesa de forma integrada.

Como Irá Funcionar a Partir de Agora?

A partir de agora, as integrações externas contam com uma nova rota via API (POST /api/financeiro/contratos/tomada-servico-prestador-municipal) para realizar o cadastro desses contratos no ERP de forma totalmente automatizada e segura.

Benefícios:

Automação de Integrações: Elimina a necessidade de digitação manual de contratos no ERP.
Garantia de Regras de Negócio: Aplica no momento do recebimento da requisição as mesmas validações fiscais, financeiras e contábeis exigidas pelo ERP.
Agilidade no Fluxo de Contas a Pagar: Permite que contratos criados via integração fiquem prontos para o lançamento subsequente de notas fiscais e despesas.

Como Irá Funcionar?

A nova rota pública estará disponível via método HTTP POST.

Endpoint: POST /api/financeiro/contratos/tomada-servico-prestador-municipal
Permissão Necessária: 263 - Contrato Financeiro Incluir

Para a criação do contrato via API, o sistema aplicará o seguinte fluxo de validação e parametrização:

Identificação do Prestador:
- O prestador é informado pelo campo cpfCnpjPrestador.
- O sistema valida se a pessoa física ou jurídica está cadastrada no ERP, se está ativa e configurada como prestadora de serviço.
Lojas e Rateio:
- Permite vincular uma ou mais lojas ao contrato (lojaKeys).
- A funcionalidade de rateio só será permitida quando o contrato for cadastrado sem nota fiscal e possuir mais de uma loja vinculada.
Vigência e Periodicidade:
- Suporta tipos de periodicidade como EVENTUAL, MENSAL, SEMANAL, QUINZENAL, TRIMESTRAL ou ANUAL.
- Permite definir datas de vigência inicial e final, ou vigência indeterminada.
Regras Fiscais e Tributação:
- Permite indicar se o contrato exige nota fiscal (exigeNotaFiscal). Quando for true, o preenchimento do tipo de nota fiscal de serviço (tipoNfServico) é obrigatório.
- Suporta a vinculação da natureza de rendimento (naturezaRendimentoKey).
- Permite indicar se o serviço é de transporte (servicoDeTransporte) e parametrizar impostos e retenções (como INSS, ISS retido, IRRF, CSLL, ISS normal, PIS, COFINS e CST PIS/COFINS).
Forma de Pagamento e Conta Caixa:
- Permite definir formas de pagamento (ex: Boleto, Pix, Dinheiro).
- Caso a forma de pagamento seja Dinheiro, é obrigatório informar a conta caixa correspondente para cada loja (contaCaixaLojas).
Contabilidade e Orçamento:
- Exige a definição das contas contábeis de origem e destino, validando que a conta de origem seja diferente da de destino.
- Exige conta contábil de apropriação para vigências superiores a 1 mês.
- Permite parametrizar a distribuição por Centro de Resultados e Canais de Venda (validando o total de 100%).
- Permite o vínculo com o orçamento da loja (orcamentoDaLojas).

Observações / Validações Importantes

Tipo Fixo e Sinal Financeiro: Todo contrato cadastrado através desta nova rota é criado automaticamente com o tipo Tomada de Serviço de Prestador Municipal e sinal financeiro de despesa (-1).
Validação de Dados: Requisições enviadas com dados faltantes, inconsistências contábeis, prestadores inativos ou percentuais de rateio/centro de resultado divergentes de 100% serão rejeitadas com mensagens de erro específicas (HTTP 4xx), sem persistência parcial no banco de dados.
Segurança e Rastreabilidade: Todas as criações via API registram o usuário solicitante, data/hora e a origem para fins de auditoria.

Exemplo de JSON:

{
    "descritivo": "Contrato de serviços municipais",
    "dataVigenciaInicial": "01/01/2026",
    "dataVigenciaFinal": "31/12/2026",
    "vigenciaIndeterminada": false,
    "contaContabilOrigem": 3070010009,
    "contaContabilDestino": 1010010001,
    "contaContabilApropriacao": 3020010029,
    "tipoPeriodicidade": "EVENTUAL",
    "tipoValor": "VARIAVEL",
    "diaVencimentoDuplicata": null,
    "mesVencimentoDuplicata": null,
    "mesesVigencia": 12,
    "permiteAdiantamento": true,
    "lojaPodeCriarDespesa": true,
    "bloquearAlteracaoDasContasContabeisNosLancamentos": true,
    "utilizarCicloPagamento": "SIM_DEFINIR_MANUALMENTE",
    "diasFixosCicloDePagamento": [
        5,
        20
    ],
    "cpfCnpjPrestador": "12344564000122",
    "naturezaRendimentoKey": 46,
    "valorMaximo": 5000.00,
    "valorMaximoDoPeriodo": null,
    "valorMaximoDespesa": null,
    "exigeNotaFiscal": false,
    "tipoNfServico": null,
    "servicoDeTransporte": false,
    "tipoDeIss": "ISS_NORMAL",
    "inss": 0.00,
    "issRetido": 0.00,
    "irrf": 1.50,
    "csll": 1.00,
    "issNormal": 5.00,
    "pis": 0.65,
    "cofins": 3.00,
    "cstPisCofins": 50,
    "aliquotaPis": 0.65,
    "aliquotaCofins": 3.00,
    "tipoFormaPagamento": "DINHEIRO",
    "prazosParcela": [
        {
            "parcela": 1,
            "dias": 30
        },
        {
            "parcela": 2,
            "dias": 60
        }
    ],
    "centroResultados": [
        {
            "centroResultadoKey": 5411,
            "porcentagem": 60.00,
            "canaisDeVenda": [
                {
                    "canalVendaKey": 2,
                    "porcentagem": 100.00
                }
            ]
        },
        {
            "centroResultadoKey": 5414,
            "porcentagem": 40.00,
            "canaisDeVenda": [
                {
                    "canalVendaKey": 2,
                    "porcentagem": 100.00
                }
            ]
        }
    ],
    "permiteRateio": true,
    "permiteRateioContabilEntreFiliais": true,
    "rateioFilial": [
        {
            "lojaKey": 1,
            "percentual": 100.00,
            "recebeDiferenca": true
        },
        {
            "lojaKey": 4,
            "percentual": 30.00,
            "recebeDiferenca": true
        }
    ],
    "contaCaixaLojas": [
        {
            "lojaKey": 1,
            "contaCaixaKey": 2
        },
        {
            "lojaKey": 4,
            "contaCaixaKey": 3
        }
    ],
    "lojaKeys": [
        1,
        4
    ],
    "vincularOrcamentoDaLoja": true,
    "orcamentoDaLojas": [
        {
            "orcamentoProjetoKey": 3,
            "lojaKey": 1,
            "valorDoContrato": 123
        },
        {
            "orcamentoProjetoKey": 4,
            "lojaKey": 4,
            "valorDoContrato": 1
        }
    ]
}

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.

Disponível a partir da versão r370.88

[Novidade] API: Financeiro – Inclusão de Contrato Financeiro de Tomada de Serviço de Prestador Municipal via API