Conceitos da API
O que todo integrador precisa saber antes da primeira chamada à API da Venddor e como esta seção se divide em páginas.
A Venddor é uma plataforma de e-commerce multi-loja: um mesmo servidor atende centenas de lojas, cada uma com os seus dados isolados. Quem integra com a plataforma (um ERP, um app, um site próprio, um BI) conversa com uma loja de cada vez, usando o endereço dela, e age como um de três atores: o administrador da loja, um seller (lojista do marketplace) ou um cliente comprador.
Esta seção reúne as regras que valem para todas as rotas da referência. Leia as páginas na ordem abaixo uma vez; depois, cada rota só precisa explicar o que é específico dela.
Como começar
A primeira chamada de uma integração tem sempre os mesmos três passos.
- Descobrir o endereço da loja
Cada loja tem um endereço próprio, como
https://minhaloja.io.venddor.com.br, ou um domínio personalizado (https://loja.exemplo.com.br). Nos exemplos desta referência esse endereço aparece como$BASE_URL. Se você só conhece o e-mail do usuário ou o nome da loja, veja Localizar a loja. - Obter um token
Para um administrador ou seller, faça login em
POST /api/v1/auth/logine guarde oaccess_tokene orefresh_token. O token de acesso dura pouco; renove-o com o refresh em vez de logar de novo (Tokens e escopos). Para um app de terceiros sem usuário, use um token de app. - Chamar a rota
Envie
Authorization: Bearer $TOKEN. O corpo e a resposta são JSON.
TOKEN=$(curl -s "$BASE_URL/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"admin@minhaloja.com.br","password":"SENHA"}' | jq -r .access_token)
curl "$BASE_URL/api/v1/admin/products?per_page=5" \
-H "Authorization: Bearer $TOKEN"Mapa desta seção
| Página | O que responde |
|---|---|
| Lojas e resolução de host | Como a plataforma descobre de qual loja é a chamada e o que acontece quando a loja está suspensa ou em manutenção. |
| Atores e APIs | Administrador, seller e cliente: qual prefixo de rota cada um usa e como escolher entre as três superfícies. |
| Tokens e escopos | Tipos de token, o que há dentro do JWT, expiração, revogação e escopos. |
| Erros | Os formatos de erro, os códigos de status e os textos reais. |
| Paginação, filtros e ordenação | page, per_page, sort_by, filtros e o formato das listas. |
| Ids, dinheiro e datas | UUID, centavos, RFC 3339 em UTC e fuso. |
| Idempotência | Como repetir uma chamada de criação sem duplicar o pedido. |
| Limites de requisições | Os limites reais por rota e como reagir a um 429. |
| CORS e versões | Chamadas feitas do navegador e como a versão aparece na URL. |
| Rastreamento de requisições | O cabeçalho X-Request-Id e como abrir um chamado de suporte com ele. |
As páginas de rotas desta mesma parte da barra lateral ficam em seções próprias: Autenticação, Autenticação avançada, Sessão do cliente, Conta do administrador, Conta do seller e Plataforma e integrações.
Erros comuns
- Chamar o endereço errado. Uma chamada sem loja identificável responde 404
tenant not found. Use o endereço da loja, não um endereço genérico da Venddor. - Reaproveitar um token em outra loja. O token só vale na loja que o emitiu (403
token not valid for this storefront). - Usar token de administrador em rota de seller ou de cliente. Cada prefixo exige o seu tipo de usuário (403
insufficient permissions). - Logar a cada chamada. O login aceita só 5 tentativas por minuto por IP. Guarde o token e renove com o refresh.
- Tratar o corpo de erro como sempre igual. Há três formatos; veja Erros.
- Tratar o valor monetário como reais.
4990são centavos.