Manual de integração do sistema de cashback da Dito com o provedor de GIFTCard da VTEX.

Neste artigo você encontrará o passo a passo completo para configurar a integração entre o cashback da Dito e a VTEX. Vamos mostrar os requisitos necessários, como criar o perfil de acesso e a service account, registrar e habilitar o provedor da Dito, configurar o método de pagamento e, por fim, testar a integração. 

Para quem é este artigo?

• 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:

• Passo a passo completo para configurar a integração
  Visão geral das etapas necessárias para conectar o cashback da Dito com a plataforma VTEX.
  
  
  • Passo 1 - Atenda aos requisitos Mínimos
  • Passo 2. Criando um Perfil do Cashback
  • Passo 3 - Crie uma service account
  • Passo 4 - Registre o provedor da Dito na VTEX 
  • Passo 5 - Habilitando o Provedor na Conta
  • Passo 6 - Configure o Método de Pagamento
  • Passo 7 - Teste a Integração.
    
    
• Atenção à conciliação com o ERP
  Pontos de cuidado para garantir que os registros do cashback estejam alinhados com o sistema financeiro da empresa.
  
  
• FAQ – Perguntas Frequentes
  
  

Passo a passo completo para configurar a integração

Este guia leva você pelas etapas necessárias para configurar corretamente a integração entre o sistema de cashback da Dito e a plataforma VTEX.

Essa integração permite consultar, usar e cancelar saldos de cashback diretamente na plataforma VTEX, utilizando o hub de integração oficial. O principal benefício é oferecer uma conexão segura e eficiente entre o sistema de cashback da Dito e o provedor de GiftCard da VTEX.

Passo 1 - Atenda aos requisitos Mínimos
Para realizar essa integração, é necessário:

• Credenciais Geradas pela Dito: As credenciais de acesso (APP Key e APP Token) fornecidas pela Dito.

• Permissões de Usuário: Um usuário na VTEX com permissões suficientes para:

  • Criar um novo perfil customizado com as permissões de giftcard

  • Criar uma service account que será utilizada na integração

  • Ativar o módulo de cashback.

  • O usuário precisa possuir a role/permissão “206163 User Administrator - RESTRICTED" ou superior.

Passo 2. Criando um Perfil do Cashback
Crie um novo perfil custom que dê acesso às APIs de giftcard da VTEX.

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

•  Configure o novo perfil/new role:

• Escolha o Choose Role como “custom”
• Defina um nome para a role/perfil
• Selecione o produto Giftcard 
  •        i. Habilite o recurso "ver provedores de giftcard" 
  •        ii. Habilite o recurso "editar provedores de giftcard"

Passo 3 - Crie uma service account

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

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

•  Forneça um nome e adicione a role criada no passo anterior. Em seguida, clique em “generate” para gerar uma nova chave/service account.
   

•  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.

   a. X-VTEX-API-AppKey

   b. X-VTEX-API-AppToken

Passo 4 - Registre o provedor da Dito na VTEX 

Adicione o provedor da Dito à lista usando os dados fornecidos e a credencial criada no passo anterior. 

• Abra o hub de integração da VTEX, role a página e clique em “Create or update a gift card provider by ID”. Uma página será aberta com algumas informações para serem preenchidas.

• Preencha o campo “Path Params” com o nome do Provider ID que vai identificar o provedor da Dito. Exemplo: “ditocrmcashback”  

• No campo “BaseURL” insira a slug da marca (nome da loja Vtex), substituindo o parâmetro “apiexamples”.

• Preencha o campo “Authentication” com os dados da service account gerada anteriormente: “chave da aplicação” e “token da aplicação”, sendo:

    a. Chave da aplicação: X-VTEX-API-AppKey

    b. Token da aplicação: X-VTEX-API-AppToken

• O campo de “Headers” não deve ter os valores já pré preenchidos alterados nos campos:

• Por fim, as informações fornecidas pela Dito devem ser preenchidas no campo “Example” no quadro de “REQUEST BODY”.
  
  

IMPORTANTE: Para ter acesso à essas informações nos acione via chat para que o nosso time possa abrir a solicitação e encaminhar os dados via ticket.

• Preencha a “appkey” substituindo a “key” pelo valor fornecido pela Dito.
• Preencha o “appToken” substituindo o “token” pelo valor fornecido pela Dito.
• Preencha o “serviceURL” substituindo o "https://api.vtex.com.br/example" por "https://cashback.dito.com.br/vtex" 

• Após essas configurações, clique em “TEST METHOD” e espere uma saída com os campos substituídos pelos valores que foram preenchidos, como na imagem abaixo:

Passo 5 - Habilitando o Provedor na Conta

Vamos disponibilizar o meio de pagamento giftcard utilizando o HUB de integração da VTEX.

• Registre o provedor acessando a Store Settings > Payment > Providers e clicando em Novo Provedor.

• Configure o novo provedor de pagamento
  
  
• Forneça  um nome para o novo provedor
• Selecione Giftcard Hub
   

Passo 6 - Configure o Método de Pagamento

Por fim, com o provedor configurado, vamos habilitar um novo meio de pagamento que utiliza o provedor de cashback da Dito através do HUB da VTEX

• Começe acessando a Store Settings > Payment > Settings.

• Clique no botão Adicionar Novo Pagamento:

• Configure o novo meio de pagamento:
  Selecione a opção “Vale” que fica na sessão "Outros"

• Selecione o VtexGiftCardHub.

OBS: após configurar o Vale como meio de pagamento, deve-se clicar nos 3 pontinhos ao lado do meio de pagamento em questão e defini-lo como padrão

Passo 7 - Teste a Integração

• Acesse a loja VTEX com o login de um cliente que possua um cashback disponível.

• No checkout, deve-se exibir o valor de cashback disponível para uso do cliente.

• Selecione o cashback e o valor deve ser deduzido do montante a pagar.

• Informe o segundo meio de pagamento e conclua a compra.
• Não se esqueça de aprovar o pedido e faturar; assim que faturado, o cashback terá o uso consolidado.

Com esses passos, a integração entre a VTEX e o sistema de cashback da Dito estará configurada e funcionando. Essa integração permite um gerenciamento eficiente de cashback, proporcionando uma melhor experiência para os clientes da marca.

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

Ao implementar a integração de cashback da Dito com a VTEX, é fundamental garantir que os valores resgatados pelos clientes sejam também registrados no ERP da marca. Essa conciliação é essencial para evitar inconsistências fiscais e problemas tributários.

O ideal é que, no momento da finalização do pedido com cashback, o valor correspondente ao resgate seja transmitido ao ERP, com o tratamento contábil adequado. Isso assegura que:

• O valor total da venda reflita corretamente os abatimentos aplicados;
• O resgate do cashback seja considerado nos relatórios financeiros;
• As obrigações fiscais da empresa sejam cumpridas de forma alinhada com a legislação vigente.
  
  

Recomendamos alinhar com o time contábil/fiscal da marca a forma correta de registrar esse valor no ERP, tratando sempre como desconto, para garantir conformidade tributária e evitar impactos financeiros indesejados.

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. 

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)

Gostou, mas acha que algo pode melhorar?

Sua opinião é muito importante para nós! Se você tem alguma sugestão ou sentiu falta de algo neste módulo, queremos ouvir você.

Compartilhe suas ideias diretamente com nosso time de Produto através do link abaixo.

➡️ Acesse aqui o Portal de Ideias

FAQ – Perguntas Frequentes

1- Preciso ter algum conhecimento técnico para configurar essa integração?
Não necessariamente. É recomendado que a configuração seja feita por alguém da equipe de tecnologia ou com familiaridade com integrações em e-commerce, mas o processo pode ser seguido com o suporte da Dito caso necessário.

2 - O que acontece se o cliente não utilizar todo o saldo de cashback em uma compra?
O valor não utilizado permanece disponível para futuras compras, até a data de validade definida na política do programa de cashback.

3- Existe algum tempo de espera para o cliente visualizar o cashback disponível no checkout?
Não. Assim que a integração está ativa e o cliente possui saldo válido, o valor aparece imediatamente no checkout.

4- O cashback pode ser usado junto com outros cupons de desconto na VTEX?
Sim, o cliente pode aplicar cashback e, dependendo da configuração da sua loja, ainda usar outros cupons. Vale revisar as regras comerciais definidas no seu ambiente VTEX.

5 - Posso limitar o uso do cashback por categorias de produto?
Sim, é possível criar regras de negócio dentro da VTEX ou na configuração das promoções de cashback para restringir onde ele pode ser aplicado.