marco/webmoney
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
webmoney/docs/API_REFERENCE.md
marco 54cccdd095 refactor: migração para desenvolvimento direto no servidor 
- Removido README.md padrão do Laravel (backend)
- Removidos scripts de deploy (não mais necessários)
- Atualizado copilot-instructions.md para novo fluxo
- Adicionada documentação de auditoria do servidor
- Sincronizado código de produção com repositório

Novo workflow:
- Trabalhamos diretamente em /root/webmoney (symlink para /var/www/webmoney)
- Mudanças PHP são instantâneas
- Mudanças React requerem 'npm run build'
- Commit após validação funcional
2025-12-19 11:45:32 +01:00

1118 lines
17 KiB
Markdown
Executable File
Raw Permalink Blame History

# 🔧 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*
Reference in New Issue View Git Blame Copy Permalink