Agora no Bluesoft ERP, é possível informar a taxa de conveniência no corpo da requisição da API de inclusão de pedido e-commerce para e-commerces gerenciados pelo módulo de Pedido Balcão.

Objetivo

O objetivo desta melhoria é garantir que os pedidos de venda e-commerce integrados via API pública registrem o valor da taxa de conveniência no ERP, alinhando as integrações externas ao comportamento já existente em integrações internas (como 99 Compras, VTEX e iFood) e evitando divergências financeiras entre o valor do pedido no e-commerce e no ERP.

O Que Mudou?

Como Era o Processo Antes?

Antes, ao integrar um pedido de venda e-commerce por meio da API pública, o contrato da requisição não expunha o campo de taxa de conveniência.

Apesar de o fluxo interno do módulo de Pedido Balcão já possuir suporte para gravar a taxa de conveniência quando o valor estivesse preenchido, os integradores externos não conseguiam enviar essa informação. Como consequência, os pedidos podiam ser gravados sem a taxa de conveniência no ERP, resultando em divergência entre o valor total registrado pelo integrador/e-commerce e o total do pedido no ERP.

Como Irá Funcionar a Partir de Agora?

A partir de agora, o contrato da API pública de inclusão de pedidos e-commerce foi atualizado com a adição do campo taxaConveniencia.

  • Envio da Requisição (POST /api/venda/pedidovenda/e-commerce):
    • O novo campo taxaConveniencia é do tipo numérico monetário (decimal) e é opcional.
    • Aceita valores maiores ou iguais a zero, com precisão de até 6 dígitos inteiros e 3 casas decimais (6,3).
    • Quando o valor for informado (maior que zero) em um e-commerce gerenciado pelo módulo de Pedido Balcão, o sistema criará o pedido e gravará o valor da taxa de conveniência no Pedido Balcão correspondente.
    • Se o campo não for informado ou for enviado com o valor zero, o pedido será criado normalmente sem gravar taxa de conveniência.
  • Consulta do Pedido (GET /api/venda/pedidovenda/{pedidoVendaKey}):
    • Ao consultar um pedido e-commerce integrado com taxa de conveniência via API, o sistema retornará a taxa gravada no campo valorTaxaConveniencia.

Observações Importantes!

  • Escopo Exclusivo: O envio do campo taxaConveniencia é permitido exclusivamente para e-commerces com gerenciamento configurado para o módulo de Pedido Balcão.
  • Validação para Força de Vendas: Caso seja informado um valor positivo de taxa de conveniência para um e-commerce gerenciado pelo módulo de Força de Vendas, a API bloqueará a requisição e exibirá a mensagem de erro: “A taxa de conveniência só pode ser informada para e-commerce gerenciado pelo módulo de Pedido Balcão”.
  • Validação de Limites e Zeros: O campo não aceita valores negativos. Caso seja enviado um valor menor que zero ou excedendo o limite numérico (mais de 6 dígitos inteiros ou mais de 3 casas decimais), a requisição será rejeitada com erro de validação (HTTP 400).
  • Validação de Pagamento: Quando a opção de validar total do pagamento estiver ativa no e-commerce, o cálculo do valor total do pedido considerará a soma dos itens, frete e taxa de conveniência para bater com o valor total dos pagamentos.

Exemplo de JSON da Requisição POST:

{
    "numeroPedido": {{numeroPedido}},
    "ecommerceKey": 1,
    "tipoDeEntrega": "RETIRA_NA_LOJA",
    "valor_frete": 10,
    "taxaConveniencia": 10.549,
    "dadosDeEntrega": {
        "numero": "numero",
        "formaDeEnvio": "formaDeEnvio",
        "valorFrete": 9.999,
        "codigoTransportadora": "Correios"
    },
    "itens": [
        {
            "gtin": 7500435127288,
            "observacao": "string",
            "quantidade": 5,
            "quantidade_pedida": 15,
            "quantidade_separada": 3,
            "desconto_total": 2,
            "valor_unitario": 11,
            "precoDeVenda": 16
        }
    ],
    "pagamentos": [
        {
            "formaDePagamento": "BOLETO_BANCARIO",
            "valor": 100.548
        }
    ],
    "lojaKey": 1,
    "cliente": {
        "cpfCnpj": "43317197072",
        "rg": "string",
        "nome": "Teste Pedido 9",
        "email": "mail@mail.com",
        "telefones": [
            "string"
        ],
        "dataNascimento": "04/08/2026",
        "enderecoEntrega": {
            "rua": "Rua 1",
            "numero": "123",
            "complemento": "Complemento",
            "bairro": "Bairro",
            "cep": "05542220",
            "uf": "sp",
            "codigo_ibge_cidade": "12258",
            "nome_cidade": "São Paulo"
        },
        "enderecoCobranca": {
            "rua": "Rua 1",
            "numero": "123",
            "complemento": "Complemento",
            "bairro": "Bairro",
            "cep": "05542220",
            "uf": "sp",
            "codigo_ibge_cidade": "12258",
            "nome_cidade": "São Paulo"
        }
    },
    "observacao": "Observação",
    "numero_do_pedido": "8923549",
    "cnpj_loja": "VDCYHD8T000180",
    "forma_pagamento": "DINHEIRO",
    "aguardandoPagamento": false
}

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.49