{
  "openapi": "3.0.3",
  "info": {
    "title": "Segmenta24 API with RBAC v2.1 Matrix",
    "version": "2.1.0",
    "description": "Especificación OpenAPI con metadatos x-permission, modelo multi-tenant, 2FA TOTP RFC 6238, M2M Granular y Motor DLP."
  },
  "paths": {
    "/api/leads/services-plans": {
      "get": {
        "summary": "Catálogo público dinámico de paquetes y servicios de marketing IA",
        "description": "Retorna paquetes preconfigurados (Starter, Growth, Enterprise, Ecosistema 24) y catálogo de servicios individuales para clientes externos.",
        "x-permission": null,
        "x-is-public": true,
        "responses": {
          "200": {
            "description": "Catálogo recuperado exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "packages": {
                      "type": "array"
                    },
                    "single_services": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/leads/public-capture": {
      "post": {
        "summary": "Captura pública de leads y prospectos de agencia",
        "description": "Captura leads comerciales con validación de honeypot, asignación de scoring preliminar, deduplicación canónica y registro en CRM/Funnel.",
        "x-permission": null,
        "x-is-public": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contact_name",
                  "email"
                ],
                "properties": {
                  "contact_name": {
                    "type": "string"
                  },
                  "company_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "plan_interest": {
                    "type": "string"
                  },
                  "services_requested": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "estimated_contacts": {
                    "type": "integer"
                  },
                  "monthly_budget": {
                    "type": "number"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string",
                    "description": "Honeypot field (debe permanecer vacío)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead capturado exitosamente"
          },
          "400": {
            "description": "Datos de entrada inválidos o honeypot activado"
          },
          "429": {
            "description": "Demasiadas solicitudes (Rate limit excedido)"
          }
        }
      }
    },
    "/api/admin/feature-flags": {
      "get": {
        "summary": "Endpoint GET /api/admin/feature-flags",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/admin/feature-flags/{key}": {
      "delete": {
        "summary": "Endpoint DELETE /api/admin/feature-flags/:key",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/admin/feature-flags/:key",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/admin/feature-flags/:key",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/admin/feature-flags/bulk/update": {
      "post": {
        "summary": "Endpoint POST /api/admin/feature-flags/bulk/update",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/can-register": {
      "get": {
        "summary": "Endpoint GET /api/auth/can-register",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/forgot-password": {
      "post": {
        "summary": "Endpoint POST /api/auth/forgot-password",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "summary": "Endpoint POST /api/auth/login",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/logout": {
      "get": {
        "summary": "Endpoint GET /api/auth/logout",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/auth/logout",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "summary": "Endpoint GET /api/auth/me",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/me/context": {
      "get": {
        "summary": "Endpoint GET /api/auth/me/context",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/register": {
      "post": {
        "summary": "Endpoint POST /api/auth/register",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/reset-password": {
      "post": {
        "summary": "Endpoint POST /api/auth/reset-password",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/auth/2fa/setup": {
      "post": {
        "summary": "Inicia enrolamiento 2FA generando secreto Base32 y QR SVG",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Secreto Base32 y SVG QR generado"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/auth/2fa/enable": {
      "post": {
        "summary": "Confirma TOTP y activa 2FA emitiendo 8 backup codes",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "2FA activado con éxito y backup codes generados"
          },
          "400": {
            "description": "Código TOTP inválido"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/auth/2fa/verify": {
      "post": {
        "summary": "Resuelve desafío 2FA de login con challenge_token",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Desafío superado, sesión autorizada y cookies establecidas"
          },
          "400": {
            "description": "Código incorrecto o challenge expirado"
          }
        }
      }
    },
    "/api/auth/2fa/disable": {
      "post": {
        "summary": "Desactiva 2FA previa validación de contraseña y TOTP",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "2FA desactivado"
          },
          "401": {
            "description": "Contraseña o código TOTP inválido"
          }
        }
      }
    },
    "/api/campaigns": {
      "get": {
        "summary": "Endpoint GET /api/campaigns",
        "x-permission": "campaigns:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Crear campaña omnicanal (con gobernanza de alcance de audiencia)",
        "x-permission": "campaigns:create",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "201": {
            "description": "Campaña creada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC) o intento no autorizado de audiencia global (FORBIDDEN_GLOBAL_AUDIENCE_RESERVED)"
          }
        },
        "description": "Crea una campaña omnicanal para la marca activa o a nivel global SaaS. Si audience_scope es 'global', se requiere estrictamente rol superadmin o cuenta de servicio gestionado OAAS.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "channel"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Nombre identificador de la campaña"
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "email",
                      "whatsapp",
                      "telegram",
                      "sms"
                    ],
                    "description": "Canal de despacho"
                  },
                  "audience_source": {
                    "type": "string",
                    "default": "brand_contacts"
                  },
                  "audience_scope": {
                    "type": "string",
                    "enum": [
                      "brand",
                      "global"
                    ],
                    "default": "brand",
                    "description": "Alcance de audiencia: 'brand' (contactos del tenant activo) o 'global' (catálogo SaaS consolidado, reservado a superadmin/OAAS)."
                  },
                  "macro_sector": {
                    "type": "string"
                  },
                  "sub_industry": {
                    "type": "string"
                  },
                  "company_size": {
                    "type": "string"
                  },
                  "decision_maker_level": {
                    "type": "string"
                  },
                  "functional_area": {
                    "type": "string"
                  },
                  "metro_area": {
                    "type": "string"
                  },
                  "cooldown_days": {
                    "type": "integer",
                    "default": 14
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/campaigns/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/campaigns/:id",
        "x-permission": "campaigns:delete",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/campaigns/:id",
        "x-permission": "campaigns:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Actualizar campaña existente",
        "x-permission": "campaigns:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC) o intento no autorizado de audiencia global (FORBIDDEN_GLOBAL_AUDIENCE_RESERVED)"
          }
        },
        "description": "Actualiza los parámetros, programación y segmentación de una campaña. Si se especifica audience_scope = 'global', se exige rol superadmin u OAAS.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "audience_scope": {
                    "type": "string",
                    "enum": [
                      "brand",
                      "global"
                    ],
                    "description": "Alcance de audiencia: 'brand' o 'global' (solo superadmin/OAAS)."
                  },
                  "macro_sector": {
                    "type": "string"
                  },
                  "sub_industry": {
                    "type": "string"
                  },
                  "company_size": {
                    "type": "string"
                  },
                  "decision_maker_level": {
                    "type": "string"
                  },
                  "functional_area": {
                    "type": "string"
                  },
                  "metro_area": {
                    "type": "string"
                  },
                  "cooldown_days": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/campaigns/{id}/clone": {
      "post": {
        "summary": "Endpoint POST /api/campaigns/:id/clone",
        "x-permission": "campaigns:clone",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/campaigns/estimate-reach": {
      "post": {
        "summary": "Estimación en vivo de alcance neto de campaña",
        "description": "Calcula de forma agregada el universo de contactos coincidentes para un tenant con filtros B2B (macro_sector, company_size, decision_maker_level, metro_area) y periodo de enfriamiento sin filtrar PII al cliente.",
        "x-permission": "campaigns:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "macro_sector": {
                    "type": "string"
                  },
                  "company_size": {
                    "type": "string"
                  },
                  "decision_maker_level": {
                    "type": "string"
                  },
                  "metro_area": {
                    "type": "string"
                  },
                  "cooldown_days": {
                    "type": "integer",
                    "default": 14
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimación calculada exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_matched": {
                          "type": "integer",
                          "example": 1250
                        },
                        "unsubscribed": {
                          "type": "integer",
                          "example": 40
                        },
                        "in_cooldown": {
                          "type": "integer",
                          "example": 110
                        },
                        "ready_to_send": {
                          "type": "integer",
                          "example": 1100
                        },
                        "cooldown_days": {
                          "type": "integer",
                          "example": 14
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere campaigns:view)"
          }
        }
      }
    },
    "/api/campaigns/{id}/audience-preview": {
      "get": {
        "summary": "Cálculo en vivo de audiencia neta y periodo de enfriamiento",
        "description": "Calcula el universo de contactos coincidentes con los filtros B2B de la campaña, deduciendo contactos en periodo de enfriamiento (cooldown) y opt-out.",
        "x-permission": "campaigns:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Audiencia neta calculada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          },
          "404": {
            "description": "Campaña no encontrada"
          }
        }
      }
    },
    "/api/campaigns/{id}/launch": {
      "post": {
        "summary": "Lanzamiento y encolamiento masivo progresivo de campaña",
        "description": "Activa la campaña, evalúa cuotas de consumo diario del tenant, genera los registros de mensajes encolados y los distribuye progresivamente a BullMQ.",
        "x-permission": "campaigns:launch",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Campaña activada y mensajes encolados"
          },
          "400": {
            "description": "Sin contactos elegibles"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes o cuenta suspendida"
          },
          "429": {
            "description": "Cuota diaria de mensajes alcanzada"
          }
        }
      }
    },
    "/api/campaigns/custom-audience/sync": {
      "post": {
        "summary": "Endpoint POST /api/campaigns/custom-audience/sync",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/campaigns/triggers": {
      "get": {
        "summary": "Obtener disparadores y eventos de automatización de campañas",
        "description": "Retorna el catálogo de disparadores reactivos del tenant: clics, aperturas, respuestas y webhooks M2M.",
        "x-permission": "campaigns:view",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Disparadores recuperados"
          }
        }
      }
    },
    "/api/channels": {
      "get": {
        "summary": "Endpoint GET /api/channels",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/channels/{id}/stats": {
      "get": {
        "summary": "Endpoint GET /api/channels/:id/stats",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/channels/cascade-config": {
      "get": {
        "summary": "Obtener configuración de cascada de 4 capas y métricas de ahorro",
        "description": "Retorna las capas activas (Push, Telegram, Email, WhatsApp), preajuste de timeouts y el ahorro financiero estimado acumulado para la marca activa.",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración recuperada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      },
      "put": {
        "summary": "Actualizar configuración de cascada inteligente",
        "description": "Configura las capas activas de notificación y el preajuste de timeouts (aggressive_cost_saver, balanced, instant_reach).",
        "x-permission": "channels:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "layer_config": {
                    "type": "object",
                    "properties": {
                      "push": {
                        "type": "boolean"
                      },
                      "telegram": {
                        "type": "boolean"
                      },
                      "ses": {
                        "type": "boolean"
                      },
                      "whatsapp": {
                        "type": "boolean"
                      },
                      "preset": {
                        "type": "string",
                        "enum": [
                          "aggressive_cost_saver",
                          "balanced",
                          "instant_reach"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuración de cascada actualizada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere channels:manage)"
          }
        }
      }
    },
    "/api/channels/ecosystem/status": {
      "get": {
        "summary": "Diagnóstico unificado de las 5 APPs hermanas del Ecosistema 24",
        "description": "Prueba en paralelo la disponibilidad y latencia de DocVault24, Mande24, Conta24, Nomi24 y Raíz Digital para el inquilino activo.",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Estado y latencia de las 5 aplicaciones hermanas recuperado exitosamente"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/company": {
      "get": {
        "summary": "Endpoint GET /api/company",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Endpoint PUT /api/company",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/company/icon": {
      "post": {
        "summary": "Endpoint POST /api/company/icon",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/company/logo": {
      "post": {
        "summary": "Endpoint POST /api/company/logo",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/company/public": {
      "get": {
        "summary": "Endpoint GET /api/company/public",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Endpoint PUT /api/company/public",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/ai": {
      "get": {
        "summary": "Endpoint GET /api/config/ai",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/ai",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/ai/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/ai/:id",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/ai/costs": {
      "get": {
        "summary": "Endpoint GET /api/config/ai/costs",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/ai/logs": {
      "get": {
        "summary": "Endpoint GET /api/config/ai/logs",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/ai/routes": {
      "get": {
        "summary": "Endpoint GET /api/config/ai/routes",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/ai/routes",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/docvault24": {
      "get": {
        "summary": "Endpoint GET /api/config/docvault24",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/docvault24",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/docvault24/diagnose": {
      "get": {
        "summary": "Endpoint GET /api/config/docvault24/diagnose",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/docvault24/test": {
      "post": {
        "summary": "Endpoint POST /api/config/docvault24/test",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/email": {
      "get": {
        "summary": "Endpoint GET /api/config/email",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/email",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/email/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/email/:id",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/email/preflight": {
      "get": {
        "summary": "Endpoint GET /api/config/email/preflight",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/email/test-send": {
      "post": {
        "summary": "Endpoint POST /api/config/email/test-send",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/limits": {
      "get": {
        "summary": "Endpoint GET /api/config/limits",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/limits en su lugar (Reglas R-11 y R-16)."
      },
      "post": {
        "summary": "Endpoint POST /api/config/limits",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/limits en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/m2m/keys": {
      "get": {
        "summary": "Endpoint GET /api/config/m2m/keys",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/m2m/keys",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/m2m/keys/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/m2m/keys/:id",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/m2m/welcome-funnels": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/m2m/welcome-funnels",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/m2m/welcome-funnels en su lugar (Reglas R-11 y R-16)."
      },
      "get": {
        "summary": "Endpoint GET /api/config/m2m/welcome-funnels",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/m2m/welcome-funnels en su lugar (Reglas R-11 y R-16)."
      },
      "post": {
        "summary": "Endpoint POST /api/config/m2m/welcome-funnels",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/m2m/welcome-funnels en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/mande24": {
      "get": {
        "summary": "Endpoint GET /api/config/mande24",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/mande24 en su lugar (Reglas R-11 y R-16)."
      },
      "post": {
        "summary": "Endpoint POST /api/config/mande24",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/mande24 en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/meta-lead-forms": {
      "get": {
        "summary": "Endpoint GET /api/config/meta-lead-forms",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/meta-lead-forms",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto": {
      "get": {
        "summary": "Endpoint GET /api/config/mtproto",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/{phone}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/mtproto/:phone",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/confirm-2fa": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/confirm-2fa",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/confirm-code": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/confirm-code",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/import-session": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/import-session",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/quota": {
      "get": {
        "summary": "Endpoint GET /api/config/mtproto/quota",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/quota",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/request-code": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/request-code",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/test": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/test",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/mtproto/unsuspend": {
      "post": {
        "summary": "Endpoint POST /api/config/mtproto/unsuspend",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/social-oauth": {
      "get": {
        "summary": "Endpoint GET /api/config/social-oauth",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/social-oauth en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/social-oauth/{platform}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/social-oauth/:platform",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/social-oauth/{platform} en su lugar (Reglas R-11 y R-16)."
      },
      "post": {
        "summary": "Endpoint POST /api/config/social-oauth/:platform",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/social-oauth/{platform} en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/telegram": {
      "get": {
        "summary": "Endpoint GET /api/config/telegram",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/telegram",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/telegram/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/telegram/:id",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/webhooks/deliveries": {
      "get": {
        "summary": "Endpoint GET /api/config/webhooks/deliveries",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/webhooks/dlq": {
      "get": {
        "summary": "Endpoint GET /api/config/webhooks/dlq",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/webhooks/dlq en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/webhooks/dlq/{id}/replay": {
      "post": {
        "summary": "Endpoint POST /api/config/webhooks/dlq/:id/replay",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        },
        "deprecated": true,
        "description": "[DEPRECATED - Sunset activo] Utilice la ruta canónica /api/platform/webhooks/dlq/{id}/replay en su lugar (Reglas R-11 y R-16)."
      }
    },
    "/api/config/webhooks/outbound": {
      "get": {
        "summary": "Endpoint GET /api/config/webhooks/outbound",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/webhooks/outbound",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/webhooks/outbound/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/webhooks/outbound/:id",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/webhooks/test": {
      "post": {
        "summary": "Endpoint POST /api/config/webhooks/test",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/whatsapp": {
      "get": {
        "summary": "Endpoint GET /api/config/whatsapp",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/config/whatsapp",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/whatsapp/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/config/whatsapp/:id",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/config/whatsapp/{id}/verify-token": {
      "post": {
        "summary": "Endpoint POST /api/config/whatsapp/:id/verify-token",
        "x-permission": "channels:sync_health",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts": {
      "get": {
        "summary": "Endpoint GET /api/contacts",
        "x-permission": "contacts:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/contacts",
        "x-permission": "contacts:create",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/contacts/:id",
        "x-permission": "contacts:delete",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "patch": {
        "summary": "Endpoint PATCH /api/contacts/:id",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Actualizar contacto (Alias REST)",
        "description": "Actualiza atributos, datos de enriquecimiento y preferencias de canal del contacto.",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Contacto actualizado exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/rescore": {
      "post": {
        "summary": "Recálculo masivo de Lead Scoring con filtros taxonómicos B2B",
        "description": "Calcula el engagement determinístico y predictivo en lote para contactos de la marca activa según los filtros suministrados.",
        "x-permission": "lead_scoring:rescore",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "segment_type": {
                    "type": "string"
                  },
                  "channel": {
                    "type": "string"
                  },
                  "app_source": {
                    "type": "string"
                  },
                  "macro_sector": {
                    "type": "string"
                  },
                  "sub_industry": {
                    "type": "string"
                  },
                  "company_size": {
                    "type": "string"
                  },
                  "decision_maker_level": {
                    "type": "string"
                  },
                  "q": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recálculo masivo completado exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "rescored_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere lead_scoring:rescore)"
          }
        }
      }
    },
    "/api/contacts/{id}/rescore": {
      "post": {
        "summary": "Endpoint POST /api/contacts/:id/rescore",
        "x-permission": "lead_scoring:rescore",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/{id}/verify": {
      "post": {
        "summary": "Endpoint POST /api/contacts/:id/verify",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/bulk-delete": {
      "post": {
        "summary": "Endpoint POST /api/contacts/bulk-delete",
        "x-permission": "contacts:delete_mass",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/export": {
      "get": {
        "summary": "Endpoint GET /api/contacts/export",
        "x-permission": "contacts:export",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/import": {
      "post": {
        "summary": "Endpoint POST /api/contacts/import",
        "x-permission": "contacts:import",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/import-logs": {
      "get": {
        "summary": "Endpoint GET /api/contacts/import-logs",
        "x-permission": "contacts:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/import-logs/{id}": {
      "get": {
        "summary": "Endpoint GET /api/contacts/import-logs/:id",
        "x-permission": "contacts:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/verification-progress": {
      "get": {
        "summary": "Endpoint GET /api/contacts/verification-progress",
        "x-permission": "contacts:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/verification-stats": {
      "get": {
        "summary": "Endpoint GET /api/contacts/verification-stats",
        "x-permission": "contacts:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/verify-all": {
      "post": {
        "summary": "Endpoint POST /api/contacts/verify-all",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/verify-bulk": {
      "post": {
        "summary": "Endpoint POST /api/contacts/verify-bulk",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/contacts/re-evaluate-marketing-eligibility": {
      "post": {
        "summary": "Re-evaluar aptitud para marketing IA de contactos del tenant",
        "description": "Ejecuta una re-evaluación exhaustiva de la aptitud de marketing para los contactos de la marca autorizada, validando canales verificados, sintaxis y MX RFC 5321 y completitud de perfil.",
        "x-permission": "contacts:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "description": "IDs específicos a re-evaluar (opcional, si se omite re-evalúa lote pendiente)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Re-evaluación completada con éxito"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-bounce/sns": {
      "post": {
        "summary": "Endpoint POST /api/email-bounce/sns",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-templates": {
      "get": {
        "summary": "Endpoint GET /api/email-templates",
        "x-permission": "email_templates:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/email-templates",
        "x-permission": "email_templates:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-templates/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/email-templates/:id",
        "x-permission": "email_templates:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/email-templates/:id",
        "x-permission": "email_templates:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Endpoint PUT /api/email-templates/:id",
        "x-permission": "email_templates:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-templates/{id}/preview": {
      "post": {
        "summary": "Endpoint POST /api/email-templates/:id/preview",
        "x-permission": "email_templates:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-templates/preview-custom": {
      "post": {
        "summary": "Previsualización segura de plantilla personalizada con inyección de tokens de sistema",
        "description": "Compila mediante Handlebars en backend e inyecta tokens de sistema predeterminados (unsubscribe_url, cta_url, sender_name, current_year) sanitizando la salida.",
        "x-permission": "email_templates:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Plantilla renderizada exitosamente"
          },
          "400": {
            "description": "Error de sintaxis Handlebars en variables"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-templates/ai/generate": {
      "post": {
        "summary": "Endpoint POST /api/email-templates/ai/generate",
        "x-permission": "email_templates:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-track/click/{eventId}": {
      "get": {
        "summary": "Endpoint GET /api/email-track/click/:eventId",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-track/open/{eventId}.gif": {
      "get": {
        "summary": "Endpoint GET /api/email-track/open/:eventId.gif",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/email-track/unsubscribe/{eventId}": {
      "get": {
        "summary": "Endpoint GET /api/email-track/unsubscribe/:eventId",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/orchestrator-status": {
      "get": {
        "summary": "Endpoint GET /api/enrichment/orchestrator-status",
        "x-permission": "enrichment:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "running": {
                      "type": "boolean"
                    },
                    "pendingLeads": {
                      "type": "integer"
                    },
                    "enrichmentHistory": {
                      "type": "array"
                    },
                    "channelCoverage": {
                      "type": "object",
                      "properties": {
                        "tg_count": {
                          "type": "integer",
                          "description": "Contactos con Telegram ID verificado ($0 por mensaje)"
                        },
                        "wa_count": {
                          "type": "integer",
                          "description": "Contactos con WhatsApp verificado (Meta WABA PMP)"
                        },
                        "email_count": {
                          "type": "integer",
                          "description": "Contactos con Email verificado"
                        },
                        "total_prospects": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/pending": {
      "get": {
        "summary": "Endpoint GET /api/enrichment/pending",
        "x-permission": "enrichment:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/request": {
      "post": {
        "summary": "Endpoint POST /api/enrichment/request",
        "x-permission": "enrichment:request",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/rules": {
      "get": {
        "summary": "Endpoint GET /api/enrichment/rules",
        "x-permission": "enrichment:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/enrichment/rules",
        "x-permission": "enrichment:manage_rules",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "locations": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "target_industries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "min_lead_score": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "preferred_channel": {
                    "type": "string",
                    "enum": [
                      "all",
                      "telegram",
                      "whatsapp",
                      "email"
                    ],
                    "default": "all",
                    "description": "Canal preferente de prospección. Permite desviar prospección fría a Telegram ($0 costo) para proteger reputación de WhatsApp Meta."
                  },
                  "macro_sector": {
                    "type": "string",
                    "enum": [
                      "ALL",
                      "B2B_TECH",
                      "B2B_FINANCE",
                      "B2B_HEALTH",
                      "B2B_LOGISTICS",
                      "B2B_LEGAL",
                      "B2B_INDUSTRY",
                      "B2B_SERVICES"
                    ],
                    "default": "ALL",
                    "description": "Macro-sector económico B2B prioritario para filtrado y afinidad semántica."
                  },
                  "decision_level": {
                    "type": "string",
                    "enum": [
                      "ALL",
                      "C_LEVEL",
                      "VP_DIRECTOR",
                      "MANAGER",
                      "SPECIALIST"
                    ],
                    "default": "ALL",
                    "description": "Nivel jerárquico de toma de decisión objetivo en prospección B2B."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/rules/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/enrichment/rules/:id",
        "x-permission": "enrichment:manage_rules",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/rules/{id}/toggle": {
      "put": {
        "summary": "Endpoint PUT /api/enrichment/rules/:id/toggle",
        "x-permission": "enrichment:manage_rules",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/run-batch": {
      "post": {
        "summary": "Endpoint POST /api/enrichment/run-batch",
        "x-permission": "enrichment:trigger_batch",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/stats": {
      "get": {
        "summary": "Endpoint GET /api/enrichment/stats",
        "x-permission": "enrichment:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/enrichment/export-audit": {
      "post": {
        "summary": "Registra auditoría inmutable de exportación CSV de prospectos B2B (DLP)",
        "description": "Inserta un registro de trazabilidad en rbac_audit_logs para prevenir fuga de datos y cumplir normativas DLP.",
        "x-permission": "enrichment:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "count": {
                    "type": "integer",
                    "example": 25
                  },
                  "filter": {
                    "type": "string",
                    "example": "c_level"
                  },
                  "format": {
                    "type": "string",
                    "example": "csv"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Auditoría registrada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/funnels": {
      "post": {
        "summary": "Endpoint POST /api/funnels",
        "x-permission": "funnels:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Listar embudos de la marca",
        "description": "Retorna todos los embudos de conversión configurados para la marca activa.",
        "x-permission": "funnels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de embudos"
          }
        }
      }
    },
    "/api/funnels/{id}": {
      "put": {
        "summary": "Actualizar configuración y etapas de embudo",
        "description": "Actualiza metadatos, etapas personalizadas (stages JSONB) y reglas reactivas de auto-avance (auto_advance_rules).",
        "x-permission": "funnels:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID del embudo"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "stage": {
                    "type": "string"
                  },
                  "auto_advance_enabled": {
                    "type": "boolean"
                  },
                  "auto_advance_rules": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embudo actualizado exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere funnels:manage)"
          },
          "404": {
            "description": "Embudo no encontrado"
          }
        }
      },
      "delete": {
        "summary": "Eliminar embudo",
        "description": "Elimina un embudo de conversión verificando aislamiento multi-tenant por brand_id.",
        "x-permission": "funnels:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID del embudo"
          }
        ],
        "responses": {
          "200": {
            "description": "Embudo eliminado exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes o pertenencia a otra marca"
          },
          "404": {
            "description": "Embudo no encontrado"
          }
        }
      }
    },
    "/api/funnels/{funnelId}/contacts/{contactId}/advance": {
      "post": {
        "summary": "Endpoint POST /api/funnels/:funnelId/contacts/:contactId/advance",
        "x-permission": "funnels:auto_advance",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/funnels/{id}/contacts": {
      "get": {
        "summary": "Listado de contactos agrupados por etapa del embudo (Kanban)",
        "description": "Retorna los contactos asignados al embudo con su etapa actual y score de engagement para visualización interactiva.",
        "x-permission": "funnels:view",
        "x-is-public": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "UUID del embudo",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Contactos recuperados exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "stage": {
                            "type": "string"
                          },
                          "contact_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "phone": {
                            "type": "string"
                          },
                          "company_name": {
                            "type": "string"
                          },
                          "lead_score": {
                            "type": "integer"
                          },
                          "updated_at": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere funnels:view)"
          }
        }
      }
    },
    "/api/funnels/{id}/stats": {
      "get": {
        "summary": "Endpoint GET /api/funnels/:id/stats",
        "x-permission": "funnels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/funnels/campaign/{campaignId}": {
      "get": {
        "summary": "Endpoint GET /api/funnels/campaign/:campaignId",
        "x-permission": "funnels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Endpoint GET /api/health",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/health/deep": {
      "get": {
        "summary": "Endpoint GET /api/health/deep",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/health/live": {
      "get": {
        "summary": "Endpoint GET /api/health/live",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/health/ready": {
      "get": {
        "summary": "Endpoint GET /api/health/ready",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/admin/actions": {
      "get": {
        "summary": "Endpoint GET /api/inbox/admin/actions",
        "x-permission": "inbox:reassign",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/admin/reassign-unassigned": {
      "post": {
        "summary": "Endpoint POST /api/inbox/admin/reassign-unassigned",
        "x-permission": "inbox:reassign",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations": {
      "get": {
        "summary": "Endpoint GET /api/inbox/conversations",
        "x-permission": "inbox:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/assign": {
      "patch": {
        "summary": "Endpoint PATCH /api/inbox/conversations/:id/assign",
        "x-permission": "inbox:assign",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/bot": {
      "patch": {
        "summary": "Endpoint PATCH /api/inbox/conversations/:id/bot",
        "x-permission": "inbox:bot_toggle",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/close": {
      "patch": {
        "summary": "Endpoint PATCH /api/inbox/conversations/:id/close",
        "x-permission": "inbox:close",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/messages": {
      "get": {
        "summary": "Endpoint GET /api/inbox/conversations/:id/messages",
        "x-permission": "inbox:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/reply": {
      "post": {
        "summary": "Endpoint POST /api/inbox/conversations/:id/reply",
        "x-permission": "inbox:reply",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}/upload-media": {
      "post": {
        "summary": "Endpoint POST /api/inbox/conversations/:id/upload-media",
        "x-permission": "inbox:reply",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/stats/by-agent": {
      "get": {
        "summary": "Endpoint GET /api/inbox/stats/by-agent",
        "x-permission": "inbox:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/stats/overview": {
      "get": {
        "summary": "Endpoint GET /api/inbox/stats/overview",
        "x-permission": "inbox:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/inbox/stats/timeseries": {
      "get": {
        "summary": "Endpoint GET /api/inbox/stats/timeseries",
        "x-permission": "inbox:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/campaigns/trigger": {
      "post": {
        "summary": "Endpoint POST /api/m2m/campaigns/trigger",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/config/whatsapp": {
      "get": {
        "summary": "Endpoint GET /api/m2m/config/whatsapp",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/m2m/config/whatsapp",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/connectors/handshake": {
      "post": {
        "summary": "Endpoint POST /api/m2m/connectors/handshake",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/connectors/schema": {
      "get": {
        "summary": "Endpoint GET /api/m2m/connectors/schema",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/connectors/status": {
      "get": {
        "summary": "Endpoint GET /api/m2m/connectors/status",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/connectors/trigger-event": {
      "post": {
        "summary": "Endpoint POST /api/m2m/connectors/trigger-event",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/contacts/enrich": {
      "post": {
        "summary": "Endpoint POST /api/m2m/contacts/enrich",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/contacts/prospects": {
      "post": {
        "summary": "Endpoint POST /api/m2m/contacts/prospects",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/contacts/sync": {
      "post": {
        "summary": "Endpoint POST /api/m2m/contacts/sync",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/knowledge/sync": {
      "post": {
        "summary": "Autoalimentación de Base de Conocimiento IA (Push Inbound)",
        "description": "Sincroniza conocimiento de negocio, catálogo y directrices para agentes IA desde Apps Hermanas o CRM/ERP externos con invalidación atómica de caché en Redis.",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Sincronización aceptada y caché invalidada"
          },
          "400": {
            "description": "Datos de entrada inválidos o faltantes"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/emails/send": {
      "post": {
        "summary": "Endpoint POST /api/m2m/emails/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/health": {
      "get": {
        "summary": "Salud de integraciones M2M y cuotas de enriquecimiento",
        "description": "Verifica conectividad y estado operativo con microservicios satélite (DocVault24, Mande24), última sincronización y consumo de cuotas del tenant.",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Telemetría de salud y sincronización M2M recuperada exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "tenant": {
                      "type": "string",
                      "example": "Financiera Global"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "docvault24": {
                          "type": "string",
                          "enum": [
                            "online",
                            "degraded"
                          ],
                          "example": "online"
                        },
                        "mande24": {
                          "type": "string",
                          "enum": [
                            "online",
                            "degraded"
                          ],
                          "example": "online"
                        },
                        "last_sync": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "tenant": {
                          "type": "string"
                        },
                        "quota": {
                          "type": "object",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/metrics": {
      "get": {
        "summary": "Endpoint GET /api/m2m/metrics",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/outreach/send": {
      "post": {
        "summary": "Endpoint POST /api/m2m/outreach/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/social-accounts/{id}/session": {
      "get": {
        "summary": "Endpoint GET /api/m2m/social-accounts/:id/session",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/social/publish": {
      "post": {
        "summary": "Endpoint POST /api/m2m/social/publish",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/webhooks/dlq": {
      "get": {
        "summary": "Endpoint GET /api/m2m/webhooks/dlq",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/webhooks/dlq/{id}/replay": {
      "post": {
        "summary": "Endpoint POST /api/m2m/webhooks/dlq/:id/replay",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/m2m/whatsapp/send": {
      "post": {
        "summary": "Endpoint POST /api/m2m/whatsapp/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/{id}/status": {
      "patch": {
        "summary": "Endpoint PATCH /api/messaging/:id/status",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/assets": {
      "get": {
        "summary": "Endpoint GET /api/messaging/ai/assets",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/messaging/ai/assets",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/assets/{assetId}": {
      "delete": {
        "summary": "Endpoint DELETE /api/messaging/ai/assets/:assetId",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "patch": {
        "summary": "Endpoint PATCH /api/messaging/ai/assets/:assetId",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/assets/{assetId}/duplicate": {
      "post": {
        "summary": "Endpoint POST /api/messaging/ai/assets/:assetId/duplicate",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/bulk-history": {
      "delete": {
        "summary": "Endpoint DELETE /api/messaging/ai/bulk-history",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/messaging/ai/bulk-history",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/messaging/ai/bulk-history",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/bulk-history/stats": {
      "get": {
        "summary": "Endpoint GET /api/messaging/ai/bulk-history/stats",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/history": {
      "get": {
        "summary": "Endpoint GET /api/messaging/ai/history",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/image": {
      "post": {
        "summary": "Endpoint POST /api/messaging/ai/image",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/ai/proposal": {
      "post": {
        "summary": "Endpoint POST /api/messaging/ai/proposal",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/balancer/status": {
      "get": {
        "summary": "Endpoint GET /api/messaging/balancer/status",
        "x-permission": "channels:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/campaign/{campaignId}": {
      "get": {
        "summary": "Endpoint GET /api/messaging/campaign/:campaignId",
        "x-permission": "campaigns:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/preflight": {
      "post": {
        "summary": "Endpoint POST /api/messaging/preflight",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/preflight-exclusion-set": {
      "delete": {
        "summary": "Endpoint DELETE /api/messaging/preflight-exclusion-set",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/messaging/preflight-exclusion-set",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/messaging/preflight-exclusion-set",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/preflight-preference": {
      "get": {
        "summary": "Endpoint GET /api/messaging/preflight-preference",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/messaging/preflight-preference",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/schedule": {
      "post": {
        "summary": "Endpoint POST /api/messaging/schedule",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/send": {
      "post": {
        "summary": "Endpoint POST /api/messaging/send",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/messaging/quotas": {
      "get": {
        "summary": "Telemetría de cuotas y consumo de mensajería para la marca activa",
        "description": "Retorna el balance en tiempo real de mensajes enviados en el día (daily_limit), ciclo mensual (max_messages_month), estado de exención para APPs hermanas y telemetría de calentamiento progresivo anti-bloqueo (R-14, R-15).",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Cuotas de la marca obtenidas exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "brand_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "brand_name": {
                          "type": "string"
                        },
                        "brand_type": {
                          "type": "string",
                          "enum": [
                            "external_client",
                            "sister_app"
                          ]
                        },
                        "plan_key": {
                          "type": "string"
                        },
                        "tier": {
                          "type": "string"
                        },
                        "billing_status": {
                          "type": "string"
                        },
                        "sent_today": {
                          "type": "integer"
                        },
                        "daily_limit": {
                          "type": "integer"
                        },
                        "sent_month": {
                          "type": "integer"
                        },
                        "monthly_limit": {
                          "type": "integer"
                        },
                        "is_unlimited": {
                          "type": "boolean"
                        },
                        "enabled_channels": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "warmup": {
                          "type": "object",
                          "properties": {
                            "whatsapp_health": {
                              "type": "string"
                            },
                            "email_warmup_pct": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere messaging:send)"
          }
        }
      }
    },
    "/api/messaging/templates": {
      "get": {
        "summary": "Obtener catálogo de plantillas de mensajería multi-tenant de la marca",
        "description": "Retorna las plantillas de mensaje persistidas en base de datos para la marca activa.",
        "tags": [
          "Messaging"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de plantillas de mensajería",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array"
                    },
                    "templates": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Crear o actualizar plantilla de mensajería para la marca",
        "description": "Guarda una nueva plantilla o actualiza existente por nombre y categoría.",
        "tags": [
          "Messaging"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "message"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "channel": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Plantilla guardada exitosamente"
          }
        }
      }
    },
    "/api/messaging/templates/{id}": {
      "delete": {
        "summary": "Eliminar plantilla de mensajería",
        "description": "Elimina la plantilla especificada si pertenece a la marca del usuario.",
        "tags": [
          "Messaging"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plantilla eliminada exitosamente"
          }
        }
      }
    },
    "/api/messaging/upload": {
      "post": {
        "summary": "Endpoint POST /api/messaging/upload",
        "x-permission": "messaging:send",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/alerts": {
      "get": {
        "summary": "Endpoint GET /api/metrics/alerts",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/channels": {
      "get": {
        "summary": "Endpoint GET /api/metrics/channels",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/funnel/{campaignId}": {
      "get": {
        "summary": "Endpoint GET /api/metrics/funnel/:campaignId",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/kpis": {
      "get": {
        "summary": "KPIs Diarios Consolidados (Despachados, Entregados, Fallidos)",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "description": "Fecha en formato ISO YYYY-MM-DD",
            "required": false,
            "schema": {
              "type": "string",
              "example": "2026-10-08"
            }
          },
          {
            "name": "brand_id",
            "in": "query",
            "description": "UUID de la marca o 'all' para panorámica global",
            "required": false,
            "schema": {
              "type": "string",
              "example": "all"
            }
          }
        ],
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/marketing": {
      "get": {
        "summary": "Endpoint GET /api/metrics/marketing",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/push": {
      "post": {
        "summary": "Endpoint POST /api/metrics/push",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/segments": {
      "get": {
        "summary": "Endpoint GET /api/metrics/segments",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/trends": {
      "get": {
        "summary": "Endpoint GET /api/metrics/trends",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/omnichannel": {
      "get": {
        "summary": "Obtener métricas omnicanal comparativas de entrega y apertura",
        "description": "Calcula tasas de entrega (% Delivery Rate) y apertura (% Open Rate) para Telegram, Email, WhatsApp y Redes Sociales de la marca autorizada, además de estadísticas de escalamiento.",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Métricas omnicanal calculadas exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/metrics/escalation-savings": {
      "get": {
        "summary": "Telemetría de ahorro financiero por notificaciones en cascada",
        "description": "Calcula el ahorro estimado en USD y MXN y el volumen de eventos resueltos en capas económicas de costo cero (Push, Telegram) antes de escalar a Email o WhatsApp WABA.",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Métricas de ahorro financiero y resolución por capa calculadas exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/notifications/subscribe": {
      "post": {
        "summary": "Endpoint POST /api/notifications/subscribe",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/notifications/test": {
      "post": {
        "summary": "Endpoint POST /api/notifications/test",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/notifications/unsubscribe": {
      "post": {
        "summary": "Endpoint POST /api/notifications/unsubscribe",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/notifications/vapid-public-key": {
      "get": {
        "summary": "Endpoint GET /api/notifications/vapid-public-key",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/docvault24": {
      "get": {
        "summary": "Endpoint GET /api/platform/docvault24",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/docvault24",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/docvault24/diagnose": {
      "get": {
        "summary": "Endpoint GET /api/platform/docvault24/diagnose",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/docvault24/test": {
      "post": {
        "summary": "Endpoint POST /api/platform/docvault24/test",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/limits": {
      "get": {
        "summary": "Endpoint GET /api/platform/limits",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/limits",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/m2m/keys": {
      "get": {
        "summary": "Endpoint GET /api/platform/m2m/keys",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/m2m/keys",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/m2m/keys/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/platform/m2m/keys/:id",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/m2m/welcome-funnels": {
      "delete": {
        "summary": "Endpoint DELETE /api/platform/m2m/welcome-funnels",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "get": {
        "summary": "Endpoint GET /api/platform/m2m/welcome-funnels",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/m2m/welcome-funnels",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/mande24": {
      "get": {
        "summary": "Endpoint GET /api/platform/mande24",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/mande24",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/conta24": {
      "get": {
        "summary": "Obtener configuración de integración Conta24 para la marca activa",
        "description": "Retorna la configuración y estado de integración de webhooks fiscales de Conta24.",
        "x-permission": "settings:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración de Conta24 recuperada"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      },
      "post": {
        "summary": "Guardar configuración de Conta24",
        "description": "Actualiza la URL de webhook y credenciales secretas de la integración Conta24.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración guardada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/platform/conta24/test": {
      "post": {
        "summary": "Probar conexión webhook con Conta24",
        "description": "Emite un ping de prueba con firma HMAC para verificar conectividad con Conta24.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Prueba exitosa"
          }
        }
      }
    },
    "/api/platform/nomi24": {
      "get": {
        "summary": "Obtener configuración de integración Nomi24 para la marca activa",
        "description": "Retorna la configuración y estado de integración de alertas de nómina de Nomi24.",
        "x-permission": "settings:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración de Nomi24 recuperada"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      },
      "post": {
        "summary": "Guardar configuración de Nomi24",
        "description": "Actualiza la URL de webhook y credenciales de la integración Nomi24.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración guardada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/platform/nomi24/test": {
      "post": {
        "summary": "Probar conexión webhook con Nomi24",
        "description": "Emite un ping de prueba con firma HMAC para verificar conectividad con Nomi24.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Prueba exitosa"
          }
        }
      }
    },
    "/api/platform/raiz-digital": {
      "get": {
        "summary": "Obtener configuración de integración Raíz Digital para la marca activa",
        "description": "Retorna la configuración y estado de integración de captación de leads de Raíz Digital.",
        "x-permission": "settings:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración de Raíz Digital recuperada"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      },
      "post": {
        "summary": "Guardar configuración de Raíz Digital",
        "description": "Actualiza la URL de webhook y credenciales de la integración Raíz Digital.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración guardada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          }
        }
      }
    },
    "/api/platform/raiz-digital/test": {
      "post": {
        "summary": "Probar conexión webhook con Raíz Digital",
        "description": "Emite un ping de prueba con firma HMAC para verificar conectividad con Raíz Digital.",
        "x-permission": "settings:edit",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Prueba exitosa"
          }
        }
      }
    },
    "/api/platform/meta-lead-forms": {
      "get": {
        "summary": "Endpoint GET /api/platform/meta-lead-forms",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/meta-lead-forms",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/social-oauth": {
      "get": {
        "summary": "Endpoint GET /api/platform/social-oauth",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/social-oauth/{platform}": {
      "delete": {
        "summary": "Endpoint DELETE /api/platform/social-oauth/:platform",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/social-oauth/:platform",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/deliveries": {
      "get": {
        "summary": "Endpoint GET /api/platform/webhooks/deliveries",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/dlq": {
      "get": {
        "summary": "Endpoint GET /api/platform/webhooks/dlq",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/dlq/{id}/replay": {
      "post": {
        "summary": "Endpoint POST /api/platform/webhooks/dlq/:id/replay",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/outbound": {
      "get": {
        "summary": "Endpoint GET /api/platform/webhooks/outbound",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/platform/webhooks/outbound",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/outbound/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/platform/webhooks/outbound/:id",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/webhooks/test": {
      "post": {
        "summary": "Endpoint POST /api/platform/webhooks/test",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/escalation-rules": {
      "get": {
        "summary": "Consulta reglas de escalamiento multicanal en cascada",
        "description": "Obtiene las reglas configuradas de escalamiento en 4 capas (Email -> Telegram -> SMS -> WhatsApp) con timeouts y orden de canales.",
        "x-permission": "escalation_rules:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Reglas de escalamiento recuperadas"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Crea o actualiza reglas de escalamiento multicanal",
        "description": "Configura la secuencia de canales, tiempos de espera entre capas y condiciones de entrega/lectura.",
        "x-permission": "escalation_rules:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Regla guardada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/escalation-jobs": {
      "get": {
        "summary": "Telemetría de jobs de escalamiento multicanal",
        "description": "Supervisa el estado y cola de mensajes en proceso de escalamiento progresivo en BullMQ.",
        "x-permission": "escalation_rules:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de jobs de escalamiento recuperada"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/dispatch-escalation": {
      "post": {
        "summary": "Despacho de mensaje en cascada multicanal",
        "description": "Inicia la entrega progresiva en Capa 1 económica escalando automáticamente ante inactividad del destinatario.",
        "x-permission": "campaigns:create",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Despacho en cascada programado"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/platform/ecosystem/apps": {
      "get": {
        "summary": "Telemetría y modelos de servicio de apps del Ecosistema 24",
        "description": "Consola Superadmin: Lista microservicios hermanos (Mande24, DocVault24) y clientes SaaS/OAAS interconectados.",
        "x-permission": "platform:admin",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de aplicaciones y estado de salud"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/reports/excel": {
      "get": {
        "summary": "Endpoint GET /api/reports/excel",
        "x-permission": "reports:export",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/reports/pdf": {
      "get": {
        "summary": "Endpoint GET /api/reports/pdf",
        "x-permission": "reports:export",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts": {
      "get": {
        "summary": "Endpoint GET /api/social/accounts",
        "x-permission": "social:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/{idOrPlatform}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/accounts/:idOrPlatform",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/audience": {
      "get": {
        "summary": "Endpoint GET /api/social/accounts/audience",
        "x-permission": "social:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/audience/sync": {
      "post": {
        "summary": "Endpoint POST /api/social/accounts/audience/sync",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/audiences": {
      "get": {
        "summary": "Lista audiencias personalizadas de Meta Ads",
        "description": "Obtiene las audiencias personalizadas sincronizadas para la marca activa.",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de audiencias recuperada"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Crea una audiencia personalizada en Meta Ads",
        "description": "Crea una nueva Custom Audience en Meta Graph API v21.0 asociada a la marca.",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Audiencia creada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/audiences/{id}": {
      "delete": {
        "summary": "Elimina una audiencia personalizada",
        "description": "Elimina el registro de la audiencia personalizada para la marca activa.",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Audiencia eliminada"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/audiences/{id}/sync": {
      "post": {
        "summary": "Sincroniza contactos con Meta Custom Audience (SHA-256)",
        "description": "Normaliza teléfonos/emails de contactos con is_marketing_eligible = true, calcula hashes SHA-256 en memoria y los envía a Meta Graph API sin persistir PII sin cifrar.",
        "x-permission": "custom_audiences:sync",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sincronización completada exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups": {
      "get": {
        "summary": "Endpoint GET /api/social/accounts/groups",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/accounts/groups/:id",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups/{id}/brands": {
      "post": {
        "summary": "Endpoint POST /api/social/accounts/groups/:id/brands",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups/{id}/brands/{brandId}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/accounts/groups/:id/brands/:brandId",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups/register": {
      "post": {
        "summary": "Endpoint POST /api/social/accounts/groups/register",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands": {
      "get": {
        "summary": "Endpoint GET /api/social/brands",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/social/brands",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{brandId}/accounts": {
      "get": {
        "summary": "Endpoint GET /api/social/brands/:brandId/accounts",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/brands/:id",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Endpoint PUT /api/social/brands/:id",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{id}/api-keys": {
      "get": {
        "summary": "Endpoint GET /api/social/brands/:id/api-keys",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/social/brands/:id/api-keys",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{id}/api-keys/{key_id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/brands/:id/api-keys/:key_id",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{id}/stats": {
      "get": {
        "summary": "Endpoint GET /api/social/brands/:id/stats",
        "x-permission": "metrics:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/brands/{id}/dlp": {
      "get": {
        "summary": "Consulta la configuración y reglas del motor DLP de la marca",
        "x-permission": "brand_settings:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración DLP (modo y reglas) de la marca"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (brand_settings:manage)"
          }
        }
      },
      "put": {
        "summary": "Actualiza el modo DLP y las reglas de detección para la marca",
        "x-permission": "brand_settings:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Política DLP actualizada correctamente"
          },
          "400": {
            "description": "Parámetros inválidos"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (brand_settings:manage)"
          }
        }
      }
    },
    "/api/social/groups/{accountId}/calendar": {
      "get": {
        "summary": "Endpoint GET /api/social/groups/:accountId/calendar",
        "x-permission": "social:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/groups/pending": {
      "get": {
        "summary": "Endpoint GET /api/social/groups/pending",
        "x-permission": "social:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/groups/posts/{postId}/approve": {
      "post": {
        "summary": "Endpoint POST /api/social/groups/posts/:postId/approve",
        "x-permission": "social:publish",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/groups/posts/{postId}/reject": {
      "post": {
        "summary": "Endpoint POST /api/social/groups/posts/:postId/reject",
        "x-permission": "social:publish",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/logs": {
      "get": {
        "summary": "Endpoint GET /api/social/logs",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/meta/health": {
      "get": {
        "summary": "Endpoint GET /api/social/meta/health",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/metrics": {
      "get": {
        "summary": "Endpoint GET /api/social/metrics",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/oauth/{platform}/authorize": {
      "get": {
        "summary": "Endpoint GET /api/social/oauth/:platform/authorize",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/oauth/{platform}/callback": {
      "get": {
        "summary": "Endpoint GET /api/social/oauth/:platform/callback",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/posts": {
      "get": {
        "summary": "Endpoint GET /api/social/posts",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/social/posts",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/posts/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/social/posts/:id",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/posts/{id}/n8n-callback": {
      "post": {
        "summary": "Callback asíncrono desde n8n con firma HMAC SHA-256",
        "description": "Recibe confirmaciones de publicación de redes sociales procesadas en flujos de n8n, actualizando el estado del post a publicado o fallido.",
        "x-permission": "social:publish",
        "security": [
          {
            "webhookSignature": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Callback procesado"
          },
          "401": {
            "description": "Firma criptográfica inválida"
          }
        }
      }
    },
    "/api/team": {
      "get": {
        "summary": "Endpoint GET /api/team",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/team/{userId}": {
      "delete": {
        "summary": "Endpoint DELETE /api/team/:userId",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/team/{userId}/assigned-groups": {
      "get": {
        "summary": "Endpoint GET /api/team/:userId/assigned-groups",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "put": {
        "summary": "Endpoint PUT /api/team/:userId/assigned-groups",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/team/{userId}/role": {
      "put": {
        "summary": "Endpoint PUT /api/team/:userId/role",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/team/invite": {
      "post": {
        "summary": "Endpoint POST /api/team/invite",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/users": {
      "get": {
        "summary": "Endpoint GET /api/users",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/users",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/users/{id}": {
      "delete": {
        "summary": "Endpoint DELETE /api/users/:id",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/users/{id}/brands": {
      "get": {
        "summary": "Endpoint GET /api/users/:id/brands",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/users/:id/brands",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/users/{id}/brands/{brandId}": {
      "delete": {
        "summary": "Endpoint DELETE /api/users/:id/brands/:brandId",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/users/{id}/status": {
      "patch": {
        "summary": "Endpoint PATCH /api/users/:id/status",
        "x-permission": "${targetKey}",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/campaigns/trigger": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/campaigns/trigger",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/config/whatsapp": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/config/whatsapp",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/config/whatsapp",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/connectors/handshake": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/connectors/handshake",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/connectors/schema": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/connectors/schema",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/connectors/status": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/connectors/status",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/connectors/trigger-event": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/connectors/trigger-event",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/contacts/enrich": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/contacts/enrich",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/contacts/prospects": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/contacts/prospects",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/contacts/sync": {
      "post": {
        "summary": "Sincronización M2M de contactos hipersegmentados con firma HMAC",
        "description": "Permite a aplicaciones hermanas (DocVault24, Mande24, Conta24) y ERPs sincronizar contactos con deduplicación global, reutilización FinOps ($0 IA) y auto-enrolamiento en embudo (captacion).",
        "x-permission": "contacts:manage",
        "security": [
          {
            "m2mAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-M2M-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contacts"
                ],
                "properties": {
                  "contacts": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/HypersegmentedContactInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contactos sincronizados exitosamente con deduplicación y estado de reutilización IA",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "inserted": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "success": {
                            "type": "boolean"
                          },
                          "contact_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "deduplicated": {
                            "type": "boolean",
                            "description": "True si el contacto ya existía en el catálogo global"
                          },
                          "enrichment_reused": {
                            "type": "boolean",
                            "description": "True si se reutilizó el enriquecimiento de IA existente a costo $0"
                          },
                          "stage": {
                            "type": "string",
                            "description": "Etapa del embudo donde fue enrolado ('captacion')"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Firma HMAC inválida o timestamp expirado (>300s)"
          },
          "403": {
            "description": "Clave M2M sin permisos suficientes"
          }
        }
      }
    },
    "/api/v1/m2m/emails/send": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/emails/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/health": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/health",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/metrics": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/metrics",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/outreach/send": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/outreach/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/social-accounts/{id}/session": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/social-accounts/:id/session",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/social/publish": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/social/publish",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/webhooks/dlq": {
      "get": {
        "summary": "Endpoint GET /api/v1/m2m/webhooks/dlq",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/webhooks/dlq/{id}/replay": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/webhooks/dlq/:id/replay",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/m2m/whatsapp/send": {
      "post": {
        "summary": "Endpoint POST /api/v1/m2m/whatsapp/send",
        "x-permission": null,
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/v1/webhooks/mande24": {
      "post": {
        "summary": "Endpoint POST /api/v1/webhooks/mande24",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/webhooks/docvault24": {
      "post": {
        "summary": "Webhook de eventos de sincronización y almacenamiento DocVault24",
        "description": "Recibe eventos transaccionales, expiración de documentos y alertas de cuota emitidas por DocVault24. Valida esquema Zod estructurado (id, type, source, data) y firma criptográfica HMAC SHA-256.",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "type",
                  "data"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "evt_docvault_12345"
                  },
                  "type": {
                    "type": "string",
                    "example": "document.created"
                  },
                  "source": {
                    "type": "string",
                    "example": "docvault24"
                  },
                  "specversion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "document_id": {
                        "type": "string"
                      },
                      "brand_id": {
                        "type": "string"
                      },
                      "filename": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evento DocVault24 procesado o encolado exitosamente"
          },
          "400": {
            "description": "Payload inválido según validación de esquema Zod"
          },
          "401": {
            "description": "Firma HMAC inválida o ausente"
          }
        }
      }
    },
    "/api/webhooks/ecosystem/{appSlug}": {
      "post": {
        "summary": "Webhook de ingesta y sincronización del Ecosistema 24",
        "description": "Recibe contactos y eventos de sincronización desde apps hermanas (Mande24, DocVault24) y clientes SaaS/OAAS externos. Autenticación por cabecera X-Signature-SHA256 (HMAC). Aplica deduplicación y preservación 1st-party (R-33).",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Contacto o evento procesado exitosamente"
          },
          "400": {
            "description": "Cuerpo de solicitud inválido o campos faltantes"
          },
          "401": {
            "description": "Firma HMAC inválida o no provista"
          }
        }
      }
    },
    "/api/webhooks/whatsapp": {
      "get": {
        "summary": "Endpoint GET /api/webhooks/whatsapp",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      },
      "post": {
        "summary": "Endpoint POST /api/webhooks/whatsapp",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/developer/api/schema": {
      "get": {
        "summary": "Endpoint GET /developer/api/schema",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/developer/api/simulate-hmac": {
      "post": {
        "summary": "Endpoint POST /developer/api/simulate-hmac",
        "x-permission": null,
        "x-is-public": true,
        "security": [],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          }
        }
      }
    },
    "/api/social/accounts/groups/{id}/reset-health": {
      "post": {
        "summary": "Reinicio de salud y contador de errores de grupo FB",
        "description": "Restablece error_count a 0, marca is_active en TRUE y actualiza timestamp de verificación para recuperar el grupo tras fallos de publicación.",
        "x-permission": "social:manage_groups",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID del registro de cuenta social (grupo)"
          }
        ],
        "responses": {
          "200": {
            "description": "Salud del grupo reiniciada exitosamente"
          },
          "400": {
            "description": "ID de grupo inválido"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          },
          "404": {
            "description": "Grupo no encontrado"
          },
          "500": {
            "description": "Error interno del servidor"
          }
        }
      }
    },
    "/api/social/brands/{id}/dlp/audit-logs": {
      "get": {
        "summary": "Consulta bitácora de incidentes DLP por marca",
        "description": "Retorna los últimos incidentes de fuga de datos sensibles detectados (tarjetas, CLABE, RFC, credenciales) con datos enmascarados de forma inmutable.",
        "x-permission": "brand_settings:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID de la marca"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Límite de registros a recuperar"
          }
        ],
        "responses": {
          "200": {
            "description": "Bitácora DLP recuperada exitosamente"
          },
          "400": {
            "description": "UUID de marca inválido"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          },
          "500": {
            "description": "Error interno del servidor"
          }
        }
      }
    },
    "/api/config/ai/test-connection": {
      "post": {
        "summary": "Prueba Dry-Run de conexión y latencia hacia proveedor IA",
        "description": "Envía una solicitud ultraligera de 1 token para validar credenciales y medir tiempo de respuesta round-trip (latencia en ms).",
        "x-permission": "ai:configure",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "example": "openrouter"
                  },
                  "brand_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conexión probada exitosamente con latencia medida"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (RBAC)"
          },
          "502": {
            "description": "Proveedor IA inalcanzable o error de credenciales"
          }
        }
      }
    },
    "/api/billing/account": {
      "get": {
        "summary": "Obtener estado de cuenta y suscripción de la marca activa",
        "description": "Retorna plan contratado, estatus de cobro (active, grace_period, past_due, suspended, exempt), saldo pendiente, fecha de vencimiento y días de gracia restantes.",
        "x-permission": "billing:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "UUID de la marca activa (multi-tenant)"
          }
        ],
        "responses": {
          "200": {
            "description": "Estado de cuenta retornado exitosamente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere billing:view)"
          }
        }
      }
    },
    "/api/billing/bank-details": {
      "get": {
        "summary": "Obtener cuentas bancarias BBVA oficiales (Nacional SPEI y LATAM SWIFT)",
        "description": "Retorna datos bancarios para transferencia: BBVA México (CLABE 18 dígitos, cuenta MXN) y BBVA LATAM Internacional (SWIFT BCMRMXMM, cuenta USD).",
        "x-permission": "billing:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Cuentas bancarias BBVA retornadas"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/billing/receipts": {
      "post": {
        "summary": "Subir comprobante de pago bancario BBVA (Cliente externo)",
        "description": "Permite a la marca activa registrar un comprobante de transferencia (PDF, JPG, PNG) para acreditación manual por el administrador.",
        "x-permission": "billing:upload_proof",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "receipt": {
                    "type": "string",
                    "format": "binary"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "MXN",
                      "USD"
                    ]
                  },
                  "reference": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  }
                },
                "required": [
                  "receipt",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comprobante registrado en estado pendiente"
          },
          "400": {
            "description": "Archivo o datos inválidos"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere billing:upload_proof)"
          }
        }
      }
    },
    "/api/billing/payments": {
      "get": {
        "summary": "Listar historial de pagos y comprobantes de la marca activa",
        "description": "Retorna historial con estado: pending, approved, rejected, con folios y URLs seguras de comprobantes.",
        "x-permission": "billing:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Historial de pagos retornado"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/billing/invoices": {
      "get": {
        "summary": "Listar facturas fiscales CFDI 4.0 emitidas para la marca activa",
        "description": "Consulta CFDIs asociados a la marca, con desglose de importes, UUID fiscal y enlaces de descarga XML y PDF.",
        "x-permission": "billing:view",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Listado de facturas fiscales"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/billing/invoices/{id}/download-pdf": {
      "get": {
        "summary": "Descargar representación impresa PDF de factura CFDI 4.0",
        "description": "Descarga el PDF generado dinámicamente o respaldado en DocVault24 con QR SAT y cadena original.",
        "x-permission": "invoices:download",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo PDF de la factura fiscal",
            "content": {
              "application/pdf": {}
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere invoices:download)"
          },
          "404": {
            "description": "Factura o PDF no encontrado"
          }
        }
      }
    },
    "/api/billing/invoices/{id}/download-xml": {
      "get": {
        "summary": "Descargar archivo XML sellado de factura CFDI 4.0",
        "description": "Descarga el XML fiscal sellado ante el SAT respaldado en almacenamiento seguro / DocVault24.",
        "x-permission": "invoices:download",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo XML de la factura fiscal",
            "content": {
              "application/xml": {}
            }
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere invoices:download)"
          },
          "404": {
            "description": "Factura o XML no encontrado"
          }
        }
      }
    },
    "/api/platform/billing/payments/pending": {
      "get": {
        "summary": "Listar comprobantes de pago pendientes de acreditación (Superadmin)",
        "description": "Consola de Superadmin para revisar comprobantes bancarios BBVA enviados por clientes externos.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de pagos pendientes de acreditación"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes (requiere platform:billing_manage)"
          }
        }
      }
    },
    "/api/platform/billing/payments/{id}/accredit": {
      "post": {
        "summary": "Acreditar pago manual BBVA y reactivar/extender vigencia del cliente",
        "description": "Aprueba el pago, extiende vigencia de la suscripción, reactiva marcas suspendidas o en gracia y notifica al cliente.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bank_auth_code": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pago acreditado y marca reactivada con éxito"
          },
          "400": {
            "description": "Datos o estado inconsistente"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/platform/billing/payments/{id}/reject": {
      "post": {
        "summary": "Rechazar comprobante de pago BBVA inválido con motivo",
        "description": "Marca el comprobante como rechazado indicando motivo de rechazo visible para el cliente.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "rejection_reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "rejection_reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comprobante rechazado correctamente"
          },
          "400": {
            "description": "Motivo de rechazo requerido"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/platform/billing/payments/upload-for-client": {
      "post": {
        "summary": "Cargar comprobante y acreditar pago directamente a nombre de un cliente",
        "description": "Permite al Superadmin registrar el comprobante recibido por canal alterno y acreditar la suscripción en un solo paso.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "brand_id": {
                    "type": "string"
                  },
                  "receipt": {
                    "type": "string",
                    "format": "binary"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "MXN",
                      "USD"
                    ]
                  },
                  "reference": {
                    "type": "string"
                  },
                  "bank_auth_code": {
                    "type": "string"
                  },
                  "auto_accredit": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "brand_id",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pago registrado y procesado exitosamente"
          },
          "400": {
            "description": "Parámetros inválidos"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/platform/billing/invoices/upload-xml": {
      "post": {
        "summary": "Cargar XML fiscal CFDI 4.0 para cliente externo y generar PDF",
        "description": "Superadmin carga XML emitido; el sistema extrae UUID, totales, emisor/receptor, genera PDF fiscal con QR SAT y sincroniza con DocVault24.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "brand_id": {
                    "type": "string"
                  },
                  "xml_file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "notes": {
                    "type": "string"
                  }
                },
                "required": [
                  "brand_id",
                  "xml_file"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Factura procesada, PDF generado y sincronizado con DocVault24"
          },
          "400": {
            "description": "XML inválido o no timbrado"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/platform/billing/invoices": {
      "get": {
        "summary": "Listar todas las facturas fiscales del sistema (Superadmin)",
        "description": "Auditoría global de facturas emitidas para clientes externos, estado de sincronización con DocVault24 y enlaces de descarga.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Listado global de facturas"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/platform/billing/config": {
      "get": {
        "summary": "Consultar configuración financiera BBVA y catálogo de precios de la plataforma",
        "description": "Retorna datos bancarios para transferencias nacionales/LATAM y la matriz de precios SaaS/OAAS.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuración financiera y catálogo actual"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      },
      "put": {
        "summary": "Actualizar cuentas bancarias BBVA, tipos de cambio y catálogo de precios dual SaaS/OAAS",
        "description": "Guarda cambios en vivo para cuentas bancarias (SPEI, SWIFT LATAM) y matriz de tarifas SaaS/OAAS.",
        "x-permission": "platform:billing_manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bbva_account": {
                    "type": "object"
                  },
                  "pricing_catalog": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuración actualizada exitosamente"
          },
          "400": {
            "description": "Estructura inválida"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      }
    },
    "/api/templates/whatsapp": {
      "get": {
        "summary": "Listar plantillas oficiales de WhatsApp Meta HSM del tenant",
        "description": "Recupera todas las plantillas HSM de WhatsApp registradas para la marca activa, con estados de aprobación Meta Graph API v21.0.",
        "x-permission": "whatsapp_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "MARKETING",
                "UTILITY",
                "AUTHENTICATION"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de plantillas WhatsApp HSM"
          },
          "401": {
            "description": "No autenticado"
          },
          "403": {
            "description": "Privilegios insuficientes"
          }
        }
      },
      "post": {
        "summary": "Crear borrador de plantilla de WhatsApp HSM",
        "description": "Registra una plantilla local para la marca activa con componentes HEADER, BODY, FOOTER y BUTTONS.",
        "x-permission": "whatsapp_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhatsAppTemplate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plantilla creada"
          },
          "400": {
            "description": "Datos inválidos"
          }
        }
      }
    },
    "/api/templates/whatsapp/{id}/submit-approval": {
      "post": {
        "summary": "Enviar plantilla WhatsApp HSM a aprobación oficial en Meta Graph API v21.0",
        "description": "Valida variables dinámicas y despacha la plantilla a los servidores de Meta para su revisión y aprobación.",
        "x-permission": "whatsapp_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enviada a Meta exitosamente"
          },
          "400": {
            "description": "Error de validación o rechazo por Meta"
          }
        }
      }
    },
    "/api/templates/whatsapp/sync": {
      "post": {
        "summary": "Sincronizar estados de plantillas HSM con Meta Graph API",
        "description": "Consulta la API de Meta y actualiza los estados locales (APPROVED, REJECTED, PAUSED) de todas las plantillas del WABA.",
        "x-permission": "whatsapp_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sincronización completada"
          }
        }
      }
    },
    "/api/templates/whatsapp/{id}": {
      "delete": {
        "summary": "Eliminar plantilla de WhatsApp HSM",
        "description": "Elimina la plantilla tanto localmente como en el WABA oficial de Meta si ya estaba registrada.",
        "x-permission": "whatsapp_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plantilla eliminada"
          }
        }
      }
    },
    "/api/templates/telegram": {
      "get": {
        "summary": "Listar plantillas de Telegram Bot con teclados inline",
        "description": "Retorna las plantillas de Telegram para la marca activa, con botones URL, callback y variables dinámicas.",
        "x-permission": "telegram_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de plantillas Telegram"
          }
        }
      },
      "post": {
        "summary": "Crear o actualizar plantilla de Telegram Bot",
        "description": "Registra una plantilla interactiva con parse_mode HTML/Markdown y botones inline.",
        "x-permission": "telegram_templates:manage",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TelegramTemplate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plantilla Telegram creada exitosamente"
          }
        }
      }
    },
    "/api/social/metrics/sync": {
      "post": {
        "summary": "Sincronización bajo demanda de métricas sociales",
        "description": "Fuerza la sincronización de KPIs de interacción, alcance y seguidores desde Meta Graph API y LinkedIn.",
        "x-permission": "social:view",
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Métricas sincronizadas"
          }
        }
      }
    },
    "/api/funnels/ai/design": {
      "post": {
        "summary": "Diseñar embudo con Copiloto IA (OpenRouter)",
        "description": "Genera una arquitectura de embudo completa (etapas, disparadores reactivos y plantillas) mediante el agente de IA.",
        "x-permission": "funnels:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "business_goal"
                ],
                "properties": {
                  "business_goal": {
                    "type": "string"
                  },
                  "target_audience": {
                    "type": "string"
                  },
                  "channel_preferences": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estructura de embudo generada"
          }
        }
      }
    },
    "/api/whatsapp-templates/sync-meta": {
      "post": {
        "summary": "Sincronizar plantillas oficiales desde Meta Graph API",
        "description": "Descarga y actualiza el estado de aprobación de las plantillas WABA registradas en Meta Business Manager.",
        "x-permission": "email_templates:manage",
        "x-is-public": false,
        "security": [
          {
            "cookieAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sincronización completada"
          }
        }
      }
    },
    "/api/v1/emails/send": {
      "post": {
        "summary": "Envío transaccional M2M de emails (DocVault24 / Apps Hermanas)",
        "description": "Endpoint compatible con DocVault24 para el despacho de correos transaccionales con firma HMAC SHA-256.",
        "x-is-public": true,
        "security": [
          {
            "m2mHmacAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Email encolado o enviado"
          }
        }
      }
    },
    "/api/v1/webhooks/docvault24": {
      "post": {
        "summary": "Ingesta de webhooks y eventos CloudEvents desde DocVault24",
        "description": "Recibe eventos CloudEvents 1.0 (document.created, invoice.issued, cascade.acknowledged) validados con HMAC.",
        "x-is-public": true,
        "security": [
          {
            "m2mHmacAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Evento procesado"
          }
        }
      }
    },
    "/api/m2m/notifications/dispatch": {
      "post": {
        "tags": [
          "M2M & Ecosystem Escalation"
        ],
        "summary": "Despacho M2M de notificaciones con cascada inteligente en 4 capas (Push, Telegram, SES, WhatsApp)",
        "description": "Punto de entrada M2M canónico para Apps Hermanas (Mande24, DocVault24, Conta24, Nomi24, Raíz-Digital) y CRM/ERP externos para disparar la cascada inteligente de optimización de costos con SLAs por severidad (security_auth, service_alert, payment_reminder, marketing_promo) y cancelación reactiva Closed-Loop en O(1).",
        "x-permission": null,
        "x-is-public": false,
        "parameters": [
          {
            "name": "X-Brand-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Identificador de la marca/tenant en el contexto de multi-tenancy (Regla 13)"
          },
          {
            "name": "X-Api-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "API Key de integración M2M (sk_live_...)"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          },
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recipient",
                  "message"
                ],
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "service_alert",
                    "description": "Tipo de severidad: security_auth, service_alert, payment_reminder, marketing_promo"
                  },
                  "recipient": {
                    "type": "object",
                    "description": "Datos del destinatario multicanal",
                    "properties": {
                      "phone": {
                        "type": "string",
                        "example": "+525512345678"
                      },
                      "email": {
                        "type": "string",
                        "example": "cliente@empresa.com"
                      },
                      "telegram_id": {
                        "type": "string",
                        "example": "@usuario_tg"
                      },
                      "name": {
                        "type": "string",
                        "example": "Juan Pérez"
                      }
                    }
                  },
                  "message": {
                    "type": "object",
                    "required": [
                      "title"
                    ],
                    "properties": {
                      "title": {
                        "type": "string",
                        "example": "Actualización de Orden #4521"
                      },
                      "text": {
                        "type": "string",
                        "example": "Tu pedido va en camino a tu domicilio."
                      },
                      "body": {
                        "type": "string",
                        "example": "Tu pedido va en camino a tu domicilio."
                      },
                      "url": {
                        "type": "string",
                        "example": "https://mande24.online/tracking/4521"
                      },
                      "media_url": {
                        "type": "string",
                        "example": "https://storage.docvault24.online/public/guia.pdf"
                      }
                    }
                  },
                  "timeout_minutes": {
                    "type": "integer",
                    "example": 5,
                    "description": "Timeout opcional personalizado para la primera capa antes de escalar"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Notificación encolada exitosamente en la cascada inteligente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Notificación encolada en cascada inteligente de optimización de costos."
                    },
                    "job_id": {
                      "type": "string",
                      "example": "esc_job_1730000000_abc"
                    },
                    "initial_channel": {
                      "type": "string",
                      "example": "push"
                    },
                    "next_escalation_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status": {
                      "type": "string",
                      "example": "queued"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetros inválidos o destinatario sin canales válidos"
          },
          "401": {
            "description": "No autenticado / API Key inválida"
          },
          "500": {
            "description": "Error interno del servidor procesando escalamiento"
          }
        }
      }
    },
    "/api/inbox/conversations/{id}": {
      "get": {
        "summary": "Obtener conversación por ID con validación multi-tenant",
        "x-permission": "inbox:view",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detalle de la conversación"
          }
        }
      }
    },
    "/api/billing/fiscal-profile": {
      "get": {
        "summary": "Consultar perfil fiscal de la marca (CFDI 4.0)",
        "x-permission": "billing:view",
        "responses": {
          "200": {
            "description": "Perfil fiscal registrado"
          }
        }
      },
      "put": {
        "summary": "Actualizar perfil fiscal de la marca (CFDI 4.0)",
        "x-permission": "billing:manage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Perfil fiscal guardado"
          }
        }
      }
    },
    "/api/billing/payments/{paymentId}/request-invoice": {
      "post": {
        "summary": "Solicitar factura CFDI 4.0 para un pago acreditado",
        "x-permission": "billing:manage",
        "parameters": [
          {
            "name": "paymentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Solicitud registrada"
          }
        }
      }
    },
    "/api/company/public/qr": {
      "get": {
        "tags": [
          "Company",
          "Public Tools"
        ],
        "summary": "Generador Nativo de Códigos QR Vectoriales y Rasterizados",
        "description": "Genera códigos QR de forma nativa sin intermediarios externos para PWA y marca blanca.",
        "parameters": [
          {
            "name": "text",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Texto o URL que codificará el código QR."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "svg",
                "png"
              ],
              "default": "svg"
            },
            "description": "Formato de salida del QR."
          },
          {
            "name": "width",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 256
            },
            "description": "Ancho en píxeles del QR generado."
          }
        ],
        "responses": {
          "200": {
            "description": "Código QR generado exitosamente con cabeceras de caché por 24 horas.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Parámetro text ausente o inválido."
          }
        }
      }
    },
    "/api/billing/bbva/webhook-reconciliation": {
      "post": {
        "tags": [
          "Billing",
          "BBVA Bancomer",
          "n8n"
        ],
        "summary": "Webhook de Conciliación Bancaria Automatizada BBVA Bancomer",
        "description": "Recibe notificaciones de depósitos detectados por n8n en el correo corporativo BBVA, realizando la conciliación de 3 vías con tolerancia de  peso y suspensión ante déficit > 30%.",
        "parameters": [
          {
            "name": "x-bbva-webhook-secret",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Secreto compartido para autenticar al worker n8n."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation_number",
                  "amount"
                ],
                "properties": {
                  "operation_number": {
                    "type": "string"
                  },
                  "tracking_key": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "default": "MXN"
                  },
                  "operation_date": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "reference": {
                    "type": "string"
                  },
                  "sender_account": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Movimiento conciliado o registrado exitosamente."
          },
          "401": {
            "description": "Secreto de webhook inválido o ausente."
          },
          "422": {
            "description": "Payload incompleto o inválido."
          }
        }
      }
    },
    "/api/billing/events": {
      "get": {
        "tags": [
          "Billing",
          "Realtime"
        ],
        "summary": "Canal Server-Sent Events (SSE) para Actualizaciones de Cobranza",
        "description": "Emisión reactiva de eventos de conciliación y cambios en facturas en tiempo real sin polling ciego.",
        "parameters": [
          {
            "name": "brand_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Identificador de la marca/tenant."
          }
        ],
        "responses": {
          "200": {
            "description": "Stream continuo SSE (text/event-stream)",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WhatsAppTemplate": {
        "type": "object",
        "required": [
          "name",
          "language",
          "category",
          "components"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "brand_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "aviso_promocional_q2"
          },
          "language": {
            "type": "string",
            "example": "es_MX"
          },
          "category": {
            "type": "string",
            "enum": [
              "MARKETING",
              "UTILITY",
              "AUTHENTICATION"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PENDING",
              "APPROVED",
              "REJECTED",
              "PAUSED"
            ]
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WhatsAppTemplateComponent"
            }
          }
        }
      },
      "WhatsAppTemplateComponent": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "HEADER",
              "BODY",
              "FOOTER",
              "BUTTONS"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "TEXT",
              "IMAGE",
              "DOCUMENT",
              "VIDEO"
            ]
          },
          "text": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "TelegramTemplate": {
        "type": "object",
        "required": [
          "name",
          "text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "brand_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "alerta_servicio_inmediato"
          },
          "text": {
            "type": "string",
            "example": "Hola <b>{{nombre}}</b>, tu entrega está en camino."
          },
          "parse_mode": {
            "type": "string",
            "enum": [
              "HTML",
              "MarkdownV2"
            ],
            "default": "HTML"
          },
          "inline_keyboard": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/InlineKeyboardButton"
              }
            }
          }
        }
      },
      "InlineKeyboardButton": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "example": "Ver Estado"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "callback_data": {
            "type": "string"
          }
        }
      },
      "HypersegmentedContactInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Ing. Sofía Morales"
          },
          "phone": {
            "type": "string",
            "example": "+525598765432"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "sofia@logistica.mx"
          },
          "company_name": {
            "type": "string",
            "example": "Distribuidora Bajío SA de CV"
          },
          "macro_sector": {
            "type": "string",
            "example": "Transporte y Logística"
          },
          "sub_industry": {
            "type": "string",
            "example": "Almacenaje y Carga Refrigerada"
          },
          "company_size": {
            "type": "string",
            "example": "51-200"
          },
          "annual_revenue_bracket": {
            "type": "string",
            "example": "50M - 200M MXN"
          },
          "decision_maker_level": {
            "type": "string",
            "example": "Director"
          },
          "functional_area": {
            "type": "string",
            "example": "Operaciones y Cadena de Suministro"
          },
          "buyer_persona": {
            "type": "string",
            "example": "Director de Operaciones"
          },
          "metro_area": {
            "type": "string",
            "example": "Zona Metropolitana de Guadalajara"
          },
          "municipality": {
            "type": "string",
            "example": "Zapopan"
          }
        }
      }
    },
    "securitySchemes": {
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "seg_token"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "m2mAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-M2M-Key"
      },
      "webhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature"
      }
    }
  },
  "x-webhooks-catalog": {
    "version": "2.1.0",
    "total_events": 59,
    "security": {
      "signature_header": "X-Segmenta24-Signature",
      "timestamp_header": "X-Segmenta24-Timestamp",
      "brand_header": "X-Brand-Id",
      "algorithm": "HMAC-SHA256",
      "replay_window_seconds": 300
    },
    "events": [
      {
        "name": "whatsapp.inbound",
        "category": "messaging_core",
        "description": "Mensaje entrante de WhatsApp recibido en tiempo real"
      },
      {
        "name": "whatsapp.status",
        "category": "messaging_core",
        "description": "Cambio de estado de mensaje WhatsApp (sent, delivered, read, failed)"
      },
      {
        "name": "telegram.inbound",
        "category": "messaging_core",
        "description": "Mensaje entrante recibido vía Telegram Bot o cuenta MTProto"
      },
      {
        "name": "email.delivered",
        "category": "messaging_core",
        "description": "Correo electrónico entregado satisfactoriamente por AWS SES"
      },
      {
        "name": "email.bounced",
        "category": "messaging_core",
        "description": "Rebote de correo (Hard/Soft bounce registrado en lista negra)"
      },
      {
        "name": "email.opened",
        "category": "messaging_core",
        "description": "Apertura de correo electrónico confirmada por pixel rastreador"
      },
      {
        "name": "email.clicked",
        "category": "messaging_core",
        "description": "Clic en enlace rastreado dentro del cuerpo del correo"
      },
      {
        "name": "chat.message_received",
        "category": "messaging_core",
        "description": "Mensaje entrante recibido en la bandeja unificada omnicanal"
      },
      {
        "name": "chat.session_closed",
        "category": "messaging_core",
        "description": "Conversación o ticket cerrado por agente o bot IA"
      },
      {
        "name": "campaign.completed",
        "category": "messaging_core",
        "description": "Campaña masiva de envíos finalizada con reporte de entrega"
      },
      {
        "name": "notification.escalated",
        "category": "escalation",
        "description": "Notificación escalada a la siguiente capa por timeout o fallo en canal previo"
      },
      {
        "name": "cascade.acknowledged",
        "category": "escalation",
        "description": "Confirmación Closed-Loop de entrega o interacción que detiene la cascada"
      },
      {
        "name": "escalation.triggered",
        "category": "escalation",
        "description": "Disparo inicial de escalamiento multinivel para notificación"
      },
      {
        "name": "escalation.resolved",
        "category": "escalation",
        "description": "Notificación resuelta en capa económica (Push, Telegram o Email)"
      },
      {
        "name": "escalation.layer_failed",
        "category": "escalation",
        "description": "Fallo de entrega en una capa (provoca avance inmediato a la siguiente)"
      },
      {
        "name": "contact.created",
        "category": "data_quality",
        "description": "Nuevo contacto registrado en la agenda del tenant o catálogo global"
      },
      {
        "name": "contact.updated",
        "category": "data_quality",
        "description": "Actualización de datos generales o fiscales del contacto"
      },
      {
        "name": "contact.enriched",
        "category": "data_quality",
        "description": "Contacto enriquecido e hipersegmentado exitosamente por IA"
      },
      {
        "name": "contact.invalidated",
        "category": "data_quality",
        "description": "Contacto o canal marcado como inválido tras falla de verificación"
      },
      {
        "name": "contact.opt_out",
        "category": "data_quality",
        "description": "Baja voluntaria o desuscripción registrada"
      },
      {
        "name": "lead.quality_rejected",
        "category": "data_quality",
        "description": "Contacto rechazado por Quality Gate sintáctico o enriquecimiento insuficiente"
      },
      {
        "name": "docvault.document_verified",
        "category": "docvault24",
        "description": "Documento o expediente verificado y validado con hash SHA-256"
      },
      {
        "name": "docvault.kyc_approved",
        "category": "docvault24",
        "description": "Expediente KYC e identidad formalmente aprobado"
      },
      {
        "name": "docvault.kyc_rejected",
        "category": "docvault24",
        "description": "Expediente KYC rechazado por inconsistencia documental"
      },
      {
        "name": "docvault.cfdi.issued",
        "category": "docvault24",
        "description": "Emisión, timbrado y custodia de comprobante fiscal CFDI 4.0 SAT"
      },
      {
        "name": "docvault.csd.expiring",
        "category": "docvault24",
        "description": "Certificado de Sello Digital (CSD) próximo a expirar (30 días)"
      },
      {
        "name": "docvault.storage_limit_warning",
        "category": "docvault24",
        "description": "Advertencia de consumo próximo al límite de almacenamiento seguro"
      },
      {
        "name": "docvault.file_uploaded",
        "category": "docvault24",
        "description": "Archivo o contrato multimedia cargado al DAM/DMS"
      },
      {
        "name": "mande.order_assigned",
        "category": "mande24",
        "description": "Orden logística asignada a repartidor de última milla"
      },
      {
        "name": "mande.delivery_completed",
        "category": "mande24",
        "description": "Envío o reparto entregado satisfactoriamente con firma de acuse"
      },
      {
        "name": "mande.driver_arrived",
        "category": "mande24",
        "description": "Repartidor arribó al punto de recolección o entrega"
      },
      {
        "name": "mande.order.created",
        "category": "mande24",
        "description": "Nueva orden de servicio o reparto generada en el sistema"
      },
      {
        "name": "mande.status_changed",
        "category": "mande24",
        "description": "Cambio de estado general en el despacho de pedido"
      },
      {
        "name": "conta.invoice_generated",
        "category": "conta24",
        "description": "Factura o póliza contable emitida en el sistema"
      },
      {
        "name": "conta.payment_received",
        "category": "conta24",
        "description": "Pago o transferencia SPEI identificada y conciliada"
      },
      {
        "name": "conta.payment_overdue",
        "category": "conta24",
        "description": "Alerta de cobro vencido o pago retrasado"
      },
      {
        "name": "conta.spei.reconciled",
        "category": "conta24",
        "description": "Conciliación bancaria SPEI BBVA exitosa"
      },
      {
        "name": "conta.tax.obligation_due",
        "category": "conta24",
        "description": "Recordatorio de vencimiento de obligación fiscal o impuestos SAT"
      },
      {
        "name": "conta.sat_alert",
        "category": "conta24",
        "description": "Notificación o requerimiento emitido por el Buzón Tributario SAT"
      },
      {
        "name": "conta.cfdi_stamped",
        "category": "conta24",
        "description": "Comprobante fiscal sellado y timbrado ante PAC autorizado"
      },
      {
        "name": "nomi.payroll_dispersed",
        "category": "nomi24",
        "description": "Dispersión masiva de nómina bancaria completada"
      },
      {
        "name": "nomi.receipt_signed",
        "category": "nomi24",
        "description": "Recibo de nómina firmado digitalmente por el empleado"
      },
      {
        "name": "nomi.payslip.stamped",
        "category": "nomi24",
        "description": "Recibo de sueldo timbrado ante el SAT"
      },
      {
        "name": "nomi.contract_expiring",
        "category": "nomi24",
        "description": "Alerta de contrato temporal próximo a vencer (15 días)"
      },
      {
        "name": "nomi.employee_onboarded",
        "category": "nomi24",
        "description": "Nuevo colaborador dado de alta en nómina e IMSS"
      },
      {
        "name": "raiz.lead_generated",
        "category": "raiz_digital",
        "description": "Prospecto capturado en sitio web o landing page de la marca"
      },
      {
        "name": "raiz.lead.qualified",
        "category": "raiz_digital",
        "description": "Prospecto calificado con alta intención de compra por IA"
      },
      {
        "name": "raiz.quote_requested",
        "category": "raiz_digital",
        "description": "Solicitud formal de cotización enviada por el visitante"
      },
      {
        "name": "raiz.domain_activated",
        "category": "raiz_digital",
        "description": "Dominio web y certificados SSL activados y en línea"
      },
      {
        "name": "funnel.stage_advanced",
        "category": "raiz_digital",
        "description": "Avance de etapa en el embudo comercial automatizado"
      },
      {
        "name": "subscription.created",
        "category": "saas_lifecycle",
        "description": "Nueva suscripción o plan SaaS aprovisionado para el tenant"
      },
      {
        "name": "subscription.renewed",
        "category": "saas_lifecycle",
        "description": "Renovación periódica de suscripción comercial acreditada"
      },
      {
        "name": "subscription.past_due",
        "category": "saas_lifecycle",
        "description": "Suscripción en periodo de gracia por intento de cobro fallido"
      },
      {
        "name": "subscription.cancelled",
        "category": "saas_lifecycle",
        "description": "Suscripción cancelada o dada de baja"
      },
      {
        "name": "oaas.tenant_provisioned",
        "category": "saas_lifecycle",
        "description": "Tenant OaaS provisionado en nodo dedicado con SLA"
      },
      {
        "name": "oaas.quota_adjusted",
        "category": "saas_lifecycle",
        "description": "Ajuste de cuota mensual o capacidad de cómputo"
      },
      {
        "name": "billing.payment_accredited",
        "category": "saas_lifecycle",
        "description": "Comprobante bancario acreditado formalmente y saldo aplicado"
      },
      {
        "name": "crm.contact_synced",
        "category": "saas_lifecycle",
        "description": "Contacto bidireccionalmente sincronizado con CRM/ERP externo"
      },
      {
        "name": "erp.transaction_notified",
        "category": "saas_lifecycle",
        "description": "Transacción contable/financiera notificada desde ERP propio"
      }
    ]
  }
}
