VTEX

Guia da integração de pedido com a VTEX — credenciais, fluxo, mapeamento de dados e troubleshooting

A integração com a VTEX permite receber pedidos automaticamente e atualizar o status de volta na plataforma quando a solicitação de coleta é feita, o pedido entra em rota ou é entregue.

Para entender o conceito geral, veja Integração de Pedido.

Como funciona

Cliente compra na VTEX — O pedido é criado na loja VTEX.
VTEX envia o pedido — Quando o pedido atinge o status configurado (pagamento aprovado ou faturado), a VTEX envia uma notificação para a Abbiamo.
Abbiamo cria o pedido — O sistema cria o pedido na filial correspondente, respeitando filtros de transportadora e mapeamento de vendedor.
Solicitação de coleta — O pedido segue para solicitação de coleta manual ou via automação de envio.
Atualização na VTEX — Quando o pedido muda de status na Abbiamo (com solicitação de coleta feita, em rota, entregue), a Abbiamo atualiza a VTEX automaticamente.

Uma integração por filial

Assim como as demais, a integração de pedido VTEX é por filial. O que costuma acontecer é: dentro de um mesmo grupo (seller group), as credenciais (conta VTEX, chave, token, ambiente etc.) são iguais para todas as filiais, e o que muda de uma integração para outra é o Tipo da integração e o ID do armazém (vtex_seller_id ou dock_id), que identifica qual filial da Abbiamo recebe os pedidos daquele seller ou dock na VTEX.

Campos da integração (o que você preenche)

Ao criar uma integração de pedido VTEX no painel, você verá os campos abaixo. Esta seção explica o que é cada um e onde obter as informações na VTEX.

Chave de API da VTEX (appKey)

AppKey gerada na VTEX. Para obter: Configurações da conta → Gerenciamento da conta → Chaves de aplicação → Gerenciar minhas chaves → Gerar chave. Copie o valor em Chave de aplicação.

Token de API da VTEX (appToken)

AppToken gerado na VTEX. Mesmo fluxo da chave acima; copie o valor em Token de aplicação. São duas informações diferentes — não confunda uma com a outra.

Perfil de acesso recomendado

Antes de gerar a chave, crie um perfil em Configurações da conta → Gerenciamento da conta → Perfis de acesso. Nomeie como "Integração Abbiamo", selecione OMS e adicione todos os recursos. Ao gerar a chave, associe esse perfil.

Tipo da integração (integration_style)

Define como a filial será identificada na VTEX:

Valor no formulário	Descrição
vtex_seller_id	Cada filial corresponde a um seller (vendedor) específico na VTEX.
dock_id	Cada filial corresponde a um armazém/centro de distribuição (dock) na VTEX.

Escolha de acordo com o tipo de operação que você utiliza.

ID do armazém (vtex_id)

Preencha com o seller_id ou o dock_id, conforme o tipo da integração escolhido:

Se Tipo da integração for vtex_seller_id: informe o ID do seller na VTEX (a Abbiamo pode ajudar a listar os sellers da sua conta).
Se for dock_id: informe o ID do dock que atende os pedidos dessa filial (configurado no fluxo de envio da VTEX ou informado pela transportadora).

TLD (tld)

Domínio de topo da URL da sua loja: .com ou .com.br. Para lojas brasileiras costuma ser .com.br.

Nome da conta VTEX (accountName)

Valor do campo accountName da sua loja VTEX — é o subdomínio. Ex.: se a URL é minhaloja.vtex.com.br, o Nome da conta VTEX é minhaloja.

Ambiente VTEX (environment)

Ambiente configurado na VTEX: myvtex (homologação/testes) ou vtexcommercestable (produção).

Status de importação do pedido (order_creation_status)

Em qual status da VTEX o pedido será criado na Abbiamo:

Opção no formulário	Significado
Faturado	Pedido é importado quando estiver faturado na VTEX.
Pagamento Aprovado	Pedido é importado assim que o pagamento for aprovado (antes da fatura).

Políticas de envio (shipping_policies)

Lista de políticas de envio VTEX que devem ser importadas para a Abbiamo. Se preenchido, apenas pedidos que usem uma dessas políticas serão importados. Os nomes devem ser exatamente iguais aos configurados na VTEX (maiúsculas, espaços e acentos importam).

Nome deve bater

O nome da política/transportadora na VTEX precisa ser idêntico ao configurado. Pequenas diferenças impedem o pedido de ser importado.

Gerar volume único (single_volume)

Se Sim: os pedidos importados terão um único volume (todos os itens agrupados). Se Não: cada item do pedido representará um volume separado.

Importar pedidos do tipo RETIRA (takeout)

Define como tratar pedidos de retirada em loja (pickup-in-point) na VTEX:

Opção no formulário	Comportamento
Não criar	Pedidos de retirada não são importados para a Abbiamo.
Criar aguardando confirmação	Pedidos de retirada são importados como pedidos normais.
Criar como pronto para retirada	Pedidos de retirada são importados já marcados como prontos para o cliente retirar.

Como o dado vem na Abbiamo

Após o mapeamento, o pedido criado na Abbiamo contém as seguintes informações vindas da VTEX:

Identificação

Na Abbiamo	Origem na VTEX
Número do pedido	`orderId`
Número da nota fiscal	`invoiceNumber` (do pacote). Só é preenchido quando o fluxo é Faturado; no fluxo Pagamento Aprovado o pedido fica sem esse dado até ser faturado na VTEX.
Chave de acesso da NF	`invoiceKey` (quando disponível)

Cliente

Na Abbiamo	Origem na VTEX
Nome	`clientProfileData.firstName` + `lastName`
E-mail	`clientProfileData.email` (ou `corporateName` em pedidos corporativos)
Telefone	`clientProfileData.phone` ou `corporatePhone`
CPF/CNPJ	`clientProfileData.document` ou `corporateDocument`

E-mail com proxy

A VTEX pode enviar pedidos com e-mail em formato proxy (ex.: 123456@ct.vtex.com). Nesses casos, a VTEX repassa as comunicações para o cliente real, e os e-mails enviados pela Abbiamo ficam registrados na página do pedido na VTEX.

Endereço de entrega

Na Abbiamo	Origem na VTEX
CEP	`shippingData.address.postalCode`
Rua	`shippingData.address.street`
Número	`shippingData.address.number`
Complemento	`shippingData.address.complement`
Bairro	`shippingData.address.neighborhood`
Cidade	`shippingData.address.city`
Estado	`shippingData.address.state`
País	`shippingData.address.country`

Itens e volumes

Cada item do pedido VTEX vira um item nos volumes da Abbiamo.
Dimensões (peso, altura, largura, comprimento) vêm de additionalInfo.dimension de cada item.
SKU, nome, imagem e preço são mapeados dos itens originais.

Informações adicionais

Na Abbiamo	Origem na VTEX
Transportadora escolhida	`logisticsInfo.deliveryIds[0].courierName`
Prazo de entrega	`shippingEstimate` ou `deliveryWindow`
Valor do frete pago	Total "Shipping" em `totals`
Data de processamento	`authorizedDate`

Tipo de pedido

Na Abbiamo	Condição na VTEX
DELIVERY	`deliveryChannel === 'delivery'`
TAKEOUT	`deliveryChannel === 'pickup-in-point'`

Atualização de status na VTEX

Quando o pedido muda de status na Abbiamo, a VTEX é atualizada automaticamente:

Status na Abbiamo	O que é enviado para a VTEX
Solicitação de coleta feita	Nome da transportadora, data da solicitação de coleta, código de rastreio e URL de rastreio.
Em rota	Data da ocorrência e status "Em Rota".
Entregue	Data da entrega, status "Entregue" e indicação de que o pedido foi entregue (campo absoluto que altera a visualização do pedido no admin da VTEX).

E-mails ao cliente

Todas essas atualizações disparam e-mails automáticos para o cliente no lado da VTEX, informando sobre o andamento da entrega.

Troubleshooting

O pedido não apareceu na Abbiamo

Checklist:

Integração ativa? Verifique em Configurações > Integrações de pedido se a integração VTEX está ativa.
Status de importação do pedido — O pedido precisa ter atingido o status escolhido (Faturado ou Pagamento Aprovado). Pedidos ainda em processamento não são importados.
Políticas de envio — Se você preencheu Políticas de envio, confira se o nome da política/transportadora do pedido bate exatamente com o configurado.
Tipo da integração e ID do armazém — O pedido precisa pertencer ao seller ou dock informado na integração para a filial correta. Se a integração for por vtex_seller_id, o seller do pedido na VTEX precisa bater com o configurado; pedidos de outros sellers/docks são ignorados.
Importar pedidos do tipo RETIRA — Se estiver em "Não criar", pedidos de retirada em loja não serão importados.

O status não atualizou na VTEX

Verifique se a solicitação de coleta foi feita na Abbiamo (não apenas criado).
Pedidos de retirada (TAKEOUT) têm um fluxo específico — a atualização "Entregue" na Abbiamo envia "Retirado pelo Cliente" na VTEX.

O pedido foi criado na filial errada

A integração VTEX mapeia por Tipo da integração (vtex_seller_id ou dock_id). Se você tem múltiplas filiais, confira se cada integração está com o seller ou dock correto para a filial desejada.

Nome da transportadora não bate

O nome da transportadora na VTEX deve ser idêntico ao configurado (incluindo maiúsculas, espaços e acentos).

Webhook ou credenciais com erro

A Abbiamo cadastra o webhook na VTEX no momento da criação da integração de pedido. Se o Token de API da VTEX estiver sem permissão de OMS nessa hora, o cadastro pode falhar e os pedidos não passarão a chegar.
Verifique se a Chave de API da VTEX e o Token de API da VTEX estão corretos e se o perfil de acesso na VTEX tem permissão de OMS.
Chave e token são dois valores diferentes — confira se foram copiados separadamente.

Onde acessar

Configuração da integração: Configurações > Integrações de pedido — o próprio cliente cadastra a integração de pedido VTEX.
Pedidos recebidos: Operação > Pedidos — filtre pela filial e verifique a coluna de origem para identificar pedidos vindos da VTEX.

Nesta página