## Visão geral

A integração **Shopify** localiza um cliente pelo e-mail ou telefone do contato e mostra os pedidos
da loja diretamente na conversa. A consulta acontece sob demanda: a ConversaLabs não persiste o cadastro
do cliente nem a resposta dos pedidos da Shopify.

Esta conexão é diferente de uma **fonte de Catálogo & Comércio**. Use esta integração para consultar
pedidos durante o atendimento; use a fonte de comércio quando quiser sincronização de catálogo,
eventos de venda, cards e automações.

## Pré-requisitos

- O operador da instalação deve configurar `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET` e a origem
  pública HTTPS da ConversaLabs. Em desenvolvimento, somente endereços HTTP de loopback são aceitos.
- O operador da instalação deve cadastrar o retorno OAuth configurado e o endpoint verificado dos
  webhooks de privacidade da Shopify nas configurações do aplicativo antes de habilitar o recurso nas contas.
- O recurso **Integração Shopify** deve estar habilitado para a conta.
- Você deve ser **Administrador** ou possuir a permissão nativa **Gerenciar integrações**.
- Tenha acesso administrativo à loja e saiba seu domínio permanente
  `sua-loja.myshopify.com`. Não use o domínio personalizado da vitrine.

## Passo a passo

1. Abra **Configurações → Integrações → Shopify**.
2. Selecione **Conectar loja** ou **Reconectar loja**.
3. Informe somente o domínio `sua-loja.myshopify.com`, sem `https://`, caminho, parâmetros ou porta.
4. Na Shopify, revise a loja e as permissões e conclua a autorização no mesmo navegador.
5. De volta à ConversaLabs, abra uma conversa cujo contato tenha e-mail ou telefone e expanda
   **Pedidos da Shopify**.

Reconectar substitui com segurança a credencial da conta e serve para renovar permissões ou trocar a
loja. Cada tentativa expira em aproximadamente dez minutos, fica vinculada ao navegador que a iniciou
e só pode ser concluída uma vez. Se cancelar, expirar ou abrir o retorno em outro navegador, comece
novamente pela tela da integração.

## Configurações & opções

- A aplicação solicita apenas `read_customers` e `read_orders`.
- O e-mail/telefone do contato é enviado à busca da Shopify; a resposta para a interface contém
  somente ID, data, valor, moeda e estados financeiro/de preparação, além do link administrativo.
- Por padrão, a API da Shopify disponibiliza pedidos dos últimos **60 dias**. Acesso histórico maior
  depende de aprovação separada da Shopify e não é solicitado por esta integração.
- O token fica no servidor, nunca é exposto no navegador, no Swagger nem no MCP.
- Os webhooks obrigatórios de privacidade são verificados por HMAC. Pedidos e clientes são consultas
  transitórias; por isso, solicitações de acesso/remoção de cliente são confirmadas sem apagar uma
  cópia local inexistente. `shop/redact` remove a conexão salva daquela loja.

## Casos de uso

- Consultar valor, data e situação de um pedido sem sair da conversa.
- Abrir o pedido correto no admin da Shopify para tratar troca, entrega ou reembolso.
- Reconectar a mesma loja depois de uma alteração de permissões.
- Trocar a loja vinculada à conta sem criar credenciais duplicadas.

## Dicas, limites e boas práticas

Na tela da Shopify, escolha **Desconectar** e confirme. A remoção continua disponível mesmo se o
recurso tiver sido desabilitado, para que uma credencial antiga nunca fique presa. Revogue também o
aplicativo no admin da Shopify quando encerrar definitivamente o uso.

Use sempre o domínio permanente `.myshopify.com`, conclua cada tentativa no navegador que a iniciou e
revise periodicamente quem possui a permissão **Gerenciar integrações**.

## Solução de problemas

- **Domínio inválido**: copie o domínio `.myshopify.com` em **Configurações → Domínios** da Shopify.
- **Integração não habilitada**: peça ao operador para ativar o recurso nesta conta.
- **Retorno com erro**: mantenha o mesmo navegador, confirme o relógio correto e reinicie a conexão;
  não reutilize um link antigo.
- **Contato sem pedidos**: confirme que o contato possui o mesmo e-mail ou telefone cadastrado na
  Shopify e lembre-se do limite padrão de 60 dias.
- **Permissões alteradas**: use **Reconectar loja** e aprove novamente.
- **Falha temporária**: use **Tentar novamente** no painel de pedidos. A mensagem não revela resposta
  técnica nem credenciais do provedor.

## Veja também

- [Integrações: provedores, credenciais, OAuth, webhooks e API](/hc/ajuda/articles/administration-integracoes-pt-br)
- [Ciclo de vida de e-commerce](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-pt-br)
- [Papéis personalizados e governança](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-pt-br)