Agora no Bluesoft ERP, é possível incluir um contrato de fornecimento via API
Com o objetivo de permitir que sistemas externos realizem o fluxo completo dos contratos de fornecimento e de proporcionar maior agilidade nos processos de compras, desenvolvemos uma nova API REST no módulo de Compras do Bluesoft ERP.
Anteriormente, o cadastro de contratos só era possível através da tela do ERP, restando à integração externa apenas a consulta. Agora, as plataformas de terceiros poderão criar novos contratos diretamente via integração, validando todas as regras de negócio.
Detalhes da Nova API:
• Endpoint: POST /api/compras/contratosdefornecimento
• Permissão Necessária: 4358 - API Contratos de Fornecimento (Incluir)
Exemplo de JSON:
{
"fornecedorKey": 4102,
"divisaoKey": 1,
"vigenciaInicial": "01/11/2025",
"vigenciaFinal": "31/12/2025",
"tipoFornecimento": "TEMPORARIO",
"diasEntrega": 1,
"intervaloVisita": 1,
"diasTolerancia": 1,
"faturamentoMinimo": 0,
"distribuicaoCdCrossDocking": true,
"prazoPagamento": {
"tipoFrete": "CONTRATACAO_DO_FRETE_POR_CONTA_DO_REMETENTE",
"formaPagamento": "BOLETO_BANCARIO",
"referenciaPrazo": "DATA_DE_FATURAMENTO_DO_FORNECEDOR",
"tipoPagamento": "PARCELA_UNICA_COM_PRAZO",
"condicaoPagamento": "A_VISTA",
"dataVencimento": "01/01/2026",
"descontoFinanceiro": 10,
"tipoBaseCalculo": "BASEADO_NAS_MERCADORIAS",
"prazosPagamento": [
{
"quantidadeDias": 30,
"percentualFatura": 100
}
]
},
"prazoRecebimento": {
"pagamentoFidelidade": "FORMA_PAGAMENTO_BONIFICACAO_MERCADORIAS",
"pagamentoAniversario": "FORMA_PAGAMENTO_BONIFICACAO_MERCADORIAS",
"devolucaoAtoRecebimento": "FORMA_PAGAMENTO_BONIFICACAO_MERCADORIAS",
"devolucaoAposRecebimento": "FORMA_PAGAMENTO_BONIFICACAO_MERCADORIAS",
"tipoRecebimento": "PARCELA_UNICA_COM_PRAZO",
"condicaoRecebimento": "A_VISTA",
"dataVencimento": "01/04/2026",
"prazosRecebimento": [
{
"quantidadeDias": 15,
"percentualFatura": 100
}
]
},
"trocas": {
"descartarTrocas": true,
"lancarNaContaFornecedor": true,
"porcentagemSobreCompras": 100,
"armazenarTrocas": false,
"autorizarRetirada": false,
"retiraTrocaAtoEntrega": true
},
"acordoComercial": {
"desconsiderarDevolucaoAtoBaseCalculo": true,
"gerarFormaDuplicataCobrancaAcordosRecebimentoMercadorias": true,
"acordosComerciais": [
{
"tipoLancamentoKey": 1,
"percentual": 50,
"baseCalculo": "BASEADO_EM_NOTA_FISCAL",
"tipoDataLancamento": "DATA_CONFIRMACAO_NF",
"dataVigenciaInicial": "01/01/2026",
"dataVigenciaFinal": "01/02/2026"
}
],
"prazoRecebimentoParaAcordosComerciais": {
"tipoRecebimento": "PARCELA_UNICA_COM_PRAZO",
"formaRecebimento": "BOLETO_BANCARIO",
"dataVencimento": "01/04/2026",
"prazoRecebimento": [
{
"quantidadeDias": 15,
"percentualFatura": 100
}
]
}
},
"performanceFornecedor": {
"baseCalculo": "BASEADO_EM_NOTA_FISCAL",
"tipoDataLancamento": "DATA_CONFIRMACAO_NF",
"performance": "COMPRAS",
"periodicidade": "EVENTUAL",
"lojasParticipantes": [
1
],
"tipoCrescimento": "PERCENTUAL",
"tipoRetorno": "PERCENTUAL",
"faixasDosValores": [
{
"valorMinimoFaixaPerformance": 0.1,
"valorMaximoFaixaPerformance": 0.1,
"porcentagemRetornoGeral": 0.1
}
]
},
"modeloContratoKey": 0,
"clausulaContratoKeys": [
0
],
"utilizarCicloPagamento": "NAO"
}O que é possível enviar através desta API? A nova estrutura permite o envio de um payload completo para formalizar o contrato com o fornecedor, incluindo:
• Dados Gerais: Chaves do fornecedor e divisão, datas de vigência inicial e final, tipo de fornecimento e prazos de entrega e visita.
• Cláusulas Contratuais: É obrigatória a vinculação de pelo menos uma cláusula de contrato válida.
• Prazos de Pagamento e Recebimento: Configuração detalhada de condições de frete, formas de pagamento, parcelas, percentuais de fatura e descontos financeiros.
• Políticas de Troca: Definições sobre autorização de retirada, armazenamento, descarte e distribuição Cross-Docking.
• Acordos Comerciais: Inclusão de acordos comerciais (como “Fidelidade na Entrada de Mercadorias”), sendo que o ERP salva automaticamente apenas os acordos enviados com percentual maior que zero.
• Performance do Fornecedor (Opcional): É possível enviar os dados de metas e periodicidade para acompanhar o desempenho do fornecedor, definindo faixas de performance e tipos de retorno.
Regras de Negócio e Validações: A API foi construída para manter a integridade dos dados do ERP, garantindo as mesmas validações de tela:
• Status do Contrato: O status final do contrato criado será atribuído automaticamente conforme o parâmetro do sistema “Definição de status padrão para criação de novos contratos de fornecimento”.
• Consistência de Dados: Há validações estritas para formatos de data (dd/MM/yyyy HH:mm), obrigatoriedade de divisão ativa, e a verificação de que a soma dos percentuais das faturas resulte em exatamente 100%.
Retornos: Em caso de sucesso na inclusão, a API retornará o status 201 Created, contendo a chave do contrato recém-criado (contratoFornecimentoKey). Em caso de divergências ou regras violadas, a API retornará 400 Bad Request com mensagens claras e específicas informando qual validação impediu o cadastro.
Para visualizar a documentação técnica completa, com os schemas detalhados, dicionário de dados (ENUMs válidos) e exemplos práticos de requisição JSON, consulte a documentação de APIs.
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.