A integração entre Dito Cashback e VTEX permite que o resgate de cashback ocorra diretamente na VTEX, utilizando as informações de pedidos e pagamentos da loja. O processo de autenticação entre as plataformas é realizado por meio de credenciais geradas na VTEX.

A ativação é self-service: você mesmo gera as credenciais na VTEX, inclui na tela de configuração do Cashback no App.Dito e ativa a integração em poucos cliques. O produto valida automaticamente as credenciais e, em alguns minutos após a ativação, o resgate de saldo já fica disponível no e-commerce.

• Nível de Acesso: Administrador, Administrador de Dados, Analista de tecnologia.
  Persona: Desenvolvedores, analistas de e-commerce e profissionais responsáveis por integrações técnicas entre plataformas.

Veja os assuntos abordados neste artigo:

• Cashback: Como integrar com a Vtex
• Atenção à conciliação com o ERP
• Pré-requisitos
• Passo a passo completo para configurar a integração
  • 1. Criar um perfil específico e gerar a Chave de API na VTEX
    • 1.1. Criando um Perfil do Cashback
    • 1.2. Crie uma service account
  • 2. Ativar a integração no app.dito (self-service)
  • 3. Gerenciar a integração (editar ou excluir)
  • 4. Teste a Integração
• FAQ – Perguntas Frequentes

Como integrar com a Vtex

Atenção à conciliação com o ERP

Na integração do Dito Cashback com a VTEX, é essencial que o cashback seja registrado corretamente no ERP como desconto. Caso contrário, a empresa pode pagar impostos sobre o valor total da venda e gerar divergências contábeis. O cashback funciona como método de pagamento na VTEX, mas deve ser tratado como desconto no ERP para garantir conformidade fiscal.

Recomendações da Dito: alinhar com o time contábil/fiscal, verificar repasse das vendas, confirmar com parceiros de integração e manter configurações corretas.

Pré-requisitos

Antes de iniciar o processo de integração, a marca deve garantir que:

• Utiliza a plataforma VTEX;
• Possui acesso administrativo à conta VTEX;
• Consegue criar uma Chave de API na VTEX;
• Possui um perfil específico (usuário ou app) dedicado à integração com a Dito Cashback.

Passo a passo completo para configurar a integração

1. Criar um perfil específico e gerar a Chave de API na VTEX

Para o resgate de cashback pela VTEX, é necessário que a marca gere uma Chave de API na própria VTEX, com as permissões adequadas para a integração com o Dito Cashback. Esse processo deve ser feito a partir de um perfil específico (usuário ou app) dedicado à Dito. O usuário precisa possuir a permissão “206163 User Administrator - RESTRICTED" ou superior.

Recomendações:

• Não utilizar usuários pessoais;
• Criar um perfil exclusivo para a Dito Cashback;
• Garantir que a Chave de API possua apenas as permissões necessárias para o processo de integração e resgate.

1.1. Criando um Perfil do Cashback

Crie um novo perfil customizado que dê acesso às APIs necessárias para a operação do Cashback na VTEX:

• Emissão e gerenciamento de giftcard (método de pagamento do resgate);
• Manutenção de provedores de pagamento;
• Consulta ao catálogo de produtos (necessária para regras de resgate baseadas em atributos do produto, como categoria).

1. Acesse Configurações da Conta > Perfis de Acesso e clique em Novo Perfil.
   
   

Configure o Novo perfil/New role:

2. Escolha o perfil de acesso (“Choose role”) como Custom.
3. Defina um nome para o perfil (role).
4. Selecione o produto GiftCarde habilite os seguintes recursos:
   • View Gift Card providers (Ver provedores de Gift Card)
   • Edit Gift Card providers (Editar provedores de Gift Card)
5. Clique em “Configurar outro produto”.
6. Selecione o produto PCI Gatewaye habilite os seguintes recursos:
   • No recurso “Payment-ManageStore”, habilite “Manage Store” (Gerenciar Loja).
   • No recurso “Payment-ViewPaymentData”, habilite “View Payment Data” (Visualizar métodos de pagamento da Loja).
7. Clique em “Configurar outro produto”.
8. Selecione o produto Cataloge habilite o seguinte recurso:
   • No recurso "Content", habilite “SKUs” (leitura de SKUs e suas categorias).

1.2. Crie uma service account

Crie uma service account que será usada para configurar o provedor de giftcard.

1. Acesse Configurações da Conta > Chaves de API e clique em Gerar Chave.

2. Forneça um nome e adicione o perfil criado no passo anterior. Em seguida, clique em Generate (Gerar) para gerar uma nova chave/service account.

3. Copie e guarde os dados da service account gerada (“chave da aplicação” e “token da aplicação”), pois essas informações serão necessárias no próximo passo.  Anote também o Nome da conta da VTEX, disponível em Configurações da conta > Conta, no campo "Nome da conta principal".

⚠️ Importante: por segurança, o Application Token é exibido apenas uma vez no momento da geração. Caso o perca, será necessário gerar uma nova chave de API.

2. Ativar a integração no app.dito (self-service)

Com as credenciais em mãos, a ativação é feita por você mesmo, direto no app.dito.

• No app.dito, acesse Configurações > Promoções > Cashback > Meios de resgate.

• No card "Resgate no e-commerce — VTEX Commerce Platform", clique em Configurar.

• Na tela "Configurar resgate na VTEX Commerce Platform", preencha os campos com as credenciais geradas na etapa 1:

• Account name: nome da sua conta na VTEX (ex.: minhamarca);
• API Key: chave de acesso gerada no painel da VTEX;
• Token: token de autenticação vinculado à API Key.

 Dica: ao salvar, o token não poderá mais ser visualizado por questões de segurança. Guarde-o em local seguro.

• Clique em Salvar e ativar.
• Na janela de confirmação, clique em Confirmar para habilitar a integração.

O produto valida automaticamente se as credenciais estão corretas e com as permissões necessárias:

• Se as credenciais forem válidas, a integração é ativada e, em alguns minutos, o resgate de saldo já fica disponível no e-commerce. É exibida a mensagem "Configuração salva com sucesso".

• Se as credenciais forem inválidas, a ativação não acontece e é exibida a mensagem "Credenciais inválidas. Verifique e tente novamente". Revise o Account name, a API Key e o Token e confirme que o perfil criado inclui os produtos GiftCard, PCI Gateway e Catalog com os recursos descritos no passo 1.1.

3. Gerenciar a integração (editar ou excluir)

Após a ativação, você pode gerenciar a integração a qualquer momento pela mesma tela em Configurações > Cashback > Meios de resgate.

Editar credenciais: use quando precisar atualizar Account name, API Key ou Token (por exemplo, ao rotacionar as credenciais na VTEX):

• No card da VTEX Commerce Platform, clique em Editar;

• Atualize os campos necessários e clique em Salvar e ativar;

• Ao confirmar, as credenciais são atualizadas automaticamente, sem interromper a integração com a VTEX.

Excluir / desativar a integração: use quando a marca deixar de utilizar a VTEX como meio de resgate:

• No card da VTEX Commerce Platform, clique em Excluir;

• Confirme a ação na janela de confirmação.

⚠️ Atenção: ao confirmar a exclusão, o resgate via VTEX é desativado e os atributos de produto deixam de poder ser usados nas regras de resgate.

4. Teste a Integração

1. Acesse a loja VTEX com o login de um cliente que possua um cashback disponível.
2. No checkout, verifique se o valor de cashback disponível para uso do cliente é exibido.

3. Selecione o cashback. O valor deve ser deduzido do montante a pagar.

4. Informe o segundo meio de pagamento e conclua a compra.
5. Aprove e fature o pedido. Assim que faturado, o uso do cashback será consolidado.

Com essas etapas, você conecta com sucesso o sistema de cashback da Dito à plataforma VTEX, permitindo que o cashback seja utilizado como método de pagamento no checkout, com segurança e visibilidade. Além disso, o uso correto das credenciais e da conciliação com o ERP garante conformidade financeira e operacional.

? Para configurar regras de resgate baseadas em características dos produtos, consulte o artigo Como Configurar o Resgate de Cashback por Atributos de Produto (VTEX).

FAQ – Perguntas Frequentes

1. Pergunta: Preciso abrir um chamado para o time da Dito ativar a integração? 
Resposta: Não. A ativação é self-service: você inclui as credenciais na tela de Meios de resgate do Cashback e ativa a integração você mesmo. O time da Dito só precisa ser acionado em caso de dúvida ou problema.

2. Pergunta: Quanto tempo leva para o resgate ficar disponível após a ativação? 
Resposta: Após a ativação com credenciais válidas, o resgate de saldo fica disponível no e-commerce em alguns minutos.

3. Pergunta: O que acontece se eu inserir credenciais incorretas? 
Resposta: O produto valida as credenciais e as permissões antes de ativar. Se algo estiver incorreto, a ativação não acontece e é exibida a mensagem "Credenciais inválidas. Verifique e tente novamente". Revise os dados e confirme que o perfil inclui os produtos GiftCard, PCI Gateway e Catalog com os recursos do passo 1.1.

4. Pergunta: Por que é recomendado criar um perfil "Custom" em vez de usar um perfil de administrador já existente? 
Resposta: Por segurança. Ao criar um perfil específico com permissões restritas apenas ao necessário (GiftCard, PCI Gateway e Catalog), você garante que a integração tenha acesso somente ao que precisa para operar o cashback, protegendo o restante das configurações da sua loja.

5. Pergunta: Como atualizo as credenciais se elas mudarem na VTEX? 
Resposta: Acesse Configurações > Cashback > Meios de resgate, clique em Editar no card da VTEX, atualize os campos e salve. As credenciais são atualizadas sem interromper a integração.

6. Pergunta: Como desativo a integração se deixar de usar a VTEX? 
Resposta: No mesmo card, clique em Excluir e confirme. O resgate via VTEX é desativado e os atributos de produto deixam de poder ser usados nas regras de resgate.

7. Pergunta: Qual o impacto de não configurar o cashback como desconto no ERP? 
Resposta:Se o ERP não reconhecer o cashback como desconto, a empresa poderá pagar impostos sobre o valor total da venda (incluindo a parte paga com cashback), gerando custos fiscais indevidos e divergências na conciliação contábil.

8. Pergunta: Onde encontro o "Nome da conta da VTEX"? 
Resposta: No painel da VTEX, em Configurações da conta > Conta, no campo "Nome da conta principal".

9. Pergunta: A chave de API gerada pode ser visualizada novamente caso eu perca o Token? 
Resposta: Não. Por segurança, o token da aplicação é exibido apenas uma vez no momento da geração. Caso o perca, será necessário gerar uma nova chave de API seguindo o mesmo procedimento.

10. Pergunta:O cashback é descontado do saldo do cliente assim que ele finaliza a compra? 
Resposta: O uso do cashback é reservado no checkout, mas sua consolidação (baixa definitiva) ocorre apenas após o pedido ser faturado na plataforma VTEX.

Ficou com alguma dúvida ou identificou algum problema? Acione nosso time pelo chat disponível no app dito. (Horário de Atendimento de Segunda a Sexta das 9hrs as 18hrs)