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

# Shopify

> Envie confirmação de pedido, rastreio e carrinho abandonado de uma loja Shopify pelo WhatsApp.

Esta página mostra como enviar confirmação de pedido, rastreio e carrinho abandonado de uma loja Shopify pelo WhatsApp. A Arara não tem app nem conector nativo para Shopify: não existe tela "Integrações → Shopify" nem templates criados automaticamente. A integração usa o que a API já oferece:

1. **Seu backend recebe os webhooks do Shopify** e chama `POST /v1/messages` com um template aprovado. Controle total, serve para qualquer evento (pedido pago, envio, entrega).
2. **Endpoint de recuperação de receita**: uma URL por organização que dispara o template configurado no dashboard. Serve quando quem chama consegue mandar headers e corpo customizados.

<Note>
  O endpoint de recuperação de receita depende do plano da organização.
</Note>

## Antes de começar

* Um número conectado na Arara.
* Templates aprovados. Veja [Templates](/concepts/templates).
* Uma chave de API (`ara_live_...`) em `ARARA_API_KEY`. Veja [Autenticação](/api-reference/authentication).

## Opção 1: webhook do Shopify no seu backend

### Configure o webhook no Shopify

No admin do Shopify, crie os webhooks (via app customizado ou em **Configurações → Notificações → Webhooks**) apontando para uma rota sua, por exemplo `https://seusite.com/webhooks/shopify`. Eventos úteis:

| Evento Shopify | Uso |
| - | - |
| `orders/paid` | Confirmação de pedido |
| `fulfillments/create` | Pedido enviado, com código de rastreio |
| `checkouts/create` / `checkouts/update` | Base para detectar carrinho abandonado |

Valide o `X-Shopify-Hmac-Sha256` de cada entrega conforme a documentação do Shopify antes de processar.

### Envie o template pela Arara

Exemplo em Node (SDK `@ararahq/sdk`) para `orders/paid`:

```typescript theme={null}
import { NodeSDK } from '@ararahq/sdk';

const arara = new NodeSDK({ apiKey: process.env.ARARA_API_KEY! });

export async function onOrderPaid(order: {
  id: number;
  name: string;
  total_price: string;
  order_status_url: string;
  customer?: { first_name?: string; phone?: string | null };
  phone?: string | null;
}) {
  const phone = order.customer?.phone ?? order.phone;
  if (!phone) return; // checkout sem telefone: nada a enviar

  await arara.messages.send(
    {
      receiver: `whatsapp:${phone}`,
      templateName: 'pedido_confirmado',
      templateVariables: [
        order.customer?.first_name ?? 'cliente', // {{1}}
        order.name,                              // {{2}} ex.: #1001
        order.total_price,                       // {{3}}
        order.order_status_url,                  // {{4}}
      ],
    },
    { idempotencyKey: `shopify-order-paid-${order.id}` },
  );
}
```

O template `pedido_confirmado` é seu: crie e aprove antes, com o número de variáveis que o código envia. O Shopify reenvia webhooks que não recebem 2xx; a `idempotencyKey` derivada do id do pedido impede mensagem duplicada.

Para `fulfillments/create`, o mesmo padrão com `tracking_number` e `tracking_url` como variáveis.

<Warning>
  O telefone precisa estar em formato internacional (`+5511999999999`). Se o checkout não obriga telefone, parte dos pedidos não terá para quem enviar. Confira nas configurações de checkout do Shopify.
</Warning>

### Carrinho abandonado

O Shopify não envia um evento "carrinho abandonado". O padrão é: grave o checkout em `checkouts/create`, agende uma verificação (por exemplo 1h depois) e, se não houver pedido para aquele checkout, envie o template com o link `abandoned_checkout_url`. O fluxo completo está na [receita de carrinho abandonado](/recipes/abandoned-cart).

## Opção 2: endpoint de recuperação de receita

Cada organização tem uma URL de ingestão que recebe eventos de carrinho abandonado e pagamento e dispara o template configurado. O contrato completo (headers, assinatura, variáveis, respostas e motivos de rejeição) está em [Recuperação de receita](/recovery).

Resumo do que importa para o Shopify:

* O endpoint nasce desligado. Ative em `PATCH /v1/recovery/endpoint` ou pelo dashboard, em Recuperação.
* Os endpoints `/v1/recovery` exigem chave de API com permissão `ADMIN`.
* Envie o `POST` do evento para `https://api.ararahq.com/l/{code}`, com o header `X-Arara-Event`.

<Note>
  Os webhooks nativos do Shopify não permitem definir `X-Arara-Event` nem o formato do corpo. Para usar o endpoint a partir do Shopify, é preciso uma camada intermediária: seu backend, ou uma ferramenta de automação que permita requisição HTTP com headers e corpo customizados.
</Note>

## Catálogo no WhatsApp

O Brain tem a action `META_CATALOG_SEND`, que envia um produto do **catálogo da Meta** (Commerce Manager) como card no WhatsApp. A Arara não sincroniza produtos do Shopify: o catálogo precisa estar configurado na Meta, com os produtos já sincronizados por você. Veja [Brain, catálogo](/brain/actions/catalog).

## Limitações

* Sem app, OAuth ou sincronização automática com Shopify.
* Sem templates Shopify pré-criados: crie e aprove os seus.
* Pagamento Pix dentro da conversa depende da action `ABACATE_PIX` do Brain, independente do Shopify. Veja [AbacatePay](/brain/actions/abacate-pix).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Receita: Carrinho abandonado" icon="cart-shopping" href="/recipes/abandoned-cart">
    Fluxo de ponta a ponta.
  </Card>

  <Card title="Recuperação de receita" icon="rotate-right" href="/recovery">
    Contrato do endpoint e eventos.
  </Card>
</CardGroup>


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