Módulo de Shop (E-commerce)

O módulo de Shop é uma solução completa de e-commerce headless. Ele permite gerenciar produtos, variantes, categorias, clientes, orçamentos, fretes e imagens de forma independente dentro de um Workspace.

Este módulo foi projetado para ser flexível e escalável, permitindo que cada Workspace tenha sua própria loja com configurações, domínios, usuários e clientes totalmente isolados.

Por que utilizar este módulo?

Antes de mergulharmos nos detalhes técnicos, é importante entender que este módulo não é apenas um catálogo de produtos. Ele foi construído com foco em:

Isolamento Total: Cada loja opera como uma entidade única dentro de um Workspace, com usuários, clientes e dados isolados.
Dois Públicos, Duas APIs: O lojista administra a loja pelo painel, enquanto o comprador final navega e compra pela vitrine — cada um com sua própria autenticação.
Liberdade de Frontend: Sendo 100% headless, você consome o catálogo e o checkout e decide como e onde exibi-los.

Autenticação e Contexto

A API do Shop utiliza headers específicos para identificar a loja e o tipo de usuário da requisição.

Identificação da Loja

Todas as requisições para os endpoints do Shop (públicos ou privados) devem incluir o identificador da loja:

Header	Tipo	Obrigatório	Descrição
`X-Shop-Id`	`UUID`	Sim	O token de identificação da loja, obtido no painel administrativo do Workspace.

Como funciona o X-Shop-Id

O middleware valida o X-Shop-Id contra o tokenHeader da loja e verifica se o domínio (ou IP) de origem está na lista de domínios autorizados do Workspace. Requisições sem o header, com loja inexistente ou com origem não autorizada recebem 401 Unauthorized. Lojas em manutenção ou inativas recebem 503 Service Unavailable.

bash

curl -X GET "https://api.us.basis.tavares.in/v1/shop/public/detail" \
  -H "X-Shop-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Os Dois Contextos de Autenticação

O módulo possui dois contextos de autenticação independentes, com tokens e credenciais separados:

Contexto	Quem é	Prefixo das rotas	Finalidade
User	Lojista / administrador da loja	`/v1/shop/user`	Gerenciar produtos, categorias, clientes, orçamentos, fretes e configurações.
Customer	Comprador final da loja	`/v1/shop/customer`	Navegar pelo catálogo, gerenciar a própria conta e criar orçamentos/pedidos.

Para endpoints protegidos, forneça o token de autenticação do contexto correspondente:

Header	Valor	Descrição
`Authorization`	`Bearer <token>`	Token obtido no login do contexto (user ou customer).

Tokens não são intercambiáveis

Um token de user não acessa endpoints de customer e vice-versa. Cada contexto possui seu próprio endpoint de login e sua própria base de credenciais.

Resumo dos Headers

http

GET /v1/shop/user/products
X-Shop-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}
Accept: application/json

Próximos Passos

Agora que você entende a base do módulo, explore as funcionalidades detalhadas:

Módulo de Shop (E-commerce) ​

Por que utilizar este módulo? ​

Autenticação e Contexto ​

Identificação da Loja ​

Os Dois Contextos de Autenticação ​

Resumo dos Headers ​