GitHub - JohnVitor-Dev/DuskWallet-API

📖 Descrição

DuskWallet API é uma API REST completa para gerenciamento de finanças pessoais, permitindo que usuários controlem suas receitas e despesas de forma inteligente e segura. A API oferece funcionalidades de autenticação, CRUD de transações financeiras, dashboard com resumos automáticos e análise inteligente de gastos utilizando IA (Google Gemini).

Problema que resolve

Muitas pessoas têm dificuldade em controlar suas finanças pessoais e entender para onde o dinheiro está indo. A DuskWallet API oferece:

✅ Controle completo de receitas e despesas
✅ Categorização automática de transações
✅ Análises inteligentes com insights personalizados
✅ Dashboard com visão geral financeira
✅ Segurança robusta com autenticação JWT
✅ Validação e sanitização de dados

Endpoints Principais

Autenticação: Registro e login de usuários
Transações: CRUD completo de transações financeiras
Dashboard: Resumo automático de finanças
Análise: Insights inteligentes gerados por IA

🚀 Status do Projeto

🚧 API em desenvolvimento ativo 🚧

Versão atual: 1.0.0
Última atualização: Novembro 2025

⚡ Funcionalidades

🔐 Autenticação e Segurança

Registro de novos usuários com hash de senha (bcrypt)
Login com geração de token JWT
Middleware de autenticação para rotas protegidas
Rate limiting para prevenir ataques de força bruta
Sanitização de dados contra injeção NoSQL
Headers de segurança com Helmet.js

💳 Gerenciamento de Transações

Criar transações de receita ou despesa
Buscar transação específica por ID
Atualizar informações de transações
Excluir transações
Categorização (14 categorias disponíveis)
Suporte a múltiplos métodos de pagamento (Dinheiro, PIX, Crédito)

📊 Dashboard e Relatórios

🤖 Análise Inteligente com IA

Análise de padrões de gastos
Insights personalizados gerados por Google Gemini AI
Recomendações de economia
Alertas sobre categorias com gastos elevados

🛡️ Recursos de Segurança

Validação rigorosa de dados com Express Validator
Limite de taxa de requisições (Rate Limiting)
Variáveis de ambiente para dados sensíveis
Tokens JWT com expiração configurável

📚 Documentação de Endpoints

Autenticação

POST `/api/auth/register`

Registra um novo usuário no sistema.

Headers:

Content-Type: application/json

Body:

{
  "name": "João Silva",
  "email": "joao@example.com",
  "password": "senhaSegura123"
}

Resposta de Sucesso (201):

{
  "message": "Usuário registrado com sucesso",
  "user": "joao@example.com",
  "name": "João Silva"
}

Observação: O endpoint de registro não retorna um token JWT. Para obter o token, é necessário fazer login através do endpoint /api/auth/login.

Erros Possíveis:

400 - Dados inválidos ou email já cadastrado
500 - Erro interno do servidor

POST `/api/auth/login`

Autentica um usuário existente.

Headers:

Content-Type: application/json

Body:

{
  "email": "joao@example.com",
  "password": "senhaSegura123"
}

Resposta de Sucesso (200):

{
  "message": "Usuário logado com sucesso",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Erros Possíveis:

401 - Credenciais inválidas
429 - Muitas tentativas de login (Rate Limit)
500 - Erro interno do servidor

Transações

Nota: Todas as rotas de transações requerem autenticação via token JWT no header.

Header obrigatório:

Authorization: Bearer {seu_token_jwt}

POST `/api/transactions`

Cria uma nova transação financeira.

Body:

{
  "description": "Compra no supermercado",
  "amount": 150.75,
  "type": "EXPENSE",
  "category": "MERCADO",
  "paymentMethod": "CREDITO",
  "date": "2025-11-16T10:30:00Z"
}

Campos:

description (string, obrigatório): Descrição da transação
amount (number, obrigatório): Valor da transação
type (enum, obrigatório): INCOME ou EXPENSE
category (enum, obrigatório): Uma das 14 categorias disponíveis
paymentMethod (enum, obrigatório): DINHEIRO, PIX ou CREDITO
date (string ISO, opcional): Data da transação (padrão: agora)

Categorias disponíveis:

MORADIA, CONTAS, MERCADO, COMIDA_FORA, TRANSPORTE
SAUDE, EDUCACAO, LAZER, COMPRAS, DIVIDAS
INVESTIMENTOS, SALARIO, OUTRAS_RECEITAS, OUTROS

Resposta de Sucesso (201):

{
  "message": "Transação criada com sucesso",
  "transaction": {
    "id": "clxy9876543210fedcba",
    "description": "Compra no supermercado",
    "amount": 150.75,
    "type": "EXPENSE",
    "category": "MERCADO",
    "paymentMethod": "CREDITO",
    "date": "2025-11-16T10:30:00.000Z",
    "userId": "clxy1234567890abcdef"
  }
}

Erros Possíveis:

400 - Dados inválidos
401 - Token inválido ou ausente
500 - Erro interno do servidor

GET `/api/transactions`

Lista todas as transações do usuário autenticado, ordenadas por data (mais recentes primeiro).

Resposta de Sucesso (200):

{
  "transactions": [
    {
      "id": "clxy9876543210fedcba",
      "description": "Compra no supermercado",
      "amount": 150.75,
      "type": "EXPENSE",
      "category": "MERCADO",
      "paymentMethod": "CREDITO",
      "date": "2025-11-16T10:30:00.000Z",
      "userId": "clxy1234567890abcdef"
    },
    {
      "id": "clxy5555666777778888",
      "description": "Salário mensal",
      "amount": 5000.00,
      "type": "INCOME",
      "category": "SALARIO",
      "paymentMethod": "PIX",
      "date": "2025-11-05T09:00:00.000Z",
      "userId": "clxy1234567890abcdef"
    }
  ]
}

Erros Possíveis:

401 - Token inválido ou ausente
500 - Erro interno do servidor

GET `/api/transactions/:id`

Busca uma transação específica por ID.

Parâmetros:

id (string): ID da transação

Resposta de Sucesso (200):

{
  "transaction": {
    "id": "clxy9876543210fedcba",
    "description": "Compra no supermercado",
    "amount": 150.75,
    "type": "EXPENSE",
    "category": "MERCADO",
    "paymentMethod": "CREDITO",
    "date": "2025-11-16T10:30:00.000Z",
    "userId": "clxy1234567890abcdef"
  }
}

Erros Possíveis:

401 - Token inválido ou ausente
404 - Transação não encontrada
500 - Erro interno do servidor

PUT `/api/transactions/:id`

Atualiza uma transação existente.

Parâmetros:

id (string): ID da transação

Body (todos os campos opcionais):

{
  "description": "Compra no mercado - atualizado",
  "amount": 175.50,
  "category": "MERCADO",
  "paymentMethod": "PIX"
}

Resposta de Sucesso (200):

{
  "message": "Transação atualizada com sucesso"
}

Erros Possíveis:

400 - Dados inválidos ou nenhum campo para atualizar foi fornecido
401 - Token inválido ou ausente
404 - Transação não encontrada
500 - Erro interno do servidor

DELETE `/api/transactions/:id`

Exclui uma transação.

Parâmetros:

id (string): ID da transação

Resposta de Sucesso (200):

{
  "message": "Transação deletada com sucesso"
}

Erros Possíveis:

401 - Token inválido ou ausente
404 - Transação não encontrada
500 - Erro interno do servidor

Dashboard

GET `/api/dashboard`

Retorna um resumo completo das finanças do usuário autenticado.

Headers:

Authorization: Bearer {seu_token_jwt}

Resposta de Sucesso (200):

{
  "totalIncome": 5000.00,
  "totalExpense": 2345.50,
  "balance": 2654.50,
  "summaryData": [
    {
      "type": "INCOME",
      "_sum": {
        "amount": 5000.00
      }
    },
    {
      "type": "EXPENSE",
      "_sum": {
        "amount": 2345.50
      }
    }
  ]
}

Erros Possíveis:

401 - Token inválido ou ausente
500 - Erro interno do servidor

Análise Inteligente

GET `/api/analysis`

Gera uma análise inteligente dos padrões de gastos do usuário utilizando Google Gemini AI.

Headers:

Authorization: Bearer {seu_token_jwt}

Resposta de Sucesso (200):

{
  "analysis": {
    "resumo": "Você teve 15 transações nos últimos 60 dias, com total de gastos de R$ 2.345,50 e receitas de R$ 5.000,00, resultando em saldo positivo de R$ 2.654,50.",
    "ponto_positivo": "Seu saldo está positivo e você mantém controle regular das suas finanças.",
    "ponto_de_atencao": "Gastos com MERCADO representam 27% do total, considere revisar esse padrão.",
    "analise_de_padroes": [
      "Gastos concentrados em MERCADO (35% do total de despesas)",
      "Uso frequente de cartão de crédito em pequenas compras",
      "Padrão de gastos estável ao longo do período"
    ],
    "conselhos": [
      "Planeje compras de mercado semanalmente para evitar idas frequentes e gastos extras",
      "Considere usar PIX para compras menores para melhor controle do fluxo de caixa",
      "Aproveite o saldo positivo para começar uma reserva de emergência"
    ],
    "plano_de_emergencia": [
      "Esta semana: revise todos os gastos com cartão de crédito e cancele assinaturas não utilizadas",
      "Próximas 2 semanas: reduza em 20% os gastos com COMIDA_FORA fazendo mais refeições em casa",
      "Resto do mês: estabeleça um limite diário de R$ 50 para gastos variáveis"
    ]
  }
}

Observações:

A análise é baseada nas transações dos últimos 60 dias
Se não houver transações, retorna: { "message": "Nenhuma transação encontrada nos últimos 60 dias." }
O formato JSON é gerado por IA (Google Gemini 2.5 Flash) e pode variar ligeiramente

Erros Possíveis:

401 - Token inválido ou ausente
500 - Erro ao gerar análise ou erro interno do servidor

Screenshots

📸

🚀 Como Executar

Pré-requisitos

Antes de começar, certifique-se de ter instalado:

Node.js (versão 18 ou superior)
npm ou yarn
PostgreSQL (versão 14 ou superior)
Git
Conta no Google AI Studio (para obter GEMINI_API_KEY)

Scripts disponíveis

npm run dev                    # Inicia em modo desenvolvimento (nodemon)
npm run prisma:generate        # Gera o Prisma Client
npm run prisma:migrate         # Executa migrações do banco
npm run prisma:studio          # Abre interface visual do banco
npm run prisma:status          # Verifica status das migrações
npm run generate:transactions  # Gera transações de exemplo

🛠️ Tecnologias Utilizadas

Backend

Node.js - Runtime JavaScript
Express.js - Framework web minimalista
Prisma ORM - ORM moderno para Node.js e TypeScript

Banco de Dados

PostgreSQL - Banco de dados relacional

Autenticação e Segurança

JWT (jsonwebtoken) - Autenticação via tokens
bcryptjs - Hash de senhas
Helmet.js - Segurança de headers HTTP
express-rate-limit - Rate limiting
express-mongo-sanitize - Sanitização de dados

Validação

Express Validator - Validação de requisições

IA e Análise

Google Generative AI - API do Google Gemini para análises inteligentes

Utilitários

dotenv - Gerenciamento de variáveis de ambiente
nodemon - Auto-reload em desenvolvimento

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Desenvolvido com ☕ por John Vitor

Name		Name	Last commit message	Last commit date
api		api
prisma		prisma
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.vercelignore		.vercelignore
DUSKWALLET.svg		DUSKWALLET.svg
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
prisma.config.ts		prisma.config.ts
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation

📖 Descrição

Problema que resolve

Endpoints Principais

🚀 Status do Projeto

⚡ Funcionalidades

🔐 Autenticação e Segurança

💳 Gerenciamento de Transações

📊 Dashboard e Relatórios

🤖 Análise Inteligente com IA

🛡️ Recursos de Segurança

📚 Documentação de Endpoints

Autenticação

POST /api/auth/register

POST /api/auth/login

Transações

POST /api/transactions

GET /api/transactions

GET /api/transactions/:id

PUT /api/transactions/:id

DELETE /api/transactions/:id

Dashboard

GET /api/dashboard

Análise Inteligente

GET /api/analysis

Screenshots

🚀 Como Executar

Pré-requisitos

Scripts disponíveis

🛠️ Tecnologias Utilizadas

Backend

Banco de Dados

Autenticação e Segurança

Validação

IA e Análise

Utilitários

📝 Licença

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

POST `/api/auth/register`

POST `/api/auth/login`

POST `/api/transactions`

GET `/api/transactions`

GET `/api/transactions/:id`

PUT `/api/transactions/:id`

DELETE `/api/transactions/:id`

GET `/api/dashboard`

GET `/api/analysis`