Conexão API Shopify: OAuth, Custom App ou token privado? Comparativo claro para escolher o método de autenticação certo em 2026.
Digitar "shopify conexão" no Google retorna quase que exclusivamente tutoriais para se reconectar à conta admin. O verdadeiro problema, para a maioria dos desenvolvedores que chegam nesta página, não tem nada a ver com uma senha esquecida: eles querem conectar uma aplicação de terceiros à API Shopify, e se perdem entre três métodos de autenticação completamente diferentes.
Essa confusão custa tempo. Muito tempo. Este artigo compara as três formas de conectar uma app à Shopify, custom app, OAuth público, token legacy, e diz claramente qual usar segundo sua situação.
Os três métodos de conexão com a API Shopify
Historicamente, Shopify oferece vários caminhos para obter acesso à Admin API. Eles não são intercambiáveis, e a documentação oficial frequentemente os mistura em páginas diferentes sem nunca compará-los frente a frente.
A custom app (aplicação admin-only)
É o método recomendado para uso interno: uma integração desenvolvida para uma única loja, sem intenção de publicá-la no Shopify App Store. O lojista gera ele mesmo um token de acesso desde seu painel de administração, definindo os scopes necessários (leitura de pedidos, escrita de produtos, etc.).
Sem flow OAuth, sem redirecionamento, sem review Shopify. Você gera o token e o usa. É direto.
O flow OAuth (public app)
Necessário se a aplicação precisa funcionar em múltiplas lojas diferentes, tipicamente uma app destinada a ser listada na Store. O lojista autoriza o acesso via uma tela de consentimento, Shopify redireciona para seu callback com um código de autorização, e seu servidor troca esse código por um token.
É mais trabalhoso de implementar. Mas é a única opção viável se você não controla a loja de destino.
O token privado legacy
Método antigo, ainda presente em parte do código em produção de alguns clientes que auditamos. Shopify está empurrando ativamente para custom apps há vários anos. Um projeto que ainda usa um private app "clássico" merece ser migrado, não é mais o caminho recomendado pela plataforma.
A tabela comparativa
| Critério | Custom App | OAuth (Public App) | Token legacy |
|---|---|---|---|
| Uso-alvo | Uma única loja | Multi-lojas, App Store | Deprecado |
| Implantação | Simples, alguns minutos | Complexa, flow completo para codificar | Simples mas obsoleto |
| Review Shopify | Não obrigatória | Obrigatória se publicada na Store | Não obrigatória |
| Rotação de tokens | Manual | Gerenciada pelo flow OAuth | Manual |
| Recomendado em 2026 | Sim | Sim, se multi-lojistas | Não |
O erro mais frequente que vemos em nossos clientes
A maioria das equipes escolhe o método de autenticação antes de saber quantas lojas sua app precisará servir. Resultado: elas partem para um flow OAuth completo, webhook de callback, gerenciamento de state, armazenamento seguro de tokens por lojista, para um projeto que nunca servirá mais de uma única loja interna.
Isso é três a quatro vezes mais código do que o necessário.
Em um cliente e-commerce que acompanhamos, a integração existente ainda rodava em um token legacy de vários anos atrás. Os scopes eram muito amplos, acesso completo a pedidos e clientes para uma ferramenta que precisava apenas ler estoques. Migramos para uma custom app com scopes precisos. Resultado imediato: superfície de ataque reduzida e nenhum alerta de segurança nessa integração nos audits subsequentes.
Uma limitação honesta a conhecer: a custom app funciona apenas na loja onde foi criada. Se seu cliente mudar de plano Shopify ou migrar para uma nova loja, é preciso regenerar o token. Isso não é automático.
Proteger sua conexão uma vez obtido o token
Escolher o método certo não é suficiente. O token em si deve ser tratado como um segredo crítico, nunca commitado em um repo, nunca logado em texto plano.
Três práticas reduzem muito o risco:
- Armazenar o token em um gerenciador de secrets (variáveis de ambiente encriptadas, vault dedicado), nunca no código-fonte.
- Limitar os scopes ao estritamente necessário desde a criação da app, em vez de marcar tudo "só por segurança".
- Implementar uma rotação regular, mesmo que manual, em vez de manter o mesmo token por anos.
E se sua equipe tem menos de três desenvolvedores no projeto Shopify, a custom app continua sendo quase sempre a escolha certa por padrão. O flow OAuth completo só faz sentido se múltiplos lojistas independentes vão instalar sua app em algum momento.
O que reter
Três métodos existem, mas uma única pergunta determina a escolha certa: sua app vai servir uma loja ou múltiplas? Para uma única loja, a custom app é suficiente e se implanta em alguns minutos. Para multi-lojistas, rumo a OAuth, apesar de sua complexidade.
O token legacy, por sua vez, não tem mais lugar em um projeto novo em 2026.
Se sua integração Shopify atual ainda usa um método antigo de autenticação, ou se você está em dúvida sobre a arquitetura a adotar para uma nova app, a equipe fstck pode auditar seu setup atual e propor uma migração limpa. Já escrevemos sobre assuntos de arquitetura parecidos em nosso guia sobre como criar um servidor MCP, onde a lógica de gerenciamento de acesso a ferramentas externas segue princípios muito similares.
Perguntas frequentes
Como obter um token de acesso Admin API sem passar pelo flow OAuth completo?
Criando uma custom app direto na interface de administração Shopify do lojista. O token é gerado imediatamente após definir os scopes necessários, sem redirecionamento ou tela de consentimento.
Por que meu token Shopify retorna um erro 401 depois de vários meses de uso?
As causas mais comuns são revogação manual do token pelo lojista, uma mudança de scopes na app, ou uma desinstalação seguida de reinstalação que gera um novo token. Verifique primeiro o status da app no admin Shopify do lojista em questão.
Qual é a diferença entre uma custom app e uma private app legacy no Shopify?
A custom app é o método atualmente recomendado pelo Shopify para uso mono-loja, com gerenciamento de scopes mais fino. O termo "private app" designava o sistema antigo, hoje deprecado em favor das custom apps.
É preciso um flow OAuth para conectar uma única loja Shopify a uma ferramenta interna?
Não. O flow OAuth só agrega valor se sua aplicação precisar ser instalada por múltiplos lojistas independentes, tipicamente para publicação no Shopify App Store. Para uso interno mono-loja, a custom app é mais rápida e suficiente.
Os scopes de uma custom app Shopify podem ser modificados após criação?
Sim, mas qualquer mudança de scopes geralmente requer regenerar o token de acesso. É justamente uma oportunidade de verificar que as permissões concedidas ainda correspondem à necessidade estrita da integração.
