{
    "openapi": "3.1.0",
    "info": {
        "title": "FinanceWS — API",
        "description": "REST API do FinanceWS. Autenticação via Bearer token (login user) ou API key (\"akm_...\") gerada no painel admin. Eventos via webhooks de saída — cadastre URLs em /admin/control/webhooks.",
        "version": "1.0.0",
        "contact": {
            "name": "Suporte FinanceWS",
            "email": "suporte@financews.com.br",
            "url": "https://www.financews.com.br"
        }
    },
    "servers": [
        {
            "url": "https://www.financews.com.br/cafeapi",
            "description": "Produção"
        }
    ],
    "tags": [
        {
            "name": "Auth",
            "description": "Login e logout de usuário (Bearer token, 7d TTL)"
        },
        {
            "name": "Me",
            "description": "Perfil do usuário autenticado"
        },
        {
            "name": "Invoices",
            "description": "Receitas e despesas"
        },
        {
            "name": "Wallets",
            "description": "Carteiras (multi-conta)"
        },
        {
            "name": "Subscriptions",
            "description": "Assinatura PRO do usuário"
        },
        {
            "name": "Admin",
            "description": "Endpoints agregados (exige scope=admin)"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "Token de user OU API key (akm_...)",
                "description": "Header: Authorization: Bearer {token}. Para API keys do painel admin, o prefixo é 'akm_'."
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "errors": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "example": "invalid_auth"
                            },
                            "message": {
                                "type": "string",
                                "example": "Token inválido ou expirado"
                            }
                        }
                    }
                }
            },
            "AuthLoginRequest": {
                "type": "object",
                "required": [
                    "email",
                    "password"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "user@example.com"
                    },
                    "password": {
                        "type": "string",
                        "format": "password",
                        "example": "senha-forte-aqui"
                    }
                }
            },
            "AuthLoginResponse": {
                "type": "object",
                "properties": {
                    "user": {
                        "type": "object"
                    },
                    "token": {
                        "type": "string",
                        "example": "f3a7d2..."
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "Invoice": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "description": {
                        "type": "string"
                    },
                    "value": {
                        "type": "number",
                        "format": "float"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "income",
                            "expense"
                        ]
                    },
                    "due_at": {
                        "type": "string",
                        "format": "date"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "unpaid",
                            "paid"
                        ]
                    },
                    "category_id": {
                        "type": "integer"
                    },
                    "wallet_id": {
                        "type": "integer"
                    }
                }
            },
            "MetricsResponse": {
                "type": "object",
                "properties": {
                    "users": {
                        "type": "object",
                        "properties": {
                            "total": {
                                "type": "integer"
                            },
                            "confirmed": {
                                "type": "integer"
                            },
                            "last_30d": {
                                "type": "integer"
                            }
                        }
                    },
                    "subscriptions": {
                        "type": "object",
                        "properties": {
                            "total": {
                                "type": "integer"
                            },
                            "active": {
                                "type": "integer"
                            },
                            "past_due": {
                                "type": "integer"
                            },
                            "canceled": {
                                "type": "integer"
                            }
                        }
                    },
                    "mrr": {
                        "type": "object",
                        "properties": {
                            "current_brl": {
                                "type": "number",
                                "format": "float"
                            },
                            "active_subs": {
                                "type": "integer"
                            }
                        }
                    },
                    "invoices": {
                        "type": "object",
                        "properties": {
                            "total": {
                                "type": "integer"
                            },
                            "last_30d_count": {
                                "type": "integer"
                            },
                            "last_30d_paid_brl": {
                                "type": "number",
                                "format": "float"
                            }
                        }
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/auth": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Login e emissão de Bearer token (7 dias)",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AuthLoginRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AuthLoginResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credenciais inválidas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/auth/logout": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Invalida o token atual",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/me": {
            "get": {
                "tags": [
                    "Me"
                ],
                "summary": "Perfil do usuário autenticado",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "put": {
                "tags": [
                    "Me"
                ],
                "summary": "Atualiza dados do perfil",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/invoices": {
            "get": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Lista invoices do usuário",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Invoice"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Cria novo lançamento",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Invoice"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/invoices/{invoice_id}": {
            "parameters": [
                {
                    "name": "invoice_id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ],
            "get": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Lê 1 invoice",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "put": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Atualiza invoice",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Remove invoice",
                "responses": {
                    "204": {
                        "description": "No Content"
                    }
                }
            }
        },
        "/wallets": {
            "get": {
                "tags": [
                    "Wallets"
                ],
                "summary": "Lista carteiras",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "tags": [
                    "Wallets"
                ],
                "summary": "Cria carteira",
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/wallets/{wallet_id}": {
            "parameters": [
                {
                    "name": "wallet_id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ],
            "get": {
                "tags": [
                    "Wallets"
                ],
                "summary": "Lê carteira",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "put": {
                "tags": [
                    "Wallets"
                ],
                "summary": "Atualiza carteira",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Wallets"
                ],
                "summary": "Remove carteira",
                "responses": {
                    "204": {
                        "description": "No Content"
                    }
                }
            }
        },
        "/subscription": {
            "get": {
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Estado da assinatura atual",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Cria nova assinatura",
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            },
            "put": {
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Atualiza cartão/plano",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/subscription/plans": {
            "get": {
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Catálogo de planos disponíveis",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/admin/metrics": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "KPIs agregados (MRR, usuários, faturas) — scope=admin",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MetricsResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "API key sem scope=admin",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/admin/tenants": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Lista tenants com plano e status (scope=admin)",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "x-webhook-events": {
        "description": "Eventos disparados pelo FinanceWS para URLs cadastradas em /admin/control/webhooks. Cada POST inclui header X-FinanceWS-Signature (HMAC-SHA256 do body com o secret da subscription).",
        "events": [
            {
                "name": "invoice.created",
                "description": "Novo lançamento criado (receita ou despesa)"
            },
            {
                "name": "invoice.paid",
                "description": "Lançamento marcado como pago"
            },
            {
                "name": "subscription.created",
                "description": "Nova assinatura PRO ativada"
            },
            {
                "name": "subscription.paid",
                "description": "Cobrança de assinatura recebida (via ASAAS webhook)"
            },
            {
                "name": "tenant.created",
                "description": "Novo tenant criado pelo super-admin"
            },
            {
                "name": "user.registered",
                "description": "Novo usuário se cadastrou via /cadastrar"
            },
            {
                "name": "webhook.test",
                "description": "Ping manual disparado do painel admin"
            }
        ],
        "example_payload": {
            "event": "invoice.created",
            "delivered_at": "2026-05-13T12:34:56-03:00",
            "data": {
                "invoice_id": 12345,
                "user_id": 42,
                "type": "expense",
                "description": "Mercado",
                "value": 187.5,
                "due_at": "2026-05-20"
            }
        }
    }
}