API de apps (token vat_)
Como aplicativos de terceiros acessam relatórios, banners, páginas e estoque em massa pelas rotas /api/admin com token de app e escopos.
Um app de terceiros (um conector de ERP, uma ferramenta de BI, um gerenciador de conteúdo) não deve usar o login de uma pessoa. A plataforma oferece um acesso próprio para eles: o app é cadastrado no portal de desenvolvedores da loja, recebe um token de app (começa com vat_live_ ou vat_test_) e só pode o que os escopos aprovados pela loja permitem.
As rotas desse acesso ficam sob /api/admin/..., sem prefixo de versão. Esta seção documenta as que não são de pedidos: relatórios, banners, páginas e atualização de estoque em massa. As rotas de pedidos com token de app estão em Pedidos por token de app.
Como funciona
- Cadastre o app
No portal de desenvolvedores da loja o administrador cadastra o app e aprova os escopos. O app recebe o token de app. Veja Autenticação.
- Chame a rota com o escopo certo
Envie
Authorization: Bearer vat_live_.... O token vale só para a loja em que foi emitido. - Trate os dois formatos de erro
Falhas de token e de escopo vêm no formato simples
{"error":"..."}. Falhas das próprias operações também usam{"error":"mensagem"}, às vezes comdetail.
Conceitos-chave
Escopos desta seção
| Escopo | Libera |
|---|---|
read_analytics | Os quatro relatórios de Relatórios. |
read_content | Listar banners (Banners e páginas). |
write_content | Criar e alterar páginas (Banners e páginas). |
write_inventory | Atualizar estoque em massa (Estoque em massa). |
Erros de autenticação
| Status | Corpo | Quando |
|---|---|---|
| 401 | {"error":"app_token_required"} | Não veio token de app (por exemplo, veio um JWT de usuário). |
| 401 | {"error":"invalid or expired app access token"} | O token de app não existe, expirou ou foi revogado. |
| 403 | {"error":"missing_scope","required":"read_analytics"} | O app não tem o escopo que a rota exige. |
Dinheiro e datas
Valores em reais são sempre inteiros em centavos (27418842 = R$ 274.188,42). Os relatórios recebem datas YYYY-MM-DD e interpretam cada dia no fuso horário da loja.
Endpoints
| Método | Caminho | Para quê | Escopo | Página |
|---|---|---|---|---|
| GET | /api/admin/analytics/orders | Resumo de pedidos de um período | read_analytics | Relatórios |
| GET | /api/admin/analytics/sales | Relatório de vendas com série diária | read_analytics | Relatórios |
| GET | /api/admin/analytics/top-products | Produtos mais vendidos | read_analytics | Relatórios |
| GET | /api/admin/analytics/customers | Estatísticas de clientes | read_analytics | Relatórios |
| GET | /api/admin/banners | Listar banners da loja | read_content | Banners e páginas |
| POST | /api/admin/pages | Criar uma página | write_content | Banners e páginas |
| PUT | /api/admin/pages/{id} | Alterar uma página | write_content | Banners e páginas |
| POST | /api/admin/inventory/bulk-update | Definir o estoque de vários produtos | write_inventory | Estoque em massa |
Erros comuns
- Usar o JWT do administrador. Estas rotas só aceitam token de app: o resultado é
401 app_token_required. - Esquecer o escopo. O app foi aprovado só com
read_productseread_orders(o padrão) e chama um relatório:403 missing_scope. - Errar o nome do relatório. O resumo de pedidos é
/api/admin/analytics/orders, o de vendas é.../salese o de clientes é.../customers. Um nome diferente responde 404. - Esperar que
status: "draft"guarde um rascunho. Na criação de página por esta API,draftviraactivee a página fica publicada. - Tratar
failed_idscomo erro HTTP. A atualização de estoque em massa responde 200 mesmo quando alguns produtos falham. - Pedir mais de um ano de relatório. Intervalos maiores que 366 dias são recusados com 400.