todolist-fullstack/backend-api/API.md

🔐 TASK MANAGER - API Backend Documentation

📌 Base URL

http://localhost:3000/api

🔑 Autenticação

Todas as requisições protegidas devem incluir o header:

Authorization: Bearer {token}

---

📋 Endpoints da API

1. Autenticação (Auth)

1.1 Registrar (Signup)

POST /auth/signup
Content-Type: application/json

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

Response (201 Created):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "email_confirmed_at": "2025-12-01T10:00:00Z"
  }
}

Erros:

• 400 Bad Request - Dados inválidos
• 409 Conflict - Email já registrado

---

1.2 Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "email_confirmed_at": "2025-12-01T10:00:00Z"
  }
}

Erros:

• 401 Unauthorized - Email ou senha incorretos
• 400 Bad Request - Dados inválidos

---

1.3 Logout

POST /auth/logout
Authorization: Bearer {token}

Response (200 OK):

{
  "message": "Logout realizado com sucesso"
}

Erros:

• 401 Unauthorized - Token inválido ou expirado

---

1.4 Obter Perfil Atual

GET /auth/me
Authorization: Bearer {token}

Response (200 OK):

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "iat": 1701427200,
  "exp": 1702032000
}

Erros:

• 401 Unauthorized - Token inválido ou expirado

---

1.5 Recuperar Senha

POST /auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

Response (200 OK):

{
  "message": "Email de recuperação enviado. Verifique sua caixa de entrada."
}

---

2. Tarefas (Tasks) - Em Desenvolvimento

2.1 Listar Tarefas

GET /tasks
Authorization: Bearer {token}

# Query params opcionais:
?status=all|completed|pending
?sort=created_at|updated_at
?order=asc|desc

Response (200 OK):

{
  "data": [
    {
      "id": "6b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Fazer compras",
      "description": "Ir ao supermercado",
      "completed": false,
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2025-12-01T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

---

2.2 Obter Tarefa Específica

GET /tasks/:id
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "6b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Fazer compras",
  "description": "Ir ao supermercado",
  "completed": false,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:00:00Z"
}

Erros:

• 404 Not Found - Tarefa não encontrada
• 401 Unauthorized - Token inválido

---

2.3 Criar Tarefa

POST /tasks
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Fazer compras",
  "description": "Ir ao supermercado"
}

Response (201 Created):

{
  "id": "6b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Fazer compras",
  "description": "Ir ao supermercado",
  "completed": false,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:00:00Z"
}

Erros:

• 400 Bad Request - Título obrigatório
• 401 Unauthorized - Token inválido

---

2.4 Atualizar Tarefa

PATCH /tasks/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Fazer compras (atualizado)",
  "description": "Ir ao supermercado e padaria",
  "completed": true
}

Response (200 OK):

{
  "id": "6b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Fazer compras (atualizado)",
  "description": "Ir ao supermercado e padaria",
  "completed": true,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:30:00Z"
}

Erros:

• 404 Not Found - Tarefa não encontrada
• 400 Bad Request - Dados inválidos
• 401 Unauthorized - Token inválido

---

2.5 Deletar Tarefa

DELETE /tasks/:id
Authorization: Bearer {token}

Response (200 OK):

{
  "message": "Tarefa deletada com sucesso"
}

Erros:

• 404 Not Found - Tarefa não encontrada
• 401 Unauthorized - Token inválido

---

🔄 Real-time (WebSocket)

Conectar ao Realtime

const subscription = supabase
  .channel('tasks')
  .on('postgres_changes', 
    { event: '*', schema: 'public', table: 'tasks' },
    (payload) => console.log(payload)
  )
  .subscribe();

Eventos

• INSERT - Nova tarefa criada
• UPDATE - Tarefa atualizada
• DELETE - Tarefa deletada

---

⚠️ Códigos de Erro

Código	Significado
200	OK - Requisição bem-sucedida
201	Created - Recurso criado
400	Bad Request - Dados inválidos
401	Unauthorized - Token inválido/expirado
404	Not Found - Recurso não encontrado
409	Conflict - Recurso já existe
500	Internal Server Error - Erro do servidor

---

🛠️ Exemplo Completo (cURL)

1. Registrar

curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "João"
  }'

2. Login

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

3. Criar Tarefa (com token)

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "title": "Fazer compras",
    "description": "Ir ao supermercado"
  }'

---

📚 Referências

• Supabase Docs: https://supabase.com/docs
• NestJS Docs: https://docs.nestjs.com
• JWT: https://jwt.io

---

API Status: ✅ Pronta para Desenvolvimento
Última Atualização: 1 de dezembro de 2025