API de micro hábitos

TLDR: Contrato dos endpoints de hábitos e execuções — criação e edição de hábitos com frequência diária/semanal/mensal, atualização de status de execução, histórico e métricas de consistência.

Nota de reconstrução: o documento original cobria 6 endpoints com paths /api/v1/... e alguns campos divergentes do model (selected_days vs weekly_days). Os paths e a lista de endpoints foram conferidos contra apps/habits/urls.py e routes/api.py, e os enums contra apps/habits/models/. Os exemplos de payload vêm do documento original. certainty: medium porque os corpos de resposta não foram reverificados campo a campo contra os serializers.

Visão geral

As rotas de hábitos são montadas sob v1/habits (ver routes/api.py). O documento original as escrevia como /api/v1/habits/....

Os endpoints de default estão documentados em default_habits.md; o de consistência por intervalo, em specs/20260508155907_consistency_range_endpoint.md.

Contratos

Tipos e enums

```python HabitFrequency = Literal[“daily”, “weekly”, “monthly”] HabitStatus = Literal[“active”, “finished”] ExecutionStatus = Literal[“pending”, “completed”, “not-completed”]

HabitCategory = Literal[ “health”, # Saúde “fitness”, # Fitness “studies”, # Estudos “work”, # Trabalho “finances”, # Finanças “relationships”, # Relacionamentos “leisure”, # Lazer “other”, # Outros ] ```

GET /v1/habits/executions/{date}

Lista todas as execuções de hábitos do usuário logado para uma data específica (YYYY-MM-DD).

json { "date": "2026-02-27", "data": [ { "id": "exec-uuid-1", "habit_id": "habit-uuid-1", "habit_name": "Dipirona, 1g", "habit_category": "health", "scheduled_time": "08:00", "status": "pending", "scheduled_date": "2026-02-27" }, { "id": "exec-uuid-4", "habit_id": "habit-uuid-2", "habit_name": "Vitamina D", "habit_category": "health", "scheduled_time": "09:00", "status": "not-completed", "scheduled_date": "2026-02-27", "executed_at": "2026-02-27T09:30:00Z" } ] }

Cada item também carrega streak e consistency do respectivo hábito, e o response é envolvido com os totais diários total (hábitos distintos com execuções na data) e completed (hábitos com todas as execuções do dia concluídas).

GET /v1/habits

Lista todos os hábitos cadastrados do usuário logado.

json { "data": [ { "id": "habit-uuid-1", "name": "Dipirona, 1g", "category": "health", "frequency": "daily", "status": "active", "start_date": "2026-01-01", "end_date": "2026-01-01", "hours": ["08:00", "14:00", "20:00"], "weekly_days": null, "monthly_day": null, "created_at": "2026-01-01T10:00:00Z", "updated_at": "2026-01-01T10:00:00Z" }, { "id": "habit-uuid-2", "name": "Academia", "category": "fitness", "frequency": "weekly", "status": "active", "hours": ["06:00"], "weekly_days": ["mon", "wed", "fri"], "monthly_day": null }, { "id": "habit-uuid-4", "name": "Antibiótico", "category": "health", "frequency": "daily", "status": "finished", "start_date": "2025-12-01", "end_date": "2025-12-14", "hours": ["08:00", "20:00"], "finished_at": "2025-12-14T20:00:00Z" } ] }

PUT /v1/habits/executions/{execution_id}

Atualiza o status de uma execução (marcar como concluída ou não concluída).

json { "status": "completed" }

Resposta 200 OK com a execução atualizada, incluindo executed_at.

POST /v1/habits

Cria um novo hábito para o usuário logado.

Exemplos por frequência:

json { "name": "Tomar remédio", "category": "health", "frequency": "daily", "hours": ["08:00", "20:00"] }

json { "name": "Academia", "category": "fitness", "frequency": "weekly", "hours": ["06:00"], "weekly_days": ["mon", "wed", "fri"] }

json { "name": "Revisão financeira", "category": "finances", "frequency": "monthly", "hours": ["10:00"], "monthly_day": 1 }

Resposta 201 Created com o hábito criado, incluindo frequency_label. As HabitExecution são geradas automaticamente na criação.

PUT /v1/habits/{habit_id}

Atualiza um hábito existente. Todos os campos são opcionais; status aceita "active" ou "finished" (para arquivar). Alterar frequency, hours, weekly_days, monthly_day ou end_date regera as execuções futuras.

GET /v1/habits/{habit_id}/executions

Histórico de execuções de um hábito específico.

json { "habit_id": "habit-uuid-1", "habit_name": "Dipirona, 1g", "total": 30, "page": 1, "per_page": 20, "streak": 5, "consistency": "developing", "executions": [ { "id": "exec-uuid-1", "scheduled_date": "2025-12-12", "scheduled_time": "12:30", "status": "completed", "executed_at": "2025-12-12T12:35:00Z", "day_of_week": "Quarta-feira" } ] }

consistency é o nível semântico do hábito: starting (0–20%), developing (21–50%), consistent (51–80%), consolidated (81–100%). streak é a contagem de dias consecutivos completados.

Códigos de erro

Formato do erro:

json { "error": { "message": ["O campo 'hours' é obrigatório"] } }

Mapeamentos

Dias da semana

Categorias

Frequências

Referências

• plans/20260302175328_habits_api.md — plano de implementação original
• specs/20260507160624_habit_streak_consistency.md — streak e consistency
• specs/20260603092340_habit_description_in_dashboard.md — description no dashboard