Agora no Bluesoft ERP, é possível consultar, empenhar e confirmar o uso de vouchers de devolução de mercadorias via API sem a necessidade de especificar a loja de origem do crédito. A partir desta atualização, a localização e a reserva do saldo passam a ocorrer por meio de uma validação centralizada e baseada em um número único para toda a rede de lojas.

Objetivo

O objetivo desta novidade é alinhar o fluxo de integrações da API pública com as regras já disponíveis nas telas do sistema, dando autonomia para os clientes utilizarem seus créditos em qualquer ponto de venda (PDV) integrado da rede. Isso elimina barreiras geográficas na utilização de saldos de devolução.

O Que Mudou?

  • Antes (O Problema): Os endpoints de consulta e empenho exigiam obrigatoriamente o envio combinado do código do voucher e da loja. Mesmo o voucher possuindo uma numeração única em toda a rede, essa restrição impedia o uso interlojas completo através de PDVs externos ou sistemas integrados, travando o fluxo caso o cliente tentasse consumir o crédito em uma filial diferente daquela que emitiu o documento.
  • Agora (A Solução): A obrigatoriedade do parâmetro de loja foi removida dos contratos da API de consulta e empenho. O sistema agora realiza uma busca dinâmica no banco de dados e localiza o registro exclusivamente pelo número único do voucher, permitindo o consumo e a movimentação financeira entre lojas distintas sem gerar bloqueios operacionais.
  • Benefícios:
    • Flexibilidade ao Consumidor: O crédito do cliente não fica preso à loja que originou a devolução.
    • Compatibilidade: Integrações legadas que continuam enviando o código da loja não serão afetadas.

Como Irá Funcionar a Partir de Agora?

Abaixo estão detalhados os ajustes técnicos e o comportamento esperado do novo fluxo de endpoints públicos:

1. Consulta de Voucher de Crédito

  • Endpoint: GET /vendas/voucher-devolucao
  • Contrato da Requisição: Passa a exigir unicamente o campo codigo.
  • Comportamento: Caso o código inserido seja inexistente, vencido ou cancelado, a operação retorna uma rejeição com a mensagem apropriada.

2. Execução do Empenho (Reserva de Saldo)

  • Endpoint: POST /vendas/voucher-devolucao/empenho
  • Contrato da Requisição: O corpo do payload deve conter codigo, ecf, operador e valorUtilizado.
  • Validações de Regra: * O sistema autoriza o empenho em qualquer loja da rede filiada (matiz/filial).
    • O voucher deve estar com o status ABERTO.
    • O valor solicitado para empenho não pode ser superior ao saldo disponível do voucher.
    • Uso Parcial e Resíduo: Se o cliente consumir apenas uma fração do crédito e o parâmetro de utilização parcial da rede estiver ativo, o saldo remanescente gerará automaticamente um novo voucher residual emitido e vinculado à loja que efetuou a confirmação do empenho.

3. Confirmação do Empenho

  • Endpoint: POST /vendas/voucher-devolucao/confirmacao-empenho
  • Comportamento: Mantém a estrutura simplificada utilizando somente o código do voucher para consolidar a transação financeira na filial consumidora.

Observações / Validações

  • Controle de Segurança por Permissão: O acesso às rotas de integração necessita das seguintes permissões:
    • Consulta: Permissão 3201
    • Empenho: Permissão 3202
    • Confirmação: Permissão 3203
    • Cancelamento: Permissão 3204

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 r367.70