🐍 API de Controle de Gastos Pessoais em Python: Aprenda Criando do Zero

🐍 Introdução

Imagine ter o controle total dos seus gastos na ponta dos dedos, mas sem precisar depender de planilhas confusas ou aplicativos complicados. É exatamente isso que você vai aprender neste artigo. Vamos construir uma API de controle de gastos pessoais do zero usando Python, de forma simples, prática e eficiente. Você não precisa ser um expert para começar, mas mesmo quem já tem anos de experiência vai encontrar boas práticas, organização de código e dicas que fazem toda a diferença em projetos reais.

Ao longo do artigo, você vai entender os conceitos fundamentais de APIs, criar endpoints que realmente funcionam, manipular dados e testar tudo de forma prática. Cada passo foi pensado para que você aprenda fazendo, construindo algo que seja útil, escalável e elegante. Prepare-se para transformar ideias em código e ver sua própria API ganhar vida.

No final, você terá não apenas uma API funcional, mas também a base para evoluir o projeto para bancos de dados, autenticação e até migração para frameworks mais avançados como FastAPI. Vamos mergulhar nesse universo e criar algo que seja útil, divertido e profissional.

🧠 Conceitos Básicos

Antes de colocar a mão no código, precisamos alinhar alguns conceitos essenciais. Não se preocupe, nada de teoria maçante. Aqui vamos direto ao ponto, mostrando o que realmente importa para criar uma API funcional e elegante.

O que é uma API?

Uma API (Application Programming Interface) é basicamente um canal de comunicação entre sistemas. Ela permite que aplicativos conversem entre si, troquem dados e executem funções de forma estruturada. No nosso caso, vamos criar uma API que organiza e gerencia gastos pessoais.

Pense assim: se você tem um aplicativo de controle financeiro no celular, ele precisa buscar, enviar e atualizar dados. Tudo isso é feito através de APIs.

Tipos de API mais comuns

REST: o mais usado no mundo web. Baseado em recursos e métodos HTTP (GET, POST, PUT, DELETE).

SOAP: mais antigo, complexo e pesado. Não é nosso foco aqui.

GraphQL: moderno, flexível, mas um pouco mais avançado. Ideal para projetos maiores.

Métodos HTTP

Cada endpoint da sua API tem uma função e um método HTTP que define essa função:

GET: recuperar informações. Exemplo: listar todas as despesas cadastradas.

POST: criar novos registros. Exemplo: adicionar uma nova despesa.

PUT: atualizar registros existentes. Exemplo: corrigir o valor ou categoria de uma despesa.

DELETE: remover registros. Exemplo: apagar uma despesa que não existe mais.

Formato de dados: JSON

O JSON (JavaScript Object Notation) é o formato padrão para troca de dados em APIs. Ele é leve, fácil de ler e escrever.

Exemplo de uma despesa em JSON:

{
"id": 1,
"descricao": "Almoço",
"valor": 45.50,
"categoria": "Alimentação"
}

id: identificador único da despesa

descricao: o que foi comprado

valor: quanto custou

categoria: classificação da despesa

Aprender esses conceitos vai facilitar muito quando começarmos a escrever nosso código. Eles são a base de qualquer API, seja ela simples ou complexa.

💻 Preparando o Ambiente

Antes de criar endpoints e manipular despesas, precisamos preparar nosso ambiente de desenvolvimento. Não se preocupe, vamos fazer de forma rápida, organizada e sem complicações.

1. Instalando Python

Se você ainda não tem Python instalado, baixe a versão mais recente no site oficial.

Para verificar se está tudo certo, abra o terminal e digite:

python --version

Você deve ver a versão instalada. Se sim, estamos prontos para seguir.

2. Criando o ambiente virtual

Um ambiente virtual mantém todas as dependências da sua API isoladas, evitando conflitos com outros projetos.

No terminal, rode:

python -m venv venv

Ative o ambiente virtual:

• Windows:

venv\Scripts\activate

• Mac/Linux:

source venv/bin/activate

3. Instalando as bibliotecas necessárias

Para nossa API de gastos pessoais, vamos usar Flask, uma biblioteca leve e fácil de aprender:

pip install Flask

4. Estrutura inicial do projeto

Organizar arquivos desde o início faz muita diferença. Aqui está um exemplo simples, mas funcional:

controle_gastos_api/
│
├── app.py          # arquivo principal da API
├── despesas.py     # lógica das despesas (CRUD)
├── requirements.txt # lista de dependências
└── venv/           # ambiente virtual

app.py vai conter a configuração da API e os endpoints.

despesas.py vai armazenar nossa lógica de gerenciamento de despesas.

requirements.txt é opcional, mas útil para instalar dependências rapidamente em outro computador.

5. Testando a instalação

Para garantir que tudo está funcionando, rode:

python app.py

Você deve ver algo como:

* Running on http://127.0.0.1:5000/

🧑‍💻 Criando o Primeiro Endpoint

Chegou a parte mais divertida: colocar o Python para trabalhar. Vamos começar simples, com um Hello World, para garantir que nossa API está respondendo corretamente.

1. Código inicial em app.py

from flask import Flask


app = Flask(__name__)


@app.route('/')
def hello():
  return {"mensagem": "Olá! Sua API de controle de gastos está funcionando!"}


if __name__ == '__main__':
  app.run(debug=True)

2. Explicando o código

from flask import Flask: importa a biblioteca Flask.

app = Flask(__name__): cria a aplicação Flask.

@app.route('/'): define o endpoint /, ou seja, a raiz da API.

def hello(): função que será executada quando acessarmos o endpoint.

return {"mensagem": "..."}: devolve um JSON com a mensagem.

app.run(debug=True): inicia o servidor local em modo de debug (ideal para desenvolvimento).

3. Testando

1.Salve o arquivo.

2.No terminal, dentro da pasta do projeto, rode:

python app.py

Abra o navegador ou use o Postman e acesse:

http://127.0.0.1:5000/

Você verá:

{"mensagem": "Olá! Sua API de controle de gastos está funcionando!"}

4. Próximo passo

Agora que temos a base funcionando, podemos avançar para criar os endpoints da nossa API de Controle de Gastos Pessoais. Vamos aprender a adicionar, listar, atualizar e remover despesas de forma prática e organizada.

💰 Estruturando a API de Controle de Gastos Pessoais

Nossa API vai permitir:

Adicionar despesas

Listar todas as despesas

Atualizar despesas existentes

Remover despesas

Tudo usando dados em memória (listas e dicionários), ideal para iniciantes, mas seguindo boas práticas que programadores experientes vão reconhecer.

1. Criando a estrutura de dados (despesas.py)

# despesas.py


despesas = []
id_contador = 1


def adicionar_despesa(descricao, valor, categoria):
  global id_contador
  despesa = {
      "id": id_contador,
      "descricao": descricao,
      "valor": valor,
      "categoria": categoria
  }
  despesas.append(despesa)
  id_contador += 1
  return despesa


def listar_despesas():
  return despesas


def atualizar_despesa(id, descricao=None, valor=None, categoria=None):
  for despesa in despesas:
      if despesa["id"] == id:
          if descricao:
              despesa["descricao"] = descricao
          if valor:
              despesa["valor"] = valor
          if categoria:
              despesa["categoria"] = categoria
          return despesa
  return None


def remover_despesa(id):
  global despesas
  for despesa in despesas:
      if despesa["id"] == id:
          despesas = [d for d in despesas if d["id"] != id]
          return True
  return False

2. Criando os endpoints em app.py

from flask import Flask, request, jsonify
from despesas import adicionar_despesa, listar_despesas, atualizar_despesa, remover_despesa


app = Flask(__name__)


@app.route('/despesas', methods=['GET'])
def get_despesas():
  return jsonify(listar_despesas())


@app.route('/despesas', methods=['POST'])
def post_despesa():
  dados = request.get_json()
  despesa = adicionar_despesa(dados["descricao"], dados["valor"], dados["categoria"])
  return jsonify(despesa), 201


@app.route('/despesas/<int:id>', methods=['PUT'])
def put_despesa(id):
  dados = request.get_json()
  despesa = atualizar_despesa(id, dados.get("descricao"), dados.get("valor"), dados.get("categoria"))
  if despesa:
      return jsonify(despesa)
  return jsonify({"erro": "Despesa não encontrada"}), 404


@app.route('/despesas/<int:id>', methods=['DELETE'])
def delete_despesa(id):
  if remover_despesa(id):
      return jsonify({"mensagem": "Despesa removida com sucesso"})
  return jsonify({"erro": "Despesa não encontrada"}), 404


if __name__ == '__main__':
  app.run(debug=True)

3. Explicando os endpoints

GET /despesas: retorna todas as despesas cadastradas.

POST /despesas: adiciona uma nova despesa.

Corpo da requisição (JSON):

{
"descricao": "Almoço",
"valor": 45.50,
"categoria": "Alimentação"
}

PUT /despesas/<id>: atualiza uma despesa existente.

DELETE /despesas/<id>: remove uma despesa pelo ID.

4. Testando a API

Use Postman ou curl para enviar requisições.

Experimente adicionar várias despesas, listar, atualizar e remover.

Observe as respostas em JSON e os códigos de status HTTP (200, 201, 404).

📝 Boas Práticas

Criar uma API que funciona é apenas o começo. Uma API bem estruturada e organizada faz toda a diferença quando o projeto cresce ou quando outros desenvolvedores precisam trabalhar com seu código. Aqui estão algumas práticas que vão deixar sua API de Controle de Gastos Pessoais mais profissional e escalável.

1. Modularização do Código

Separe a lógica da aplicação em arquivos diferentes.

Exemplo: app.py para endpoints e despesas.py para funções de CRUD.

Vantagem: facilita manutenção, testes e futuras expansões.

2. Validação de Dados

Sempre valide o que o usuário envia. Isso evita erros e mantém a API segura.

Exemplo: verificar se o valor é numérico e positivo antes de adicionar uma despesa.

if not isinstance(dados["valor"], (int, float)) or dados["valor"] <= 0:
  return jsonify({"erro": "Valor inválido"}), 400

3. Respostas e Códigos HTTP Consistentes

Use sempre códigos de status corretos:

200 OK para requisições bem-sucedidas.

201 Created ao criar um novo recurso.

404 Not Found quando um recurso não existir.

400 Bad Request para dados inválidos.

Isso ajuda quem consome a API a entender rapidamente o que aconteceu.

4. Mensagens de Erro Claras

Evite mensagens genéricas. Explique o problema.

Exemplo: "erro": "Despesa não encontrada" é muito melhor que "erro": "falha"

5. Comentários e Documentação

Comente funções complexas e endpoints.

Documente o que cada rota faz e quais parâmetros espera.

Futuramente, você pode adicionar Swagger/OpenAPI para gerar documentação automática.

6. Preparando para o Futuro

Quando quiser evoluir, você pode:

Substituir o armazenamento em memória por um banco de dados real (SQLite, PostgreSQL).

Adicionar autenticação de usuários com JWT.

Migrar para FastAPI para melhorar performance e documentação automática.

Seguindo essas práticas, sua API já estará no nível de um projeto profissional, mesmo sendo simples e didática.

💡 Conclusão

Chegamos ao final desta jornada e agora você tem em mãos uma API de Controle de Gastos Pessoais funcional, organizada e testável. Começamos do zero, entendendo conceitos essenciais de APIs, métodos HTTP, JSON e boas práticas de desenvolvimento. Criamos endpoints para adicionar, listar, atualizar e remover despesas, testamos tudo localmente e ainda aprendemos como preparar o projeto para evoluções futuras, como banco de dados, autenticação e deploy online.

O mais importante é que você não apenas leu sobre APIs, mas construiu uma API real e prática. Esse tipo de aprendizado é o que diferencia quem apenas consome conteúdo de quem realmente sabe programar e criar soluções.

Agora é com você: experimente adicionar novos recursos, conectar sua API a um banco de dados, proteger endpoints com autenticação, escrever testes automatizados e até publicar sua API online. Cada passo que você der vai transformar esse projeto de aprendizado em algo profissional e escalável.

Lembre-se, aprender programação é muito mais sobre fazer do que só ler. Então abra o editor, execute seu código e continue experimentando. Sua API de Controle de Gastos Pessoais é só o começo de projetos ainda mais incríveis que você pode criar com Python.

referências

Api no Python - https://www.hashtagtreinamentos.com/api-no-python

Como usar APIs no Python - https://www.datacamp.com/pt/tutorial/python-api

Como criar API de JSON com Python - https://www.freecodecamp.org/portuguese/news/como-criar-uma-api-de-json-com-python/