Pular para conteúdo

Giftyback — Integração de Fidelidade e Bônus

Parâmetros Especiais > grupo Giftyback | Fluxo automático no PDV e em Vendas e Devoluções

O que é

Giftyback é uma plataforma externa de fidelidade e cashback. A integração permite que o sistema Master Key: 1. Consulte na API do Giftyback se o cliente possui bônus disponível para usar como desconto na venda. 2. Envie a venda para a plataforma ao finalizar, acumulando pontos/bônus para o cliente. 3. Cancele a venda no Giftyback quando uma nota é cancelada no Master Key.

A integração funciona tanto no PDV quanto em Vendas e Devoluções.

Configuração (Parâmetros Especiais)

Acesse Utilitários → Parâmetros do Sistema → aba/grupo Giftyback. Os campos são gravados na tabela PARAMESP por filial.

Campo Banco (PARAMESP) O que é
Usar Giftyback USA_GIFTYBACK 'S' = ativa a integração; 'N' = desativa. Habilita/desabilita os controles do grupo.
Store Key GIFTYBACK_STOREKEY Chave de identificação da loja na plataforma Giftyback (fornecida pela Giftyback)
Campanha ID GIFTYBACK_CAMPANHAID Identificador da campanha de fidelidade ativa na Giftyback

Sem Store Key e Campanha ID configurados, a integração não funciona mesmo que USA_GIFTYBACK = 'S'.

Fluxo no PDV

Consulta de bônus disponível

Quando o operador informa o cliente na venda, o PDV verifica se USA_GIFTYBACK = 'S'. Se sim, abre automaticamente a janela de consulta Giftyback:

  1. Tela de Telefone — o operador informa o número de telefone do cliente (mínimo 10 dígitos).
  2. O sistema consulta a API Giftyback (GetBonus) enviando: store_key, campanha_id, fone e valor_venda (campo SUM_DESCONTO_ELEGIVEL dos itens).
  3. Se a consulta retornar success = true:
  4. A tela avança para a tela de PIN.
  5. O cliente recebe o PIN no celular via Giftyback.
  6. Tela de PIN — o cliente digita o PIN recebido (ou o operador usa o PIN de suporte 2025).
  7. Se o PIN for válido, o bônus é liberado e a venda continua com o desconto aplicado.
  8. Se o cliente cancelar (btnCancelar), o sistema pergunta: "Esta venda será finalizada SEM a geração de bônus para o cliente. Confirma?"

Envio da venda finalizada

Ao finalizar a venda com sucesso (EnviaVendaGiftyback), o sistema chama Giftyback.EnviaVenda enviando para a API: - store_key e campanha_id - fone do cliente (primeiros 11 dígitos numéricos do campo FoneGiftyback) - nro_venda — controle da venda (VE_CONTROLE) - valor_venda — valor total + bônus usado - valor_bonus_usado — valor do bônus descontado - nome_cliente e data_nascimento — enviados apenas quando não é consumidor padrão

Cancelamento de venda

Quando uma nota é cancelada no Master Key, o sistema automaticamente chama Giftyback.CancelaVenda enviando: - store_key, campanha_id e nro_venda (VE_CONTROLE)

Fluxo em Vendas e Devoluções

O comportamento é equivalente ao PDV: ao cancelar uma nota que foi enviada ao Giftyback, o sistema dispara o cancelamento na plataforma automaticamente usando o VE_CONTROLE como identificador.

Tolerância a falhas

A integração tenta até 5 vezes (MAX_TENTATIVAS = 5) em caso de falha de conexão (erros HTTP 12007 e 12002 — sem internet ou timeout). Após as tentativas: - Para envio de venda: exibe aviso "Falha ao enviar venda ao Giftyback" com o detalhe do erro. - Para cancelamento: exibe aviso "Falha ao enviar cancelamento ao Giftyback". - O processo de venda/cancelamento no Master Key não é bloqueado pela falha no Giftyback.

Tabelas e campos relevantes

Tabela Campo Função
PARAMESP USA_GIFTYBACK Liga/desliga a integração por filial
PARAMESP GIFTYBACK_STOREKEY Chave da loja
PARAMESP GIFTYBACK_CAMPANHAID ID da campanha
VENDAS VE_CONTROLE Identificador único da venda enviado ao Giftyback como nro_venda
CLIENTES CL_FONEGIFTYBACK Telefone do cliente usado na integração (apenas os 11 primeiros dígitos numéricos)

Perguntas frequentes do suporte

"A janela do Giftyback não aparece no PDV" → Verifique se USA_GIFTYBACK = 'S' em Parâmetros do Sistema para a filial correta. Verifique também se GIFTYBACK_STOREKEY e GIFTYBACK_CAMPANHAID estão preenchidos.

"O cliente diz que não recebeu o PIN" → O PIN é enviado pela plataforma Giftyback via SMS para o telefone cadastrado. Verifique se o número informado na tela está correto. O suporte pode usar o PIN 2025 para liberar em caso de emergência.

"Falha ao enviar venda ao Giftyback — o que fazer?" → A venda é concluída normalmente no Master Key independente da falha. A falha é apenas comunicada em tela. Verifique a conectividade com a internet e, se persistir, entre em contato com o suporte da Giftyback.

"A venda foi cancelada no Master Key mas não aparece cancelada no painel Giftyback" → O sistema tenta cancelar automaticamente. Se a conexão falhou nas 5 tentativas, o cancelamento no Giftyback precisa ser feito manualmente no painel da plataforma. O VE_CONTROLE da venda é o nro_venda no Giftyback.

"O campo de telefone do Giftyback no cadastro de clientes — onde fica?" → No Cadastro de Clientes/Fornecedores, campo CL_FONEGIFTYBACK. É o número usado pela integração para vincular o cliente à plataforma.