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

# Linx Commerce

> Conecte sua loja Linx Commerce por usuário de API e fila de integração para disparar comunicações de pedido, cliente novo e carrinho abandonado e sincronizar clientes, pedidos e produtos

A integração com a **Linx Commerce** conecta sua loja à OctaSend pela API de integração da Linx (Layer). Com ela você:

* **Dispara comunicações** a partir dos eventos de pedido (criado, pago, faturado, enviado, entregue, cancelado e qualquer status que a sua loja use), de cliente novo e de carrinho abandonado.
* **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).

A integração é **somente leitura** sobre os dados da loja. A única escrita na Linx é retirar da fila de integração os itens já consumidos, que é o protocolo da própria fila. O funcionamento geral do mapeamento, do histórico e dos status é o mesmo da [Nuvem Shop](https://docs.octasend.com.br/integracoes/nuvemshop.md).

> [!NOTE]
>
> A Linx não tem webhook para sistemas de terceiros. A OctaSend lê uma **fila de integração** que você cria no Admin da Linx, uma vez por minuto. Por isso as mensagens não saem na hora.

## Antes de começar

Faça no Admin da Linx:

**1. Crie um usuário de API**

Crie um usuário de API só para a OctaSend.

**2. Opcional: ligue o JWT**

Em **Configurações gerais › Sistema › Segurança › Autenticação**, ligue a autenticação JWT. Sem ela, a conexão manda o usuário e a senha em cada consulta (modo Basic). A OctaSend tenta JWT primeiro e usa Basic se ele não estiver habilitado.

**3. Crie uma fila exclusiva**

Em **Integrações › Gerenciamento de Filas**, crie uma fila só para a OctaSend (sugestão de alias: `octasend`) e assine **Pedidos**, **Clientes** e **Produtos**.

> [!WARNING]
>
> Não use a fila do seu ERP. Quem lê primeiro retira o item da fila, e o outro sistema perde a mudança.

## Conectar

**1. Abra o card da Linx**

Em **Configurações → Integrações**, clique em **Conectar** no card **Linx Commerce**.

**2. Preencha os dados**

| Campo | O que informar |
| - | - |
| **Endereço da Layer** | O nome do ambiente (`minhaloja`) ou o endereço completo, como `https://minhaloja.layer.core.dcg.com.br`. |
| **Usuário de API** | O usuário criado no Admin da Linx só para a OctaSend. |
| **Senha do usuário de API** | A senha desse usuário. |
| **Alias da fila** | A fila criada para a OctaSend. O padrão é `octasend`. |
| **Endereço da loja** | Usado nas mensagens de carrinho abandonado e na variável `loja_url`. |
| **Nome da loja** | Aparece nas mensagens. Em branco, usamos o endereço da Layer. |

**3. Salve a conexão**

A OctaSend confere o usuário e a senha, e confere se a fila existe e está ativa. Se algo estiver errado, o erro aparece no campo certo.

Regras da conexão:

* Se a Linx recusar o usuário ou a senha depois da conexão, a integração fica **Com erro** e pede para você atualizar a conexão.
* Se a fila deixar de existir na Linx, a integração também fica **Com erro**: recrie a fila e atualize a conexão.
* **Uma integração guarda os dados de uma loja Linx.** Depois de conectada, não dá para trocar o endereço da Layer por outra loja na mesma integração: para conectar uma loja diferente, fale com o suporte. O mesmo endereço em outro formato (com `https://`, maiúsculas ou barra no final) é aceito.
* Uma instalação Linx com várias lojas (sites) usa uma só conexão.

## Importação inicial

Ao salvar a conexão, a OctaSend importa em segundo plano os **clientes**, os **produtos** e os **pedidos dos últimos 90 dias**. Essa importação:

* **não envia mensagem**: só o que acontecer depois da conexão dispara;
* é **retomável**: se a Linx ficar fora do ar ou o tempo de execução acabar, ela continua de onde parou no minuto seguinte;
* tem seu andamento na lista de integrações e abaixo do título da tela de mapeamento: **Importação em andamento**, **Importação concluída em dd/mm** ou **Importação com erro**;
* vai para **erro** se a Linx ficar indisponível por mais de 24 horas, ou se 5 tentativas seguidas não avançarem. Para recomeçar, abra **Editar conexão** e salve de novo.

Lojas com muitos pedidos levam horas para importar, e os eventos da fila continuam saindo enquanto isso.

## 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). Na Linx não há aba **Rotinas**: os dados chegam pela fila.

| Evento | Quando dispara |
| - | - |
| Pedido criado | Um pedido novo entra na loja, depois da conexão. Só sai quando o pedido é incluído: um pedido que muda para o status "criado" gera apenas a linha **Status: (nome)** dele. |
| Pagamento aprovado | O pedido passa a **Pagamento Aprovado**. |
| Pedido faturado | O pedido passa a **Faturado**. |
| Pedido enviado | O pedido passa a **Enviado**. Leva as variáveis de rastreio. |
| Pedido entregue | O pedido passa a **Entregue**. Leva as variáveis de rastreio. |
| Pedido cancelado | O pedido passa a **Pedido Cancelado**. |
| Status: (nome do status) | Uma linha para cada status cadastrado na sua loja, com o nome que você usa na Linx. |
| Cliente cadastrado | Um cliente novo é criado na loja. |
| Carrinho abandonado | Um carrinho é marcado como abandonado pela Linx. |

* **Status padrão e status da sua loja.** Os eventos fixos são ligados pelo **número** do status padrão da Linx (não pelo nome). Se a sua loja renomeou ou recriou os status, use as linhas **Status: (nome)**, que acompanham os status que você cadastrou.
* **Uma vez só.** Cada evento sai uma vez por pedido, cliente ou carrinho. Reprocessar o mesmo item nunca reenvia.
* **Só o que aconteceu depois da conexão** dispara.
* Um pedido que muda de status gera o evento fixo do novo status (quando existe) **e** a linha **Status: (nome)** dele. Mapeie só uma das duas se não quiser mensagem duplicada.

### Quem recebe a mensagem

O destinatário prefere o celular e cai para o telefone fixo. O e-mail vai junto para os canais de e-mail. Sem e-mail e sem celular, o evento aparece como **Ignorado**.

## Variáveis

**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**

| Variável | Conteúdo |
| - | - |
| `{{pedido_numero}}` | Número do pedido |
| `{{pedido_total}}` | Valor total |
| `{{pedido_subtotal}}` | Soma dos itens, sem frete e desconto |
| `{{pedido_frete}}` | Valor do frete |
| `{{pedido_desconto}}` | Valor do desconto |
| `{{pedido_status}}` | Status do pedido, com o nome usado pela loja |
| `{{pedido_itens}}` | Itens do pedido, um por linha (`2× Nome`) |
| `{{pedido_pagamento}}` | Forma de pagamento |
| `{{pedido_data}}` | Data do pedido (dd/mm/aaaa) |

**Rastreio** (eventos de envio e entrega, e linhas **Status: (nome)**), além das variáveis de pedido

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

**Carrinho abandonado** (mais as variáveis comuns)

| Variável | Conteúdo |
| - | - |
| `{{carrinho_total}}` | Valor do carrinho |
| `{{carrinho_quantidade}}` | Quantidade de itens no carrinho |

Os valores saem no formato brasileiro (`R$ 1.234,56`).

## Carrinho abandonado

A Linx marca o carrinho como **Abandonado** conforme o tempo configurado no Admin da Linx. A OctaSend confere os carrinhos a cada 5 minutos e envia a comunicação mapeada em **Carrinho abandonado** para quem tem e-mail ou celular.

* Não precisa de script na loja.
* Só entram carrinhos que ficaram abandonados nas últimas 24 horas: depois de uma pausa longa da integração, carrinhos mais antigos não disparam.
* Na hora do envio, a OctaSend confere o carrinho de novo. Se ele já foi convertido em pedido ou não está mais abandonado, o envio aparece como **Ignorado** ("Carrinho convertido").
* A mensagem leva o endereço da loja, **não** um link para retomar o carrinho.
* Diferente da [Wake](https://docs.octasend.com.br/integracoes/wake.md), o carrinho da Linx passa pelo fluxo normal: vale no mapeamento, nas automações e no passo **Aguardar evento**.

## Tempo até a mensagem sair

| Evento | Atraso típico |
| - | - |
| Pedido e cliente | Até cerca de 1 minuto. |
| Carrinho abandonado | Até cerca de 5 minutos **mais** o tempo de abandono configurado na Linx. |

Quando um item da fila falha, a OctaSend espera mais a cada tentativa (1, 2, 4, 8, 16, 32 e 60 minutos, sem passar disso), em vez de insistir a cada minuto. Um item com erro de dado é descartado na 10ª tentativa, com o motivo no histórico. Um item com erro temporário nunca é descartado: se passar de 24 horas assim, o histórico registra um aviso e a OctaSend continua tentando.

Uma vez por dia, a OctaSend também confere os pedidos alterados desde a última conferência, olhando no máximo 72 horas para trás, o que cobre uma fila apagada, pausada ou esvaziada por engano.

## OctaTag e Conteúdo Rico na vitrine

A Linx não permite que outro sistema instale scripts na loja, então **você cola o código da [OctaTag](https://docs.octasend.com.br/plataforma/octatag.md) uma vez**. A OctaSend não altera o tema nem a descrição dos produtos. Os códigos ficam no cartão **OctaTag na loja**, em **Configurações → Integrações → Linx Commerce**, e só quem pode editar a integração os vê. Use **só um** dos caminhos.

**1. Cole o código**

* **No tema (recomendado):** no painel da Linx, abra **Aparência › Gerenciador de arquivos › Pasta do tema › Templates › Masters › Includes**, edite o template **Header** ou o **Footer** (só um deles) e cole o primeiro código do cartão no fim do arquivo.
* **Pelo Google Tag Manager:** crie uma tag **HTML personalizado**, cole o segundo código do cartão, use o acionador **Todas as páginas** e publique o contêiner.

**2. Opcional: cole o id do produto**

No template da página de produto, cole a linha que o cartão mostra em **Id do produto**. Ela diz à OctaSend qual produto está na página.

**3. Confira o Conteúdo Rico automático**

O interruptor **Inserir o Conteúdo Rico nas páginas de produto** já vem ligado na primeira vez que você conecta a loja. Se você reconectar ou editar a conexão depois, sua escolha é mantida. Ele só faz efeito com a OctaTag colada e o módulo Conteúdo Rico liberado para a sua conta.

> [!WARNING]
>
> Se a **Tag do site** genérica já está na loja, **troque-a** pelo código do cartão. Só o código do cartão avisa que a página é da sua loja Linx: com a tag genérica, o Conteúdo Rico automático não age, e o código do Tag Manager não instala o seu.

Onde o conteúdo entra:

* Com um **Seletor CSS (opcional)**, logo depois desse elemento. Clique em **Salvar seletor** para gravar. Como cada tema da Linx é diferente, recomendamos informar o seletor.
* Sem seletor, no fim do `<main>` da página (ou de `[role="main"]`). Num tema sem nenhum dos dois e sem seletor, o conteúdo não aparece.

A OctaSend descobre o produto da página nesta ordem: a linha do id do produto; o evento `view_item` do Tag Manager; os dados estruturados da página (JSON-LD com um único `Product`). Se a página descreve mais de um produto nos dados estruturados, esse item não é usado, para não mostrar o conteúdo de outro produto.

Regras:

* O conteúdo vem do produto da OctaSend com o mesmo `ProductID` ou SKU da Linx. Produto sem conteúdo publicado não mostra nada.
* Páginas que não são de produto não recebem nada.
* Se você já colou o bloco do Conteúdo Rico à mão no tema (`<div data-octasend-content …>`), o automático não coloca outro.
* Se você usa a lista de domínios autorizados (**Conteúdo Rico › Configuração**), inclua o endereço da loja. O cartão avisa quando o endereço salvo na conexão não está na lista.
* Os widgets respeitam o consentimento de cookies configurado na OctaSend.

Para remover, apague o código do Header/Footer ou pause a tag no Tag Manager. Para só parar o Conteúdo Rico automático, desligue o interruptor no cartão.

## Desconectar

**Desconectar**, no card, age na hora e sem pedir confirmação. A integração passa a **Desconectado**, para de ler a fila e as credenciais salvas (usuário e senha da API) são apagadas: para voltar, você informa tudo de novo em **Conectar**. O mapeamento e os dados já sincronizados no E-commerce são mantidos, e só pode ser reconectada a mesma loja Linx.

Ao reconectar, a importação inicial recomeça do zero e só o que acontecer depois da nova conexão dispara mensagem. A OctaSend não remove nada da fila da Linx ao desconectar.

## Limitações

* **A integração ainda não foi validada com uma loja Linx real.** A API foi conferida no ambiente demo da Linx, mas o comportamento da fila real e a instalação da OctaTag precisam ser confirmados na primeira loja. Se algo se comportar diferente do descrito, fale com o suporte.
* Não há link de recuperação de carrinho.
* Não há filtro por loja (site) dentro de uma instalação Linx.
* O nome da variável do id do produto no template da Linx ainda não foi conferido: confirme com quem cuida do seu tema. Se a página mostrar `{{ … }}` no lugar do número, a OctaSend ignora a linha e usa o evento do Tag Manager ou os dados estruturados.
* O Conteúdo Rico é inserido uma vez por página. Se a vitrine trocar de produto sem recarregar a página, o conteúdo pode não acompanhar.

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