# 🔧 WebMoney - Documentação Técnica da API

## Referência Completa dos Endpoints

**Versão:** 1.0  
**Base URL:** `https://webmoney.cnxifly.com/api`  
**Autenticação:** Bearer Token (Laravel Sanctum)

---

## 📋 Índice

1. [Autenticação](#1-autenticação)
2. [Contas](#2-contas)
3. [Transações](#3-transações)
4. [Categorias](#4-categorias)
5. [Centros de Custo](#5-centros-de-custo)
6. [Importação](#6-importação)
7. [Passivos](#7-passivos)
8. [Transações Recorrentes](#8-transações-recorrentes)
9. [Detecção de Transferências](#9-detecção-de-transferências)
10. [Detecção de Reembolsos](#10-detecção-de-reembolsos)
11. [Dashboard](#11-dashboard)

---

## 1. Autenticação

### POST /register
Cria uma nova conta de usuário.

**Request Body:**
```json
{
  "name": "string",
  "email": "string",
  "password": "string",
  "password_confirmation": "string"
}
```

**Response:** `201 Created`
```json
{
  "success": true,
  "data": {
    "user": { "id": 1, "name": "...", "email": "..." },
    "token": "1|abc123..."
  }
}
```

---

### POST /login
Autentica um usuário existente.

**Request Body:**
```json
{
  "email": "string",
  "password": "string"
}
```

**Response:** `200 OK`
```json
{
  "success": true,
  "data": {
    "user": { "id": 1, "name": "...", "email": "...", "role": "admin" },
    "token": "2|xyz789..."
  }
}
```

---

### POST /logout
Encerra a sessão do usuário autenticado.

**Headers:** `Authorization: Bearer {token}`

**Response:** `200 OK`
```json
{
  "success": true,
  "message": "Logged out successfully"
}
```

---

### GET /me
Retorna dados do usuário autenticado.

**Headers:** `Authorization: Bearer {token}`

**Response:** `200 OK`
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Marco Leite",
    "email": "marco@cnxifly.com",
    "role": "admin"
  }
}
```

---

## 2. Contas

### GET /accounts
Lista todas as contas do usuário.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| type | string | Filtrar por tipo (checking, savings, etc.) |
| is_active | boolean | Filtrar por status |

**Response:** `200 OK`
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Nubank",
      "type": "checking",
      "bank_name": "Nu Pagamentos",
      "account_number": "1234567-8",
      "initial_balance": 0,
      "current_balance": 5420.50,
      "credit_limit": null,
      "currency": "BRL",
      "color": "#8B5CF6",
      "icon": "bi-bank",
      "is_active": true,
      "include_in_total": true
    }
  ]
}
```

---

### POST /accounts
Cria uma nova conta.

**Request Body:**
```json
{
  "name": "string (required)",
  "type": "string (required)",
  "bank_name": "string",
  "account_number": "string",
  "initial_balance": "number",
  "credit_limit": "number",
  "currency": "string (default: BRL)",
  "color": "string (hex)",
  "icon": "string",
  "description": "string",
  "is_active": "boolean",
  "include_in_total": "boolean"
}
```

---

### GET /accounts/{id}
Retorna detalhes de uma conta específica.

---

### PUT /accounts/{id}
Atualiza uma conta existente.

---

### DELETE /accounts/{id}
Remove uma conta (soft delete).

---

### POST /accounts/recalculate-balances
Recalcula saldos de todas as contas.

**Response:** `200 OK`
```json
{
  "success": true,
  "message": "Balances recalculated",
  "data": {
    "updated_accounts": 5
  }
}
```

---

### POST /accounts/{id}/adjust-balance
Ajusta o saldo de uma conta criando transação de ajuste.

**Request Body:**
```json
{
  "target_balance": 5000.00
}
```

---

## 3. Transações

### GET /transactions
Lista transações com filtros.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| account_id | integer | Filtrar por conta |
| category_id | integer | Filtrar por categoria |
| cost_center_id | integer | Filtrar por centro de custo |
| type | string | debit, credit |
| status | string | pending, completed, cancelled |
| search | string | Busca por descrição |
| start_date | date | Data inicial |
| end_date | date | Data final |
| page | integer | Página |
| per_page | integer | Itens por página |

---

### GET /transactions/by-week
Retorna transações agrupadas por semana.

**Query Parameters:** Mesmos do `/transactions`

**Response:** `200 OK`
```json
{
  "success": true,
  "data": {
    "weeks": [
      {
        "week_start": "2025-12-09",
        "week_end": "2025-12-15",
        "total_income": 5000.00,
        "total_expense": 3200.00,
        "balance": 1800.00,
        "transactions": [...]
      }
    ],
    "pagination": {...}
  }
}
```

---

### GET /transactions/summary
Retorna resumo financeiro do período.

---

### POST /transactions
Cria nova transação.

**Request Body:**
```json
{
  "account_id": "integer (required)",
  "category_id": "integer",
  "cost_center_id": "integer",
  "type": "string (required: debit|credit)",
  "planned_amount": "number (required)",
  "amount": "number",
  "description": "string (required)",
  "notes": "string",
  "planned_date": "date (required)",
  "effective_date": "date",
  "status": "string (default: pending)",
  "reference": "string"
}
```

---

### PUT /transactions/{id}
Atualiza uma transação.

---

### DELETE /transactions/{id}
Remove uma transação.

---

### POST /transactions/{id}/complete
Marca transação como concluída.

**Request Body:**
```json
{
  "amount": 150.00,
  "effective_date": "2025-12-13"
}
```

---

### POST /transactions/{id}/quick-complete
Completa com valores planejados.

---

### POST /transactions/{id}/cancel
Cancela uma transação.

---

### POST /transactions/{id}/revert
Reverte transação concluída para pendente.

---

### POST /transactions/{id}/duplicate
Cria cópia da transação.

---

### POST /transactions/{id}/split
Divide transação em múltiplas.

**Request Body:**
```json
{
  "splits": [
    { "category_id": 1, "amount": 100, "description": "Parte 1" },
    { "category_id": 2, "amount": 50, "description": "Parte 2" }
  ]
}
```

---

### POST /transactions/{id}/unsplit
Desfaz divisão de transação.

---

### GET /transactions/{id}/splits
Lista divisões de uma transação.

---

### POST /transactions/transfer
Cria transferência entre contas.

**Request Body:**
```json
{
  "from_account_id": 1,
  "to_account_id": 2,
  "amount": 500.00,
  "description": "Transferência",
  "date": "2025-12-13",
  "notes": "string"
}
```

---

### POST /transactions/{id}/unlink-transfer
Desvincula transações de transferência.

---

### GET /transactions/{id}/liability-installments
Busca parcelas de passivo compatíveis.

---

### POST /transactions/{id}/reconcile-liability
Concilia transação com parcela de passivo.

---

## 4. Categorias

### GET /categories
Lista categorias (hierárquicas).

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| type | string | expense, income, both |
| flat | boolean | Lista plana (sem hierarquia) |

---

### POST /categories
Cria nova categoria.

**Request Body:**
```json
{
  "name": "string (required)",
  "parent_id": "integer (para subcategoria)",
  "type": "string (expense|income|both)",
  "description": "string",
  "color": "string (hex)",
  "icon": "string",
  "is_active": "boolean",
  "keywords": ["uber", "99", "cabify"]
}
```

---

### PUT /categories/{id}
Atualiza categoria.

---

### DELETE /categories/{id}
Remove categoria.

---

### POST /categories/{id}/keywords
Adiciona palavras-chave.

**Request Body:**
```json
{
  "keywords": ["netflix", "spotify"]
}
```

---

### DELETE /categories/{id}/keywords/{keywordId}
Remove palavra-chave.

---

### POST /categories/match
Busca categoria por palavra-chave.

**Request Body:**
```json
{
  "description": "UBER TRIP SAO PAULO"
}
```

---

### GET /categories/categorize-batch/preview
Preview da categorização em lote.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| include_cost_centers | boolean | Incluir centros de custo |
| limit | integer | Limite de transações |

---

### POST /categories/categorize-batch
Executa categorização em lote automática.

---

### POST /categories/categorize-batch/manual
Categorização em lote manual.

**Request Body:**
```json
{
  "category_id": 5,
  "cost_center_id": 2,
  "add_keyword": true,
  "filters": {
    "search": "UBER",
    "account_id": 1
  }
}
```

---

### PUT /categories/reorder
Reordena categorias.

---

## 5. Centros de Custo

### GET /cost-centers
Lista centros de custo.

---

### POST /cost-centers
Cria centro de custo.

**Request Body:**
```json
{
  "name": "string (required)",
  "code": "string",
  "description": "string",
  "color": "string (hex)",
  "icon": "string",
  "is_active": "boolean",
  "keywords": ["cliente-abc"]
}
```

---

### PUT /cost-centers/{id}
Atualiza centro de custo.

---

### DELETE /cost-centers/{id}
Remove centro de custo.

---

### POST /cost-centers/{id}/keywords
Adiciona palavras-chave.

---

### DELETE /cost-centers/{id}/keywords/{keywordId}
Remove palavra-chave.

---

### POST /cost-centers/match
Busca centro de custo por palavra-chave.

---

## 6. Importação

### POST /import/upload
Upload de arquivo para importação.

**Request:** `multipart/form-data`
- `file`: Arquivo (CSV, XLSX, XLS, OFX, PDF)

**Response:**
```json
{
  "success": true,
  "data": {
    "temp_file": "imports/temp/abc123.csv",
    "preview": {
      "headers": [...],
      "preview": [...]
    }
  }
}
```

---

### POST /import/headers
Obtém cabeçalhos com configuração.

**Request Body:**
```json
{
  "temp_file": "imports/temp/abc123.csv",
  "header_row": 0,
  "data_start_row": 1
}
```

---

### POST /import/process
Executa a importação.

**Request Body:**
```json
{
  "temp_file": "string",
  "account_id": "integer (required)",
  "category_id": "integer",
  "cost_center_id": "integer",
  "column_mappings": {
    "date": 0,
    "description": 1,
    "amount": 2
  },
  "date_format": "d/m/Y",
  "decimal_separator": ",",
  "thousands_separator": ".",
  "save_mapping": true,
  "mapping_name": "Nubank CSV",
  "bank_name": "Nubank"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "imported": 45,
    "duplicates": 3,
    "errors": 0
  }
}
```

---

### GET /import/mappings
Lista mapeamentos salvos.

---

### GET /import/mappings/{id}
Detalhes de um mapeamento.

---

### PUT /import/mappings/{id}
Atualiza mapeamento.

---

### DELETE /import/mappings/{id}
Remove mapeamento.

---

### GET /import/presets
Lista presets de bancos.

---

### POST /import/presets/create
Cria mapeamento a partir de preset.

---

### GET /import/history
Histórico de importações.

---

### GET /import/fields
Definições de campos e formatos de data.

---

## 7. Passivos

### GET /liabilities
Lista passivos/financiamentos.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| status | string | active, paid, cancelled |
| is_active | boolean | Ativo |

**Response:**
```json
{
  "success": true,
  "data": [...],
  "summary": {
    "total_contracts": 2,
    "total_value": 150000,
    "total_paid": 45000,
    "total_pending": 105000
  }
}
```

---

### POST /liabilities/import
Importa passivo de PDF.

**Request:** `multipart/form-data`
- `file`: PDF do contrato/simulação
- `name`: Nome do passivo
- `creditor`: Nome do credor
- `contract_number`: Número do contrato
- `currency`: Moeda
- `description`: Descrição

---

### GET /liabilities/{id}
Detalhes do passivo com parcelas.

---

### PUT /liabilities/{id}
Atualiza passivo.

---

### DELETE /liabilities/{id}
Remove passivo.

---

### GET /liabilities/{id}/installments
Lista parcelas do passivo.

---

### POST /liabilities/{id}/installments/{installmentId}/reconcile
Concilia parcela com transação.

**Request Body:**
```json
{
  "transaction_id": 123,
  "mark_as_paid": true
}
```

---

## 8. Transações Recorrentes

### GET /recurring
Lista templates de recorrência.

---

### POST /recurring
Cria novo template.

**Request Body:**
```json
{
  "account_id": "integer (required)",
  "category_id": "integer",
  "type": "string (required: debit|credit)",
  "amount": "number (required)",
  "description": "string (required)",
  "frequency": "string (required)",
  "start_date": "date (required)",
  "end_date": "date",
  "is_active": "boolean"
}
```

---

### GET /recurring/{id}
Detalhes do template.

---

### PUT /recurring/{id}
Atualiza template.

---

### DELETE /recurring/{id}
Remove template.

---

### POST /recurring/{id}/pause
Pausa template.

---

### POST /recurring/{id}/resume
Retoma template pausado.

---

### GET /recurring/{id}/instances
Lista instâncias do template.

---

### GET /recurring/frequencies
Lista frequências disponíveis.

---

### GET /recurring/pending
Lista instâncias pendentes (todas).

---

### GET /recurring/overdue
Lista instâncias vencidas.

---

### GET /recurring/due-soon
Lista instâncias a vencer.

---

### POST /recurring/regenerate-all
Regenera instâncias de todos os templates.

---

### POST /recurring/from-transaction
Cria recorrência a partir de transação.

**Request Body:**
```json
{
  "transaction_id": 123,
  "frequency": "monthly",
  "end_date": "2026-12-31"
}
```

---

### POST /recurring-instances/{id}/pay
Marca instância como paga (cria transação).

---

### POST /recurring-instances/{id}/reconcile
Concilia com transação existente.

**Request Body:**
```json
{
  "transaction_id": 456
}
```

---

### GET /recurring-instances/{id}/candidates
Busca transações candidatas para conciliação.

---

### POST /recurring-instances/{id}/skip
Pula instância.

---

### POST /recurring-instances/{id}/cancel
Cancela instância.

---

### PUT /recurring-instances/{id}
Edita instância específica.

---

## 9. Detecção de Transferências

### GET /transfer-detection
Lista transferências detectadas.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| tolerance_days | integer | Tolerância em dias (default: 3) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "debit": { "id": 1, "amount": 500, "date": "2025-12-10", "account": {...} },
      "credit": { "id": 2, "amount": 500, "date": "2025-12-11", "account": {...} },
      "confidence": "high",
      "day_difference": 1
    }
  ]
}
```

---

### GET /transfer-detection/stats
Estatísticas de transferências detectadas.

---

### GET /transfer-detection/{id}/pairs
Busca pares para uma transação.

---

### POST /transfer-detection/confirm
Confirma uma transferência.

**Request Body:**
```json
{
  "debit_id": 1,
  "credit_id": 2
}
```

---

### POST /transfer-detection/confirm-batch
Confirma múltiplas transferências.

**Request Body:**
```json
{
  "transfers": [
    { "debit_id": 1, "credit_id": 2 },
    { "debit_id": 3, "credit_id": 4 }
  ]
}
```

---

### POST /transfer-detection/ignore
Ignora par de transferência.

---

### POST /transfer-detection/delete-both
Exclui ambas as transações.

---

## 10. Detecção de Reembolsos

### GET /refund-detection
Lista reembolsos detectados.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| tolerance_days | integer | Tolerância em dias (default: 7) |

---

### POST /refund-detection/confirm
Confirma reembolso.

**Request Body:**
```json
{
  "debit_id": 1,
  "credit_id": 2
}
```

---

### POST /refund-detection/confirm-batch
Confirma múltiplos reembolsos.

---

### POST /refund-detection/ignore
Ignora par de reembolso.

---

### POST /refund-detection/undo
Desfaz vinculação de reembolso.

---

## 11. Dashboard

### GET /dashboard/summary
Resumo financeiro geral.

**Response:**
```json
{
  "success": true,
  "data": {
    "total_balance": 15420.50,
    "month_income": 8000.00,
    "month_expense": 5200.00,
    "month_balance": 2800.00,
    "pending_transactions": 12,
    "overdue_transactions": 3
  }
}
```

---

### GET /dashboard/cashflow
Fluxo de caixa por mês.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| months | integer | Número de meses (default: 12) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "month": "2025-12",
      "income": 8000,
      "expense": 5200,
      "balance": 2800
    }
  ]
}
```

---

### GET /dashboard/expenses-by-category
Despesas agrupadas por categoria.

---

### GET /dashboard/income-by-category
Receitas agrupadas por categoria.

---

### GET /dashboard/payment-variances
Análise de variações de pagamento.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| months | integer | Período de análise |

---

### GET /dashboard/calendar
Dados para calendário financeiro.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| month | integer | Mês (1-12) |
| year | integer | Ano |

---

### GET /dashboard/calendar-day
Transações de um dia específico.

**Query Parameters:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| date | date | Data (YYYY-MM-DD) |

---

### GET /dashboard/upcoming
Transações próximas (7 dias).

---

### GET /dashboard/overdue
Transações vencidas.

---

## Códigos de Resposta

| Código | Significado |
|--------|-------------|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 400 | Requisição inválida |
| 401 | Não autenticado |
| 403 | Não autorizado |
| 404 | Não encontrado |
| 422 | Validação falhou |
| 500 | Erro interno |

---

## Formato de Erro

```json
{
  "success": false,
  "message": "Descrição do erro",
  "errors": {
    "campo": ["mensagem de validação"]
  }
}
```

---

*Documentação gerada em Dezembro 2025*