API Reference

Referência da API

A API é implementada em api/app.py. As respostas de negócio são JSON, exceto downloads CSV/XLSX e arquivos estáticos. Os endpoints abaixo foram conferidos em docs/development.md.

Autenticação e sessões

Método	Rota	Descrição
GET	/api/auth/setup-status	Verifica se o primeiro administrador precisa ser criado
POST	/api/auth/setup	Provisiona o administrador usando token temporário
POST	/api/auth/login	Inicia sessão
GET	/api/auth/me	Retorna usuário atual e token CSRF
POST	/api/auth/logout	Revoga a sessão atual
GET	/api/auth/users	Lista usuários; acesso administrativo
POST	/api/auth/users	Cria usuário; acesso administrativo
POST	/api/auth/users/{id}/deactivate	Desativa usuário e revoga sessões; acesso administrativo

Saúde e catálogo

Método	Rota	Descrição
GET	/api/health	Estado básico do serviço
GET	/api/dashboard	Indicadores, categorias, clientes recentes e estoque crítico
GET	/api/categories	Categorias e contagem de produtos
GET	/api/clients	Consulta clientes
POST	/api/clients	Cadastra cliente; admin/operação
GET	/api/products	Lista produtos; aceita filtro category
POST	/api/products	Cadastra produto; admin/operação
POST	/api/products/{id}	Atualiza produto; admin/operação
POST	/api/products/{id}/deactivate	Desativa produto sem apagar seu cadastro
POST	/api/products/{id}/activate	Reativa produto desativado
POST	/api/products/{id}/delete	Remove produto e alertas associados; admin
GET	/api/dashboard/export.csv	Exporta dashboard em CSV
GET	/api/dashboard/export.xlsx	Exporta dashboard em XLSX

Exemplo de filtro: GET /api/products?category=Hardware. Use category=all para todas as categorias.

Financeiro, alertas e itens de trabalho

Método	Rota	Descrição
GET	/api/finance/summary	Totais realizados e saldo projetado
GET/POST	/api/finance/entries	Lista/cria receitas e despesas
GET	/api/alerts/stock	Consulta alertas ativos de estoque
GET	/api/alerts/config	Consulta limite padrão
POST	/api/alerts/stock/{id}/threshold	Atualiza mínimo do produto
POST	/api/alerts/stock/{id}/acknowledge	Reconhece um alerta
GET/POST	/api/work-items	Lista/registra bugs e riscos
POST	/api/work-items/{id}	Atualiza estado/responsável; admin/operação

Google Sheets

Método	Rota	Descrição
GET	/api/integrations/google-sheets/status	Informa se a integração está configurada, sem expor credenciais
POST	/api/integrations/google-sheets/export	Exporta indicadores e catálogo para a planilha configurada

Requisitos de autenticação

Todas as rotas, exceto /api/auth/setup-status, /api/auth/setup, /api/auth/login e arquivos estáticos, exigem sessão autenticada. Rotas de escrita exigem o cookie pm_session e o cabeçalho X-CSRF-Token, cujo valor é obtido em GET /api/auth/me. Os papéis são verificados no servidor.

Erros e validação

A documentação do projeto indica HTTP 400 para erros de validação e HTTP 409 para conflitos de unicidade. Os campos obrigatórios e restrições devem ser consultados em db/schema.sql e doc/data-model.md. Não presuma que endpoints de escrita aceitam chamadas sem sessão/CSRF.

Exportações

CSV e XLSX são gerados localmente. Google Sheets é uma integração opcional que usa um token OAuth de curta duração configurado no ambiente do servidor; o aplicativo não renova esse token automaticamente. O envio transfere os dados selecionados à conta/planilha configurada.

Exemplo de chamada autenticada

O fluxo geral de integração é:

1. Autenticar-se por POST /api/auth/login e conservar o cookie de sessão.
2. Consultar GET /api/auth/me para obter o token CSRF.
3. Enviar o cookie e X-CSRF-Token nas requisições de escrita.
4. Tratar respostas de erro e conflitos; não repetir escritas sem avaliar idempotência.

O contrato exato de campos JSON deve ser validado no código de api/app.py; esta página resume rotas, não substitui os validadores implementados.