Agora no Bluesoft ERP, é possível criar acordos comerciais diretamente via integração de API de forma automatizada, sem a necessidade de digitação ou inclusão manual através da interface do sistema.

Objetivo

O objetivo desta novidade é permitir a integração ágil de negociações comerciais externas diretamente com o ERP, garantindo que os acordos sejam registrados de forma simples, padronizada e segura na conta comercial do fornecedor.

O Que Mudou?

Como Era o Processo Antes?

Antes, embora já existissem APIs para consultas e apurações pontuais, a inclusão direta e avulsa de um novo acordo comercial só podia ser realizada manualmente através da tela do sistema. Quando o cliente possuía negociações ou contratos originados em sistemas externos, era necessário digitar cada informação manualmente na interface do ERP, o que gerava gargalos operacionais e dependência de digitação manual.

Como Irá Funcionar a Partir de Agora?

A partir de agora, foi disponibilizado o novo endpoint POST /api/compras/acordos-comerciais, permitindo realizar a inclusão direta de acordos comerciais de forma totalmente integrada.

A nova API atende às seguintes capacidades e regras do processo:

  • Formatos de Acordo Suportados:
    • Acordo Simples: Inclusão direta para uma única loja ou distribuição.
    • Acordo Agrupado: Criação de um único acordo comercial englobando múltiplas lojas, respeitando o parâmetro de agrupamento do sistema.
    • Vínculo com Pedido: Possibilidade de vincular o acordo comercial a um pedido de compras válido e compatível com a divisão do fornecedor.
    • Parcelamento: Suporte ao parcelamento (de 1 a 99 parcelas) para lançamentos de débito, com distribuição de vencimentos mensais a partir da data informada.
  • Automação e Consistência de Regras:
    • Sinal do Lançamento: O sinal (débito ou crédito) é derivado automaticamente a partir do tipo de lançamento informado, garantindo a integridade dos saldos.
    • Validação de Fornecedor de Impressão: O fornecedor de impressão deve obrigatoriamente ser o fornecedor principal ou uma de suas filiais cadastradas.
    • Competência Contábil: O sistema valida a competência contábil de todas as lojas envolvidas, impedindo a gravação em períodos encerrados ou bloqueados.
  • Retorno do Endpoint: Ao concluir a inclusão com sucesso, a API retorna o status HTTP 201 com a lista contendo o(s) número(s) do(s) acordo(s) gerado(s) para acompanhamento e auditoria.

Observações Importantes!

  • Permissão de Acesso: O acesso ao novo endpoint é restrito e exige a atribuição da nova permissão específica 4704 – API Acordos Comerciais (Incluir). Requisições sem esta permissão receberão o retorno de acesso negado (HTTP 401).
  • Escopo de Lojas e Setor de Compra: A API valida se o setor de compra informado está ativo e se a credencial utilizada possui permissão de acesso a todas as lojas da distribuição.
  • Tipos de Lançamento Permitidos: Não é permitida a inclusão utilizando tipos de lançamento de ajuste, estorno, sistêmicos ou marcados como ignorados; apenas tipos de lançamento disponíveis para uso manual são aceitos.
  • Fornecedor Destino: As informações de fornecedor e divisão de destino pertencem exclusivamente ao fluxo de apuração de acordos e não fazem parte do contrato de inclusão direta.

Exemplo de JSON da Requisição POST:

{
    "fornecedorKey": 12345,
    "fornecedorDivisaoKey": 1,
    "setorCompraKey": 10,
    "tipoLancamentoKey": 301,
    "modeloAcordoComercialKey": 1,
    "fornecedorImpressaoKey": 12345,
    "formaPagamento": "BOLETO_BANCARIO",
    "dataCompetencia": "01/08/2026",
    "descricaoAcordo": "Acordo comercial criado por integração",
    "representanteKey": 23456,
    "negociadorKey": 34567,
    "pedidoKey": 987654,
    "gerarAcordoComercialAgrupado": true,
    "lojaParaImpressaoKey": 1,
    "quantidadeParcelas": 3,
    "vencimentoComercial": "30/09/2026",
    "distribuicoes": [
        {
            "lojaKey": 1,
            "valor": 600.00,
            "observacao": "Distribuição referente à loja 1"
        },
        {
            "lojaKey": 2,
            "valor": 300.00,
            "observacao": "Distribuição referente à loja 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.

Disponível a partir da versão r371.60