Entrar
.md

Odoo POS Cashback

O módulo Guper POS Cashback (guper_pos_cashback) integra a geração e o resgate de cashback Guper dentro do Ponto de Venda (POS) do Odoo 19 Enterprise, com validação do cliente por PIN via WhatsApp. O resgate é representado fiscalmente como um desconto por linha (Desconto por conceito do CFDI).

Este guia explica, passo a passo, como instalá-lo e configurá-lo em um projeto Odoo.sh.

Pré-requisitos

  • Um projeto Odoo.sh já criado sobre Odoo 19 Enterprise.
  • Acesso ao repositório do projeto no GitHub (o que o Odoo.sh constrói).
  • As credenciais Guper da organização do cliente: API Key, API Secret e URL base (https://{org}.myguper.com). Consulte Autenticação se precisar obtê-las.

Parte A. Instalação do módulo

O módulo é distribuído como um git submódulo que aponta para o repositório MyGuper/guper-odoo. Assim cada cliente reutiliza o mesmo código e recebe atualizações sem copiar arquivos.

Passo 1. Abrir o projeto no Odoo.sh e adicionar o submódulo

No painel do Odoo.sh, entre na aba Branches e selecione seu branch (por exemplo main). No canto superior direito, clique no botão Submodule.

Passo 1: botão Submodule no Odoo.sh

Passo 2. Preencher os dados do submódulo

No diálogo Add a submodule, preencha exatamente estes valores e clique em Add a submodule:

Campo Valor
Repository URL git@github.com:MyGuper/guper-odoo.git
Branch 19.0
Path MyGuper/guper-odoo

Passo 2: diálogo Add a submodule

Ao confirmar, o Odoo.sh gera um novo build do branch. Aguarde o build ficar Success (verde).

Passo 3. Conectar ao ambiente Odoo

Quando o build estiver pronto, clique em CONNECT para abrir a base de dados. Você verá o menu de aplicativos do Odoo.

Nota: em branches de desenvolvimento/staging, o Odoo mostra um aviso de que a base é temporária. Use-as apenas para testes.

Passo 3: ambiente Odoo conectado

Passo 4. Instalar o módulo pelo Apps

Entre em Apps, digite guper na busca e localize Guper POS Cashback (guper_pos_cashback). Clique em Ativar / Instalar.

Se o módulo não aparecer, use Update Apps List (menu superior) e busque novamente.

Passo 4: módulo Guper POS Cashback no Apps


Parte B. Configuração

A integração é configurada por meio de Parâmetros do sistema. Para acessá-los é preciso ativar o modo desenvolvedor.

Passo 5. Ativar o modo desenvolvedor

Vá em Ajustes (Settings), desça até a seção Developer Tools e clique em Activate the developer mode.

Passo 5: ativar modo desenvolvedor

Passo 6. Abrir Parâmetros do sistema

Com o modo desenvolvedor ativo, em Ajustes aparece o menu Technical. Abra-o e, sob Parameters, entre em System Parameters.

Passo 6: menu Técnico, System Parameters

Passo 7. Configurar os parâmetros da Guper

O módulo cria automaticamente as chaves guper.*. Ajuste os valores conforme o cliente:

Passo 7: lista de parâmetros guper.*
Parâmetro Valor Descrição
guper.base_url https://{org}.myguper.com URL base da organização Guper do cliente.
guper.apikey (fornecido pela Guper) API Key da organização.
guper.apisecret (fornecido pela Guper) API Secret da organização.
guper.client_id_field phone Campo que identifica o cliente. Valores possíveis: phone, email, document.
guper.enabled True Ativa a comunicação com a Guper. Ver a nota de segurança abaixo.
guper.access_token (automático) Token de sessão. Gerenciado pelo módulo, não editar.
guper.token_expires_in (automático) Vencimento do token. Gerenciado pelo módulo, não editar.

Para editar um valor, clique na linha do parâmetro e altere o campo Value.


Nota de segurança: guper.enabled

guper.enabled vem como False por padrão, de propósito.

No Odoo.sh, as bases de staging são uma cópia de produção, incluindo as credenciais Guper. Se uma cópia de staging ficasse ativa, ela poderia se comunicar com a organização Guper de produção e enviar PINs reais por WhatsApp.

Por isso:

  • Deixe guper.enabled = False em staging e desenvolvimento.
  • Coloque guper.enabled = True somente em produção.

Atualizar o módulo para uma nova versão

Como o módulo foi instalado como submódulo, um push no repositório guper-odoo não atualiza automaticamente os projetos que já o têm: um submódulo aponta para um commit fixo. Para trazer a última versão, no repositório do projeto Odoo.sh execute:

git submodule update --remote MyGuper/guper-odoo
git add MyGuper/guper-odoo
git commit -m "update: Guper POS Cashback para a última versão"
git push

O --remote pega o último commit do branch 19.0 (definido no .gitmodules). Ao fazer push, o Odoo.sh reconstrói o build com a versão nova.


Verificação rápida

  1. Abra o Ponto de Venda e crie um pedido com um cliente que tenha o campo identificador (por padrão, telefone) cadastrado.
  2. Ao clicar em Pagar, o fluxo Guper cota o pedido: se houver saldo, oferece resgatar (com PIN); se não, informa quanto vai acumular.
  3. Confirme na Guper que o pedido fica registrado com o número do ticket do POS e o valor com imposto incluído.

A experiência no POS

Este vídeo mostra como fica o fluxo de cashback no Ponto de Venda depois de configurado:

▶️ Ver o vídeo no YouTube

Suporte

O time de integração está no WhatsApp 24/7 — +52 55 2328 5981.