Endereço e ambientes
Como montar a URL base da API, como a plataforma identifica a loja de cada requisição e quais famílias de rotas existem.
A Venddor é uma plataforma multi-loja. Cada loja (o termo técnico é tenant) tem o seu próprio catálogo, os seus próprios clientes e pedidos e o seu próprio banco de dados. Não existe uma "API global" que enxergue todas as lojas: cada chamada que você faz opera uma loja, e a primeira coisa que a plataforma faz ao receber a requisição é descobrir qual.
Loja e tenant
Pense em cada loja como uma instalação independente da plataforma. O que você cria numa loja (produto, cliente, pedido) não existe nas outras, e os ids (UUID) de uma loja não significam nada em outra. Se a sua empresa tem três lojas, você terá três URLs base e três credenciais.
Dentro de uma loja podem existir vários sellers (lojistas): empresas que vendem pelo mesmo site, num modelo de marketplace. A API administrativa enxerga todos eles; veja Sub-pedidos para o efeito disso nos pedidos.
Endereço base
Use o endereço público da loja, sempre com https:
| Tipo de endereço | Exemplo | Quando |
|---|---|---|
| Subdomínio da plataforma | https://minhaloja.io.venddor.com.br | Todas as lojas têm um. O trecho antes de .io.venddor.com.br é o identificador (slug) da loja. |
| Domínio próprio | https://www.minhaloja.com.br | Quando a loja configurou um domínio. A API responde no mesmo domínio da vitrine. |
Nos exemplos desta documentação, $BASE_URL é esse endereço, sem barra no final, e $TOKEN é o seu JWT.
export BASE_URL="https://minhaloja.io.venddor.com.br"Como a plataforma descobre a loja
A cada requisição, a plataforma resolve a loja nesta ordem:
- Cabeçalho
X-Tenant-ID, se vier na requisição. Ele tem prioridade sobre qualquer outra coisa. O valor é o identificador (slug) da loja, por exemplominhaloja. - O host da requisição (
Host, ouX-Forwarded-Hostquando há um proxy na frente): o subdomínio da plataforma ou um domínio próprio cadastrado.
Se nenhum dos dois identificar uma loja, a resposta é 404:
{ "error": "tenant not found", "message": "could not resolve storefront from request" }Se o identificador existe mas a loja não, ou foi desativada:
{ "error": "tenant not found", "message": "storefront does not exist or is disabled" }Token e loja
O JWT emitido no login contém a loja. Numa rota administrativa, um token de outra loja é recusado:
{ "error": "token not valid for this storefront" }Estados da loja
| Resposta | Corpo | Significado |
|---|---|---|
404 | tenant_not_found | A loja foi cancelada ou excluída. |
503 | tenant_suspended | A loja está suspensa. Aguarde ou fale com a Venddor. |
503 | tenant_maintenance | A loja está em modo de manutenção. Vale para as rotas públicas da vitrine; o painel e as APIs administrativas continuam no ar. |
404 | storefront_disabled | A vitrine pública foi despublicada. As APIs administrativas continuam funcionando. |
Famílias de rotas
A mesma loja responde por várias famílias de rotas. Este guia rápido usa a primeira.
| Prefixo | Quem usa | Credencial |
|---|---|---|
/api/v1/admin/... | Integrações (ERP, PDV, BI) e o painel de administração. | Bearer JWT de um usuário administrador. |
/api/v1/vendor/... | O painel do seller. | Bearer JWT de um usuário seller. |
/api/v1/storefront/... | A vitrine: carrinho, checkout, conta do comprador. | Público ou Bearer JWT do comprador. |
/api/v1/auth/... | Login, renovação e conta, para todos os perfis. | Pública (login) ou Bearer JWT. |
Ambientes
Todas as páginas desta documentação usam o ambiente de produção. Se você precisa de um ambiente de homologação para testar a integração antes de ligá-la na loja real, peça à Venddor: ele tem o mesmo contrato, o mesmo código e um endereço próprio. Nunca teste escrita (criar cliente, criar pedido) numa loja de produção com dados de verdade.
Duas lições práticas:
- Ids não são portáveis entre ambientes. O UUID de um produto em homologação não existe em produção, mesmo que a loja seja uma cópia.
- Credenciais também não. A senha de homologação não funciona em produção, e vice-versa.
Cabeçalhos de resposta úteis
Toda resposta traz X-Request-Id, um identificador único da requisição. Guarde-o nos seus logs e informe-o ao suporte quando abrir um chamado: é o que permite localizar a chamada do outro lado.