Agora no Bluesoft ERP, é possível realizar devoluções de vendas por cupom fiscal entre diferentes lojas da mesma rede diretamente pela API pública. A melhoria permite que PDVs e integrações externas identifiquem separadamente a loja em que a venda foi realizada e a loja responsável por receber a devolução, utilizando o fluxo de devolução interlojas já disponível no ERP.

Objetivo

O objetivo desta melhoria é ampliar a integração do processo de devolução de vendas, proporcionando maior flexibilidade operacional e permitindo que as devoluções realizadas em uma loja diferente da venda original sejam registradas e acompanhadas por sistemas integrados.

Como Era o Processo Antes?

Anteriormente, a API de devolução de venda por cupom fiscal utilizava o identificador lojaKey para representar a loja envolvida na operação, atendendo ao processo de devolução realizado na própria loja da venda.

O Bluesoft ERP já disponibilizava o processo de devolução interlojas pela interface, permitindo registrar a devolução em outra loja e realizar o processamento fiscal correspondente.

Benefícios:

  • Permite operações de devolução entre lojas de forma 100% automatizada e via integração.
  • Garante que o voucher de devolução interlojas possa ser consultado e empenhado em qualquer filial da rede.
  • Oferece rastreabilidade e visibilidade de todo o trâmite fiscal de forma ordenada, com registro de acompanhamento assíncrono.

Como Irá Funcionar a Partir de Agora?

Devolução de cupom interlojas

Agora, a API passa a contemplar também o cenário interlojas, permitindo que PDVs e integrações externas utilizem o mesmo processo de negócio disponível no ERP. A localização e a baixa dos vouchers também foram atualizadas para operar de forma global na rede, exigindo apenas o código EAN13 do título.

A integração deverá utilizar o endpoint:

/api/varejo/devolucao-venda/cupom

Para realizar a devolução interlojas, deverão ser observadas as seguintes etapas:

1. Identificação das lojas

A requisição passa a permitir a identificação separada da loja de origem da venda e da loja que receberá a devolução.

  • cnpjLojaVenda: identifica a loja em que a venda foi realizada, utilizando seu CNPJ sem formatação.
  • lojaKey: identificador anterior da loja da venda, mantido para compatibilidade com as integrações existentes.
  • lojaDevolucaoKey: identifica a loja que receberá os produtos devolvidos.

Será necessário informar pelo menos um dos identificadores cnpjLojaVenda ou lojaKey. Quando ambos forem enviados, deverão corresponder à mesma loja.

2. Identificação do tipo de devolução

O ERP identificará automaticamente a modalidade da operação:

  • Devolução comum: quando lojaDevolucaoKey não for informado ou corresponder à mesma loja da venda.
  • Devolução interlojas: quando lojaDevolucaoKey identificar uma loja diferente da origem da venda.

Na devolução comum, o processamento continuará seguindo as regras já existentes, preservando a compatibilidade das integrações atuais.

3. Validação e registro da devolução

Para realizar uma devolução interlojas, as lojas deverão atender às configurações e aos requisitos fiscais aplicáveis.

O sistema utilizará a loja de origem para localizar e validar o cupom fiscal e os dados da venda. Já a loja receptora será utilizada para o registro da devolução e da entrada dos produtos no estoque.

A operação deverá possuir a configuração de devolução interlojas habilitada, assim como o parâmetro Permite geração de voucher na devolução, disponível nos Parâmetros do Módulo Varejo (@1637).

4. Geração do voucher e processamento fiscal

Na devolução interlojas, o voucher de crédito será gerado obrigatoriamente, e o processamento fiscal seguirá o fluxo específico dessa modalidade.

O processo contempla a emissão e a autorização das notas fiscais de entrada de devolução, devolução simbólica e transferência simbólica, bem como as entradas correspondentes.

A configuração geraNotaFiscalDevolucao continuará sendo aplicada às devoluções comuns. Para as devoluções interlojas, a geração das notas fiscais seguirá o processo fiscal próprio.

Acompanhamento da operação

Após o envio da devolução, a integração receberá um identificador de processamento assíncrono (requestId).

Esse identificador poderá ser utilizado para acompanhar a solicitação pelo endpoint:

GET /api/monitoramento/async/{requestId}

Além do acompanhamento pela API, o processo poderá ser consultado na rotina:

Varejo > Devolução Interlojas > Gerenciamento de Devolução Interlojas (@2281)

Nessa tela, será possível localizar a devolução, utilizar a opção Visualizar processo de devolução interloja e consultar as etapas de processamento dos documentos fiscais e do voucher.

Caso ocorra alguma situação que impeça a conclusão do processo fiscal, será possível utilizar os mecanismos existentes de tratamento e reprocessamento, conforme a situação apresentada.


{
  "numeroCupom": 123456,
  "cnpjLojaVenda": "12345678000195",
  "lojaDevolucaoKey": 2,
  "ecfVenda": 1,
  "codigoOperadorVenda": 1001,
  "dataDaVenda": "15/10/2026",
  "dataDevolucao": "20/10/2026",
  "motivoDevolucaoKey": 1,
  "remetente": "CLIENTE",
  "tipoDevolucao": "COM_CUPOM",
  "cpfCnpj": "12345678909",
  "ecfDevolucao": 2,
  "codigoOperadorDevolucao": 1002,
  "geraNotaFiscalDevolucao": false,
  "produtosDevolvidos": [
    {
      "produtoKey": 12345,
      "quantidadeDevolvida": 1
    },
    {
      "gtin": <gtinEAN13DoProduto>,
      "quantidadeDevolvida": 2
    }
  ]
}

Permissões necessárias

Para utilizar a nova funcionalidade de devolução interlojas por API, a credencial de integração deverá possuir:

  • 4218 — API Devolução cupom venda (Incluir)
  • 4716 — API – Devolução cupom venda interlojas (Incluir)

A nova permissão 4716 será exigida especificamente nas operações interlojas, mantendo a devolução comum disponível com a permissão já utilizada anteriormente.

Observações / Validações

  • Para o funcionamento do fluxo interlojas, as lojas envolvidas devem pertencer à mesma Unidade Econômica/Fiscal.
  • O processo exige que a flag “Habilitar Devolução Interloja” e a configuração de geração de voucher obrigatória estejam ativas no ERP.
  • A operação via API está validada e restrita para as unidades federativas SP, SC, PR, ES, BA e GO.
  • Além da permissão atual de uso da API, a credencial de integração precisará receber a nova permissão de devolução interlojas.
  • As integrações antigas (legadas) continuam funcionando sem impactos estruturais: o campo lojaKey foi marcado como depreciado, mas a API continuará processando a devolução comum caso os novos parâmetros sejam omitidos.

Para conhecer as funcionalidades relacionadas, consulte as documentações:

Para saber mais sobre a utilização das APIs do ERP, clique aqui.

Disponível a partir da versão r375.01