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

# Shopify

> Conectar a loja, receber os pedidos novos e importar o histórico.

A integração com a Shopify traz os pedidos da loja para a Atriby sem que você
escreva código. Depois de conectada, cada pedido pago, estornado ou contestado
chega sozinho.

## 1. Conectar a loja

No painel, vá em **Integrações → Plataformas**, encontre o cartão da Shopify,
informe o endereço da loja e clique em **Conectar**.

Use o domínio `.myshopify.com`, e não o domínio público da vitrine. Ele é a
identidade da loja na Shopify e não muda quando você troca de domínio — e o
botão só habilita quando o endereço tem essa forma.

A Shopify vai pedir para instalar o app e mostrar as permissões. Ao aceitar,
você volta para o painel com a confirmação na tela, e a loja passa a aparecer
no cartão.

### As permissões pedidas

A Atriby pede quatro, e nenhuma delas escreve na sua loja:

| Permissão                        | Para quê                                               |
| -------------------------------- | ------------------------------------------------------ |
| `read_orders`                    | ler os pedidos                                         |
| `read_all_orders`                | alcançar pedidos com mais de 60 dias, para o histórico |
| `read_customers`                 | nome e e-mail do comprador no pedido                   |
| `read_shopify_payments_disputes` | saber quais pedidos viraram chargeback                 |

<Note>
  A tela de permissões da Shopify pode mostrar **uma a mais** do que estas
  quatro. Ela concede `customer_read_orders` por implicação, junto com
  `read_orders`, e por isso a loja conectada aparece no painel com cinco. Também
  é leitura.
</Note>

A Atriby **não pede permissão de escrita**. Ela não altera pedidos, produtos,
preços nem clientes.

## 2. Criar a fonte de venda

No painel, vá em **Integrações → Webhooks → Receber vendas**, escolha
**Shopify**, dê um nome e clique em **Criar fonte**.

Aqui não há URL para copiar nem chave para colar. A Atriby registra os webhooks
na loja pela API, no momento em que você cria a fonte, e mostra quais foram
registrados:

```text theme={null}
orders/create   orders/paid   orders/updated
refunds/create  disputes/create  disputes/update
```

Desativar a fonte cancela esses registros na loja; reativar registra de novo.

## 3. Importar o histórico

Os webhooks só trazem o que acontece **de agora em diante**. Para trazer as
vendas anteriores, a importação retroativa lê a loja inteira e grava os pedidos
que ainda não existem na Atriby.

Ela roda em modo de conferência por padrão: conta o que traria, o que recusaria
e quanto soma, **sem gravar nada**. Só depois de os números baterem com a tela
da Shopify é que a gravação acontece.

Peça a importação pelo suporte informando a loja. Ela ainda não é disparada
pelo painel.

## O que a Atriby faz com cada pedido

**A taxa do Shopify Payments é descontada.** O líquido do vendedor sai de
`transactions[].fees`, e não do valor pago. Sem isso a loja apareceria cerca de
3% mais lucrativa do que é.

**Chargeback não fica escondido atrás do estado do pedido.** Um pedido com
disputa perdida continua marcado como pago na Shopify. A Atriby cruza com a
lista de disputas do Shopify Payments e registra a perda no dia em que ela
aconteceu, mantendo o pagamento no dia em que ele entrou. São dois eventos
independentes: um pedido pago em janeiro e contestado em março é receita de
janeiro **e** perda de março.

**A moeda é a da loja, com a cotação do dia congelada.** Uma loja em GBP entra
em GBP, e a conversão usa a taxa do dia da venda, não a de hoje.

**Pedido de teste entra marcado como teste** e fica fora das telas por padrão.

## Limites de hoje

* **Estorno parcial não é aceito.** O pedido é recusado e contado, em vez de
  entrar arredondado. A Atriby trata estorno como valor cheio, então tratar
  20 de um pedido de 100 como estorno completo subtrairia 100.
* **Atribuição por UTM não é preenchida.** As vendas da Shopify entram sem
  campanha e aparecem em `(not set)` na visão por campanha. O dado existe do
  lado da Shopify e a integração está pronta para usá-lo; falta a decisão de
  ligar.
* **A importação retroativa ainda não tem botão.** O passo 3 é feito por
  suporte.

## Se algo não chegar

Abra **Integrações → Webhooks**, encontre a fonte da Shopify e olhe **Eventos
recentes**. Cada entrega aparece com o desfecho:

| Desfecho  | O que significa                |
| --------- | ------------------------------ |
| Pedido    | virou ou atualizou um pedido   |
| Atividade | chegou e não mexia em dinheiro |
| Recusado  | a assinatura não conferiu      |
| Falhou    | chegou e não pôde ser aplicado |

Uma entrega que falha por indisponibilidade momentânea é **retentada pela
Shopify** por até quatro horas. Não é preciso fazer nada nesse caso.