Endereço e ambientes
Como montar a URL base da API legada, 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 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 enxerga todos eles; veja 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, $EMAIL é o e-mail do usuário de integração e $API_KEY é a chave de API dele.
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 token emitido por auth_tokens contém a loja. Usado em outra loja, é recusado:
{ "status": 403, "message": "Token not valid for this storefront" }A chave de API, por sua vez, pertence a um usuário, e o usuário pertence a uma loja: o par e-mail:chave só autentica na loja onde o usuário existe.
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 rotas administrativas continuam no ar. |
404 | storefront_disabled | A vitrine pública foi despublicada. As rotas administrativas continuam funcionando. |
Famílias de rotas
A mesma loja responde por várias famílias de rotas. Este guia rápido usa as duas primeiras.
| Prefixo | Quem usa | Credencial |
|---|---|---|
/api/v1.0/... | Sistemas escritos para a Venddor 1.0: ERP, PDV, BI, middleware. | Basic e-mail:chave_de_api, ou Bearer. |
/api/... (sem v1.0) | As mesmas rotas, sem o prefixo de versão, usadas por apps e conectores antigos. Os ids saem em formato decimal. | Igual à anterior. |
/api/admin/... | Apps de terceiros com acesso restrito. | Bearer com token de app (vat_...). |
/api/4.0/... | O aplicativo móvel da loja. | Veja API 4.0. |
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 id 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 chave de API 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.