Integração Shopify

Emissão automática de NF-e quando o cliente paga um pedido na sua loja Shopify.

Como funciona

Cliente paga no Shopify → Shopify dispara webhook → Nossa API
                                                        ↓
                                                 Monta payload NF-e
                                                        ↓
                                                  Emite automaticamente
                                                        ↓
                                               E-mail ao cliente com XML+DANFE

1. Configurar webhook no Shopify

1. Acesse Admin → Settings → Notifications → Webhooks
2. Crie um novo webhook:
   • Event: Order payment
   • URL: https://api.nferapido.com.br/webhooks/shopify/order-paid
   • Format: JSON
3. Copie o Shopify webhook signature key
4. Cole no .env da API: SHOPIFY_WEBHOOK_SECRET=sua-key-aqui

2. Vincular loja à empresa

No dashboard ou via API:

PATCH /api/v1/empresas/{id}

{
  "shopify_domain": "sua-loja.myshopify.com"
}

3. Configurar NCM padrão dos produtos

No Shopify, em cada produto:

• Metafields → Custom → NCM = 61091000 (por exemplo)

Quando vier o webhook, a API lê essa metafield para preencher a nota.

4. Fluxo automático

Ao pagamento confirmado:

1. Shopify envia o payload para /webhooks/shopify/order-paid
2. API valida assinatura HMAC-SHA256
3. Converte order em payload NF-e (produto, cliente, valores)
4. Enfileira emissão assíncrona
5. SEFAZ autoriza em segundos
6. E-mail automático ao cliente com XML + DANFE anexos
7. Webhook disparado para seu sistema com status final

5. Cancelamento automático

Webhook adicional para cancelar NF-e quando pedido for cancelado:

URL: https://api.nferapido.com.br/webhooks/shopify/order-cancelled
Event: Order cancellation

A API identifica a NF-e pelo shopify_order_id e dispara o cancelamento SEFAZ automaticamente.

Troubleshooting

Webhook retornou 401: verifique SHOPIFY_WEBHOOK_SECRET

NF-e rejeitada com CNPJ destinatário inválido: consumidor Shopify geralmente não tem CNPJ. A API consulta o CPF em customer.note (você precisa configurar um campo customizado no checkout).

NCM não informado: configure a metafield em cada produto ou use um NCM padrão (empresa.ncm_padrao).