Referência da API REST

Explorar no Swagger UI spec.json

Documentação técnica da API RESTful do Caderno Milionário. Esta API fornece endpoints estruturados para gestão financeira pessoal (metas e dívidas) e comercial (produtos, stock, clientes e transações).

Visão Geral

Todos os endpoints seguem as convenções REST e retornam respostas no formato application/json com codificação UTF-8.

Base URL https://cadernomilionario.online/api/v1

Autenticação

A API utiliza Laravel Sanctum para autenticação baseada em tokens. Após efetuar o login ou registo, inclua o token no cabeçalho Authorization como Bearer Token em todas as requisições autenticadas:

Exemplo de cabeçalho HTTP 
Authorization: Bearer 1|a8f9c2d4e7...

Cabeçalhos Obrigatórios

Cabeçalho Valor Esperado Descrição
Accept application/json Garante que erros de validação e respostas sejam entregues em JSON.
Content-Type application/json Necessário para requisições com corpo (POST, PUT, PATCH).
X-Context personal ou business Alterna o escopo de dados entre visão pessoal e empresarial.

1. Autenticação

Método Endpoint Descrição Autenticação
POST /auth/register Registo de novo utilizador (nome, email, telefone, senha) Pública
POST /auth/login Autenticação e geração de token Sanctum Pública
GET /auth/me Obter dados do perfil do utilizador autenticado Bearer Token
POST /auth/logout Revogação do token atual Bearer Token

2. Gestão Comercial & Stock

Método Endpoint Descrição Subscrição
GET /negocio/resumo Painel e métricas de desempenho comercial Requerida
GET /produtos Listagem de produtos e níveis de stock Requerida
POST /produtos Cadastro de produto com preço e stock inicial Requerida
GET /clientes Listagem de clientes registados Requerida
POST /transacoes Registo de venda com baixa automática de stock Requerida

3. Finanças Pessoais

Método Endpoint Descrição Subscrição
GET /pessoal/resumo Resumo de receitas, despesas e saldo pessoal Requerida
GET /pessoal/dividas Termómetro de dívidas e planos de liquidação Requerida
GET /pessoal/metas Gestor de Sonhos (metas de poupança progressivas) Requerida

4. Planos & Pagamentos

Método Endpoint Descrição Acesso
GET /planos Catálogo de planos disponíveis (preço, funcionalidades) Pública
POST /pagamentos/processar Iniciar subscrição digital ou registar pagamento Bearer Token
POST /pagamentos/manual/comprovativo Envio de comprovativo de transferência bancária Bearer Token

Formato de Resposta Padrão

Todas as respostas de sucesso utilizam a estrutura consistente:

Exemplo de Sucesso (200 OK) JSON 
{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": { ... }
}

Em caso de erro ou validação inválida (422 / 401 / 403 / 500):

Exemplo de Erro (422 Unprocessable Entity) JSON 
{
  "sucesso": false,
  "mensagem": "Os dados fornecidos são inválidos.",
  "erros": {
    "email": ["O campo email já se encontra registado."]
  }
}
Consola Interativa: Para executar requisições diretamente pelo navegador, testar parâmetros de consulta e inspecionar schemas OpenAPI completos, aceda ao Swagger UI.