Atores e APIs

A Venddor tem três atores, e cada um fala com uma parte diferente da API. Escolher o prefixo certo é a decisão mais importante de uma integração: ele define quem pode chamar, o que enxerga e qual token serve.

As três superfícies

Existe também a área de operação da própria plataforma (/api/v1/root/... e /api/v1/platform/...), usada pela equipe Venddor. Ela não faz parte desta referência.

Administrador

O administrador faz login com e-mail e senha em POST /api/v1/auth/login e recebe um token com user_type: "admin". Nas rotas /api/v1/admin/..., além de ser administrador, a pessoa precisa dos privilégios da rota.

Os privilégios são códigos como view_orders e manage_orders, concedidos pelo grupo de usuários (usergroup) ao qual o administrador pertence. Convenção: view_* lê, manage_* altera. Uma rota pode aceitar mais de um privilégio ("qualquer um destes"). Quando falta o privilégio, a resposta é 403 e o corpo lista o que teria bastado:

{
  "error": "insufficient privileges",
  "privilege_required_any": ["view_orders", "manage_orders"]
}

Para ver o que o usuário logado pode fazer, consulte Conta do administrador.

Seller

Em uma loja que opera como marketplace, cada seller (lojista) tem a sua conta. O login é o mesmo (/api/v1/auth/login), mas o token traz user_type: "vendor". As rotas /api/v1/vendor/... sempre filtram pelos dados do seller dono do token: ele nunca vê produtos ou pedidos de outro seller. O seller também pode ter uma equipe com grupos de usuários próprios (Conta do seller).

Um token de administrador não abre as rotas de seller que dependem de ser um seller (a resposta é 403 insufficient permissions). Para agir em nome de um seller pela API de administração, use os filtros vendor_id das rotas /api/v1/admin/....

Cliente e visitante

O comprador pode se cadastrar (POST /api/v1/auth/register) e entrar com a conta, ou comprar como visitante, sem conta. O catálogo público (/api/v1/storefront/products, /categories...) não exige token algum. O carrinho e o checkout usam um identificador de sessão e, quando há login, o token do cliente. Veja Sessão do cliente e Autenticação.

Uma loja pode exigir aprovação de contas novas (por exemplo, cadastros de empresas B2B). Enquanto a conta não é aprovada, o cliente só alcança as rotas de preenchimento de perfil e envio de documentos; as demais respondem 403 account_pending_approval.

Tokens de aplicativo

Um sistema de terceiros pode acessar parte das rotas de administração sem usuário, com um token de app (vat_...) e escopos como read_orders. Os detalhes estão em Tokens e escopos.

Erros comuns

• Usar o token do administrador na vitrine esperando agir como cliente. O token de administrador não é um token de cliente; faça login com a conta do cliente.
• Esquecer o privilégio. Um administrador autenticado ainda recebe 403 insufficient privileges se o grupo dele não tem o privilégio da rota.
• Procurar produtos de todos os sellers na API de seller. Ela só devolve os do dono do token.

Veja também