# 📚 API Reference - PlanFi BFF

Documentação completa de todos os endpoints disponíveis no PlanFi BFF.

## 🔐 Autenticação

Todos os endpoints protegidos requerem autenticação via JWT ou API Key.

### Headers Necessários

```http
# Para endpoints com JWT
Authorization: Bearer <jwt-token>

# Para endpoints com API Key
x-api-key: <api-key>

# Content-Type para requisições POST/PATCH
Content-Type: application/json
```

---

## 🔐 Auth Module

Endpoints relacionados à autenticação e autorização.

### Health Check

```http
GET /auth/health
```

**Descrição**: Verificação de saúde do sistema (sem autenticação necessária).

**Resposta**:
```json
{
  "status": "OK",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "message": "BFF PlanFi está funcionando!"
}
```

### Perfil do Usuário

```http
GET /auth/profile
Authorization: Bearer <jwt-token>
```

**Descrição**: Obtém informações do perfil do usuário autenticado.

**Resposta**:
```json
{
  "message": "Perfil acessado com sucesso",
  "user": {
    "id": "user-123",
    "type": "user",
    "expiresAt": "2024-01-01T15:00:00Z",
    "issuedAt": "2024-01-01T12:00:00Z"
  }
}
```

### Dashboard do Usuário

```http
GET /auth/user/dashboard
Authorization: Bearer <user-jwt-token>
```

**Descrição**: Dashboard específico para usuários (não clients).

**Resposta**:
```json
{
  "message": "Dashboard do usuário",
  "userId": "user-123",
  "userType": "user",
  "payload": { "sub": "user-123", "prv": "users" }
}
```

### Dashboard do Client

```http
GET /auth/client/dashboard
Authorization: Bearer <client-jwt-token>
```

**Descrição**: Dashboard específico para clients.

**Resposta**:
```json
{
  "message": "Dashboard do client",
  "clientId": "client-123",
  "userType": "client",
  "payload": { "sub": "client-123", "prv": "clients" }
}
```

### Debug do Token

```http
GET /auth/token/debug
Authorization: Bearer <jwt-token>
```

**Descrição**: Informações detalhadas sobre o token JWT.

**Resposta**:
```json
{
  "message": "Debug completo do token JWT",
  "authentication": {
    "id": "user-123",
    "type": "user",
    "expiresAt": "2024-01-01T15:00:00Z",
    "issuedAt": "2024-01-01T12:00:00Z"
  },
  "rawToken": {
    "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "length": 245,
    "parts": 3
  },
  "tokenData": {
    "issuer": "http://localhost:8000/api/login",
    "jwtId": "abc123",
    "provider": "users",
    "uuid": "user-uuid-123",
    "email": "user@example.com",
    "name": "João Silva"
  },
  "laravelCompatible": true
}
```

---

## 📊 Portfolios Module

Gestão de portfolios de investimento.

### Listar Portfolios

```http
GET /portfolios?userId=<user-id>
x-api-key: <api-key>
```

**Parâmetros de Query**:
- `userId` (opcional): Filtrar por ID do usuário

**Resposta**:
```json
[
  {
    "id": "portfolio_1",
    "name": "Portfolio Principal",
    "description": "Investimentos principais",
    "userId": "user_123",
    "totalValue": 50000.00,
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": "2024-01-01T10:00:00Z"
  }
]
```

### Buscar Portfolio

```http
GET /portfolios/:id
x-api-key: <api-key>
```

**Parâmetros**:
- `id`: ID do portfolio

**Resposta**:
```json
{
  "id": "portfolio_1",
  "name": "Portfolio Principal",
  "description": "Investimentos principais",
  "userId": "user_123",
  "totalValue": 50000.00,
  "assets": [
    {
      "id": "asset_1",
      "name": "Petrobras PN",
      "symbol": "PETR4",
      "quantity": 100,
      "price": 30.50
    }
  ]
}
```

### Valor do Portfolio

```http
GET /portfolios/:id/value
x-api-key: <api-key>
```

**Resposta**:
```json
{
  "portfolioId": "portfolio_1",
  "totalValue": 50000.00,
  "currency": "BRL",
  "lastUpdate": "2024-01-01T12:00:00Z"
}
```

### Criar Portfolio

```http
POST /portfolios
x-api-key: <api-key>
Content-Type: application/json

{
  "name": "Novo Portfolio",
  "description": "Descrição do portfolio",
  "userId": "user_123"
}
```

**Resposta**:
```json
{
  "id": "portfolio_new",
  "name": "Novo Portfolio",
  "description": "Descrição do portfolio",
  "userId": "user_123",
  "totalValue": 0,
  "createdAt": "2024-01-01T12:00:00Z"
}
```

### Atualizar Portfolio

```http
PATCH /portfolios/:id
x-api-key: <api-key>
Content-Type: application/json

{
  "name": "Portfolio Atualizado",
  "description": "Nova descrição"
}
```

### Remover Portfolio

```http
DELETE /portfolios/:id
x-api-key: <api-key>
```

**Resposta**:
```json
{
  "message": "Portfolio removido com sucesso",
  "id": "portfolio_1"
}
```

---

## 💎 Portfolio Assets Module

Gestão de ativos dos portfolios.

### Listar Assets

```http
GET /portfolio-assets?portfolioId=<portfolio-id>
x-api-key: <api-key>
```

**Parâmetros de Query**:
- `portfolioId` (opcional): Filtrar por ID do portfolio

**Resposta**:
```json
[
  {
    "id": "asset_1",
    "name": "Petrobras PN",
    "symbol": "PETR4",
    "type": "STOCK",
    "quantity": 100,
    "price": 30.50,
    "totalValue": 3050.00,
    "portfolioId": "portfolio_1"
  }
]
```

### Assets por Tipo

```http
GET /portfolio-assets/type/:type
x-api-key: <api-key>
```

**Parâmetros**:
- `type`: Tipo do asset (STOCK, BOND, FUND, CRYPTO, COMMODITY)

### Preço do Asset

```http
GET /portfolio-assets/price/:symbol
x-api-key: <api-key>
```

**Parâmetros**:
- `symbol`: Símbolo do asset (ex: PETR4)

**Resposta**:
```json
{
  "symbol": "PETR4",
  "price": 30.50,
  "currency": "BRL",
  "lastUpdate": "2024-01-01T12:00:00Z",
  "source": "B3"
}
```

### Dashboard do Asset

```http
GET /portfolio-assets/:id/dashboard
x-api-key: <api-key>
```

**Descrição**: Dashboard completo com todas as informações do asset.

**Resposta**:
```json
{
  "basicInfo": {
    "ticker": "PETR4",
    "name": "Petrobras PN",
    "imageUrl": "https://example.com/petr4.png",
    "quantity": 100,
    "averagePrice": 30.00,
    "lastQuote": 30.50,
    "investedValue": 3000.00,
    "grossValue": 3050.00,
    "result": 50.00,
    "resultPercentage": 1.67
  },
  "monthlyHistory": [
    {
      "month": "Jan.2024",
      "currentBalance": 3050.00,
      "quantity": 100,
      "returnPercentage": 1.67,
      "portfolioPercentage": 6.10,
      "ibovPercentage": 2.30
    }
  ],
  "historicalChart": [
    {
      "month": "Jan/24",
      "appliedValue": 3000.00,
      "grossBalance": 3050.00
    }
  ],
  "transactions": [
    {
      "id": "tx_1",
      "date": "2024-01-01",
      "type": "BUY",
      "description": "Compra",
      "quantity": 100,
      "pricePerUnit": 30.00,
      "totalValue": 3000.00
    }
  ]
}
```

### Criar Asset

```http
POST /portfolio-assets
x-api-key: <api-key>
Content-Type: application/json

{
  "name": "Vale S.A.",
  "symbol": "VALE3",
  "type": "STOCK",
  "quantity": 50,
  "price": 65.80,
  "portfolioId": "portfolio_1"
}
```

### Atualizar Asset

```http
PATCH /portfolio-assets/:id
x-api-key: <api-key>
Content-Type: application/json

{
  "quantity": 150,
  "price": 32.00
}
```

### Remover Asset

```http
DELETE /portfolio-assets/:id
x-api-key: <api-key>
```

---

## 🔌 Pluggy Module

Integração com a API do Pluggy.

### Requisição Genérica

```http
POST /pluggy
Content-Type: application/json

{
  "endpoint": "items",
  "method": "GET",
  "limit": 10,
  "offset": 0
}
```

**Parâmetros**:
- `endpoint`: Endpoint da API Pluggy
- `method`: Método HTTP (GET, POST, PUT, DELETE, PATCH)
- Outros parâmetros são enviados como query params (GET) ou body (outros métodos)

### Connect Token

```http
POST /pluggy/connect_token
Content-Type: application/json

{
  "itemId": "item_123"
}
```

**Parâmetros**:
- `itemId` (opcional): ID do item para gerar token

**Resposta**:
```json
{
  "accessToken": "pluggy_access_token_here",
  "expiresIn": 3600,
  "itemId": "item_123"
}
```

### Webhook

```http
POST /pluggy/webhook
Content-Type: application/json

{
  "event": "item.updated",
  "data": {
    "itemId": "item_123",
    "status": "UPDATED"
  }
}
```

---

## 🌐 Laravel API Module

Proxy para a API Laravel.

### Health Check

```http
GET /laravel-api/health
Authorization: Bearer <jwt-token>
```

**Resposta**:
```json
{
  "status": "OK",
  "laravel": {
    "connected": true,
    "responseTime": "45ms"
  },
  "token": {
    "valid": true,
    "expiresIn": "2h 30m"
  }
}
```

### Validar Token

```http
POST /laravel-api/validate-token
Authorization: Bearer <jwt-token>
```

**Resposta**:
```json
{
  "valid": true,
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "João Silva"
  }
}
```

### Perfil via Laravel

```http
GET /laravel-api/user/profile
Authorization: Bearer <jwt-token>
```

### Proxy Genérico

```http
POST /laravel-api/proxy/{endpoint}
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "method": "GET",
  "params": { "limit": 10 },
  "headers": { "Custom-Header": "value" }
}
```

**Exemplo - Listar Portfolios via Laravel**:
```http
POST /laravel-api/proxy/api/user/portfolios
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "method": "GET",
  "params": { "page": 1, "limit": 10 }
}
```

---

## 💰 OpenFinance Module

Gestão de transações excluídas do OpenFinance.

### Criar Transação Excluída

```http
POST /openfinance-excluded-transactions
Content-Type: application/json

{
  "client_id": "client_123",
  "transaction_id": "tx_456",
  "reason": "Transação duplicada",
  "excluded_at": "2024-01-01T12:00:00Z"
}
```

**Resposta**:
```json
{
  "id": "excl_789",
  "client_id": "client_123",
  "transaction_id": "tx_456",
  "reason": "Transação duplicada",
  "excluded_at": "2024-01-01T12:00:00Z",
  "created_at": "2024-01-01T12:00:00Z"
}
```

### Listar Transações Excluídas

```http
GET /openfinance-excluded-transactions?client_id=client_123
```

**Parâmetros de Query**:
- `client_id`: ID do client

**Resposta**:
```json
[
  {
    "id": "excl_789",
    "client_id": "client_123",
    "transaction_id": "tx_456",
    "reason": "Transação duplicada",
    "excluded_at": "2024-01-01T12:00:00Z"
  }
]
```

### Remover Exclusão

```http
DELETE /openfinance-excluded-transactions/:id
```

**Resposta**:
```json
{
  "message": "Exclusão removida com sucesso",
  "id": "excl_789"
}
```

---

## 🔧 Endpoints Utilitários

### Estatísticas do Sistema

```http
GET /stats
x-api-key: <api-key>
```

**Resposta**:
```json
{
  "totalPortfolios": 10,
  "totalAssets": 45,
  "totalValue": 150000.00,
  "activeUsers": 25,
  "lastUpdate": "2024-01-01T12:00:00Z"
}
```

### Reset do Sistema (Desenvolvimento)

```http
POST /reset
x-api-key: <api-key>
```

**Descrição**: Reseta o banco de dados mockado para o estado inicial (apenas em desenvolvimento).

### Configuração de Provider

```http
GET /provider-config
```

**Resposta**:
```json
{
  "userProviderHash": "23bd5c8949f600adb39e701c400872db7a5976f7",
  "clientProviderHash": "92c16d29654705716ae122db976a0fdd7d70873d",
  "autoCalculated": true,
  "models": {
    "user": "App\\Models\\User",
    "client": "App\\Models\\User\\Client"
  }
}
```

---

## 🚨 Códigos de Erro

### Códigos HTTP Comuns

| Código | Descrição | Cenários |
|--------|-----------|----------|
| **200** | OK | Operação realizada com sucesso |
| **201** | Created | Recurso criado com sucesso |
| **400** | Bad Request | Dados inválidos ou malformados |
| **401** | Unauthorized | Token inválido, expirado ou não fornecido |
| **403** | Forbidden | Token válido mas sem permissão |
| **404** | Not Found | Recurso não encontrado |
| **422** | Unprocessable Entity | Dados válidos mas não processáveis |
| **500** | Internal Server Error | Erro interno do servidor |
| **502** | Bad Gateway | Serviço externo indisponível |
| **504** | Gateway Timeout | Timeout em serviço externo |

### Formato de Erro Padrão

```json
{
  "statusCode": 400,
  "message": "Descrição do erro",
  "error": "Bad Request",
  "timestamp": "2024-01-01T12:00:00Z",
  "path": "/portfolios"
}
```

### Erros de Validação

```json
{
  "statusCode": 400,
  "message": [
    "name should not be empty",
    "userId must be a string"
  ],
  "error": "Bad Request"
}
```

---

## 📝 Tipos de Dados

### Portfolio

```typescript
interface Portfolio {
  id: string;
  name: string;
  description?: string;
  userId: string;
  totalValue: number;
  createdAt: Date;
  updatedAt: Date;
}
```

### Portfolio Asset

```typescript
interface PortfolioAsset {
  id: string;
  name: string;
  symbol: string;
  type: 'STOCK' | 'BOND' | 'FUND' | 'CRYPTO' | 'COMMODITY';
  quantity: number;
  price: number;
  totalValue: number;
  portfolioId: string;
  createdAt: Date;
  updatedAt: Date;
}
```

### Authenticated User

```typescript
interface AuthenticatedUser {
  id: string;
  type: 'user' | 'client';
  payload: JwtPayload;
  expiresAt: Date;
  issuedAt: Date;
  tokenData: Record<string, any>;
  rawToken: string;
}
```

### JWT Payload

```typescript
interface JwtPayload {
  iss: string;    // Issuer
  iat: number;    // Issued at
  exp: number;    // Expiration time
  nbf: number;    // Not before
  sub: string;    // Subject (user ID)
  jti: string;    // JWT ID
  prv?: string;   // Provider (users ou clients)
}
```

---

## 🧪 Exemplos de Uso

### Fluxo Completo - Criar Portfolio e Asset

```bash
# 1. Criar portfolio
curl -X POST "http://localhost:3333/portfolios" \
  -H "x-api-key: JOqyUcP45H875xmuI2gT3H9dDK42I2Wt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu Portfolio",
    "description": "Portfolio de ações",
    "userId": "user_123"
  }'

# 2. Criar asset no portfolio
curl -X POST "http://localhost:3333/portfolio-assets" \
  -H "x-api-key: JOqyUcP45H875xmuI2gT3H9dDK42I2Wt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Petrobras PN",
    "symbol": "PETR4",
    "type": "STOCK",
    "quantity": 100,
    "price": 30.50,
    "portfolioId": "portfolio_new"
  }'

# 3. Ver dashboard do asset
curl "http://localhost:3333/portfolio-assets/asset_new/dashboard" \
  -H "x-api-key: JOqyUcP45H875xmuI2gT3H9dDK42I2Wt"
```

### Integração com Laravel

```bash
# 1. Login no Laravel para obter token
curl -X POST "http://localhost:8000/api/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

# 2. Usar token no BFF
curl -H "Authorization: Bearer SEU_TOKEN" \
  "http://localhost:3333/auth/profile"

# 3. Proxy para Laravel
curl -X POST "http://localhost:3333/laravel-api/proxy/api/user/portfolios" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET"}'
```

---

## 📚 Recursos Adicionais

### Collections Postman

- [Pluggy Collection](../postman/) - Collection completa para testes

### Documentação Relacionada

- [Autenticação JWT](authentication.md)
- [Integração Laravel](laravel-integration.md)
- [Guia de Testes](testing-guide.md)

### Ferramentas de Desenvolvimento

- **Swagger/OpenAPI**: Em desenvolvimento
- **GraphQL Playground**: Planejado para futuras versões
- **API Documentation**: Esta documentação é mantida atualizada

---

## 🔄 Versionamento

Atualmente na versão **1.0.0**. Mudanças breaking serão comunicadas com antecedência.

### Changelog

- **v1.0.0**: Versão inicial com todos os módulos principais
- **v0.9.0**: Beta com testes E2E completos
- **v0.8.0**: Implementação dos módulos core

---

**Última atualização**: Janeiro 2024  
**Mantida por**: Equipe PlanFi