{
  "openapi": "3.1.0",
  "info": {
    "title": "DirectServi API",
    "version": "1.0.0",
    "description": "API para empresas y comparadores de luz: tarifas energía, Faro (análisis de facturas luz/gas), ranking top 10, white label, marco retributivo, contratos y webhooks."
  },
  "servers": [
    {
      "url": "https://api.directservi.com",
      "description": "Producción"
    }
  ],
  "tags": [
    { "name": "Facturas", "description": "Faro · analizar facturas y ranking de tarifas" },
    { "name": "Productos", "description": "API tarifas energía / catálogo" },
    { "name": "Cuenta", "description": "Identidad de tu clave API" },
    { "name": "Webhooks", "description": "Webhook tarifas y estado de contratos" }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": ["Cuenta"],
        "summary": "Comprobar que la API responde",
        "operationId": "getHealth",
        "responses": {
          "200": { "description": "Servicio disponible" }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["Cuenta"],
        "summary": "Ver la identidad de tu clave",
        "operationId": "getMe",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": { "description": "Datos de la clave activa" },
          "401": { "description": "Clave ausente o no válida" }
        }
      }
    },
    "/v1/products": {
      "get": {
        "tags": ["Productos"],
        "summary": "Listar tarifas y productos",
        "operationId": "listProducts",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": { "description": "Catálogo de productos activos" },
          "401": { "description": "Clave ausente o no válida" }
        }
      }
    },
    "/v1/invoices/analyze": {
      "post": {
        "tags": ["Facturas"],
        "summary": "Analizar una factura con Faro",
        "description": "Faro extrae titular, CUPS, potencias, consumos e importes. PDF o hasta 3 imágenes. JSON o tiempo real (SSE).",
        "operationId": "analyzeInvoice",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": { "description": "Datos extraídos" },
          "401": { "description": "Clave ausente o no válida" }
        }
      }
    },
    "/v1/invoices/analyze-and-rank": {
      "post": {
        "tags": ["Facturas"],
        "summary": "Analizar factura y devolver las 10 mejores tarifas",
        "description": "Faro + ranking calculado por el motor de precios (top 10 por €/mes).",
        "operationId": "analyzeInvoiceAndRank",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": { "description": "Extracción + ranking top 10" },
          "401": { "description": "Clave ausente o no válida" }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "Listar webhooks",
        "operationId": "listWebhooks",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": { "200": { "description": "Lista de endpoints" } }
      },
      "post": {
        "tags": ["Webhooks"],
        "summary": "Registrar un webhook",
        "description": "URL HTTPS + eventos. Devuelve el secreto HMAC una sola vez.",
        "operationId": "createWebhook",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": { "201": { "description": "Webhook creado con secret" } }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "tags": ["Webhooks"],
        "summary": "Eliminar un webhook",
        "operationId": "deleteWebhook",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": { "204": { "description": "Eliminado" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Invoice-AI-Key",
        "description": "Clave sk- (servidor) o pk- (navegador con orígenes). También Authorization: Bearer."
      }
    }
  }
}