{
  "openapi": "3.1.0",
  "info": {
    "title": "PushLeads API de mensajería",
    "version": "1.1.0",
    "description": "Campañas y mensajes individuales de SMS y WhatsApp, autenticados con una API key\nde un solo workspace. Se exige tanto el scope de la key como el permiso vigente\ndel usuario en el workspace. accountId identifica al propietario del workspace.\nTodos los POST de este contrato requieren Idempotency-Key. No hay una consulta\nindependiente que garantice que un destinatario tiene WhatsApp antes de enviar.\nLos mensajes individuales informan aceptación del proveedor, no entrega o lectura.\nAplicar scripts/142_public_messaging_api.sql antes del despliegue.\nv1.1: plantillas de WhatsApp (/whatsapp/templates), webhooks salientes (/webhooks) y recibos\nde entrega reales (sent/delivered/read/failed) en /messages/{id}. Aplicar también\nscripts/171_api_webhooks.sql.\n"
  },
  "servers": [
    {
      "url": "https://app.pushleads.co/api/v1",
      "description": "Sustituir el dominio para otra instalación"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Contexto"
    },
    {
      "name": "Mensajes"
    },
    {
      "name": "Campañas"
    },
    {
      "name": "Plantillas"
    },
    {
      "name": "Webhooks"
    }
  ],
  "paths": {
    "/me": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getApiContext",
        "tags": [
          "Contexto"
        ],
        "summary": "Consultar cuenta, usuario, workspace y permisos de la key",
        "responses": {
          "200": {
            "description": "Contexto autorizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "accountId",
                        "userId",
                        "workspaceId",
                        "permissions",
                        "workspacePermissions"
                      ],
                      "properties": {
                        "accountId": {
                          "type": "string",
                          "description": "Propietario del workspace"
                        },
                        "userId": {
                          "type": "string",
                          "description": "Creador de la API key"
                        },
                        "workspaceId": {
                          "type": "string"
                        },
                        "permissions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "workspacePermissions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/messaging/resources": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getMessagingResources",
        "tags": [
          "Contexto"
        ],
        "summary": "Consultar remitentes y plantillas aprobadas del workspace",
        "description": "Requiere messaging:read y conversations.view o campaigns.view. No devuelve credenciales de proveedores.",
        "x-required-scopes": [
          "messaging:read"
        ],
        "responses": {
          "200": {
            "description": "Recursos del workspace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/MessagingResources"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/sms/send": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "sendSms",
        "tags": [
          "Mensajes"
        ],
        "summary": "Enviar un SMS a un destinatario",
        "description": "Requiere sms:send y conversations.respond. Usa Háblame y verifica bajas, remitente y cupo del workspace.",
        "x-required-scopes": [
          "sms:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsSend"
              },
              "example": {
                "to": "+573001234567",
                "text": "Tu pedido 123 está confirmado.",
                "priority": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "$ref": "#/components/responses/MessageAccepted"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/whatsapp/send": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "sendWhatsApp",
        "tags": [
          "Mensajes"
        ],
        "summary": "Enviar una plantilla aprobada o texto dentro de la ventana de atención",
        "description": "Requiere whatsapp:send y conversations.respond. Se valida el destinatario,\nbajas y restricciones conocidas, el remitente y la plantilla del workspace.\nPara texto se exige un mensaje entrante verificable dentro de 24 horas en\nla línea seleccionada. Las variables son valores concretos, sin resolver contactos.\n",
        "x-required-scopes": [
          "whatsapp:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhatsAppSend"
              },
              "examples": {
                "twilioTemplate": {
                  "summary": "Plantilla Twilio",
                  "value": {
                    "to": "+573001234567",
                    "provider": "twilio",
                    "type": "template",
                    "contentSid": "HX00000000000000000000000000000000",
                    "senderPhone": "+573009876543",
                    "variables": {
                      "1": "Ana",
                      "2": "123"
                    }
                  }
                },
                "metaTemplate": {
                  "summary": "Plantilla Meta",
                  "value": {
                    "to": "+573001234567",
                    "provider": "meta",
                    "type": "template",
                    "metaTemplateId": "ID_PLANTILLA_DEL_WORKSPACE",
                    "metaPhoneNumberId": "ID_LINEA_DEL_WORKSPACE",
                    "variables": {
                      "1": "Ana"
                    }
                  }
                },
                "twilioText": {
                  "summary": "Texto dentro de 24 horas",
                  "value": {
                    "to": "+573001234567",
                    "provider": "twilio",
                    "type": "text",
                    "senderPhone": "+573009876543",
                    "text": "Estamos revisando tu solicitud."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "$ref": "#/components/responses/MessageAccepted"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/messages/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getMessage",
        "tags": [
          "Mensajes"
        ],
        "summary": "Consultar el resultado de un envío individual",
        "description": "Requiere messages:read y conversations.view. Solo encuentra registros de la\ncuenta y workspace de la key. Los recibos del proveedor actualizan status,\ndeliveredAt, readAt y errorCode; el webhook message.status los avisa en tiempo real.\n",
        "x-required-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Registro del envío",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/campaigns": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "listCampaigns",
        "tags": [
          "Campañas"
        ],
        "summary": "Listar campañas del workspace con paginación",
        "description": "Requiere campaigns:read y campaigns.view. Orden por creación descendente.",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000,
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "channel",
            "schema": {
              "type": "string",
              "enum": [
                "sms",
                "whatsapp",
                "email"
              ]
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "$ref": "#/components/schemas/CampaignStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de campañas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Campaign"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "page",
                        "limit",
                        "total",
                        "totalPages"
                      ],
                      "properties": {
                        "page": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "total": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "totalPages": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createCampaign",
        "tags": [
          "Campañas"
        ],
        "summary": "Crear una campaña de SMS, WhatsApp o email",
        "description": "Requiere campaigns:write y campaigns.create. sendNow o scheduledAt requieren\nademás campaigns:send y campaigns.send. La lista y recursos deben pertenecer\nal workspace. Sin programación ni sendNow queda draft. sendNow realiza el\ndespacho real; 201 confirma creación y data.status indica el estado alcanzado.\nAnte fallo posterior a crear, se devuelve data.id para consultar la campaña.\n",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignCreate"
              },
              "examples": {
                "sms": {
                  "value": {
                    "name": "Confirmaciones SMS",
                    "channel": "sms",
                    "listId": "ID_LISTA_DEL_WORKSPACE",
                    "smsContent": "Hola {{first_name}}, tu pedido está confirmado.",
                    "sendNow": false
                  }
                },
                "whatsapp": {
                  "value": {
                    "name": "Confirmaciones WhatsApp",
                    "channel": "whatsapp",
                    "listId": "ID_LISTA_DEL_WORKSPACE",
                    "whatsapp": {
                      "provider": "twilio",
                      "contentSid": "HX00000000000000000000000000000000",
                      "senderPhone": "+573009876543",
                      "variableMapping": {
                        "1": "{{first_name}}"
                      }
                    },
                    "sendNow": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campaña creada; consultar data.status para el resultado del envío",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/campaigns/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getCampaign",
        "tags": [
          "Campañas"
        ],
        "summary": "Consultar estado y contadores de una campaña",
        "description": "Requiere campaigns:read y campaigns.view. Los contadores separan pendientes, enviados, fallidos y entregados.",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "responses": {
          "200": {
            "description": "Campaña del workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/campaigns/{id}/send": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "sendCampaign",
        "tags": [
          "Campañas"
        ],
        "summary": "Despachar una campaña en borrador o programada",
        "description": "Requiere campaigns:send y campaigns.send. Reclama la campaña de forma atómica\npara evitar dobles envíos. No reinicia campañas sending, sent, failed o cancelled.\nInvocarlo sobre una campaña programada adelanta su envío.\n",
        "x-required-scopes": [
          "campaigns:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "workspaceId": {
                    "$ref": "#/components/schemas/Identifier"
                  },
                  "accountId": {
                    "$ref": "#/components/schemas/Identifier"
                  }
                }
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ejecución terminada; revisar estado y contadores",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "202": {
            "description": "Campaña en proceso de envío",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/whatsapp/templates": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "listWhatsAppTemplates",
        "tags": [
          "Plantillas"
        ],
        "summary": "Listar plantillas de WhatsApp del workspace",
        "description": "Requiere templates:read. Incluye Twilio Content y la línea oficial de Meta con su estado de aprobación.",
        "x-required-scopes": [
          "templates:read"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "provider",
            "schema": {
              "type": "string",
              "enum": [
                "meta",
                "twilio"
              ]
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "pending",
                "approved",
                "rejected",
                "unsubmitted"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plantillas",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateListResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createWhatsAppTemplate",
        "tags": [
          "Plantillas"
        ],
        "summary": "Crear una plantilla",
        "description": "Requiere templates:write e Idempotency-Key. Meta: se crea en la WABA y entra en revisión.\nTwilio: borrador local y, con submit=true (default), creación en Twilio y envío a aprobación.\n",
        "x-required-scopes": [
          "templates:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plantilla creada (status pending/draft)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/whatsapp/templates/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getWhatsAppTemplate",
        "tags": [
          "Plantillas"
        ],
        "summary": "Consultar una plantilla y refrescar su estado",
        "description": "Requiere templates:read. Consulta al proveedor el estado de aprobación y lo guarda; ?refresh=false devuelve la copia local.",
        "x-required-scopes": [
          "templates:read"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "refresh",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plantilla",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "operationId": "deleteWhatsAppTemplate",
        "tags": [
          "Plantillas"
        ],
        "summary": "Eliminar una plantilla",
        "description": "Requiere templates:write. En Meta también la borra de la WABA (solo ese idioma).",
        "x-required-scopes": [
          "templates:write"
        ],
        "responses": {
          "200": {
            "description": "Eliminada"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/whatsapp/templates/{id}/submit": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "submitWhatsAppTemplate",
        "tags": [
          "Plantillas"
        ],
        "summary": "Enviar un borrador de Twilio a aprobación",
        "description": "Requiere templates:write. Solo Twilio en estado draft, rejected o unsubmitted; Meta se envía al crearse (409).",
        "x-required-scopes": [
          "templates:write"
        ],
        "responses": {
          "200": {
            "description": "Plantilla en revisión",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/whatsapp/templates/sync": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "syncWhatsAppTemplates",
        "tags": [
          "Plantillas"
        ],
        "summary": "Sincronizar plantillas desde Twilio y Meta",
        "description": "Requiere templates:write. Trae a PushLeads las plantillas existentes en la cuenta de Twilio y en cada WABA activa.",
        "x-required-scopes": [
          "templates:write"
        ],
        "responses": {
          "200": {
            "description": "Resultado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplateSyncResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/webhooks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "listWebhooks",
        "tags": [
          "Webhooks"
        ],
        "summary": "Listar webhooks salientes del workspace",
        "description": "Requiere webhooks:manage y workspace.settings. Los secretos van enmascarados.",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "responses": {
          "200": {
            "description": "Webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "workspaceId": {
                          "type": "string"
                        },
                        "webhooks": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Webhook"
                          }
                        },
                        "events": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WebhookEvent"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Registrar una URL que recibirá eventos",
        "description": "Requiere webhooks:manage. La respuesta incluye el secreto completo una sola vez. Máximo 10 por workspace.",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook creado con secreto",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/webhooks/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "getWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Consultar un webhook",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "responses": {
          "200": {
            "description": "Webhook",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "operationId": "updateWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Actualizar nombre, URL, eventos, estado o rotar el secreto",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Eliminar un webhook",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "responses": {
          "200": {
            "description": "Eliminado"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/webhooks/{id}/test": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "post": {
        "operationId": "testWebhook",
        "tags": [
          "Webhooks"
        ],
        "summary": "Enviar un evento ping firmado",
        "description": "200 si el endpoint respondió 2xx; 502 con el código y error en data si no.",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "responses": {
          "200": {
            "description": "Entregado"
          },
          "502": {
            "description": "El endpoint no respondió 2xx"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/webhooks/{id}/deliveries": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Id"
        },
        {
          "$ref": "#/components/parameters/WorkspaceHeader"
        },
        {
          "$ref": "#/components/parameters/AccountHeader"
        }
      ],
      "get": {
        "operationId": "listWebhookDeliveries",
        "tags": [
          "Webhooks"
        ],
        "summary": "Últimas entregas del webhook",
        "x-required-scopes": [
          "webhooks:manage"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entregas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "deliveries": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WebhookDelivery"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pk_live_..."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "Id": {
        "in": "path",
        "name": "id",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "WorkspaceHeader": {
        "in": "header",
        "name": "X-Workspace-Id",
        "required": false,
        "description": "Verificación opcional; debe coincidir con el workspace de la key. No cambia de workspace.",
        "schema": {
          "type": "string"
        }
      },
      "AccountHeader": {
        "in": "header",
        "name": "X-Account-Id",
        "required": false,
        "description": "Verificación opcional; debe coincidir con el usuario propietario del workspace.",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "in": "header",
        "name": "Idempotency-Key",
        "required": true,
        "description": "Identificador único y persistente de la operación. Repetir la misma key y\nsolicitud reproduce el resultado; otro cuerpo devuelve 409. Una operación\npendiente devuelve 409 REQUEST_IN_PROGRESS. No usar otra key si el resultado\ndel proveedor es incierto. El alcance incluye API key, workspace, método y ruta.\n",
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]{8,128}$"
        },
        "example": "pedido-123-confirmacion-v1"
      }
    },
    "responses": {
      "Error": {
        "description": "400 validación/configuración; 401 key inválida; 403 permisos, contexto o cupo;\n404 recurso ajeno/inexistente; 409 conflicto, baja/restricción, ventana cerrada\no proveedor sin configurar; 413 cuerpo mayor a 256 KB; 500/502/503 error interno,\nproveedor o dependencia. Consultar estado antes de un nuevo envío.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MessageAccepted": {
        "description": "Proveedor aceptó el mensaje; no confirma entrega ni lectura",
        "headers": {
          "Idempotency-Replayed": {
            "description": "true cuando se reproduce una respuesta persistida",
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/MessageResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "E164": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{7,14}$",
        "description": "Número internacional válido; se verifica también el plan de numeración. No garantiza WhatsApp.",
        "example": "+573001234567"
      },
      "Identifier": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "ContentSid": {
        "type": "string",
        "pattern": "^HX[a-fA-F0-9]{32}$"
      },
      "MessagingServiceSid": {
        "type": "string",
        "pattern": "^MG[a-fA-F0-9]{32}$"
      },
      "HttpsUrl": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://",
        "maxLength": 2048
      },
      "SmsSend": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "to",
          "text"
        ],
        "properties": {
          "to": {
            "$ref": "#/components/schemas/E164"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "senderPhone": {
            "$ref": "#/components/schemas/E164",
            "description": "Remitente SMS verificado del workspace; omitir para usar el proveedor configurado"
          },
          "priority": {
            "type": "boolean",
            "default": true
          },
          "workspaceId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "accountId": {
            "$ref": "#/components/schemas/Identifier"
          }
        }
      },
      "WhatsAppSend": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "to",
          "type",
          "provider"
        ],
        "properties": {
          "to": {
            "$ref": "#/components/schemas/E164"
          },
          "type": {
            "type": "string",
            "enum": [
              "template",
              "text"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "twilio",
              "meta"
            ]
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "contentSid": {
            "$ref": "#/components/schemas/ContentSid"
          },
          "senderPhone": {
            "$ref": "#/components/schemas/E164"
          },
          "messagingServiceSid": {
            "$ref": "#/components/schemas/MessagingServiceSid"
          },
          "metaTemplateId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "metaPhoneNumberId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "variables": {
            "type": "object",
            "default": {},
            "propertyNames": {
              "minLength": 1,
              "maxLength": 100
            },
            "additionalProperties": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            },
            "description": "Valores concretos de todas las variables del cuerpo; se rechazan variables faltantes y extras"
          },
          "headerMediaUrl": {
            "$ref": "#/components/schemas/HttpsUrl",
            "description": "Solo plantillas Meta con encabezado multimedia"
          },
          "couponCode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Solo plantillas Meta con botón de copiar código"
          },
          "workspaceId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "accountId": {
            "$ref": "#/components/schemas/Identifier"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "type": {
                  "const": "text"
                }
              }
            },
            "then": {
              "required": [
                "text"
              ],
              "properties": {
                "contentSid": false,
                "metaTemplateId": false,
                "headerMediaUrl": false,
                "couponCode": false,
                "variables": {
                  "maxProperties": 0
                }
              }
            },
            "else": {
              "properties": {
                "text": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "provider": {
                  "const": "twilio"
                }
              }
            },
            "then": {
              "anyOf": [
                {
                  "required": [
                    "senderPhone"
                  ]
                },
                {
                  "required": [
                    "messagingServiceSid"
                  ]
                }
              ],
              "properties": {
                "metaTemplateId": false,
                "metaPhoneNumberId": false,
                "headerMediaUrl": false,
                "couponCode": false
              },
              "allOf": [
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "template"
                      }
                    }
                  },
                  "then": {
                    "required": [
                      "contentSid"
                    ]
                  },
                  "else": {
                    "required": [
                      "senderPhone"
                    ]
                  }
                }
              ]
            },
            "else": {
              "required": [
                "metaPhoneNumberId"
              ],
              "properties": {
                "contentSid": false,
                "senderPhone": false,
                "messagingServiceSid": false
              },
              "allOf": [
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "template"
                      }
                    }
                  },
                  "then": {
                    "required": [
                      "metaTemplateId"
                    ]
                  }
                }
              ]
            }
          }
        ]
      },
      "WhatsAppCampaign": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "provider"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "enum": [
              "twilio",
              "meta"
            ]
          },
          "contentSid": {
            "$ref": "#/components/schemas/ContentSid"
          },
          "senderPhone": {
            "$ref": "#/components/schemas/E164"
          },
          "messagingServiceSid": {
            "$ref": "#/components/schemas/MessagingServiceSid"
          },
          "metaTemplateId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "metaPhoneNumberId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "variableMapping": {
            "type": "object",
            "default": {},
            "propertyNames": {
              "maxLength": 100
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "Expresiones por contacto, por ejemplo {{first_name}}, {{custom_fields.pedido}}, o texto fijo"
          },
          "headerMediaUrl": {
            "$ref": "#/components/schemas/HttpsUrl"
          },
          "couponCode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "provider": {
                  "const": "twilio"
                }
              }
            },
            "then": {
              "required": [
                "contentSid"
              ],
              "anyOf": [
                {
                  "required": [
                    "senderPhone"
                  ]
                },
                {
                  "required": [
                    "messagingServiceSid"
                  ]
                }
              ],
              "properties": {
                "metaTemplateId": false,
                "metaPhoneNumberId": false,
                "headerMediaUrl": false,
                "couponCode": false
              }
            },
            "else": {
              "required": [
                "metaTemplateId",
                "metaPhoneNumberId"
              ],
              "properties": {
                "contentSid": false,
                "senderPhone": false,
                "messagingServiceSid": false
              }
            }
          }
        ]
      },
      "CampaignCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "channel",
          "listId"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "description": {
            "type": "string",
            "maxLength": 5000
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp",
              "email"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "promotional",
              "transactional",
              "newsletter",
              "announcement"
            ],
            "default": "promotional"
          },
          "listId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "smsContent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1600
          },
          "senderPhone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "Remitente SMS verificado y activo del workspace"
          },
          "smsPriority": {
            "type": "boolean",
            "default": false
          },
          "smsFlash": {
            "type": "boolean",
            "default": false
          },
          "whatsapp": {
            "$ref": "#/components/schemas/WhatsAppCampaign"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 998
          },
          "htmlContent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 250000
          },
          "templateId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "domainId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "senderEmail": {
            "type": "string",
            "format": "email"
          },
          "senderName": {
            "type": "string",
            "maxLength": 200
          },
          "scheduledAt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Fecha futura ISO 8601 con zona explícita o fecha local en scheduleTimezone; incompatible con sendNow true",
            "example": "2030-11-01T10:00:00-05:00"
          },
          "scheduleTimezone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "default": "America/Bogota",
            "description": "Zona IANA para interpretar fechas locales"
          },
          "sendNow": {
            "type": "boolean",
            "default": false
          },
          "workspaceId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "accountId": {
            "$ref": "#/components/schemas/Identifier"
          }
        },
        "allOf": [
          {
            "if": {
              "required": [
                "sendNow"
              ],
              "properties": {
                "sendNow": {
                  "const": true
                }
              }
            },
            "then": {
              "properties": {
                "scheduledAt": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "channel": {
                  "const": "sms"
                }
              }
            },
            "then": {
              "required": [
                "smsContent"
              ]
            },
            "else": {
              "properties": {
                "smsContent": false,
                "senderPhone": false,
                "smsPriority": false,
                "smsFlash": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "channel": {
                  "const": "whatsapp"
                }
              }
            },
            "then": {
              "required": [
                "whatsapp"
              ]
            },
            "else": {
              "properties": {
                "whatsapp": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "channel": {
                  "const": "email"
                }
              }
            },
            "then": {
              "required": [
                "subject",
                "senderEmail"
              ],
              "oneOf": [
                {
                  "required": [
                    "templateId"
                  ]
                },
                {
                  "required": [
                    "htmlContent"
                  ]
                }
              ]
            },
            "else": {
              "properties": {
                "subject": false,
                "senderEmail": false,
                "senderName": false,
                "templateId": false,
                "htmlContent": false,
                "domainId": false
              }
            }
          }
        ]
      },
      "CampaignStatus": {
        "type": "string",
        "enum": [
          "draft",
          "scheduled",
          "sending",
          "sent",
          "failed",
          "cancelled"
        ]
      },
      "Campaign": {
        "type": "object",
        "required": [
          "id",
          "name",
          "channel",
          "type",
          "status",
          "workspaceId",
          "listId",
          "totalContacts",
          "queuedCount",
          "pendingCount",
          "sentCount",
          "failedCount"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp",
              "email"
            ]
          },
          "type": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/CampaignStatus"
          },
          "workspaceId": {
            "type": "string"
          },
          "listId": {
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "totalContacts": {
            "type": "integer",
            "minimum": 0,
            "description": "Contactos de la lista; no todos necesariamente elegibles"
          },
          "queuedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Total de registros de envío de la campaña"
          },
          "pendingCount": {
            "type": "integer",
            "minimum": 0
          },
          "sentCount": {
            "type": "integer",
            "minimum": 0
          },
          "failedCount": {
            "type": "integer",
            "minimum": 0
          },
          "deliveredCount": {
            "type": "integer",
            "minimum": 0
          },
          "openedCount": {
            "type": "integer",
            "minimum": 0
          },
          "clickedCount": {
            "type": "integer",
            "minimum": 0
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "scheduleTimezone": {
            "type": "string"
          },
          "sentAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CampaignResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "$ref": "#/components/schemas/Campaign"
          }
        }
      },
      "Message": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "channel",
          "provider",
          "to",
          "status",
          "providerMessageId",
          "deliveryTracking",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspaceId": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "hablame",
              "twilio",
              "meta"
            ]
          },
          "to": {
            "$ref": "#/components/schemas/E164"
          },
          "from": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "accepted",
              "sent",
              "delivered",
              "read",
              "failed",
              "unknown"
            ],
            "description": "accepted = el proveedor aceptó el envío; sent/delivered/read/failed llegan por los callbacks de Meta o Twilio"
          },
          "providerMessageId": {
            "type": [
              "string",
              "null"
            ]
          },
          "errorCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "deliveryTracking": {
            "const": "provider_callbacks"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "errorMessage": {
            "type": [
              "string",
              "null"
            ]
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "readAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "MessageResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "$ref": "#/components/schemas/Message"
          }
        }
      },
      "TemplateVariable": {
        "type": "object",
        "required": [
          "index"
        ],
        "properties": {
          "index": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "sample": {
            "type": "string"
          }
        }
      },
      "MessagingResources": {
        "type": "object",
        "required": [
          "workspaceId",
          "sms",
          "whatsapp"
        ],
        "properties": {
          "workspaceId": {
            "type": "string"
          },
          "sms": {
            "type": "object",
            "required": [
              "configured",
              "senderPhone",
              "senderPhones"
            ],
            "properties": {
              "configured": {
                "type": "boolean"
              },
              "senderPhone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "senderPhones": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "whatsapp": {
            "type": "object",
            "required": [
              "senders",
              "templates"
            ],
            "properties": {
              "senders": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "provider",
                    "senderPhone"
                  ],
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "twilio",
                        "meta"
                      ]
                    },
                    "senderPhone": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "messagingServiceSid": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "metaPhoneNumberId": {
                      "type": "string"
                    },
                    "wabaAccountId": {
                      "type": "string",
                      "description": "Permite emparejar línea y plantilla Meta de la misma cuenta"
                    }
                  }
                }
              },
              "templates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "provider",
                    "name",
                    "language",
                    "variables"
                  ],
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "twilio",
                        "meta"
                      ]
                    },
                    "contentSid": {
                      "type": "string"
                    },
                    "metaTemplateId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "language": {
                      "type": "string"
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "body": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "variables": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TemplateVariable"
                      }
                    },
                    "components": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "wabaAccountId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {}
            }
          },
          "data": {
            "$ref": "#/components/schemas/Campaign",
            "description": "Presente si una campaña se creó pero el despacho no terminó correctamente"
          }
        }
      },
      "TemplateButton": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "QUICK_REPLY",
              "URL",
              "PHONE_NUMBER",
              "COPY_CODE",
              "FLOW",
              "CATALOG"
            ]
          },
          "title": {
            "type": "string",
            "maxLength": 25
          },
          "url": {
            "type": "string",
            "description": "Botón URL (HTTPS)"
          },
          "phone": {
            "type": "string",
            "description": "Botón de llamada, formato internacional"
          },
          "example": {
            "type": "string",
            "description": "COPY_CODE: cupón de ejemplo"
          },
          "flowId": {
            "type": "string",
            "description": "FLOW (solo Meta)"
          }
        }
      },
      "TemplateCreate": {
        "type": "object",
        "required": [
          "provider",
          "name",
          "body"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "enum": [
              "meta",
              "twilio"
            ]
          },
          "name": {
            "type": "string",
            "pattern": "^[a-z0-9_]+$",
            "maxLength": 512
          },
          "displayName": {
            "type": "string",
            "maxLength": 200
          },
          "language": {
            "type": "string",
            "default": "es"
          },
          "category": {
            "type": "string",
            "enum": [
              "marketing",
              "utility",
              "authentication"
            ],
            "default": "marketing"
          },
          "body": {
            "type": "string",
            "maxLength": 1024,
            "description": "Variables consecutivas {{1}}, {{2}}..."
          },
          "samples": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Ejemplo por variable, en orden (Meta lo exige)"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "index"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "minimum": 1
                },
                "label": {
                  "type": "string"
                },
                "sample": {
                  "type": "string"
                }
              }
            }
          },
          "headerText": {
            "type": "string",
            "maxLength": 60
          },
          "footerText": {
            "type": "string",
            "maxLength": 60
          },
          "headerFormat": {
            "type": "string",
            "enum": [
              "TEXT",
              "IMAGE",
              "VIDEO",
              "DOCUMENT"
            ]
          },
          "headerMediaUrl": {
            "$ref": "#/components/schemas/HttpsUrl"
          },
          "buttons": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/TemplateButton"
            }
          },
          "metaPhoneNumberId": {
            "type": "string",
            "description": "Meta: línea cuya WABA recibe la plantilla"
          },
          "wabaAccountId": {
            "type": "string",
            "description": "Meta: WABA interna (alternativa a metaPhoneNumberId)"
          },
          "senderPhone": {
            "$ref": "#/components/schemas/E164",
            "description": "Twilio: línea de la plantilla"
          },
          "senderId": {
            "type": "string",
            "description": "Twilio: id interno de la línea"
          },
          "submit": {
            "type": "boolean",
            "default": true,
            "description": "Twilio: crear en Twilio y enviar a aprobación de inmediato"
          }
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "id",
          "provider",
          "name",
          "language",
          "category",
          "status",
          "body",
          "variables"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "provider": {
            "type": "string",
            "enum": [
              "meta",
              "twilio"
            ]
          },
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "pending",
              "approved",
              "rejected",
              "unsubmitted"
            ]
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "body": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TemplateVariable"
            }
          },
          "header": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "format": {
                "type": "string"
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "url": {
                "type": "string"
              }
            }
          },
          "footer": {
            "type": [
              "string",
              "null"
            ]
          },
          "buttons": {
            "type": "array",
            "items": {}
          },
          "contentSid": {
            "type": [
              "string",
              "null"
            ],
            "description": "Twilio: usar en /whatsapp/send"
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Meta: usar en /whatsapp/send"
          },
          "wabaAccountId": {
            "type": [
              "string",
              "null"
            ]
          },
          "senderId": {
            "type": [
              "string",
              "null"
            ]
          },
          "linePhone": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TemplateResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "$ref": "#/components/schemas/Template"
          },
          "warning": {
            "type": "string"
          }
        }
      },
      "TemplateListResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "workspaceId": {
                "type": "string"
              },
              "templates": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Template"
                }
              }
            }
          }
        }
      },
      "TemplateSyncResponse": {
        "type": "object",
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "adopted": {
                "type": "integer"
              },
              "imported": {
                "type": "integer"
              },
              "updated": {
                "type": "integer"
              },
              "metaSynced": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "WebhookEvent": {
        "type": "string",
        "enum": [
          "message.received",
          "message.status",
          "template.status"
        ]
      },
      "WebhookCreate": {
        "type": "object",
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "url": {
            "$ref": "#/components/schemas/HttpsUrl",
            "description": "HTTPS pública; se rechazan redes privadas y localhost"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            },
            "default": [
              "message.received",
              "message.status"
            ]
          }
        }
      },
      "WebhookPatch": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "url": {
            "$ref": "#/components/schemas/HttpsUrl"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "isActive": {
            "type": "boolean"
          },
          "rotateSecret": {
            "type": "boolean",
            "description": "Genera un secreto nuevo y lo devuelve completo"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "name",
          "url",
          "events",
          "isActive",
          "secret"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspaceId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "isActive": {
            "type": "boolean"
          },
          "secret": {
            "type": "string",
            "description": "Completo solo al crear o rotar; después enmascarado"
          },
          "lastDeliveryAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastDeliveryStatus": {
            "type": [
              "integer",
              "null"
            ]
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "consecutiveFailures": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookResponse": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "$ref": "#/components/schemas/Webhook"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "endpointId": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "delivered",
              "failed"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "nextAttemptAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastStatusCode": {
            "type": [
              "integer",
              "null"
            ]
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "payload": {
            "$ref": "#/components/schemas/WebhookEnvelope"
          }
        }
      },
      "WebhookEnvelope": {
        "type": "object",
        "description": "Cuerpo de cada entrega. Headers: X-PushLeads-Event, X-PushLeads-Delivery y X-PushLeads-Signature (t=<unix>,v1=<HMAC-SHA256 hex de \"t.cuerpo\" con el secreto>). Responder 2xx en menos de 10 s; reintentos a 1, 5, 15, 60, 180, 360 y 720 minutos.",
        "required": [
          "id",
          "type",
          "createdAt",
          "workspaceId",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "message.received",
              "message.status",
              "template.status",
              "ping"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "workspaceId": {
            "type": "string"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MessageReceivedData"
              },
              {
                "$ref": "#/components/schemas/MessageStatusData"
              },
              {
                "$ref": "#/components/schemas/TemplateStatusData"
              },
              {
                "type": "object"
              }
            ]
          }
        }
      },
      "MessageReceivedData": {
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string"
          },
          "conversationId": {
            "type": [
              "string",
              "null"
            ]
          },
          "contactId": {
            "type": [
              "string",
              "null"
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "whatsapp",
              "sms"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "meta",
              "twilio"
            ]
          },
          "line": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string"
              },
              "metaPhoneNumberId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "senderPhone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "from": {
            "type": "object",
            "properties": {
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "identity": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Usuario de WhatsApp sin número visible"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "text": {
            "type": "string"
          },
          "messageType": {
            "type": "string"
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "contentType": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "type": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "providerMessageId": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "referral": {
            "type": [
              "object",
              "null"
            ],
            "description": "Anuncio Click-to-WhatsApp de origen"
          },
          "humanControlled": {
            "type": "boolean",
            "description": "true: la conversación no la atiende un agente IA de PushLeads"
          },
          "isNewConversation": {
            "type": "boolean"
          }
        }
      },
      "MessageStatusData": {
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "sent",
              "delivered",
              "read",
              "failed"
            ]
          },
          "previousStatus": {
            "type": "string"
          },
          "channel": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "from": {
            "type": [
              "string",
              "null"
            ]
          },
          "providerMessageId": {
            "type": "string"
          },
          "errorCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "errorMessage": {
            "type": [
              "string",
              "null"
            ]
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "readAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TemplateStatusData": {
        "type": "object",
        "properties": {
          "templateId": {
            "type": "string"
          },
          "provider": {
            "const": "meta"
          },
          "metaTemplateId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "approved",
              "rejected",
              "pending",
              "paused",
              "disabled"
            ]
          },
          "providerStatus": {
            "type": "string"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}
