VTEX - Como integrar com a Bevean

O que você vai precisar

Antes de começar, tenha em mãos:

• Acesso ao Admin da VTEX com um usuário que tenha permissão para gerenciar chaves de API (idealmente o usuário Master da conta).

• Acesso à sua conta Bevean com permissão para gerenciar integrações.

• O nome da sua conta VTEX (o "Account Name", que aparece na URL, ex: MINHALOJA.myvtex.com).

Passo 1: Gerar as credenciais de API na VTEX

Passo 1: Gerar as credenciais de API na VTEX

A VTEX usa um par de credenciais — App Key e App Token — para autenticar qualquer integração externa. É esse par que a Bevean vai usar para se comunicar com sua loja. O processo abaixo segue o tutorial oficial da VTEX, Chaves geradas.

1. Na barra superior do Admin VTEX, clique no avatar do seu perfil, marcado pela inicial do seu email, e depois em Configurações da conta > Chaves de API.

2. Certifique-se de que você está na aba Geradas.

3. Clique em + Gerar chave.

4. Preencha o campo Identificação da chave com o nome para identificar a chave de API (ex: "Bevean"). Este campo é obrigatório.

5. Selecione os perfis de acesso que serão associados à chave. Por padrão, nenhum perfil é pré-selecionado. Marque os perfis necessários para a integração com a Bevean:

   1. Catalog > Content — Product And Sku Management, Categories Management, SKUs (somente leitura)

   2. Pricing > Price List — Read Prices (somente leitura)

   3. MasterData — leitura de Clientes e Endereços (CL/AD)

   4. ListOrders e OMSViewer — leitura de pedidos (Orders/OMS)

   5. Feed v3 and Hook Admin — feed de pedidos

   6. Manage benefits and rates — Promoções e Cupons

6. Clique em Gerar. A App Key já é exibida nesse momento; o App Token ficará disponível a partir de um link de acesso único, válido por 24 horas caso não seja acessado.

7. Clique em Copiar para copiar esse link de acesso único à área de transferência. O link é exibido apenas uma vez nesta tela. Nesse momento, a chave já está ativa e disponível para uso.

8. Clique em Encerrar.

9. Acesse o link copiado (ou compartilhe-o com quem for configurar a integração na Bevean). Lembre-se: o link só pode ser acessado uma vez e expira em 24 horas se não for usado.

10. Na página aberta pelo link, clique em Copiar para copiar o App Token para a área de transferência. Esse valor também é exibido apenas uma vez — salve-o em um local seguro antes de sair da página.

⚠️ Atenção: tanto o link de acesso quanto o App Token têm exibição única. Se você perder o token antes de colá-lo na Bevean, será necessário gerar uma nova chave para substituir a anterior.

Associando permissões (perfil de acesso)

Por padrão, uma chave de API recém-criada não tem nenhuma permissão associada. Para que a Bevean consiga importar pedidos e clientes, é preciso vincular a chave a um perfil de acesso com, no mínimo, permissões de leitura sobre:

• Catalog > Content — Product And Sku Management, Categories Management, SKUs (somente leitura)

• Pricing > Price List — Read Prices (somente leitura)

• MasterData — leitura de Clientes e Endereços (CL/AD)

• ListOrders e OMSViewer — leitura de pedidos (Orders/OMS)

• Feed v3 and Hook Admin — feed de pedidos

• Manage benefits and rates — Promoções e Cupons

Para isso:

1. Ainda em Configurações da conta, acesse Perfis de acesso (ou Gestão de contas > Usuários, dependendo da versão do Admin).

2. Localize a App Key gerada no passo anterior.

3. Associe-a a um perfil de acesso existente com as permissões necessárias, ou crie um novo perfil específico para a integração com a Bevean, contendo apenas os recursos de Pedidos e Clientes.

4. Salve as alterações.

Mais detalhes sobre perfis de acesso podem ser encontrados na documentação oficial da VTEX: Chaves de API.

Passo 2: Conectar a VTEX na Bevean

Com o Account Name, a App Key e o App Token em mãos, o próximo passo é feito diretamente na Bevean.

1. Acesse Integrações > Explorar integrações.

2. Localize o card da VTEX na lista de integrações disponíveis e clique para abri-la.

3. Um painel de configuração será exibido, dividido em três seções:

1. Instruções

A própria tela relembra o processo: acessar o Admin da VTEX, gerar a chave de API e colar as credenciais nos campos abaixo.

2. Configurações de sincronização

Marque quais informações você deseja importar da VTEX para a Bevean:

• Pedidos — sincroniza os pedidos realizados na loja.

• Clientes — sincroniza a base de clientes cadastrada.

Ambas as opções podem ficar marcadas para uma sincronização completa, ou você pode desmarcar a que não for necessária para o seu caso de uso.

3. Credenciais

Preencha os três campos com os dados obtidos no Passo 1:

4. Após preencher todos os campos, clique em Conectar.

   

Passo 3: Validar a integração

Depois de clicar em Conectar, a Bevean fará uma chamada de teste às APIs da VTEX usando as credenciais informadas. Se tudo estiver correto:

• A integração aparecerá como ativa na lista de Integrações.

• Pedidos e/ou clientes começarão a ser sincronizados de acordo com as opções marcadas no Passo 2.

Se a conexão falhar, verifique:

• Se o Account Name foi digitado sem espaços e sem a parte .myvtex.com.

• Se o App Key e o App Token foram copiados corretamente (sem espaços extras).

• Se a chave de API possui um perfil de acesso associado com permissão para Pedidos e Clientes — chaves sem perfil vinculado não conseguem retornar dados, mesmo com credenciais corretas.

Passo 4: Configurar o Carrinho Abandonado

Além da sincronização de pedidos e clientes, você também pode habilitar o envio do evento de carrinho abandonado da VTEX para a Bevean. Isso é feito através de um Trigger configurado no Master Data da VTEX, que dispara uma chamada para o webhook da Bevean sempre que um cliente abandona o carrinho.

⚠️ Atenção: sua loja VTEX precisa estar com o status Em Produção para que os eventos de carrinho abandonado sejam enviados.

Habilitar o webhook de carrinho abandonado na Bevean

Antes de configurar o Trigger na VTEX, copie a URL do webhook gerada pela Bevean:

1. Acesse Integrações > VTEX (integração já conectada) e abra a aba Webhooks.

2. Copie a URL exibida (ex: https://connector.bevean.com/webhooks/vtex?tenantId=...&integrationId=...).

3. Habilite o evento Carrinho abandonado (cart-updated).

Criar o Trigger no Master Data da VTEX

Com a URL do webhook em mãos, o restante da configuração é feito no Admin da VTEX:

1. No Admin da VTEX, acesse Configurações da loja > Master Data.

2. Em Quick Links, clique em Advanced Settings.

3. Em Settings, clique em Data Structure.

4. Acesse o menu Trigger e clique em Add New.

5. Preencha Name (ex: "Bevean Carrinho Abandonado"), Data Entity: Customer e Status: Enabled.

Aba Rules

Configure a regra que identifica o carrinho abandonado:

• Trigger rule: An attribute value is changed

• Field: Last session

• Clique 4x em Add Filter e adicione, com o operador and entre eles:

  • Checkout — Different from — Finalizado

  • Checkout — Is not null

  • Cart — Is not null

  • Last cart — Is not null

Aba Schedule

Selecione Run ASAP, para que o evento seja enviado assim que a regra for atendida.

Aba If Positive

Nesta aba você configura o envio dos dados do carrinho para a Bevean:

• Action: Send an HTTP request

• URL: cole a URL do webhook copiada em Integrações > VTEX > Webhooks

• Method: POST

• Content as JSON: substitua pelo código abaixo

{
    "html_url": "{=UrlRegistro}",
    "isCorporate": "{!isCorporate}",
    "tradeName": "{!tradeName}",
    "rclastcart": "{!rclastcart}",
    "rclastcartvalue": {!rclastcartvalue},
    "rclastsession": "{!rclastsession}",
    "rclastsessiondate": "{!rclastsessiondate}",
    "homePhone": "{!homePhone}",
    "phone": "{!phone}",
    "stateRegistration": "{!stateRegistration}",
    "email": "{!email}",
    "userId": "{!userId}",
    "firstName": "{!firstName}",
    "lastName": "{!lastName}",
    "document": "{!document}",
    "isNewsletterOptIn": "{!isNewsletterOptIn}",
    "localeDefault": "{!localeDefault}",
    "attach": "{!attach}",
    "approved": "{!approved}",
    "birthDate": "{!birthDate}",
    "businessPhone": "{!businessPhone}",
    "corporateDocument": "{!corporateDocument}",
    "corporateName": "{!corporateName}",
    "documentType": "{!documentType}",
    "gender": "{!gender}",
    "customerClass": "{!customerClass}",
    "priceTables": "{!priceTables}",
    "profilePicture": "{!profilePicture}",
    "birthDateMonth": {!birthDateMonth},
    "id": "{!id}",
    "accountId": "{!accountId}",
    "accountName": "{!accountName}",
    "dataEntityId": "{!dataEntityId}",
    "createdBy": "{!createdBy}",
    "createdIn": "{!createdIn}",
    "updatedBy": "{!updatedBy}",
    "updatedIn": "{!updatedIn}",
    "lastInteractionBy": "{!lastInteractionBy}",
    "lastInteractionIn": "{!lastInteractionIn}"
}

• Response action → Data entity: Customer

• Parameters: Name: Cart (deixe o JSON Path em branco)

Aba If Negative

Deixe como está (Action: Select).

Ao finalizar, clique em Save. Depois, volte ao menu Trigger para confirmar que a configuração foi criada com sucesso.