Índice do artigofaltam 6 min de leitura
A dúvida que aparece em toda loja com aplicativo próprio é se precisa de "alguma coisa no meio" entre a VTEX e o app. A resposta não depende de arquitetura preferida. Depende de onde a credencial vai morar.
Uma operação que roda em VTEX e decide construir um aplicativo próprio, um portal de vendedores ou uma experiência de compra fora do padrão chega rápido nessa bifurcação: o app fala direto com a plataforma ou existe um serviço intermediário?
A pergunta costuma ser tratada como preferência de arquitetura, com argumentos de custo e simplicidade dos dois lados. Ela não é. Existe um critério objetivo, e ele começa pelo tipo de credencial que a integração precisa usar.
Resumo do artigo
- A VTEX separa credenciais por contexto: application key para backend, user token para frontend e auth token para apps VTEX IO. Usar a errada é um defeito de segurança recorrente nesse tipo de projeto.
- O par appKey e appToken viaja nos headers
X-VTEX-API-AppKeyeX-VTEX-API-AppTokene carrega as permissões concedidas a ele. Credencial assim não pode ser embarcada em aplicativo. - A camada intermediária existe primeiro por causa da credencial. Cache, agregação e regra de negócio própria são consequências, não a justificativa.
- Nem toda loja precisa dela. Consumo apenas de catálogo público dentro das ferramentas da plataforma dispensa a camada.
A pergunta certa é onde a credencial vai morar
Aplicativo instalado no celular do consumidor é um ambiente que você não controla. Qualquer chave embarcada ali pode ser extraída por quem tem o aplicativo, e nenhuma técnica de ofuscação muda esse fato de forma confiável.
Isso importa porque a credencial de backend da VTEX não é uma chave de leitura inofensiva. A application key é um par de valores, appKey e appToken, enviado nos headers X-VTEX-API-AppKey e X-VTEX-API-AppToken, e ela chega ao servidor da plataforma carregando o conjunto de permissões que foi concedido a ela quando foi criada. Uma chave gerada com folga de permissão, embarcada num aplicativo público, é uma chave da loja distribuída na loja de aplicativos.
O que isso destrava, em termos de decisão: a discussão sobre camada intermediária deixa de ser sobre elegância de arquitetura e passa a ser sobre exposição de credencial. Se a integração precisa de application key, a chamada sai de um servidor seu. Ponto.
Três credenciais, três lugares diferentes
A plataforma distingue os contextos de autenticação, e a maior parte dos erros de projeto vem de tratar os três como intercambiáveis.
| Credencial | Para que serve |
|---|---|
| Application key | Requisições de backend feitas por sistemas próprios da loja. É o par appKey e appToken, com permissões definidas na criação. |
| User token | Aplicações de frontend e requisições feitas em nome de um usuário, carregando o contexto e as permissões daquela pessoa. |
| Auth token | Autenticação de apps desenvolvidos na VTEX IO, dentro do modelo de extensão da própria plataforma. |
Fonte: documentação de autenticação da VTEX para desenvolvedores, consultada em 31 de agosto de 2026.
A leitura prática dessa tabela é direta. Se a tela precisa de algo que só a loja pode fazer, a chamada nasce no seu servidor com application key. Se a tela precisa de algo em nome do consumidor logado, o caminho é o token de usuário, que já limita naturalmente o que aquela pessoa pode ver.
O que a camada faz além de esconder a chave
Depois que o serviço intermediário existe por razão de segurança, ele passa a resolver de graça quatro problemas que apareceriam de qualquer forma.
O primeiro é agregação. Uma tela de produto costuma precisar de catálogo, preço, disponibilidade e avaliação. Feita direto do aplicativo, isso vira uma sequência de chamadas encadeadas em uma rede móvel instável. Feita no servidor, vira uma resposta única já no formato da tela.
O segundo é cache. Boa parte do que uma vitrine mostra não muda a cada acesso, e responder de cache o que não mudou costuma ser o ganho de desempenho mais barato do projeto.
O terceiro é regra própria. Programa de fidelidade, cashback, regra de frete negociada e catálogo por perfil de cliente raramente cabem exatamente no modelo padrão da plataforma. A camada é onde isso vive sem virar customização difícil de manter.
O quarto é permissão mínima. Com o serviço no meio, cada integração pode receber uma chave criada com apenas os resources do License Manager de que precisa, em vez de uma credencial ampla reaproveitada por todo mundo.
Com camada intermediária
- Credencial de backend nunca sai do seu servidor
- Uma resposta pronta por tela, em vez de chamadas encadeadas no celular
- Regra de negócio própria fora da customização da plataforma
- Chave por integração, com permissão mínima
Sem camada intermediária
- Menos um serviço para manter, monitorar e pagar
- Entrega inicial mais rápida quando o escopo é só vitrine
- Menos um ponto onde o dado pode ficar desatualizado
- Time menor consegue tocar sozinho
Quando você não precisa de camada nenhuma
Vale dizer com todas as letras, porque a resposta padrão do mercado é sempre construir mais: se a operação consome só dados públicos de catálogo e a experiência cabe nas ferramentas da própria plataforma, a camada é custo sem retorno.
O sinal de que ela ainda não é necessária é a ausência das três condições: nenhuma credencial privilegiada envolvida, nenhuma regra de negócio que a plataforma não expresse, nenhuma agregação de fonte externa. Faltando as três, construir um serviço no meio é adicionar um ponto de falha e uma conta mensal para resolver um problema que você não tem.
O sinal de que ela passou a ser necessária costuma ser um destes: apareceu uma integração com sistema de fora, apareceu uma regra que exige dado de mais de um lugar, ou apareceu a necessidade de fazer pelo app algo que só a loja pode fazer.
O caso de um app de e-commerce em VTEX
A Polishop opera em VTEX e contratou a X-Apps para reconstruir o aplicativo de e-commerce. O trabalho envolveu fazer o sistema web da marca conversar com o aplicativo, além de conectar serviços que não vivem dentro da plataforma, como a entrega expressa em parceria com uma transportadora e o mecanismo de cashback.
Esse conjunto é uma ilustração exata do critério deste artigo. Vitrine e catálogo são o pedaço fácil. O que puxou a arquitetura para uma camada própria foram os serviços de fora e as regras que a loja quis ter do seu jeito. Vale registrar a honestidade: a avaliação do aplicativo subiu de 2,3 para 4,6 estrelas ao longo do projeto, e isso é resultado de um trabalho inteiro de produto e experiência, do qual a arquitetura de integração é uma parte, não a causa isolada.
As roles do License Manager são o controle que quase ninguém usa
Ao criar uma chave de API na VTEX, você escolhe quais roles e quais resources do License Manager ela carrega. Essa escolha define, na prática, o que aquela credencial consegue fazer se vazar.
O padrão que se vê em campo é uma chave só, criada com permissão folgada no começo do projeto, compartilhada entre todas as integrações e nunca revista. O padrão que evita incidente é o oposto: uma chave por integração, com o conjunto mínimo de resources, e uma anotação de qual sistema usa qual. Isso também torna possível revogar uma integração específica sem derrubar as outras, que é a diferença entre um incidente contido e uma manhã ruim.
- Nenhuma application key embarcada em aplicativo, site público ou repositório
- Uma chave por integração, com os resources mínimos daquele uso
- Registro de qual sistema usa qual chave, para permitir revogação cirúrgica
- Token de usuário no que é feito em nome do consumidor logado
- Plano de resposta definido para quando a plataforma estiver indisponível
O último item é o mais esquecido. Vitrine que mostra preço de cache com um aviso discreto é uma experiência muito melhor do que vitrine que mostra tela de erro, e essa decisão precisa ser tomada no desenho, não durante o incidente.
Vai construir app ou portal em cima da sua loja VTEX?
Solicite um orçamento e desenhe a integração começando pela credencial, não pela tela.
Perguntas frequentes
Com as credenciais de backend, não. O par appKey e appToken é feito para requisições de sistemas próprios em servidor. Qualquer credencial embarcada em app ou site pode ser extraída por quem instala o aplicativo, e a chave carrega as permissões que foram concedidas a ela.
É um par de credenciais, appKey e appToken, enviado nos headers X-VTEX-API-AppKey e X-VTEX-API-AppToken. As permissões da chave vêm das roles e dos resources do License Manager escolhidos no momento em que ela é criada.
A application key autentica sistemas próprios em requisições de backend. O user token autentica um usuário específico em aplicações de frontend, carregando o contexto e as permissões daquele usuário, e não da loja inteira.
Não. Quando o consumo é só de dados públicos de catálogo e a experiência cabe nas ferramentas da própria plataforma, a camada é custo sem retorno. Ela passa a valer quando existe credencial privilegiada, regra de negócio própria ou agregação de mais de uma fonte.
Ela adiciona um salto de rede e costuma devolver isso com sobra, porque permite responder de cache o que não muda a cada requisição e reduzir várias chamadas à plataforma a uma só resposta pronta para a tela.
É o sistema de permissões da VTEX. Ao criar uma chave de API você escolhe quais recursos ela pode acessar, o que permite emitir uma credencial com o mínimo necessário para cada integração em vez de uma chave que faz tudo.
Fontes e método
As afirmações sobre autenticação vêm da documentação oficial da VTEX para desenvolvedores, consultada em 31 de agosto de 2026: a página de introdução à autenticação, que distingue application keys, user tokens e auth tokens, e a página de autenticação com application keys, que descreve os headers X-VTEX-API-AppKey e X-VTEX-API-AppToken e a origem das permissões nas roles e resources do License Manager.
O caso da Polishop é público e está descrito no case do projeto. Preços, limites de chamada e níveis de serviço da VTEX não foram apurados e por isso não aparecem no texto.
