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)
```http
POST /auth/signup
Content-Type: application/json

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

**Response (201 Created):**
```json
{
  "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
```http
POST /auth/login
Content-Type: application/json

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

**Response (200 OK):**
```json
{
  "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
```http
POST /auth/logout
Authorization: Bearer {token}
```

**Response (200 OK):**
```json
{
  "message": "Logout realizado com sucesso"
}
```

**Erros:**
- `401 Unauthorized` - Token inválido ou expirado

---

#### 1.4 Obter Perfil Atual
```http
GET /auth/me
Authorization: Bearer {token}
```

**Response (200 OK):**
```json
{
  "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
```http
POST /auth/forgot-password
Content-Type: application/json

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

**Response (200 OK):**
```json
{
  "message": "Email de recuperação enviado. Verifique sua caixa de entrada."
}
```

---

### 2. Tarefas (Tasks) - Em Desenvolvimento

#### 2.1 Listar Tarefas
```http
GET /tasks
Authorization: Bearer {token}

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

**Response (200 OK):**
```json
{
  "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
```http
GET /tasks/:id
Authorization: Bearer {token}
```

**Response (200 OK):**
```json
{
  "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
```http
POST /tasks
Authorization: Bearer {token}
Content-Type: application/json

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

**Response (201 Created):**
```json
{
  "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
```http
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):**
```json
{
  "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
```http
DELETE /tasks/:id
Authorization: Bearer {token}
```

**Response (200 OK):**
```json
{
  "message": "Tarefa deletada com sucesso"
}
```

**Erros:**
- `404 Not Found` - Tarefa não encontrada
- `401 Unauthorized` - Token inválido

---

## 🔄 Real-time (WebSocket)

### Conectar ao Realtime
```javascript
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
```bash
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
```bash
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)
```bash
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