Lojas e resolução de host

Na Venddor uma loja (internamente chamada de tenant) é um negócio completo: catálogo, clientes, pedidos, administradores, sellers, tema e configurações. Cada loja tem o seu próprio banco de dados. Nada de uma loja é visível em outra: um id de produto da loja A simplesmente não existe na loja B, e um usuário da loja A não existe na loja B, mesmo que o e-mail seja o mesmo.

Por isso, toda chamada precisa dizer de qual loja ela é. É a primeira coisa que a plataforma resolve, antes de olhar o token.

Como a loja é resolvida

A plataforma segue esta ordem e usa a primeira que der resultado.

1. Cabeçalho X-Tenant-ID

   Se a requisição trouxer X-Tenant-ID, o valor (o identificador curto da loja, como store1) é usado. É útil em testes e ao chamar um endereço que não é o da loja.

2. Subdomínio

   O host da requisição é comparado ao domínio base da plataforma. minhaloja.io.venddor.com.br resolve para a loja minhaloja. Quando a chamada passa por um proxy ou CDN que reescreve o host, o cabeçalho X-Forwarded-Host é lido no lugar.

3. Domínio personalizado

   Se o host não termina no domínio base (por exemplo loja.exemplo.com.br), a plataforma procura esse domínio entre os que as lojas cadastraram. Se achar, a loja dona do domínio é a resolvida.

Se nada resolver, a resposta é 404 com tenant not found e a requisição nem chega à rota.

Isolamento e tokens

Depois de resolver a loja, a autenticação confere que o tenant_id dentro do token é o da loja resolvida. Se não for, a chamada é recusada com 403 token not valid for this storefront. Na prática: faça login em cada loja separadamente e guarde um token por loja. Os detalhes do token estão em Tokens e escopos.

Os ids também são isolados. Ao integrar várias lojas, guarde sempre o par (loja, id) no seu sistema.

Estados da loja

Uma loja pode estar fora do ar por motivos diferentes. Cada um tem uma resposta própria, e saber qual é evita horas de diagnóstico.

Todos esses corpos têm o formato {"error": "...", "message": "..."}. Veja o quadro completo em Erros.

Exemplo

# Pelo host da loja (recomendado)
curl "https://minhaloja.io.venddor.com.br/api/v1/storefront/categories"

# Por um endereço compartilhado, nomeando a loja
curl "https://io.venddor.com.br/api/v1/auth/login" \
  -H "X-Tenant-ID: minhaloja" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@minhaloja.com.br","password":"SENHA"}'

{
  "error": "tenant not found",
  "message": "could not resolve storefront from request"
}

Erros comuns

• Testar contra localhost ou um IP sem X-Tenant-ID. Sem host de loja e sem cabeçalho, o resultado é 404 tenant not found.
• Enviar X-Tenant-ID com a loja errada e um token de outra. O cabeçalho tem prioridade sobre o host; o token então não bate e a resposta é 403.
• Cachear o token entre lojas. Um token por loja.
• Confundir storefront_disabled com loja inexistente. A loja existe e o painel funciona; só a vitrine pública está fora.

Veja também