> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Olist Ecommerce

> Conecte sua loja Olist Ecommerce por token para disparar comunicações de pedido, cliente novo e carrinho abandonado e sincronizar clientes, pedidos e produtos

A integração com a **Olist Ecommerce** (antiga Vnda) conecta sua loja à OctaSend por um token da API da Olist. Com ela você:

* **Dispara comunicações** a cada momento do pedido: pedido recebido, pagamento aprovado, cancelado, enviado e entregue. Também há boas-vindas para cliente novo.
* **Recupera carrinhos abandonados**, com uma comunicação enviada a quem deixou o carrinho sem comprar.
* **Sincroniza clientes, pedidos e produtos** com o menu [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md) e alimenta as [automações](https://docs.octasend.com.br/plataforma/automacoes.md).
* **Mostra o Conteúdo Rico** nas páginas de produto da vitrine, pela [OctaTag](https://docs.octasend.com.br/plataforma/octatag.md).

O funcionamento geral do mapeamento, do histórico e dos status é o mesmo da [Nuvem Shop](https://docs.octasend.com.br/integracoes/nuvemshop.md). Esta página descreve o que é próprio da Olist.

> [!NOTE]
>
> A Olist não envia webhook. A OctaSend consulta a API da loja a cada minuto, então as mensagens não saem na hora. Veja [Tempo até a mensagem sair](#tempo-até-a-mensagem-sair).

## Antes de começar

No Admin da Olist Ecommerce, em **Configurações > Integrações > API**, gere um token só para a OctaSend e marque a permissão de **leitura** de **Pedidos**, **Clientes**, **Produtos** e **Carrinhos**. Se faltar alguma, a conexão avisa qual. O token chega por e-mail e não expira. Se você revogar, ele não volta: gere outro.

## Conectar

**1. Abra o card da Olist**

Em **Configurações → Integrações**, clique em **Conectar** no card **Olist Ecommerce**.

**2. Preencha os dados da loja**

| Campo | O que informar |
| - | - |
| **Domínio da loja** | O endereço que seus clientes acessam, sem `https://` (ex.: `www.minhaloja.com.br`). |
| **Token da API** | O token que chegou por e-mail. |
| **Nome da loja** | Opcional. Aparece nas mensagens; em branco, usamos o domínio. |
| **Minutos para considerar o carrinho abandonado** | De 15 a 1440. O padrão é 60. |
| **Ambiente** | **Produção** (padrão) ou **Testes**. |

**3. Salve**

A OctaSend confere o domínio e o token na Olist antes de gravar. Se algo estiver errado, o erro aponta o campo.

Regras da conexão:

* Ao editar a conexão, o token salvo só é reaproveitado se o domínio continuar o mesmo.
* O ambiente **Testes** usa a API de sandbox da Olist e um token diferente, que você pede à Olist. Use só com uma loja de testes.
* Ao conectar, a OctaSend importa os clientes e os produtos da loja e os pedidos dos **últimos 90 dias**, em segundo plano. **Essa importação não envia mensagem**: só o que acontecer depois da conexão dispara.

## Mapear os eventos

Com a loja conectada, clique em **Configurar eventos** no card e escolha a comunicação de cada evento. Evento sem comunicação não dispara nada. Os eventos também servem de gatilho nas [automações](https://docs.octasend.com.br/plataforma/automacoes.md).

| Evento | Quando dispara |
| - | - |
| Pedido recebido (aguardando pagamento) | O pedido aparece na loja pela primeira vez, depois da conexão. Leva o link do boleto e o código Pix quando houver. |
| Pagamento aprovado | O pedido passa a confirmado. Se ele já chega pago na primeira leitura, saem **recebido** e **pago**, nessa ordem. |
| Pedido cancelado | O pedido passa a cancelado. |
| Pedido enviado | O **primeiro pacote** do pedido é enviado. Sai uma mensagem por pedido, não por pacote. |
| Pedido entregue | **Todos os pacotes** do pedido estão entregues. |
| Cliente cadastrado | Um cliente novo aparece na loja. |
| Carrinho abandonado | Um carrinho fica parado pelos minutos configurados sem virar pedido. |

Regras para todos os eventos:

* Cada evento sai **uma vez** por pedido, cliente ou carrinho.
* Nada que aconteceu antes da conexão dispara.
* Se um pacote tem um status que a OctaSend não conhece (por exemplo, "separado" ou "devolvido"), ele não dispara evento. O status só fica registrado no pedido.

### Cliente cadastrado

A Olist não informa a data de cadastro do cliente. A OctaSend usa o número de identificação: dispara para o cliente cujo id é **maior que o maior id conhecido** na importação inicial. Clientes antigos que só atualizam o cadastro não disparam, e cada cliente dispara uma vez só.

### Carrinho abandonado

Dispara para o carrinho que:

* parou depois da conexão, há mais que os minutos de abandono configurados, e tem itens;
* tem e-mail ou telefone de contato;
* **não virou pedido**: não existe pedido com o mesmo código de carrinho **e** o mesmo e-mail ou cliente não fez nenhum pedido depois da última atualização do carrinho.

> [!NOTE]
>
> Quem abandona um produto e compra **outro** não recebe o aviso. A conversão também é conferida na hora do envio: a mensagem que ficou para trás aparece no histórico como **Ignorado** ("Carrinho convertido" ou "Cliente comprou depois"). Se o carrinho não existir mais na loja, o motivo é "Carrinho não existe mais na loja".

Um carrinho que ficou **mais de 24 horas além do tempo de abandono sem ser lido** (por exemplo, por uma falha prolongada da API da Olist) não dispara. A mensagem leva o link da loja, os itens (nome, link e foto) e o total, mas **não** um link para retomar o carrinho.

### Quem recebe a mensagem

O telefone e o nome vêm do endereço de entrega do pedido; se não houver, do cadastro do cliente. No carrinho abandonado, o e-mail vem do endereço de entrega, do cadastro ou, se nenhum dos dois tiver, do e-mail que a Olist mostra na lista de carrinhos. Sem nenhum contato, o envio aparece no histórico como **Ignorado**, com o motivo.

## Variáveis

O painel **Variáveis disponíveis**, ao lado do mapeamento, mostra as variáveis do evento com botão de copiar. Os nomes são os mesmos da [Linx Commerce](https://docs.octasend.com.br/integracoes/linx.md) e da [Wake](https://docs.octasend.com.br/integracoes/wake.md) onde existe equivalente.

**Em todos os eventos**

| Variável | Conteúdo |
| - | - |
| `{{loja_nome}}` | Nome da loja |
| `{{loja_url}}` | Endereço da loja |
| `{{cliente_nome}}` | Nome do cliente |
| `{{cliente_primeiro_nome}}` | Primeiro nome do cliente |
| `{{cliente_email}}` | E-mail do cliente |
| `{{cliente_telefone}}` | Telefone do cliente |

**Eventos de pedido** (recebido, pago, cancelado, enviado e entregue)

| Variável | Conteúdo |
| - | - |
| `{{pedido_numero}}` | Número do pedido |
| `{{pedido_data}}` | Data do pedido (dd/mm/aaaa) |
| `{{pedido_status}}` | Status do pedido (Aguardando pagamento, Pagamento aprovado, Enviado, Entregue ou Cancelado) |
| `{{pedido_total}}` | Valor total |
| `{{pedido_subtotal}}` | Soma dos itens, sem frete e desconto |
| `{{pedido_frete}}` | Valor do frete |
| `{{pedido_desconto}}` | Valor do desconto |
| `{{pedido_itens}}` | Itens do pedido, um por linha |
| `{{pedido_pagamento}}` | Forma de pagamento |

**Só em Pedido recebido**

| Variável | Conteúdo |
| - | - |
| `{{boleto_link}}` | Link do boleto (vazio se o pagamento não for boleto) |
| `{{boleto_vencimento}}` | Vencimento do boleto |
| `{{pix_codigo}}` | Pix copia e cola (vazio se o pagamento não for Pix) |

**Em Pedido enviado e Pedido entregue**

| Variável | Conteúdo |
| - | - |
| `{{rastreio_codigo}}` | Código de rastreio |
| `{{rastreio_link}}` | Link de rastreio |
| `{{transportadora}}` | Transportadora |

**Só em Carrinho abandonado**

| Variável | Conteúdo |
| - | - |
| `{{carrinho_total}}` | Valor do carrinho |
| `{{carrinho_quantidade}}` | Quantidade de itens |
| `{{carrinho_itens}}` | Itens, um por linha (quantidade, nome, variação e link) |
| `{{primeiro_item_nome}}` | Nome do primeiro item |
| `{{primeiro_item_link}}` | Link do primeiro item |
| `{{primeiro_item_imagem}}` | Imagem do primeiro item |

## Tempo até a mensagem sair

| Evento | Atraso típico |
| - | - |
| Pedido recebido, pago e cancelado | Cerca de 1 minuto. Um boleto pago tarde (pedido com mais de 3 dias) é pego pela releitura dos últimos 30 dias, que roda a cada 15 minutos. |
| Pedido enviado e entregue | Até cerca de 15 minutos nos pedidos pagos há até 7 dias; até cerca de 1 hora nos pagos de 7 a 30 dias. Depois de 30 dias sem entrega, o pedido deixa de ser conferido. |
| Cliente cadastrado | Cerca de 5 minutos. |
| Carrinho abandonado | Cerca de 5 minutos **mais** os minutos de abandono configurados. |

## OctaTag e Conteúdo Rico na vitrine

A [OctaTag](https://docs.octasend.com.br/plataforma/octatag.md) faz os widgets da OctaSend, como o **Conteúdo Rico**, funcionarem na vitrine. Na Olist, a OctaSend **não altera a sua loja**: no cartão **OctaTag na loja** (em **Configurações → Integrações → Olist Ecommerce**) ela mostra dois códigos para você copiar e colar. Use **só um dos caminhos**.

**1. Cole o código**

* **Pelo tema (recomendado):** no editor de código do tema, abra `layout.liquid`, clique em **Copiar código do tema** e cole logo antes de `</body>`. Esse código usa Liquid e também informa ao Conteúdo Rico qual é o produto da página. **Nunca cole esse código no Tag Manager.**
* **Pelo Google Tag Manager:** crie uma tag **HTML personalizado**, clique em **Copiar código do Tag Manager**, cole na tag, use o acionador **All Pages** e publique o contêiner. O produto vem do evento `view_item` que a loja já envia.

**2. Ligue o Conteúdo Rico automático**

No cartão, ligue **Inserir o Conteúdo Rico nas páginas de produto**. Ele precisa de um dos códigos instalado e do módulo Conteúdo Rico liberado para a sua conta.

**3. Inclua o domínio da vitrine**

Se você usa a lista de domínios autorizados do embed, inclua o endereço da loja (por exemplo, `www.sualoja.com.br`). Sem isso, o conteúdo não aparece. Se nunca configurou a lista, não há nada a fazer.

> [!WARNING]
>
> A tag genérica da **Tag do site** (`…/octa/l.js` com `data-octa="pk_live_…"`) **não ativa** a inserção automática na Olist, porque não identifica a plataforma. E o código do Tag Manager não faz nada se a página já tiver um script com `data-octa`. **Troque a tag genérica pelo código do cartão** em vez de instalar um por cima do outro.

Onde o conteúdo entra:

* Com um **Seletor CSS (opcional)**, logo depois desse elemento. Clique em **Salvar seletor** para gravar. É o recomendado, porque o tema varia de loja para loja.
* Sem seletor, no fim do `<main>` da página (ou de `[role="main"]`). Se o tema não tiver nenhum dos dois, o conteúdo não é inserido.

A OctaSend descobre o produto da página nesta ordem: o `product.id` do código do tema; o último evento `view_item` do `dataLayer` (formato do Google Tag Manager); o `productID` ou `sku` do JSON-LD do tipo `Product`. Produto sem id ou SKU identificável não mostra Conteúdo Rico. Pelo Tag Manager, o id pode chegar depois da carga, e a OctaSend tenta por até 5 segundos.

O Conteúdo Rico aparece só em páginas de produto.

## O que é sincronizado

Clientes, produtos e pedidos chegam ao menu [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md) pela importação da conexão e pelas leituras periódicas. Os pedidos também disparam as automações com o gatilho **Chegou um pedido**. Veja [Automações](https://docs.octasend.com.br/plataforma/automacoes.md).

## Desconectar

**Desconectar**, no card, age na hora e sem pedir confirmação. A integração passa a **Desconectado**, para de consultar a loja e o token salvo é apagado: para voltar, você informa o token de novo. O mapeamento e os dados já sincronizados no E-commerce são mantidos.

## O que a OctaSend não faz

* **Só lê.** Nunca confirma, cancela nem atualiza nada na sua loja, e não consome o Orders Feed da Olist (a fila que o seu ERP pode estar usando).
* **Sem webhook.** Tudo é por consulta periódica.
* **Sem link de recuperação de carrinho.**
* **Teto de 60 chamadas por minuto por loja**, para não pesar na sua operação. Quando o teto estoura, o ciclo continua no minuto seguinte, e em loja muito grande os envios atrasam mais. Se a Olist pedir para esperar, a OctaSend espera, no máximo 60 minutos.
* Com o teto apertado, carrinho e cliente (que geram mensagem) são lidos antes de pacotes e produtos (catálogo).

## Limitações

* **A importação da conexão não é retomável.** Ela pode ser cortada pelo tempo máximo de execução. Em loja grande, o catálogo e o histórico de pedidos podem ficar parciais; o que faltar de pedidos recentes, clientes e produtos alterados é coberto pelas leituras periódicas. Os eventos de pedido e carrinho não são afetados.
* **Cliente cadastrado depende da importação.** Se ela for cortada no meio da leitura de clientes, um cliente antigo ainda não lido pode receber a mensagem de boas-vindas quando atualizar o cadastro. Clientes criados entre a conexão e a primeira leitura podem não receber a mensagem.
* **Carrinho só com telefone:** a conversão desse carrinho só é conferida na hora do envio, olhando até 500 pedidos desde o dia do carrinho.
* **Recurso recusado pela Olist** (por exemplo, a permissão de carrinhos foi retirada do token): só aquele ciclo para, e os outros seguem. Token revogado põe a integração em erro.
* Um cliente novo que compra logo em seguida pode aparecer só no ciclo de clientes, com até 5 minutos de atraso.
* O uso com loja real da Olist ainda está sendo validado. Se algo se comportar diferente do descrito, fale com o suporte.

## Veja também

> [card] [Integrações](https://docs.octasend.com.br/integracoes/visao-geral.md)
>
> As plataformas disponíveis e o que muda entre elas

> [card] [Nuvem Shop](https://docs.octasend.com.br/integracoes/nuvemshop.md)
>
> Detalhes do mapeamento, do histórico e dos status

> [card] [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md)
>
> Clientes, pedidos e produtos sincronizados da loja

> [card] [Automações](https://docs.octasend.com.br/plataforma/automacoes.md)
>
> Sequências de mensagens a partir dos pedidos da loja


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.