{"openapi":"3.1.0","info":{"title":"API de WiCloud","version":"1 (WiCloud 3.12.6)","description":"Envía mensajes de WhatsApp, gestiona contactos y listas, y crea campañas desde tus sistemas, n8n u otras herramientas.\n\n**Autenticación:** `Authorization: Bearer wic_…`. Crea la clave en tu panel → Integraciones → API e integraciones. Documentación en Markdown para agentes de IA: `/llms.txt`, `/llms-full.txt` y `GET /api/v1/docs`.\n\n**Permisos de la clave:** `lectura`, `mensajes`, `contactos`, `campanas`, `campanas_enviar`, `eventos`, `bandeja`, `plantillas`, `estados`, `canales`. Cada ruta indica el que necesita (`x-permiso`).\n\n**Números:** mándalos con código de país (`+593991234567`). Sin código se usa el del WhatsApp de tu cuenta o el que pases en `codigoPais`.\n\n**Protección anti-bloqueo:** los mensajes salen por una cola, de a uno por número y con pausas humanas. Las campañas respetan las pausas mínimas y el horario de tu cuenta, y quedan como **borrador** salvo que la clave tenga `campanas_enviar` y pidas `enviarDirecto`.\n\n**Errores:** siempre traen `codigo` (estable, para tu lógica) y `message` (para personas).\n\n**Eventos (webhooks):** WiCloud te avisa con un `POST` a tu dirección cuando pasa algo: `mensaje.recibido` (llegó un mensaje), `campana.respuesta` (alguien respondió a una campaña), `campana.terminada` (terminó una campaña), `instancia.desconectada` (se desconectó un número), `instancia.conectada` (se conectó un número), `contacto.creado` (se creó un contacto), `contacto.actualizado` (se actualizó un contacto), `contacto.eliminado` (se eliminó un contacto), `lista.creada` (se creó una lista), `lista.actualizada` (cambió una lista), `campana.creada` (se creó una campaña), `campana.iniciada` (empezó una campaña), `campana.pausada` (se pausó una campaña), `campana.fallida` (falló una campaña), `mensaje.en_cola` (mensaje en cola), `mensaje.enviado` (mensaje enviado), `mensaje.entregado` (mensaje entregado), `mensaje.leido` (mensaje leído), `mensaje.fallido` (mensaje fallido), `contacto.baja` (un contacto pidió la baja). Créalos en tu panel o con `POST /v1/suscripciones`.\n\n**Asistentes de IA (MCP):** en `POST /api/mcp` hay un servidor MCP de solo lectura (Streamable HTTP) para Claude, Cursor, n8n u otros clientes MCP, con la misma clave (`Authorization: Bearer wic_…`; si el cliente no permite headers, `?key=wic_…` en la URL, solo en el MCP). Herramientas: cuenta, números, campañas y sus resultados, contactos, listas, estadísticas y, con el permiso `bandeja`, las conversaciones recibidas.\n\n**Cada aviso trae:** `X-WiCloud-Evento`, `X-WiCloud-Id` (único: si llega dos veces por un reintento, ignora el segundo), `X-WiCloud-Timestamp` y `X-WiCloud-Firma` = `sha256=` + HMAC-SHA256 con tu clave de `\"<timestamp>.<cuerpo>\"`. Responde 2xx en menos de 10 s; si no, se reintenta a 1 min, 5 min, 30 min, 2 h y 6 h. Tras 20 avisos fallidos seguidos el webhook se pausa solo."},"servers":[{"url":"/api","description":"Este servidor"}],"security":[{"claveApi":[]}],"tags":[{"name":"Cuenta"},{"name":"Números"},{"name":"Mensajes"},{"name":"Contactos"},{"name":"Listas"},{"name":"Campañas"},{"name":"Plantillas"},{"name":"Conversaciones"},{"name":"Estados"},{"name":"Reportes"},{"name":"Eventos"},{"name":"Grupos"},{"name":"Canales"}],"paths":{"/v1/cuenta":{"get":{"tags":["Cuenta"],"summary":"Probar la conexión: tu cuenta, plan, permisos de la clave y límites","responses":{"200":{"description":"Cuenta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cuenta"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instancias":{"get":{"tags":["Números"],"summary":"Tus números de WhatsApp y si están conectados","x-permiso":"lectura","responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Instancia"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instancias/{id}":{"get":{"tags":["Números"],"summary":"Un número: conexión, calidad, cupo, motor y si es apto para campañas","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Número","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanciaDetalle"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mensajes":{"post":{"tags":["Mensajes"],"summary":"Enviar un mensaje (texto, archivo o plantilla) a un número","x-permiso":"mensajes","description":"Entra a la cola y sale en segundos. Responde 202 con el id para consultar su estado; 200 si la Idempotency-Key ya se había usado. Con `plantillaId` (o `plantilla`: nombre) manda una plantilla: las variables se completan con el contacto y con `variables`; si falta alguna responde 400 `VARIABLES_FALTANTES` y no envía.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Valor único por operación. Si la integración reintenta con la misma clave, no se duplica.","schema":{"type":"string","maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevoMensaje"}}}},"responses":{"200":{"description":"Repetido (misma Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mensaje"}}}},"202":{"description":"En cola","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mensaje"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Número desconectado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mensajes/{id}":{"get":{"tags":["Mensajes"],"summary":"Estado de un mensaje","x-permiso":"mensajes","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Mensaje","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mensaje"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Mensajes"],"summary":"Cancelar un mensaje que todavía está en cola","x-permiso":"mensajes","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mensaje"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ya salió","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos":{"get":{"tags":["Contactos"],"summary":"Buscar contactos","x-permiso":"lectura","parameters":[{"name":"numero","in":"query","description":"Número exacto","schema":{"type":"string"}},{"name":"buscar","in":"query","description":"Texto en nombre, apellido, número, empresa o correo","schema":{"type":"string"}},{"name":"correo","in":"query","schema":{"type":"string"}},{"name":"etiqueta","in":"query","schema":{"type":"string"}},{"name":"listaId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"porPagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Página","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Contacto"}},"pagina":{"type":"integer"},"porPagina":{"type":"integer"},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contactos"],"summary":"Crear o actualizar un contacto (por número)","x-permiso":"contactos","description":"Si el número ya existe, actualiza los campos que mandes (201 si lo creó, 200 si lo actualizó).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevoContacto"}}}},"responses":{"200":{"description":"Actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contacto"}}}},"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contacto"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos/{id}":{"get":{"tags":["Contactos"],"summary":"Un contacto, con sus listas","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contacto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contacto"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Contactos"],"summary":"Editar un contacto","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditarContacto"}}}},"responses":{"200":{"description":"Contacto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contacto"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Contactos"],"summary":"Borrar un contacto (sale de todas sus listas)","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Borrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultadoBorrado"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos/eliminar":{"post":{"tags":["Contactos"],"summary":"Borrar varios contactos (por id o por número, máximo 500)","x-permiso":"contactos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactoIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500},"numeros":{"type":"array","items":{"type":"string"},"maxItems":500},"codigoPais":{"type":"string"}}}}}},"responses":{"200":{"description":"Borrados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultadoBorrado"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos/importar":{"post":{"tags":["Contactos"],"summary":"Importar contactos (lista, CSV o URL pública; máximo 2000)","x-permiso":"contactos","description":"Con `vistaPrevia: true` solo informa (válidos, inválidos con motivo, nuevos, existentes) y no guarda nada. Los números que ya existen no se tocan salvo `actualizarExistentes: true`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Importacion"}}}},"responses":{"200":{"description":"Reporte o vista previa","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"creados":{"type":"integer"},"actualizados":{"type":"integer"},"omitidos":{"type":"integer"},"invalidos":{"type":"integer"},"errores":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos/duplicados":{"get":{"tags":["Contactos"],"summary":"Posibles contactos duplicados (no cambia nada)","x-permiso":"lectura","parameters":[{"name":"limite","in":"query","schema":{"type":"integer","maximum":200,"default":50}}],"responses":{"200":{"description":"Grupos","content":{"application/json":{"schema":{"type":"object","properties":{"grupos":{"type":"array","items":{"type":"object","properties":{"motivo":{"type":"string","enum":["mismo_numero","mismo_correo","mismo_nombre"]},"contactos":{"type":"array","items":{"type":"object"}}}}},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas":{"get":{"tags":["Listas"],"summary":"Tus listas de contactos","x-permiso":"lectura","responses":{"200":{"description":"Listas","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Lista"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Listas"],"summary":"Crear una lista (si ya existe una con ese nombre, la devuelve)","x-permiso":"contactos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nombre"],"properties":{"nombre":{"type":"string","maxLength":150},"descripcion":{"type":"string"},"color":{"type":"string","example":"#3b82f6"}}}}}},"responses":{"200":{"description":"Ya existía","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lista"}}}},"201":{"description":"Creada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lista"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/{id}":{"get":{"tags":["Listas"],"summary":"Una lista con sus contactos (paginado)","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"porPagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lista"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Listas"],"summary":"Cambiar nombre, descripción o color","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","maxLength":150},"descripcion":{"type":"string"},"color":{"type":"string","example":"#3b82f6"}}}}}},"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lista"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Listas"],"summary":"Borrar la lista (los contactos se conservan)","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Borrada"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/{id}/duplicar":{"post":{"tags":["Listas"],"summary":"Copiar la lista con sus contactos","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string"}}}}}},"responses":{"201":{"description":"Copia","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lista"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/{id}/vaciar":{"post":{"tags":["Listas"],"summary":"Sacar todos los contactos de la lista (siguen en la cuenta)","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Vaciada"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/mover":{"post":{"tags":["Listas"],"summary":"Mover (o copiar) contactos de una lista a otra","x-permiso":"contactos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origenId","destinoId"],"properties":{"origenId":{"type":"string","format":"uuid"},"destinoId":{"type":"string","format":"uuid"},"contactoIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sin esto, todos."},"copiar":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Resultado"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/{id}/contactos":{"post":{"tags":["Listas"],"summary":"Agregar contactos a una lista (por id o por número; los números nuevos se crean)","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id de la lista","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactoIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":1000},"numeros":{"type":"array","maxItems":1000,"items":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/NuevoContacto"}]}},"codigoPais":{"type":"string"}}}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"agregados":{"type":"integer"},"yaEstaban":{"type":"integer"},"contactoIds":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listas/{id}/contactos/{contactoId}":{"delete":{"tags":["Listas"],"summary":"Quitar un contacto de una lista","x-permiso":"contactos","parameters":[{"name":"id","in":"path","required":true,"description":"Id de la lista","schema":{"type":"string","format":"uuid"}},{"name":"contactoId","in":"path","required":true,"description":"Id del contacto","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listo"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas":{"get":{"tags":["Campañas"],"summary":"Tus campañas a contactos","x-permiso":"lectura","parameters":[{"name":"estado","in":"query","schema":{"type":"string","enum":["borrador","pendiente","ejecutando","pausado","completado","error","cancelado","no_enviado"]}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"porPagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Página","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Campana"}},"pagina":{"type":"integer"},"porPagina":{"type":"integer"},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Campañas"],"summary":"Crear una campaña (queda como borrador salvo enviarDirecto + permiso campanas_enviar)","x-permiso":"campanas","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Valor único por operación. Si la integración reintenta con la misma clave, no se duplica.","schema":{"type":"string","maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevaCampana"}}}},"responses":{"201":{"description":"Creada","content":{"application/json":{"schema":{"type":"object","properties":{"campana":{"$ref":"#/components/schemas/Campana"},"aviso":{"type":["string","null"]},"plantilla":{"type":["object","null"]},"avisos":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}":{"get":{"tags":["Campañas"],"summary":"Estado y resultados de una campaña","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Campañas"],"summary":"Editar una campaña en borrador, pendiente o no enviada","x-permiso":"campanas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string"},"texto":{"type":"string"},"archivoUrl":{"type":"string"},"programadoPara":{"type":["string","null"],"format":"date-time"},"pausaMinima":{"type":"integer"},"pausaMaxima":{"type":"integer"}}}}}},"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No editable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Campañas"],"summary":"Borrar una campaña y su historial (no si está enviando)","x-permiso":"campanas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Borrada"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Está enviando","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/destinatarios":{"get":{"tags":["Campañas"],"summary":"Destinatarios con su estado","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}},{"name":"estado","in":"query","schema":{"type":"string","enum":["pendiente","enviado","entregado","leido","respondido","fallido","omitido"]}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"porPagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Página","content":{"application/json":{"schema":{"type":"object","properties":{"resumen":{"type":"object"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/Destinatario"}},"pagina":{"type":"integer"},"porPagina":{"type":"integer"},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/validar":{"get":{"tags":["Campañas"],"summary":"Revisar antes de enviar: a cuántos, por qué números, cuándo, problemas y avisos","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidacionCampana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/respuestas":{"get":{"tags":["Campañas"],"summary":"Quién respondió y qué dijo primero","x-permiso":"bandeja","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}},{"name":"limite","in":"query","schema":{"type":"integer","maximum":200}}],"responses":{"200":{"description":"Respuestas"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/pausar":{"post":{"tags":["Campañas"],"summary":"Pausar una campaña que está enviando","x-permiso":"campanas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No está enviando","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/reanudar":{"post":{"tags":["Campañas"],"summary":"Reanudar una campaña pausada","x-permiso":"campanas_enviar","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No está pausada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/cancelar":{"post":{"tags":["Campañas"],"summary":"Cancelar una campaña (los pendientes no salen)","x-permiso":"campanas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/reintentar":{"post":{"tags":["Campañas"],"summary":"Reintentar los envíos fallidos","x-permiso":"campanas_enviar","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Resultado"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/duplicar":{"post":{"tags":["Campañas"],"summary":"Copiar la campaña como borrador nuevo","x-permiso":"campanas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string"}}}}}},"responses":{"201":{"description":"Copia"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/eventos":{"get":{"tags":["Eventos"],"summary":"Los eventos que se pueden recibir, con un ejemplo de cada uno","x-permiso":"eventos","responses":{"200":{"description":"Catálogo","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Evento"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suscripciones":{"get":{"tags":["Eventos"],"summary":"Tus webhooks","x-permiso":"eventos","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Suscripcion"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Eventos"],"summary":"Crear un webhook (devuelve la clave para verificar la firma, una sola vez)","x-permiso":"eventos","description":"La dirección tiene que ser https:// y pública. Los webhooks creados con una clave se borran si se borra esa clave.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","eventos"],"properties":{"url":{"type":"string","example":"https://n8n.tudominio.com/webhook/wicloud"},"eventos":{"type":"array","items":{"type":"string","enum":["mensaje.recibido","campana.respuesta","campana.terminada","instancia.desconectada","instancia.conectada","contacto.creado","contacto.actualizado","contacto.eliminado","lista.creada","lista.actualizada","campana.creada","campana.iniciada","campana.pausada","campana.fallida","mensaje.en_cola","mensaje.enviado","mensaje.entregado","mensaje.leido","mensaje.fallido","contacto.baja"]}},"nombre":{"type":"string"}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Suscripcion"},{"type":"object","properties":{"secreto":{"type":"string","description":"Guárdalo: no se vuelve a mostrar."}}}]}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suscripciones/{id}":{"delete":{"tags":["Eventos"],"summary":"Borrar un webhook","x-permiso":"eventos","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listo"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas/{id}/enviar":{"post":{"tags":["Campañas"],"summary":"Aprobar y enviar un borrador","x-permiso":"campanas_enviar","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campana"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/conversaciones":{"get":{"tags":["Conversaciones"],"summary":"Buscar chats (sin responder, no leídos, por número o texto)","x-permiso":"bandeja","parameters":[{"name":"sinResponder","in":"query","schema":{"type":"boolean"}},{"name":"noLeidos","in":"query","schema":{"type":"boolean"}},{"name":"numero","in":"query","schema":{"type":"string"}},{"name":"texto","in":"query","schema":{"type":"string"}},{"name":"horas","in":"query","schema":{"type":"integer"}},{"name":"limite","in":"query","schema":{"type":"integer","maximum":100,"default":20}}],"responses":{"200":{"description":"Conversaciones","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/conversaciones/{id}":{"get":{"tags":["Conversaciones"],"summary":"Los últimos mensajes de un chat","x-permiso":"bandeja","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}},{"name":"limite","in":"query","schema":{"type":"integer","maximum":100,"default":30}}],"responses":{"200":{"description":"Mensajes"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plantillas":{"get":{"tags":["Plantillas"],"summary":"Tus plantillas y las globales","x-permiso":"lectura","parameters":[{"name":"buscar","in":"query","schema":{"type":"string"}},{"name":"tipo","in":"query","schema":{"type":"string"}},{"name":"soloPropias","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Plantillas","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Plantilla"}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Plantillas"],"summary":"Crear una plantilla (texto o archivo)","x-permiso":"plantillas","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevaPlantilla"}}}},"responses":{"201":{"description":"Creada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plantilla"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plantillas/{id}":{"get":{"tags":["Plantillas"],"summary":"Una plantilla","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Plantilla","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plantilla"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Plantillas"],"summary":"Editar una plantilla propia","x-permiso":"plantillas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevaPlantilla"}}}},"responses":{"200":{"description":"Plantilla","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plantilla"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Plantillas"],"summary":"Borrar una plantilla propia","x-permiso":"plantillas","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Borrada"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plantillas/{id}/previsualizar":{"post":{"tags":["Plantillas"],"summary":"Cómo quedaría para un contacto y qué variables faltan","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contactoId":{"type":"string","format":"uuid"},"numero":{"type":"string"},"variables":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"Vista previa","content":{"application/json":{"schema":{"type":"object","properties":{"textoFinal":{"type":"string"},"variablesUsadas":{"type":"array","items":{"type":"string"}},"variablesFaltantes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/estados":{"get":{"tags":["Estados"],"summary":"Estados publicados en las últimas 24 h","x-permiso":"estados","parameters":[{"name":"instanciaId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estados"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Estados"],"summary":"Publicar un estado (texto con color y fuente, o imagen/video con pie)","x-permiso":"estados","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevoEstado"}}}},"responses":{"201":{"description":"Publicado"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/estados/{id}":{"delete":{"tags":["Estados"],"summary":"Pedir a WhatsApp que borre un estado publicado","x-permiso":"estados","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Borrado"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"El motor lo rechazó","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/estadisticas":{"get":{"tags":["Reportes"],"summary":"Resumen de los últimos N días","x-permiso":"lectura","parameters":[{"name":"dias","in":"query","schema":{"type":"integer","maximum":90,"default":7}}],"responses":{"200":{"description":"Resumen"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/grupos":{"get":{"tags":["Grupos"],"summary":"Tus grupos de WhatsApp (sincronizados en el panel)","x-permiso":"lectura","parameters":[{"name":"instanciaId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"buscar","in":"query","schema":{"type":"string"}},{"name":"limite","in":"query","schema":{"type":"integer","maximum":500,"default":100}}],"responses":{"200":{"description":"Grupos","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Grupo"}},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas-grupos":{"get":{"tags":["Grupos"],"summary":"Tus campañas a grupos","x-permiso":"lectura","parameters":[{"name":"estado","in":"query","schema":{"type":"string"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"porPagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Campañas","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/CampanaGrupos"}},"total":{"type":"integer"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Grupos"],"summary":"Enviar (o programar) una campaña a grupos — sale de verdad","x-permiso":"campanas_enviar","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevaCampanaGrupos"}}}},"responses":{"201":{"description":"Campaña","content":{"application/json":{"schema":{"type":"object","properties":{"campana":{"$ref":"#/components/schemas/CampanaGrupos"},"avisos":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Grupo no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas-grupos/validar":{"post":{"tags":["Grupos"],"summary":"Revisar una campaña a grupos sin crearla (grupos, participantes y avisos)","x-permiso":"campanas","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevaCampanaGrupos"}}}},"responses":{"200":{"description":"Vista previa"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campanas-grupos/{id}":{"get":{"tags":["Grupos"],"summary":"Una campaña a grupos, con entregados y leídos por grupo (48 h)","x-permiso":"lectura","parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaña","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampanaGrupos"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/canales":{"get":{"tags":["Canales"],"summary":"Canales de WhatsApp de un número","x-permiso":"lectura","parameters":[{"name":"instanciaId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Canales"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/canales/{jid}/publicaciones":{"get":{"tags":["Canales"],"summary":"Últimas publicaciones de un canal, con vistas y reacciones","x-permiso":"lectura","parameters":[{"name":"jid","in":"path","required":true,"schema":{"type":"string","example":"120363000000000000@newsletter"}},{"name":"instanciaId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limite","in":"query","schema":{"type":"integer","maximum":100,"default":20}}],"responses":{"200":{"description":"Publicaciones"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/canales/{jid}/publicar":{"post":{"tags":["Canales"],"summary":"Publicar texto, imagen o video en un canal","x-permiso":"canales","parameters":[{"name":"jid","in":"path","required":true,"schema":{"type":"string","example":"120363000000000000@newsletter"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["texto","imagen","video"],"default":"texto"},"texto":{"type":"string"},"archivoUrl":{"type":"string"},"instanciaId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Publicado"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bajas":{"get":{"tags":["Contactos"],"summary":"Bajas automáticas: si están activas y qué palabras las disparan","x-permiso":"lectura","responses":{"200":{"description":"Configuración","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bajas"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Contactos"],"summary":"Cambiar las bajas automáticas","x-permiso":"contactos","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bajas"}}}},"responses":{"200":{"description":"Configuración","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bajas"}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contactos/completar-datos":{"post":{"tags":["Contactos"],"summary":"Completar nombre, foto y si es empresa desde WhatsApp (solo campos vacíos, hasta 300, por detrás)","x-permiso":"contactos","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactoIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":300},"listaId":{"type":"string","format":"uuid"},"instanciaId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"En proceso","content":{"application/json":{"schema":{"type":"object","properties":{"enProceso":{"type":"boolean"},"contactos":{"type":"integer","description":"Cuántos se van a consultar ahora (máx. 300)"},"pendientesDespues":{"type":"integer","description":"Los que quedan para una próxima vez"}}}}}},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reportes":{"get":{"tags":["Reportes"],"summary":"Reporte por campañas, números, listas o motivos de fallo","x-permiso":"lectura","parameters":[{"name":"tipo","in":"query","required":true,"schema":{"type":"string","enum":["campanas","numeros","listas","fallos"]}},{"name":"dias","in":"query","schema":{"type":"integer","maximum":365,"default":30}}],"responses":{"200":{"description":"Reporte"},"400":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan sin API, plan vencido o clave sin el permiso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de pedidos por minuto (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"claveApi":{"type":"http","scheme":"bearer","bearerFormat":"wic_…","description":"Clave de API de tu panel (también se acepta el header X-API-Key)."}},"schemas":{"Evento":{"type":"object","properties":{"evento":{"type":"string","enum":["mensaje.recibido","campana.respuesta","campana.terminada","instancia.desconectada","instancia.conectada","contacto.creado","contacto.actualizado","contacto.eliminado","lista.creada","lista.actualizada","campana.creada","campana.iniciada","campana.pausada","campana.fallida","mensaje.en_cola","mensaje.enviado","mensaje.entregado","mensaje.leido","mensaje.fallido","contacto.baja"]},"titulo":{"type":"string"},"descripcion":{"type":"string"},"ejemplo":{"type":"object"}}},"Suscripcion":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"url":{"type":"string"},"eventos":{"type":"array","items":{"type":"string"}},"origen":{"type":"string","enum":["panel","api"]},"activa":{"type":"boolean"},"fallosSeguidos":{"type":"integer"},"motivoPausa":{"type":["string","null"]},"creadoEn":{"type":"string"}}},"Error":{"type":"object","properties":{"statusCode":{"type":"integer"},"codigo":{"type":"string","example":"INSTANCIA_DESCONECTADA"},"message":{"type":"string"}}},"Cuenta":{"type":"object","properties":{"usuario":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"usuario":{"type":"string"},"correo":{"type":"string"}}},"plan":{"type":"object","properties":{"nombre":{"type":["string","null"]},"venceEl":{"type":["string","null"],"format":"date-time"}}},"clave":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"permisos":{"type":"array","items":{"type":"string","enum":["lectura","mensajes","contactos","campanas","campanas_enviar","eventos","bandeja","plantillas","estados","canales"]}}}},"limites":{"type":"object","properties":{"pedidosPorMinuto":{"type":"integer"},"mensajesEnCola":{"type":"integer"}}},"codigoPaisPorDefecto":{"type":["string","null"],"example":"+593"},"estado":{"type":"string","example":"activo"},"zonaHoraria":{"type":"string","example":"America/Guayaquil"},"horarioEnvio":{"type":"object"},"pais":{"type":["object","null"]},"consumoHoy":{"type":"object","properties":{"mensajesApi":{"type":"integer"},"enCola":{"type":"integer"},"campanasCreadas":{"type":"integer"},"enviadosEnCampanas":{"type":"integer"}}},"version":{"type":"string"}}},"InstanciaDetalle":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"numero":{"type":["string","null"]},"estado":{"type":"string"},"conectada":{"type":"boolean"},"motor":{"type":"string"},"cupo":{"type":"object","properties":{"mensajesPorMinuto":{"type":["integer","null"]},"enCola":{"type":"integer"}}},"calidad":{"type":"object","properties":{"enviados7d":{"type":"integer"},"fallidos7d":{"type":"integer"},"tasaFalloPorcentaje":{"type":["number","null"]},"nivel":{"type":"string","enum":["buena","media","baja","sin_datos"]}}},"aptoCampanas":{"type":"boolean"},"campanasActivas":{"type":"integer"}}},"ResultadoBorrado":{"type":"object","properties":{"eliminados":{"type":"integer"},"contactos":{"type":"array","items":{"type":"object"}},"noEncontrados":{"type":"array","items":{"type":"string"}}}},"Importacion":{"type":"object","properties":{"contactos":{"type":"array","maxItems":2000,"items":{"type":"object","properties":{"numero":{"type":"string"},"nombre":{"type":"string"},"apellido":{"type":"string"},"correo":{"type":"string"},"empresa":{"type":"string"},"etiquetas":{"type":"array","items":{"type":"string"}}}}},"csv":{"type":"string","description":"Contenido CSV con cabecera (numero,nombre,apellido,correo,empresa…; separador , o ;)."},"url":{"type":"string","description":"URL pública https de un CSV o JSON (máximo 2 MB, sin redirecciones)."},"listaId":{"type":"string","format":"uuid"},"actualizarExistentes":{"type":"boolean","default":false},"vistaPrevia":{"type":"boolean","default":false},"codigoPais":{"type":"string"}}},"Destinatario":{"type":"object","properties":{"id":{"type":"string"},"contactoId":{"type":["string","null"]},"nombre":{"type":"string"},"numero":{"type":"string"},"estado":{"type":"string","enum":["pendiente","enviado","entregado","leido","respondido","fallido","omitido"]},"enviadoEn":{"type":["string","null"]},"entregadoEn":{"type":["string","null"]},"leidoEn":{"type":["string","null"]},"respondioEn":{"type":["string","null"]},"error":{"type":["string","null"]}}},"ValidacionCampana":{"type":"object","properties":{"listaParaEnviar":{"type":"boolean"},"problemas":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"mensaje":{"type":"string"}}}},"avisos":{"type":"array","items":{"type":"string"}},"resumen":{"type":"object"},"campana":{"$ref":"#/components/schemas/Campana"}}},"Plantilla":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"tipo":{"type":"string"},"texto":{"type":["string","null"]},"archivoUrl":{"type":["string","null"]},"etiquetas":{"type":"array","items":{"type":"string"}},"global":{"type":"boolean"},"propia":{"type":"boolean"},"vecesUsada":{"type":"integer"},"enviablePorApi":{"type":"boolean"},"variables":{"type":"array","items":{"type":"string"}}}},"NuevaPlantilla":{"type":"object","properties":{"nombre":{"type":"string","maxLength":150},"tipo":{"type":"string","enum":["texto","imagen","video","audio","documento"],"default":"texto"},"texto":{"type":"string","description":"Admite {nombre}, {apellido}, {empresa}, {var01}…"},"archivoUrl":{"type":"string"},"archivoNombre":{"type":"string"},"etiquetas":{"type":"array","items":{"type":"string"}}}},"Grupo":{"type":"object","properties":{"jid":{"type":"string","example":"120363012345678901@g.us"},"nombre":{"type":"string"},"instanciaId":{"type":"string"},"participantes":{"type":["integer","null"]},"soyAdmin":{"type":"boolean"},"soloAdminsEscriben":{"type":"boolean"}}},"NuevaCampanaGrupos":{"type":"object","required":["nombre","grupos"],"properties":{"nombre":{"type":"string"},"grupos":{"type":"array","items":{"type":"string"},"description":"Jid (…@g.us) o nombre exacto de cada grupo (máx. 500)."},"instanciaId":{"type":"string","format":"uuid","description":"Número que envía (por defecto, el primero conectado)."},"tipo":{"type":"string","enum":["texto","imagen","video","audio","documento"],"default":"texto"},"texto":{"type":"string","description":"Texto o pie del archivo. Admite spintax {Hola|Buenas}."},"archivoUrl":{"type":"string"},"archivoNombre":{"type":"string"},"mencionarTodos":{"type":"boolean","default":false,"description":"Notifica a todos los participantes aunque tengan el grupo silenciado. Úsalo con moderación."},"programadoPara":{"type":"string","description":"ISO 8601, minutos múltiplos de 10. Sin esto sale ya (dentro del horario de la cuenta)."},"pausaMinima":{"type":"integer","minimum":3,"maximum":300,"default":10},"pausaMaxima":{"type":"integer","minimum":3,"maximum":600,"default":20}}},"CampanaGrupos":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"estado":{"type":"string"},"tipo":{"type":"string"},"instancia":{"type":"object"},"totalGrupos":{"type":"integer"},"enviados":{"type":"integer"},"fallidos":{"type":"integer"},"mencionarTodos":{"type":"boolean"},"programadaPara":{"type":["string","null"]},"iniciadaEn":{"type":["string","null"]},"terminadaEn":{"type":["string","null"]},"entregas":{"type":"object","description":"Totales (solo en el detalle): entregados, leidos, participantes, gruposConDatos."},"grupos":{"type":"array","description":"Solo en el detalle: estado, entregados y leídos de cada grupo.","items":{"type":"object"}}}},"Bajas":{"type":"object","properties":{"activo":{"type":"boolean","description":"Si un contacto responde con una palabra de baja, se bloquea y sale de las campañas pendientes."},"bloquearEnWhatsapp":{"type":"boolean","description":"Además, bloquearlo en WhatsApp."},"palabras":{"type":"array","items":{"type":"string"},"description":"Una palabra suelta (BAJA, STOP) cuenta solo si es todo el mensaje; las frases cuentan dentro de un mensaje corto."}}},"NuevoEstado":{"type":"object","properties":{"tipo":{"type":"string","enum":["texto","imagen","video"],"default":"texto"},"texto":{"type":"string","description":"Texto del estado o pie de la imagen/video."},"colorFondo":{"type":"string","example":"#25D366","description":"Se usa el color más parecido de la paleta de WhatsApp."},"tipoFuente":{"type":"string","enum":["predeterminada","serif","negrita","cursiva","monoespaciada","manuscrita","decorativa"]},"archivoUrl":{"type":"string","description":"Imagen (jpg/png) o video .mp4."},"instanciaId":{"type":"string","format":"uuid"},"todos":{"type":"boolean","description":"Publicar en todos los números conectados."},"nombre":{"type":"string"}}},"Instancia":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"numero":{"type":["string","null"]},"perfil":{"type":["string","null"]},"estado":{"type":"string"},"conectada":{"type":"boolean"},"ultimaDesconexion":{"type":["string","null"]}}},"NuevoMensaje":{"type":"object","required":["numero"],"properties":{"numero":{"type":"string","example":"+593991234567"},"texto":{"type":"string","maxLength":4096,"description":"Obligatorio si tipo es texto; en archivos es el pie."},"tipo":{"type":"string","enum":["texto","imagen","video","audio","documento"],"default":"texto"},"archivoUrl":{"type":"string","description":"URL pública https del archivo, o uno de tu biblioteca de medios."},"archivoNombre":{"type":"string","description":"Nombre visible del documento."},"instanciaId":{"type":"string","format":"uuid","description":"Desde qué número enviar. Si no se manda, el primero conectado."},"programadoPara":{"type":"string","format":"date-time","description":"Para enviarlo más tarde (hasta 90 días)."},"codigoPais":{"type":"string","example":"+593","description":"Para números sin código de país."},"plantillaId":{"type":"string","description":"Id (o nombre en `plantilla`) de una plantilla: reemplaza tipo/texto/archivo."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Valores para las variables de la plantilla (pisan los del contacto)."}}},"Mensaje":{"type":"object","properties":{"id":{"type":"string"},"estado":{"type":"string","enum":["en_cola","enviando","enviado","fallido","cancelado"]},"estadoEntrega":{"type":["string","null"],"enum":["entregado","leido",null],"description":"Lo que avisó WhatsApp después del envío."},"entregadoEn":{"type":["string","null"]},"leidoEn":{"type":["string","null"]},"plantillaId":{"type":["string","null"]},"numero":{"type":"string"},"tipo":{"type":"string"},"texto":{"type":["string","null"]},"archivoUrl":{"type":["string","null"]},"instanciaId":{"type":"string"},"intentos":{"type":"integer"},"error":{"type":["string","null"]},"idWhatsapp":{"type":["string","null"]},"programadoPara":{"type":["string","null"]},"enviadoEn":{"type":["string","null"]},"creadoEn":{"type":"string"}}},"Variables":{"type":"object","description":"Campos libres que puedes usar en los mensajes como {var01}…{var05}","properties":{"var01":{"type":"string"},"var02":{"type":"string"},"var03":{"type":"string"},"var04":{"type":"string"},"var05":{"type":"string"}}},"NuevoContacto":{"type":"object","required":["numero"],"properties":{"numero":{"type":"string","example":"+593991234567"},"nombre":{"type":"string"},"apellido":{"type":"string"},"correo":{"type":"string"},"empresa":{"type":"string"},"cargo":{"type":"string"},"notas":{"type":"string"},"etiquetas":{"type":"array","items":{"type":"string"},"maxItems":20},"variables":{"$ref":"#/components/schemas/Variables"},"listaIds":{"type":"array","items":{"type":"string","format":"uuid"}},"codigoPais":{"type":"string"}}},"EditarContacto":{"type":"object","properties":{"numero":{"type":"string"},"nombre":{"type":"string"},"apellido":{"type":"string"},"correo":{"type":"string"},"empresa":{"type":"string"},"cargo":{"type":"string"},"notas":{"type":"string"},"etiquetas":{"type":"array","items":{"type":"string"},"maxItems":20},"variables":{"$ref":"#/components/schemas/Variables"},"listaIds":{"type":"array","description":"Listas a las que se agrega (no quita de otras).","items":{"type":"string","format":"uuid"}}}},"Contacto":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"apellido":{"type":["string","null"]},"numero":{"type":"string"},"correo":{"type":["string","null"]},"empresa":{"type":["string","null"]},"cargo":{"type":["string","null"]},"notas":{"type":["string","null"]},"etiquetas":{"type":"array","items":{"type":"string"}},"origen":{"type":["string","null"],"example":"api"},"variables":{"$ref":"#/components/schemas/Variables"},"bloqueado":{"type":"boolean"},"vecesContactado":{"type":"integer"},"ultimoContacto":{"type":["string","null"]},"listas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"}}}},"creadoEn":{"type":"string"},"actualizadoEn":{"type":"string"}}},"Lista":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"descripcion":{"type":["string","null"]},"color":{"type":"string"},"totalContactos":{"type":"integer"},"creadoEn":{"type":"string"}}},"NuevaCampana":{"type":"object","required":["nombre"],"properties":{"nombre":{"type":"string"},"tipo":{"type":"string","enum":["texto","imagen","video","audio","documento"],"default":"texto"},"texto":{"type":"string","description":"Admite {nombre}, {empresa}, {var01}… y spintax {Hola|Buenas}."},"archivoUrl":{"type":"string"},"archivoNombre":{"type":"string"},"listaId":{"type":"string","format":"uuid","description":"A quién: una lista…"},"plantillaId":{"type":"string","description":"Id o nombre de una plantilla: se copia su contenido (si después cambia, la campaña no)."},"numeros":{"type":"array","maxItems":5000,"description":"…o números sueltos (texto o {numero, nombre, variables}).","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"numero":{"type":"string"},"nombre":{"type":"string"},"variables":{"type":"object"}}}]}},"instanciaIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Números que envían (rotan). Si no se manda, el primero conectado."},"programadoPara":{"type":"string","format":"date-time","description":"Se redondea al siguiente múltiplo de 10 minutos."},"pausaMinima":{"type":"integer","description":"Segundos entre mensajes. Nunca menos que el mínimo de seguridad según el tamaño."},"pausaMaxima":{"type":"integer"},"enviarDirecto":{"type":"boolean","default":false,"description":"Solo con el permiso campanas_enviar. Si no, queda como borrador."},"codigoPais":{"type":"string"}}},"Campana":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"estado":{"type":"string"},"tipo":{"type":"string"},"texto":{"type":["string","null"]},"archivoUrl":{"type":["string","null"]},"totalContactos":{"type":"integer"},"enviados":{"type":"integer"},"fallidos":{"type":"integer"},"pendientes":{"type":"integer"},"instancias":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"}}}},"programadoPara":{"type":["string","null"]},"iniciadaEn":{"type":["string","null"]},"terminadaEn":{"type":["string","null"]},"error":{"type":["string","null"]},"origen":{"type":"string","example":"api:n8n"},"creadoEn":{"type":"string"}}}}}}