Plataforma e integrações

Esta seção reúne as rotas de plataforma que qualquer integração pode precisar antes (ou fora) do login: descobrir o endereço de uma loja, saber se a API está de pé e consultar a vitrine por GraphQL.

Nenhuma delas exige um usuário administrador. Todas respondem em JSON, exceto o playground do GraphQL, que é uma página HTML.

Como funciona

O caminho típico de uma integração que acabou de receber o endereço de uma loja:

1. Descobrir o endereço
   Se você só tem o nome curto (slug) da loja, use Descoberta da loja para obter o domínio.
2. Verificar a saúde
   Chame Saúde da API para saber se o serviço está respondendo.
3. Autenticar
   Faça o login pela seção de autenticação.
4. Consultar
   Para leitura de catálogo em vitrines e apps, use o GraphQL.

Conceitos-chave

Rotas sem tenant e rotas com tenant

tenant-lookup e public/tenants/{slug} funcionam em qualquer host da plataforma, porque servem justamente para descobrir qual é a loja. Já health e graphql valem para a loja do host (ou do cabeçalho X-Tenant-ID) em que você chamou.

Formato de erro

As rotas REST desta seção devolvem {"error": "...", "detail": "..."}. O GraphQL devolve o formato do próprio GraphQL: {"errors": [{"message": "..."}]}. Veja Erros.

Endpoints

Rotas que ficam de fora

GET /api/v1/integrations/orders, order-products, sales-summary e stores são de uso interno da Venddor: agregam todas as lojas da plataforma e só respondem com uma chave de acesso que a operação da plataforma configura no servidor. Elas não fazem parte da API de uma loja e por isso não são documentadas aqui. Para ler os pedidos da sua loja use a API administrativa.

Erros comuns

• Enviar PUT, PATCH ou DELETE ao /graphql: só GET e POST são aceitos (405).
• Esperar introspecção do GraphQL em produção: ela é bloqueada para quem não é administrador.
• Fazer addToCart sem token e sem X-Session-ID: o carrinho precisa de um dos dois.
• Chamar tenant-lookup mais de 20 vezes por minuto a partir do mesmo IP: volta 429.

Próximos passos