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

# Conectando a Shopify

> Instale o app do BulkRoute na sua loja Shopify e importe pedidos automaticamente.

A [Shopify](https://www.shopify.com) é a principal plataforma de e-commerce do mundo. O BulkRoute tem um app embedded (iframe no admin Shopify) que importa pedidos e sincroniza tracking.

## Como funciona

```
Shopify App (embedded no admin) → BulkRoute importa pedidos pagos
BulkRoute atualiza tracking → Shopify fulfillment atualizado
```

## Instalando o app

### 1. Acessar a Shopify App Store

O app BulkRoute está disponível na Shopify App Store. Para instalar:

1. Acesse a Shopify App Store e busque por "BulkRoute"
2. Clique em **Add app**
3. Selecione a loja onde deseja instalar
4. Autorize os escopos solicitados

### Escopos solicitados

| Escopo               | O que permite                            |
| :------------------- | :--------------------------------------- |
| `read_orders`        | Importar pedidos pagos                   |
| `write_fulfillments` | Marcar pedido como fulfilled + tracking  |
| `write_shipping`     | Registrar BulkRoute como carrier service |
| `read_products`      | Ler dimensões e peso dos produtos        |
| `read_locations`     | Identificar CD de origem                 |

### 2. Configurar o app

Após instalar, o app abre dentro do admin Shopify (iframe):

1. **Conectar ao BulkRoute**: insira sua API Key (`bk_live_...`)
2. **Selecionar CD de origem**: qual location da Shopify é o CD padrão
3. **Mapear carriers**: qual carrier do BulkRoute despacha os pedidos
4. **Ativar sincronização**: pedidos pagos passam a ser importados automaticamente

## O que é sincronizado

### Shopify → BulkRoute

* **Pedidos pagos** (`orders/paid` webhook) → viram shipments
* **Dados do cliente** (nome, e-mail, telefone, endereço)
* **Itens do pedido** (SKU, título, quantidade, peso, dimensões)
* **CEP de origem** (do location selecionado)

### BulkRoute → Shopify

* **Fulfillment** criado no pedido Shopify com o tracking code
* **Status de entrega** atualizado quando o carrier entrega
* O cliente final vê o tracking dentro do Shopify ou pelo link do BulkRoute

## Carrier Service

O BulkRoute se registra como um **Carrier Service** na Shopify. Isso permite que:

* O checkout da Shopify mostre o BulkRoute como opção de frete
* O preço seja calculado em tempo real pelo orquestrador do BulkRoute
* O prazo seja exibido conforme cada carrier

## Webhooks

O app BulkRoute registra os seguintes webhooks na Shopify:

| Webhook                  | Uso                             |
| :----------------------- | :------------------------------ |
| `orders/paid`            | Importar pedido quando é pago   |
| `orders/cancelled`       | Cancelar shipment no BulkRoute  |
| `orders/fulfilled`       | Confirmar fulfillment           |
| `shop/redact`            | GDPR: apagar dados da loja      |
| `customers/redact`       | GDPR: apagar dados de cliente   |
| `customers/data_request` | GDPR: exportar dados de cliente |

## Custom App vs Public App

| Tipo           | Quando usar                                                |
| :------------- | :--------------------------------------------------------- |
| **Custom App** | Primeiros clientes, distribuição controlada, acesso direto |
| **Public App** | Publicação na App Store, disponível para qualquer loja     |

O BulkRoute começou como **Custom App** para os primeiros clientes e está sendo preparado para publicação como **Public App** na Shopify App Store.

## Troubleshooting

| Problema                      | Causa                              | Solução                                             |
| :---------------------------- | :--------------------------------- | :-------------------------------------------------- |
| Pedidos não importam          | App não conectado ao BulkRoute     | Verificar API Key no app                            |
| Tracking não sincroniza       | Sem permissão `write_fulfillments` | Reautorizar app                                     |
| Frete não aparece no checkout | Carrier Service não registrado     | Reinstalar app                                      |
| Webhook não chega             | URL do app inacessível             | Verificar subdomínio `shopify-app.bulkroute.com.br` |

## Documentação técnica

Para detalhes técnicos sobre o app Shopify (Partner Dashboard, OAuth, deploy, nginx, PM2), veja `docs/integrations/shopify.md` no repositório do BulkRoute.