Integração Dito Cashback + VTEX

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

A integração entre a plataforma VTEX e o sistema de cashback da Dito permite a consulta, uso e cancelamento de saldos de cashback diretamente na VTEX. Utilizamos o hub de integração da VTEX para realizar essa comunicação de forma eficiente e segura.

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

2. Criando um Perfil do Cashback

Crie um novo perfil custom que dê acesso às APIs de giftcard da VTEX.

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

2. Configure o novo perfil/new role:

a. Escolha o Choose Role como “custom”

b. Defina um nome para a role/perfil

c. Selecione o produto Giftcard 

       i. Habilite o recurso "ver provedores de giftcard" 

       ii. Habilite o recurso "editar provedores de giftcard"

3. 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 a role criada no passo anterior. Em seguida, clique em “generate” 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.

   a. X-VTEX-API-AppKey

   b. X-VTEX-API-AppToken

4. Registrando o Provedor da Dito

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

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

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

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

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

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

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

  a. Preencha a “appkey” substituindo a “key” pelo valor fornecido pela Dito.

  b. Preencha o “appToken” substituindo o “token” pelo valor fornecido pela Dito.

  c. Preencha o “serviceURL” substituindo o "https://api.vtex.com.br/example" por "https://cashback.dito.com.br/vtex" 

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

5. Habilitando o Provedor na Conta

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

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

2. Configure o novo provedor de pagamento

  a. Forneça  um nome para o novo provedor

  b. Selecione Giftcard Hub

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

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

2. Clique no botão Adicionar Novo Pagamento:

3. Configure o novo meio de pagamento:

   a. Selecione a opção “Vale” que fica na sessão "Outros"

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

7. Teste a Integração

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

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

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

4. Informe o segundo meio de pagamento e conclua a compra.

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