Fuente: https://crm.begraffic.com/docs/api
Índice para agentes: [llms.txt](https://crm.begraffic.com/llms.txt)

# API v1 de Be CRM

Versión: 1.0.0

API pública v1 de Be CRM. Autenticación con `Authorization: Bearer <clave>` (claves v1 de Ajustes → API, con alcances). Errores `{error:{code,message,details?}, requestId}`; listas `{data, nextCursor}`. Límite por clave: 120 llamadas por minuto (cabeceras `X-RateLimit-*`, `Retry-After` en el 429). Toda escritura acepta `Idempotency-Key`. Solo de servidor a servidor: no hay CORS.

Las claves v1 empiezan por bcrm_. Las claves clásicas bmkt_ y los ID tokens de sesión no sirven aquí. Para conectar una plataforma mediante login y selección de workspace, sigue [BeCRM Connect](https://crm.begraffic.com/docs/becrm-connect.md): registro, PKCE, callback, tokens OAuth, renovación y desconexión. Estos tokens también autentican la API v1. Nunca incluir claves reales en el contexto de un LLM.

GET /api/v1/me incluye el [estado de correo, SMS, WhatsApp y Telegram](https://crm.begraffic.com/docs/becrm-channels.md) en data.integrations: configuración, plan, permisos y enlaces a los ajustes de BeCRM.

Un recurso devuelve {data}; una lista {data: [...], nextCursor}. Usar cursor=nextCursor hasta recibir null.

La misma Idempotency-Key y el mismo cuerpo reproducen la respuesta durante la retención de 24 h; otro cuerpo devuelve 422 y una operación en curso, 409. En /messaging/messages la cabecera es obligatoria. WhatsApp consume cuota del plan y SMS saldo: 402 requiere resolver el límite antes de reintentar.

# API externa: WhatsApp y SMS

La mensajería usa `/api/v1`. La referencia de endpoints está en [/docs/api](https://crm.begraffic.com/docs/api)
y la especificación OpenAPI en [`/api/v1/openapi.json`](https://crm.begraffic.com/api/v1/openapi.json).
Las rutas de correo y leads existentes siguen funcionando.

## Autenticación y disponibilidad

Crear una clave v1 (`bcrm_...`) en **Ajustes → API** y enviar la cabecera
`Authorization: Bearer <API_KEY_DEL_WORKSPACE>` en todas las llamadas. Las claves antiguas
`bmkt_...` y los tokens de sesión no sirven para estas rutas. Usar la clave solo desde tu servidor.
Alcances: `conversations:read` para consultar; `conversations:write` para enviar;
`webhooks:manage` para suscribir el receptor. La clave decide el workspace: nunca se acepta un
`tableId` del cliente. Se mantienen bloqueo por límite de contactos, rate limit, cuota de
WhatsApp y saldo de SMS del CRM.

`GET /api/v1/messaging/channels` devuelve números propios y tipos de mensaje. No expone tokens,
secretos de Meta ni credenciales AWS. `configured=false` implica que no hay número utilizable.
Un envío sin número configurado/activo, con token vencido o solicitando un número ajeno se
rechaza con **403 `feature_disabled`** antes de contactar al proveedor. Las respuestas a
conversaciones antiguas también verifican el número original. El historial se conserva consultable.

Cada número incluye `canSend`, `canReceive` y `reason`. **`canReceive=null` significa desconocido**:
un token válido o un número activo no prueban que el webhook o la recepción bidireccional estén
configurados. Para SMS la recepción requiere two-way habilitado por el proveedor y su ruta de
entrada al CRM; cuando el mirror tenga `twoWayEnabled`, se informa ese valor. La API externa
no habilita ni compra números automáticamente.

## Ventana de WhatsApp y plantillas

`GET /api/v1/conversations/{id}/capabilities` para WhatsApp y SMS:

```json
{
  "data": {
    "conversationId": "whatsapp__18095551234",
    "channel": "whatsapp",
    "checkedAt": "2026-10-01T16:00:00.000Z",
    "phoneNumberId": "123456789",
    "configured": true,
    "canSend": true,
    "reason": null,
    "canSendDirect": true,
    "canSendTemplate": true,
    "supportedMessageTypes": [
      "text",
      "template",
      "image",
      "audio",
      "interactive.button",
      "interactive.list",
      "interactive.cta_url"
    ],
    "window": {
      "lastInboundAt": "2026-10-01T15:00:00.000Z",
      "expiresAt": "2026-10-02T15:00:00.000Z",
      "open": true,
      "remainingSeconds": 82800,
      "templateRequired": false
    }
  }
}
```

La ventana dura 24 horas desde el último mensaje del **contacto**. Un envío nuestro, incluida una
plantilla, no la abre ni renueva. Al vencer exactamente las 24 horas, `open=false`, quedan cero
segundos y se necesita plantilla. Sin mensaje entrante, la ventana está cerrada. Botones, listas,
CTA, imágenes y audio libres requieren ventana abierta. SMS devuelve `window=null`, no requiere
plantillas ni ventana y admite texto con enlaces, sin botones nativos.

Las capacidades son una foto informativa: no reservan cuota/saldo ni garantizan aceptación por
Meta/AWS. El envío vuelve a comprobar las condiciones, incluida la baja del contacto en WhatsApp.
SMS estima el coste según contenido/segmentación antes del envío. El proveedor puede rechazar
un destinatario dado de baja aunque la consulta previa permita enviar.

`GET /api/v1/messaging/whatsapp/templates?phoneNumberId=123456789&limit=50` lista el espejo local
de la **WABA de ese número**, paginado con `nextCursor`. Devuelve `name`, `language`, `status`,
`category` y `components` (cabecera, cuerpo y botones). Solo usar `APPROVED`; Meta decide el estado
vigente al enviar. El idioma es el código exacto de Meta, por ejemplo `es`, `es_MX` o `en_US`.
Las plantillas legacy sin WABA se omiten para no ofrecer una plantilla de otra cuenta.
Sin `phoneNumberId`, se consulta el número predeterminado. Sin WABA identificada se rechaza la consulta.

## Enviar e iniciar conversaciones

`POST /api/v1/messaging/messages`. Cabeceras:

```http
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: pedido-1042-confirmacion
```

**Idempotency-Key es obligatoria en esta ruta.** Reutilizar la misma clave para el mismo cuerpo
reproduce la respuesta, sin reenviar. Usar una clave distinta por operación lógica, nunca por
cada reintento. La reserva tiene retención TTL de 24 horas; después de su eliminación la clave puede reenviar.

Texto con vista previa de enlace, dentro de la ventana:

```json
{
  "channel": "whatsapp",
  "to": "+18095551234",
  "phoneNumberId": "123456789",
  "message": {
    "type": "text",
    "text": "Consulta https://example.com/pedido/1042",
    "previewUrl": true
  }
}
```

Plantilla (dentro o fuera de la ventana), con variables de cuerpo y botón URL:

```json
{
  "channel": "whatsapp",
  "to": "+18095551234",
  "phoneNumberId": "123456789",
  "message": {
    "type": "template",
    "template": {
      "name": "pedido_confirmado",
      "language": "es",
      "components": [
        { "type": "body", "parameters": [{ "type": "text", "text": "Ana" }] },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [{ "type": "text", "text": "1042" }]
        }
      ]
    }
  }
}
```

Los componentes deben coincidir con la plantilla aprobada en Meta. Las plantillas con parámetros
nombrados necesitan `parameter_name` en cada parámetro. También se admiten componentes de
cabecera y botones quick reply/copy code según la plantilla.

Botones de respuesta rápida:

```json
{
  "channel": "whatsapp",
  "to": "+18095551234",
  "phoneNumberId": "123456789",
  "message": {
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "¿Confirmas tu cita?" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "confirmar", "title": "Confirmar" } },
          { "type": "reply", "reply": { "id": "cambiar", "title": "Cambiar fecha" } }
        ]
      }
    }
  }
}
```

Hasta tres botones, título máximo de 20 caracteres e identificadores únicos. Para listas usar:

```json
{
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": { "text": "Elige un servicio" },
    "action": {
      "button": "Ver servicios",
      "sections": [
        {
          "title": "Servicios",
          "rows": [{ "id": "consulta", "title": "Consulta", "description": "Agenda una llamada" }]
        }
      ]
    }
  }
}
```

Hasta diez filas **en total**, ids únicos, títulos de fila de hasta 24 caracteres y descripciones
de hasta 72. Si hay varias secciones, todas requieren título.

Enlace con botón CTA:

```json
{
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": { "text": "Puedes agendar aquí" },
    "action": {
      "name": "cta_url",
      "parameters": { "display_text": "Agendar", "url": "https://example.com/agenda" }
    }
  }
}
```

Imagen: `{"type":"image","image":{"link":"https://example.com/foto.jpg","caption":"Tu pedido"}}`.
Audio: `{"type":"audio","audio":{"link":"https://example.com/audio.ogg"}}`.
Los enlaces de medios deben ser accesibles para Meta y cumplir la validación del servicio de envío.
No se aceptan `media_id` externos, que podrían pertenecer a otro número.

SMS:

```json
{
  "channel": "sms",
  "to": "+18095551234",
  "phoneNumberId": "sms-number-id-del-crm",
  "text": "Tu cita: https://example.com/cita/1042",
  "messageType": "TRANSACTIONAL"
}
```

SMS admite hasta 1600 caracteres; `messageType` admite `TRANSACTIONAL` (predeterminado) o
`PROMOTIONAL`. `phoneNumberId` es el id mostrado en `/messaging/channels`. Sin selección se usa un
número activo del workspace. Si hay varios, seleccionar explícitamente para conservar el origen.

`leadId` es opcional: si se incluye debe existir en el workspace y su teléfono debe coincidir con
el destino. No se reasigna una conversación que ya pertenezca a otro contacto. En WhatsApp,
una conversación existente por otro número devuelve **409 `conflict`**; la API no cambia su
origen silenciosamente. La estructura actual del CRM tiene un chat WhatsApp por destinatario.

Éxito: **201** con `data: {conversationId, channel, messageId, status:"sent"}`. `sent` indica que
el proveedor aceptó el envío, no que lo haya entregado. El índice de conversaciones se proyecta
asíncronamente: una conversación recién creada puede tardar en aparecer en lecturas.

## Responder y recibir

La ruta existente `POST /api/v1/conversations/{id}/reply` conserva `{"text":"..."}` y
`{"template":{...}}`; ahora también admite `{"message":{...}}` para los mensajes WhatsApp descritos.
Debe enviarse exactamente uno de `text`, `template` o `message`. Recomendada `Idempotency-Key`
también en esta ruta. Sale por el número por el que llegó la conversación.

Para recibir en tiempo real, registrar un destino con el mecanismo existente:

```http
POST /api/v1/webhooks
Authorization: Bearer <CLAVE_CON_WEBHOOKS_MANAGE>
Content-Type: application/json
```

```json
{
  "name": "Mi plataforma",
  "url": "https://example.com/webhooks/becrm",
  "events": ["message.received"],
  "active": true
}
```

Guardar el secreto devuelto al crear. El CRM entrega el sobre de evento existente con `id`,
`event`, `timestamp` y `data`; filtrar `data.channel` por `whatsapp`/`sms`. Verificar
`X-Webhook-Signature` como HMAC-SHA256 de **`timestamp + "." + cuerpo HTTP original`**, con el
secreto del destino y prefijo `sha256=`. Usar comparación en tiempo constante, validar el timestamp del evento considerando los retrasos de los reintentos y deduplicar por id de evento. Persistir el evento y
responder 2xx rápidamente; procesarlo después. El sistema existente proporciona reintentos durables.

El catálogo efectivo se consulta en `GET /api/v1/webhooks/events` (`available` indica emisión
habilitada). Para WhatsApp, la cuenta conectada debe recibir mensajes en el CRM. Para SMS,
se necesita un número con recepción bidireccional habilitada y conectado al CRM.
Confirma la recepción en el CRM antes de conectar el webhook de tu plataforma.

Después del evento, consultar `GET /api/v1/conversations/{id}/messages`. El `conversationId`
de `data` del webhook conserva el contrato histórico: es el id del chat **sin** prefijo de canal;
para la API usar `whatsapp__{conversationId}` o `sms__{conversationId}`.
Los mensajes se paginan del más reciente al más antiguo y excluyen notas internas. Los DTO
WhatsApp/SMS incorporan `messageType`, `deliveryStatus`, `replyToMessageId` e `interaction`.
Una selección de botón/lista devuelve, por ejemplo:

```json
{
  "interaction": {
    "type": "button_reply",
    "id": "confirmar",
    "title": "Confirmar",
    "description": null
  }
}
```

`deliveryStatus` refleja el estado guardado por el webhook de Meta; puede ser null o cambiar a
`delivered`, `read`, `failed`, etc. No se ha añadido un evento público de entrega SMS/WhatsApp:
para WhatsApp consultar mensajes; SMS no tiene confirmación de entrega expuesta en este contrato.
La conservación de ids de botones se aplica a los mensajes recibidos tras desplegar Functions.
El historial antiguo que no guardó estos campos no puede reconstruirlos.

## Errores

- 400 `invalid_request`: formato, combinación de mensajes, SMS demasiado largo o falta de idempotencia.
- 401/403: clave inválida, permisos insuficientes o 403 `feature_disabled` por integración no disponible.
- 402 `quota_exceeded`: cuota WhatsApp o saldo SMS; `contact_limit_exceeded` si el workspace está bloqueado.
- 404 `not_found`: conversación oculta/ajena o contacto inexistente.
- 409 `invalid_state`: ventana vencida, baja o rechazo permanente del proveedor; revisar `details.reason`.
- 409 `conflict`: número/contacto no coincide con la conversación.
- 409 `unknown_outcome`: pudo enviarse, pero no hubo respuesta. No cambiar de clave ni reenviar automáticamente.
- 429 `rate_limited`: respetar `Retry-After`; 503 `unavailable`: fallo recuperable conocido sin envío.

## Verificar tu integración

Con números de prueba propios, comprobar la recepción WhatsApp, el tiempo restante de la ventana,
una plantilla aprobada de cada cuenta, respuestas a botones/listas y recepción SMS bidireccional.
Comprobar también los reintentos con la misma clave de idempotencia y la validación de firma del
webhook. Consultar los canales disponibles antes de enviar y tratar `canReceive=null` como
recepción sin confirmar.

Referencias: [mensajes interactivos de Meta](https://whatsapp.github.io/WhatsApp-Nodejs-SDK/api-reference/messages/interactive/)
y [recepción y opt-out SMS en AWS](https://docs.aws.amazon.com/sms-voice/latest/userguide/opt-out-list-self-managed.html).


# Referencia completa OpenAPI

Los bloques schema describen el contrato; no son cuerpos de ejemplo. Consultar required, oneOf/anyOf y x-scope de cada operación antes de construir la solicitud.

```json
{"openapi":"3.1.0","info":{"title":"Be CRM API","version":"1.0.0","description":"API pública v1 de Be CRM. Autenticación con `Authorization: Bearer <clave>` (claves v1 de Ajustes → API, con alcances). Errores `{error:{code,message,details?}, requestId}`; listas `{data, nextCursor}`. Límite por clave: 120 llamadas por minuto (cabeceras `X-RateLimit-*`, `Retry-After` en el 429). Toda escritura acepta `Idempotency-Key`. Solo de servidor a servidor: no hay CORS."},"servers":[{"url":"https://crm.begraffic.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Clave"},{"name":"Contactos"},{"name":"Etiquetas"},{"name":"Correo"},{"name":"Negocios"},{"name":"Actividades y tareas"},{"name":"Conversaciones"},{"name":"Tickets"},{"name":"Reuniones"},{"name":"Webhooks"}],"paths":{"/api/v1/me":{"get":{"operationId":"me.get","summary":"Comprobar la clave","description":"Devuelve la clave (sin secreto), el workspace y el estado de correo, SMS, WhatsApp y Telegram, con disponibilidad del plan, permisos y enlaces de configuración. Vale con cualquier alcance. Es una foto de la configuración guardada, sin consultar proveedores ni garantizar entrega.","tags":["Clave"],"x-scope":"any","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"integrations":{"type":"object","properties":{"checkedAt":{"type":"string","format":"date-time"},"source":{"type":"string","const":"crm_configuration"},"email":{"type":"object","properties":{"available":{"type":"boolean","description":"El plan incluye este canal."},"configured":{"type":"boolean","description":"Hay configuración utilizable guardada en BeCRM."},"active":{"type":"boolean","description":"Configurado y disponible en el plan; no garantiza entrega del proveedor."},"status":{"type":"string","enum":["active","not_configured","configuration_pending","plan_required"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"canReceive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"null indica recepción sin confirmar."},"apiCanSend":{"type":"boolean","description":"Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar."},"configurationUrl":{"type":"string","format":"uri"},"verified":{"type":"boolean"},"identitiesCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"verifiedSendersCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"verifiedDomainsCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["available","configured","active","status","reason","canReceive","apiCanSend","configurationUrl","verified","identitiesCount","verifiedSendersCount","verifiedDomainsCount"]},"sms":{"type":"object","properties":{"available":{"type":"boolean","description":"El plan incluye este canal."},"configured":{"type":"boolean","description":"Hay configuración utilizable guardada en BeCRM."},"active":{"type":"boolean","description":"Configurado y disponible en el plan; no garantiza entrega del proveedor."},"status":{"type":"string","enum":["active","not_configured","configuration_pending","plan_required"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"canReceive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"null indica recepción sin confirmar."},"apiCanSend":{"type":"boolean","description":"Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar."},"configurationUrl":{"type":"string","format":"uri"},"numbersCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"activeNumbersCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["available","configured","active","status","reason","canReceive","apiCanSend","configurationUrl","numbersCount","activeNumbersCount"]},"whatsapp":{"type":"object","properties":{"available":{"type":"boolean","description":"El plan incluye este canal."},"configured":{"type":"boolean","description":"Hay configuración utilizable guardada en BeCRM."},"active":{"type":"boolean","description":"Configurado y disponible en el plan; no garantiza entrega del proveedor."},"status":{"type":"string","enum":["active","not_configured","configuration_pending","plan_required"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"canReceive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"null indica recepción sin confirmar."},"apiCanSend":{"type":"boolean","description":"Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar."},"configurationUrl":{"type":"string","format":"uri"},"accountsCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"numbersCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"activeNumbersCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["available","configured","active","status","reason","canReceive","apiCanSend","configurationUrl","accountsCount","numbersCount","activeNumbersCount"]},"telegram":{"type":"object","properties":{"available":{"type":"boolean","description":"El plan incluye este canal."},"configured":{"type":"boolean","description":"Hay configuración utilizable guardada en BeCRM."},"active":{"type":"boolean","description":"Configurado y disponible en el plan; no garantiza entrega del proveedor."},"status":{"type":"string","enum":["active","not_configured","configuration_pending","plan_required"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"canReceive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"null indica recepción sin confirmar."},"apiCanSend":{"type":"boolean","description":"Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar."},"configurationUrl":{"type":"string","format":"uri"},"botConnected":{"type":"boolean"},"webhookRegistered":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["available","configured","active","status","reason","canReceive","apiCanSend","configurationUrl","botConnected","webhookRegistered"]}},"required":["checkedAt","source","email","sms","whatsapp","telegram"]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rateLimitPerMinute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","name","prefix","scopes","expiresAt","createdAt","rateLimitPerMinute"]},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan":{"type":"string"}},"required":["id","name","plan"]}},"required":["integrations","key","workspace"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts":{"get":{"operationId":"contacts.list","summary":"Listar contactos","description":"Filtros por correo, etiqueta y responsable (combinables) o `updatedSince` (solo). Orden estable por id, o por `updatedAt` con `updatedSince`. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).","tags":["Contactos"],"x-scope":"contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"email","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"ownerEmail","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"updatedSince","in":"query","required":false,"description":"Solo contactos con `updatedAt` posterior (no se combina con otros filtros).","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"contacts.create","summary":"Crear un contacto","description":"409 `conflict` (con `details.id`) si ya existe un contacto con ese correo: para crear o actualizar, `POST /api/v1/contacts/upsert`.","tags":["Contactos"],"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"noteCreatedId":{"type":"string"}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"secondName":{"type":"string","maxLength":200},"lastname":{"type":"string","maxLength":200},"secondLastname":{"type":"string","maxLength":200},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"phone":{"type":"string","maxLength":40}},"required":["phone_code","phone"],"additionalProperties":false},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"movil":{"type":"string","maxLength":40}},"required":["movil_code","movil"],"additionalProperties":false},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"state":{"type":"string","maxLength":200},"country":{"type":"string","maxLength":200},"zip":{"type":"string","maxLength":20}},"additionalProperties":false},{"type":"null"}]},"gender":{"anyOf":[{"type":"string","enum":["Masculino","Femenino"]},{"type":"null"}]},"birthdate":{"description":"`AAAA-MM-DD`; `null` la borra.","anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"type":"string","maxLength":2000},"tags":{"description":"Se COMBINAN con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","maxLength":100}},"groups":{"description":"Ids de listas; se combinan con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},"organizationId":{"description":"`null` desasigna la organización.","anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},{"type":"null"}]},"organizationName":{"type":"string","maxLength":200},"active":{"type":"boolean"},"note":{"description":"Nota que se añade al contacto.","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","maxLength":20000},"type":{"type":"string","enum":["note","reminder"]},"dueDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"reminderAt":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title"],"additionalProperties":false}},"additionalProperties":false,"description":"Al menos `email`, `phone` o `movil`."}}}}}},"/api/v1/contacts/upsert":{"post":{"operationId":"contacts.upsert","summary":"Crear o actualizar por correo","description":"Si existe un contacto con ese correo lo actualiza (combina etiquetas y listas; reactiva si estaba de baja salvo `active:false`); si no, lo crea. 201 al crear, 200 al actualizar.","tags":["Contactos"],"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"noteCreatedId":{"type":"string"},"created":{"type":"boolean"},"reactivated":{"type":"boolean"}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt","created","reactivated"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"secondName":{"type":"string","maxLength":200},"lastname":{"type":"string","maxLength":200},"secondLastname":{"type":"string","maxLength":200},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"phone":{"type":"string","maxLength":40}},"required":["phone_code","phone"],"additionalProperties":false},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"movil":{"type":"string","maxLength":40}},"required":["movil_code","movil"],"additionalProperties":false},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"state":{"type":"string","maxLength":200},"country":{"type":"string","maxLength":200},"zip":{"type":"string","maxLength":20}},"additionalProperties":false},{"type":"null"}]},"gender":{"anyOf":[{"type":"string","enum":["Masculino","Femenino"]},{"type":"null"}]},"birthdate":{"description":"`AAAA-MM-DD`; `null` la borra.","anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"type":"string","maxLength":2000},"tags":{"description":"Se COMBINAN con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","maxLength":100}},"groups":{"description":"Ids de listas; se combinan con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},"organizationId":{"description":"`null` desasigna la organización.","anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},{"type":"null"}]},"organizationName":{"type":"string","maxLength":200},"active":{"type":"boolean"},"note":{"description":"Nota que se añade al contacto.","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","maxLength":20000},"type":{"type":"string","enum":["note","reminder"]},"dueDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"reminderAt":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title"],"additionalProperties":false}},"required":["email"],"additionalProperties":false}}}}}},"/api/v1/contacts/{id}":{"get":{"operationId":"contacts.get","summary":"Leer un contacto","tags":["Contactos"],"x-scope":"contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"contacts.update","summary":"Actualizar un contacto","description":"Solo cambia lo que llega. `tags` y `groups` se combinan; `removeTags` y `removeGroups` quitan; `null` borra `phone`, `movil`, `address`, `gender` y `birthdate`. Cambiar `email` al de otro contacto: 409 `conflict` (con su `id` en `details`).","tags":["Contactos"],"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"noteCreatedId":{"type":"string"}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"secondName":{"type":"string","maxLength":200},"lastname":{"type":"string","maxLength":200},"secondLastname":{"type":"string","maxLength":200},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"phone":{"type":"string","maxLength":40}},"required":["phone_code","phone"],"additionalProperties":false},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"type":"string","maxLength":8,"description":"Prefijo del país, p. ej. `+57`."},"movil":{"type":"string","maxLength":40}},"required":["movil_code","movil"],"additionalProperties":false},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"state":{"type":"string","maxLength":200},"country":{"type":"string","maxLength":200},"zip":{"type":"string","maxLength":20}},"additionalProperties":false},{"type":"null"}]},"gender":{"anyOf":[{"type":"string","enum":["Masculino","Femenino"]},{"type":"null"}]},"birthdate":{"description":"`AAAA-MM-DD`; `null` la borra.","anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"type":"string","maxLength":2000},"tags":{"description":"Se COMBINAN con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","maxLength":100}},"groups":{"description":"Ids de listas; se combinan con las que ya tenga.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},"organizationId":{"description":"`null` desasigna la organización.","anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},{"type":"null"}]},"organizationName":{"type":"string","maxLength":200},"active":{"type":"boolean"},"note":{"description":"Nota que se añade al contacto.","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","maxLength":20000},"type":{"type":"string","enum":["note","reminder"]},"dueDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"reminderAt":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title"],"additionalProperties":false},"removeTags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}},"removeGroups":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}},"additionalProperties":false}}}}},"delete":{"operationId":"contacts.delete","summary":"Borrar un contacto","tags":["Contactos"],"x-scope":"contacts:delete","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/tags":{"post":{"operationId":"contacts.tags","summary":"Añadir y quitar etiquetas","tags":["Contactos"],"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondLastname":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"phone_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_code","phone"]},{"type":"null"}]},"movil":{"anyOf":[{"type":"object","properties":{"movil_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"movil":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["movil_code","movil"]},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address1","address2","city","state","country","zip"]},{"type":"null"}]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthdate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","secondName","lastname","secondLastname","email","phone","movil","address","gender","birthdate","image","tags","groups","active","ownerEmail","organizationId","organizationName","source","stage","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}},"remove":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":100}}},"additionalProperties":false,"description":"`remove` gana si una etiqueta está en las dos listas."}}}}}},"/api/v1/contacts/{id}/notes":{"get":{"operationId":"contacts.notes","summary":"Notas de un contacto","tags":["Contactos"],"x-scope":"activities:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","content","type","tags","createdBy","createdAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tags":{"get":{"operationId":"tags.list","summary":"Listar etiquetas","tags":["Etiquetas"],"x-scope":"contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"inactive":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","name","total","active","inactive"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"tags.create","summary":"Crear una etiqueta","description":"Si ya existe (sin distinguir mayúsculas) devuelve la existente con 200.","tags":["Etiquetas"],"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"inactive":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","name","total","active","inactive"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false}}}}}},"/api/v1/emails":{"post":{"operationId":"emails.send","summary":"Enviar un correo","description":"Con plantilla (`template.name` = `sesTemplateId`) o con `subject` + `html`/`text`. Consume 1 de la cuota mensual (cc y bcc incluidos) y responde 402 `quota_exceeded` al agotarla; con el workspace bloqueado por el límite de contactos, 402 `contact_limit_exceeded` (antes que la cuota; reintentar no sirve: hay que subir de plan o de tramo). Los errores del remitente, la plantilla y `contactId` (400/404/409) llegan antes que los 402. `contactId` asocia el envío a un contacto que ya existe y cuyo correo es `to` (si no, 400/409): no crea ni cambia contactos. 202: encolado.","tags":["Correo"],"x-scope":"emails:send","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Id del envío (`jobId`)."},"status":{"type":"string","const":"queued"},"type":{"type":"string","enum":["template","standard"]},"queuedAt":{"type":"string","format":"date-time"}},"required":["id","status","type","queuedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla). `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Servicio no disponible temporalmente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"description":"Un único destinatario.","type":"string","format":"email"},"cc":{"maxItems":50,"type":"array","items":{"type":"string","format":"email"}},"bcc":{"maxItems":50,"type":"array","items":{"type":"string","format":"email"}},"replyTo":{"maxItems":50,"type":"array","items":{"type":"string","format":"email"}},"from":{"description":"Remitente: una identidad verificada o una dirección de un dominio verificado.","type":"string","format":"email"},"senderId":{"description":"Id de la identidad de envío (alternativa a `from`).","type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"fromName":{"type":"string","maxLength":120},"subject":{"type":"string","maxLength":998},"html":{"type":"string","maxLength":500000},"text":{"type":"string","maxLength":500000},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"`sesTemplateId` de la plantilla."},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"],"additionalProperties":false},"contactId":{"description":"Contacto al que se asocia el envío.","type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},"required":["to"],"additionalProperties":false,"description":"Con `template`, o con `subject` y al menos `html` o `text`."}}}}}},"/api/v1/emails/{id}":{"get":{"operationId":"emails.get","summary":"Estado de un envío","tags":["Correo"],"x-scope":"emails:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"queued, sent, delivered, bounced, complained, failed…"},"to":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactId":{"anyOf":[{"type":"string"},{"type":"null"}]},"queuedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"bouncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"complainedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"clickedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"failureReason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","to","subject","contactId","queuedAt","sentAt","deliveredAt","bouncedAt","complainedAt","openedAt","clickedAt","failureReason"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals":{"get":{"operationId":"deals.list","summary":"Listar negocios","description":"Sin archivados. Por `leadId` (más recientes primero) o por pipeline, estado y responsable (últimos actualizados primero). Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).","tags":["Negocios"],"x-scope":"deals:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"query","required":false,"description":"Negocios de un contacto (no se combina con los demás filtros).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"pipelineId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","won","lost"]}},{"name":"ownerEmail","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"deals.create","summary":"Crear un negocio","description":"Por defecto, pipeline predeterminado y su primera etapa abierta. Con `Idempotency-Key`, un reintento devuelve el mismo negocio (200).","tags":["Negocios"],"x-scope":"deals:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"leadId":{"type":"string","minLength":1,"maxLength":200},"pipelineId":{"type":"string","minLength":1,"maxLength":200},"stageId":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$"},"value":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000000000},{"type":"null"}]},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"probability":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"customFields":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,59}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["title","leadId"],"additionalProperties":false}}}}}},"/api/v1/deals/{id}":{"get":{"operationId":"deals.get","summary":"Leer un negocio","tags":["Negocios"],"x-scope":"deals:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"deals.update","summary":"Actualizar un negocio","description":"No cambia etapa ni estado (`move`, `close`, `reopen`). 409 `rev_mismatch` con un `expectedRev` viejo.","tags":["Negocios"],"x-scope":"deals:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"value":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000000000},{"type":"null"}]},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"probability":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"customFields":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,59}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"isPrimary":{"type":"boolean","const":true},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}}}}}},"/api/v1/deals/{id}/move":{"post":{"operationId":"deals.move","summary":"Mover de etapa","tags":["Negocios"],"x-scope":"deals:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toStageId":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$"},"toPipelineId":{"type":"string","minLength":1,"maxLength":200},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["toStageId"],"additionalProperties":false}}}}}},"/api/v1/deals/{id}/close":{"post":{"operationId":"deals.close","summary":"Ganar o perder","tags":["Negocios"],"x-scope":"deals:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["won","lost"]},"stageId":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$"},"value":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000000000},{"type":"null"}]},"closedAt":{"type":"string"},"lostReasonId":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["outcome"],"additionalProperties":false}}}}}},"/api/v1/deals/{id}/reopen":{"post":{"operationId":"deals.reopen","summary":"Reabrir","tags":["Negocios"],"x-scope":"deals:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"organizationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"pipelineId":{"type":"string"},"stageId":{"type":"string"},"status":{"type":"string","enum":["open","won","lost"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}]},"expectedCloseDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recurrence":{"type":"string","enum":["none","monthly","yearly"]},"ownerEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"stageEnteredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lostReasonId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostReasonLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"lostNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"customFields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","leadId","leadName","leadEmail","organizationId","organizationName","pipelineId","stageId","status","value","currency","probability","expectedCloseDate","recurrence","ownerEmail","ownerName","isPrimary","stageEnteredAt","lastActivityAt","closedAt","lostReasonId","lostReasonLabel","lostNote","customFields","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toStageId":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$"},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["toStageId"],"additionalProperties":false}}}}}},"/api/v1/pipelines":{"get":{"operationId":"pipelines.list","summary":"Listar pipelines (solo lectura)","tags":["Negocios"],"x-scope":"deals:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["sales","donation","membership","enrollment"]},"active":{"type":"boolean"},"isDefault":{"type":"boolean"},"defaultCurrency":{"type":"string"},"requireLostReason":{"type":"boolean"},"lostReasons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"active":{"type":"boolean"}},"required":["id","label","active"]}},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["open","won","lost"]},"order":{"type":"number"},"probability":{"type":"number"}},"required":["id","name","type","order","probability"]}}},"required":["id","name","kind","active","isDefault","defaultCurrency","requireLostReason","lostReasons","stages"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/activities":{"get":{"operationId":"activities.list","summary":"Línea de tiempo de un contacto o negocio","description":"Llamadas, reuniones registradas e hitos (negocio, ticket, conversación). Las notas, en `GET /api/v1/contacts/{id}/notes`. Por `dealId`, con los negocios apagados: 403 `feature_disabled`.","tags":["Actividades y tareas"],"x-scope":"activities:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"dealId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"leadId":{"type":"string"},"dealId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"body":{"anyOf":[{"type":"string"},{"type":"null"}]},"occurredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"type":"object","properties":{"type":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","email","name"]},"call":{"anyOf":[{"type":"object","properties":{"direction":{"type":"string"},"outcome":{"type":"string"},"durationSec":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["direction","outcome","durationSec"]},{"type":"null"}]},"meeting":{"anyOf":[{"type":"object","properties":{"startAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"endAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"type":"string"}},"required":["startAt","endAt","location","outcome"]},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","type","leadId","dealId","title","body","occurredAt","actor","call","meeting","createdAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"activities.create","summary":"Crear nota, tarea, llamada o reunión registrada","description":"Mismo cuerpo que el panel (`type`: note, task, call, meeting). Una tarea necesita `assignedToEmail`. Con `Idempotency-Key`, el documento tiene id determinista (un reintento responde 200 con `alreadyExisted`). Con `dealId` y los negocios apagados: 403 `feature_disabled`.","tags":["Actividades y tareas"],"x-scope":"activities:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["note","task","call","meeting"]},"store":{"type":"string","description":"Dónde vive: `activities`, `notes` (del contacto) o `reminders`."},"leadId":{"type":"string"},"nextStepTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"alreadyExisted":{"type":"boolean"}},"required":["id","type","store","leadId","nextStepTaskId","alreadyExisted"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"leadId":{"type":"string","minLength":1,"maxLength":200},"dealId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"title":{"type":"string","maxLength":200},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"type":{"type":"string","const":"note"},"pinned":{"type":"boolean"}},"required":["leadId","type"],"additionalProperties":false},{"type":"object","properties":{"leadId":{"type":"string","minLength":1,"maxLength":200},"dealId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"title":{"type":"string","minLength":1,"maxLength":200},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"type":{"type":"string","const":"task"},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"assignedToEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"type":"string","enum":["high","medium","low","none"]},"reminderType":{"type":"string","enum":["call","email","whatsapp","meeting","task"]}},"required":["leadId","title","type"],"additionalProperties":false},{"type":"object","properties":{"leadId":{"type":"string","minLength":1,"maxLength":200},"dealId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"title":{"type":"string","maxLength":200},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"type":{"type":"string","const":"call"},"occurredAt":{"type":"string"},"call":{"type":"object","properties":{"direction":{"type":"string","enum":["outbound","inbound"]},"outcome":{"type":"string","enum":["connected","no_answer","voicemail","busy","wrong_number"]},"durationSec":{"anyOf":[{"type":"integer","minimum":0,"maximum":86400},{"type":"null"}]}},"required":["direction","outcome"],"additionalProperties":false},"nextStep":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"dueAt":{"type":"string"},"assignedToEmail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title","dueAt"],"additionalProperties":false}},"required":["leadId","type","call"],"additionalProperties":false},{"type":"object","properties":{"leadId":{"type":"string","minLength":1,"maxLength":200},"dealId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"title":{"type":"string","maxLength":200},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"type":{"type":"string","const":"meeting"},"meeting":{"type":"object","properties":{"startAt":{"type":"string"},"endAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"outcome":{"type":"string","enum":["held","no_show","rescheduled","canceled"]}},"required":["startAt","outcome"],"additionalProperties":false},"nextStep":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"dueAt":{"type":"string"},"assignedToEmail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title","dueAt"],"additionalProperties":false}},"required":["leadId","type","meeting"],"additionalProperties":false}]}}}}}},"/api/v1/tasks":{"get":{"operationId":"tasks.list","summary":"Listar tareas","description":"De un contacto (`leadId`) o del workspace: abiertas por vencimiento (`status=open`, con `assignedToEmail` opcional), hechas (`status=done`) o todas.","tags":["Actividades y tareas"],"x-scope":"activities:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"query","required":false,"description":"Tareas de un contacto.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"assignedToEmail","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"status","in":"query","required":false,"description":"Sin él, todas por fecha de vencimiento.","schema":{"type":"string","enum":["open","done"]}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"doneAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignedToEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assignedToName":{"anyOf":[{"type":"string"},{"type":"null"}]},"dealId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","leadId","leadName","title","content","type","priority","dueAt","doneAt","assignedToEmail","assignedToName","dealId","createdAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/tasks/{taskId}/complete":{"post":{"operationId":"tasks.complete","summary":"Completar (o reabrir) una tarea","tags":["Actividades y tareas"],"x-scope":"activities:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"leadId":{"type":"string"},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"doneAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assignedToEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assignedToName":{"anyOf":[{"type":"string"},{"type":"null"}]},"dealId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","leadId","leadName","title","content","type","priority","dueAt","doneAt","assignedToEmail","assignedToName","dealId","createdAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"done":{"description":"`false` la reabre. Por defecto `true`.","type":"boolean"}},"additionalProperties":false}}}}}},"/api/v1/messaging/channels":{"get":{"operationId":"messaging.channels","summary":"Números e integraciones disponibles para mensajería.","description":"canReceive=null significa que la recepción no está verificada. SMS admite texto con enlaces, sin botones nativos.","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["whatsapp","sms"]},"configured":{"type":"boolean"},"numbers":{"type":"array","items":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"phoneNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"wabaId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"canSend":{"type":"boolean"},"canReceive":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phoneNumberId","phoneNumber","wabaId","isDefault","canSend","canReceive","reason"]}},"supportedMessageTypes":{"type":"array","items":{"type":"string"}},"balanceCents":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["channel","configured","numbers","supportedMessageTypes","balanceCents"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/messaging/messages":{"post":{"operationId":"messaging.send","summary":"Iniciar o continuar una conversación WhatsApp/SMS.","description":"Idempotency-Key obligatoria para evitar duplicados. Sin integración disponible: 403 feature_disabled. WhatsApp requiere plantilla fuera de la ventana. El destino debe ser E.164. SMS admite hasta 1600 caracteres y consume saldo.","tags":["Conversaciones"],"x-scope":"conversations:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"conversationId":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"messageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["sent","queued"]}},"required":["conversationId","channel","messageId","status"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla. `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual. `conflict`: Conflicto con el estado actual (p. ej. ya existe). `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Servicio no disponible temporalmente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"channel":{"type":"string","const":"whatsapp"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{9,14}$"},"phoneNumberId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"leadId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"message":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":4096},"previewUrl":{"type":"boolean"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"template"},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512},"language":{"description":"Código exacto de Meta (`es`, `es_MX`…).","type":"string","minLength":2,"maxLength":15},"components":{"maxItems":20,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["name"],"additionalProperties":false}},"required":["type","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"interactive"},"interactive":{"oneOf":[{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"button"},"action":{"type":"object","properties":{"buttons":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"reply"},"reply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":20}},"required":["id","title"],"additionalProperties":false}},"required":["type","reply"],"additionalProperties":false}}},"required":["buttons"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false},{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"list"},"action":{"type":"object","properties":{"button":{"type":"string","minLength":1,"maxLength":20},"sections":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":24},"rows":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":24},"description":{"type":"string","minLength":1,"maxLength":72}},"required":["id","title"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}},"required":["button","sections"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false},{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"cta_url"},"action":{"type":"object","properties":{"name":{"type":"string","const":"cta_url"},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["display_text","url"],"additionalProperties":false}},"required":["name","parameters"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false}]}},"required":["type","interactive"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"image":{"type":"object","properties":{"link":{"type":"string","maxLength":2000,"format":"uri"},"caption":{"type":"string","maxLength":1024}},"required":["link"],"additionalProperties":false}},"required":["type","image"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"audio"},"audio":{"type":"object","properties":{"link":{"type":"string","maxLength":2000,"format":"uri"}},"required":["link"],"additionalProperties":false}},"required":["type","audio"],"additionalProperties":false}]}},"required":["channel","to","message"],"additionalProperties":false},{"type":"object","properties":{"channel":{"type":"string","const":"sms"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{9,14}$"},"phoneNumberId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"leadId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"text":{"type":"string","minLength":1,"maxLength":1600},"messageType":{"type":"string","enum":["TRANSACTIONAL","PROMOTIONAL"]}},"required":["channel","to","text"],"additionalProperties":false}]}}}}}},"/api/v1/messaging/whatsapp/templates":{"get":{"operationId":"messaging.templates","summary":"Plantillas de la WABA del número seleccionado.","description":"Espejo local de Meta: incluye status, idioma, componentes y botones. Solo APPROVED es enviable; Meta valida el estado definitivo. No incluye plantillas legacy cuya WABA no se conoce.","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"phoneNumberId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"wabaId":{"type":"string"},"components":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["id","name","language","status","category","wabaId","components"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}/capabilities":{"get":{"operationId":"conversations.capabilities","summary":"Disponibilidad del canal y ventana de respuesta WhatsApp.","description":"Consulta informativa: el envío vuelve a validar integración, ventana, cuota, saldo y proveedor. La ventana abre con el último mensaje del contacto, nunca con un mensaje saliente. SMS no requiere plantilla ni ventana.","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"conversationId":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","sms"]},"checkedAt":{"type":"string","format":"date-time"},"phoneNumberId":{"anyOf":[{"type":"string"},{"type":"null"}]},"configured":{"type":"boolean"},"canSend":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"canSendDirect":{"type":"boolean"},"canSendTemplate":{"type":"boolean"},"supportedMessageTypes":{"type":"array","items":{"type":"string"}},"window":{"anyOf":[{"type":"object","properties":{"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"open":{"type":"boolean"},"remainingSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"templateRequired":{"type":"boolean"}},"required":["lastInboundAt","expiresAt","open","remainingSeconds","templateRequired"]},{"type":"null"}]}},"required":["conversationId","channel","checkedAt","phoneNumberId","configured","canSend","reason","canSendDirect","canSendTemplate","supportedMessageTypes","window"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations":{"get":{"operationId":"conversations.list","summary":"Listar conversaciones","description":"Las del workspace (no los buzones privados), por último mensaje. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","closed","snoozed"]}},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["whatsapp","telegram","sms","email"]}},{"name":"assigneeEmail","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"status":{"type":"string"},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"awaitingReply":{"type":"boolean"},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"botActive":{"type":"boolean"},"handoffOpen":{"type":"boolean"},"openTicketId":{"anyOf":[{"type":"string"},{"type":"null"}]},"snoozedUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","channel","status","leadId","contactName","contactHandle","assigneeEmail","assigneeName","lastMessageAt","lastMessagePreview","lastMessageBy","lastInboundAt","awaitingReply","unreadCount","botActive","handoffOpen","openTicketId","snoozedUntil","rev","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}":{"get":{"operationId":"conversations.get","summary":"Leer una conversación","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"status":{"type":"string"},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"awaitingReply":{"type":"boolean"},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"botActive":{"type":"boolean"},"handoffOpen":{"type":"boolean"},"openTicketId":{"anyOf":[{"type":"string"},{"type":"null"}]},"snoozedUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","channel","status","leadId","contactName","contactHandle","assigneeEmail","assigneeName","lastMessageAt","lastMessagePreview","lastMessageBy","lastInboundAt","awaitingReply","unreadCount","botActive","handoffOpen","openTicketId","snoozedUntil","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}/messages":{"get":{"operationId":"conversations.messages","summary":"Mensajes de una conversación","description":"Del más reciente al más antiguo, sin notas internas.","tags":["Conversaciones"],"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"text":{"type":"string"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Solo correo."},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"sender":{"type":"object","properties":{"type":{"type":"string","enum":["contact","user","bot","automation","api"]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","email"]},"messageType":{"anyOf":[{"type":"string"},{"type":"null"}]},"deliveryStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"replyToMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"interaction":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","id","title","description"]},{"type":"null"}]},"attachment":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","url","name"]},{"type":"null"}]}},"required":["id","direction","text","subject","at","sender","attachment"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}/reply":{"post":{"operationId":"conversations.reply","summary":"Responder","description":"Texto por el canal de la conversación (WhatsApp: dentro de la ventana de 24 h; fuera, `template`). Cuota de cada canal: WhatsApp y correo del plan, SMS del saldo (402). 201 enviado; 202 correo encolado. 409 `unknown_outcome`: el proveedor no respondió y el mensaje pudo salir; con la misma Idempotency-Key se repite esa respuesta sin reenviar. 403 `forbidden` (`sending_paused`): el envío de correo del workspace está pausado. 402 `contact_limit_exceeded`: el workspace superó su límite de contactos (contestar a mano desde el panel sigue permitido).","tags":["Conversaciones"],"x-scope":"conversations:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"conversationId":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"messageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["sent","queued"]}},"required":["conversationId","channel","messageId","status"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla). `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Servicio no disponible temporalmente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4096},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512},"language":{"description":"Código exacto de Meta (`es`, `es_MX`…).","type":"string","minLength":2,"maxLength":15},"components":{"maxItems":20,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["name"],"additionalProperties":false},"message":{"description":"Solo WhatsApp: texto, plantilla, imagen, audio, botones, lista o enlace CTA.","oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":4096},"previewUrl":{"type":"boolean"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"template"},"template":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512},"language":{"description":"Código exacto de Meta (`es`, `es_MX`…).","type":"string","minLength":2,"maxLength":15},"components":{"maxItems":20,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["name"],"additionalProperties":false}},"required":["type","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"interactive"},"interactive":{"oneOf":[{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"button"},"action":{"type":"object","properties":{"buttons":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"reply"},"reply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":20}},"required":["id","title"],"additionalProperties":false}},"required":["type","reply"],"additionalProperties":false}}},"required":["buttons"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false},{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"list"},"action":{"type":"object","properties":{"button":{"type":"string","minLength":1,"maxLength":20},"sections":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":24},"rows":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":24},"description":{"type":"string","minLength":1,"maxLength":72}},"required":["id","title"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}},"required":["button","sections"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false},{"type":"object","properties":{"body":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024}},"required":["text"],"additionalProperties":false},"footer":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60}},"required":["text"],"additionalProperties":false},"type":{"type":"string","const":"cta_url"},"action":{"type":"object","properties":{"name":{"type":"string","const":"cta_url"},"parameters":{"type":"object","properties":{"display_text":{"type":"string","minLength":1,"maxLength":20},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["display_text","url"],"additionalProperties":false}},"required":["name","parameters"],"additionalProperties":false}},"required":["body","type","action"],"additionalProperties":false}]}},"required":["type","interactive"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"image":{"type":"object","properties":{"link":{"type":"string","maxLength":2000,"format":"uri"},"caption":{"type":"string","maxLength":1024}},"required":["link"],"additionalProperties":false}},"required":["type","image"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"audio"},"audio":{"type":"object","properties":{"link":{"type":"string","maxLength":2000,"format":"uri"}},"required":["link"],"additionalProperties":false}},"required":["type","audio"],"additionalProperties":false}]}},"additionalProperties":false}}}}}},"/api/v1/conversations/{id}/assign":{"post":{"operationId":"conversations.assign","summary":"Asignar","tags":["Conversaciones"],"x-scope":"conversations:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"status":{"type":"string"},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"awaitingReply":{"type":"boolean"},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"botActive":{"type":"boolean"},"handoffOpen":{"type":"boolean"},"openTicketId":{"anyOf":[{"type":"string"},{"type":"null"}]},"snoozedUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","channel","status","leadId","contactName","contactHandle","assigneeEmail","assigneeName","lastMessageAt","lastMessagePreview","lastMessageBy","lastInboundAt","awaitingReply","unreadCount","botActive","handoffOpen","openTicketId","snoozedUntil","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeEmail":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"`null` la deja sin responsable."},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["assigneeEmail"],"additionalProperties":false}}}}}},"/api/v1/conversations/{id}/close":{"post":{"operationId":"conversations.close","summary":"Cerrar","tags":["Conversaciones"],"x-scope":"conversations:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"status":{"type":"string"},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"awaitingReply":{"type":"boolean"},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"botActive":{"type":"boolean"},"handoffOpen":{"type":"boolean"},"openTicketId":{"anyOf":[{"type":"string"},{"type":"null"}]},"snoozedUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","channel","status","leadId","contactName","contactHandle","assigneeEmail","assigneeName","lastMessageAt","lastMessagePreview","lastMessageBy","lastInboundAt","awaitingReply","unreadCount","botActive","handoffOpen","openTicketId","snoozedUntil","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}}}}}},"/api/v1/conversations/{id}/reopen":{"post":{"operationId":"conversations.reopen","summary":"Reabrir","tags":["Conversaciones"],"x-scope":"conversations:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"`{canal}__{id}` (p. ej. `whatsapp__573001234567`).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["whatsapp","telegram","sms","email"]},"status":{"type":"string"},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contactHandle":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessagePreview":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastInboundAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"awaitingReply":{"type":"boolean"},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"botActive":{"type":"boolean"},"handoffOpen":{"type":"boolean"},"openTicketId":{"anyOf":[{"type":"string"},{"type":"null"}]},"snoozedUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","channel","status","leadId","contactName","contactHandle","assigneeEmail","assigneeName","lastMessageAt","lastMessagePreview","lastMessageBy","lastInboundAt","awaitingReply","unreadCount","botActive","handoffOpen","openTicketId","snoozedUntil","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}}}}}},"/api/v1/tickets":{"get":{"operationId":"tickets.list","summary":"Listar tickets","description":"Por estado, prioridad y responsable (combinables salvo prioridad + responsable) o por `leadId`. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).","tags":["Tickets"],"x-scope":"tickets:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]}},{"name":"priority","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high","urgent"]}},{"name":"assigneeEmail","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"leadId","in":"query","required":false,"description":"Tickets de un contacto (no se combina con los demás filtros).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"tickets.create","summary":"Crear un ticket","description":"Con `Idempotency-Key`, un reintento devuelve el mismo ticket (200). `conversationId` tiene que ser una conversación del workspace (si no, 404); `originThread` de correo no se admite (400: usa `conversationId`).","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":20000},"leadId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"channel":{"anyOf":[{"type":"string","enum":["email","whatsapp","telegram","sms","slack","web_form","chat_ai","phone","manual"]},{"type":"null"}]},"category":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"tags":{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"originThread":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":500},"subject":{"type":"string","maxLength":500},"channel":{"type":"string","enum":["email","whatsapp","telegram","sms","slack","web_form","chat_ai","phone","manual"]}},"required":["id","channel"],"additionalProperties":false},{"type":"null"}]},"attachments":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"},"size":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"type":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["name","url"],"additionalProperties":false}},"ticketId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},"required":["subject"],"additionalProperties":false}}}}}},"/api/v1/tickets/{id}":{"get":{"operationId":"tickets.get","summary":"Leer un ticket","tags":["Tickets"],"x-scope":"tickets:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"tickets.update","summary":"Actualizar un ticket","description":"`conversationId` tiene que ser una conversación del workspace (si no, 404).","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":20000},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string","enum":["email","whatsapp","telegram","sms","slack","web_form","chat_ai","phone","manual"]},{"type":"null"}]},"category":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"tags":{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"leadId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false}}}}}},"/api/v1/tickets/{id}/status":{"post":{"operationId":"tickets.status","summary":"Cambiar el estado","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/tickets/{id}/priority":{"post":{"operationId":"tickets.priority","summary":"Cambiar la prioridad","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"string","enum":["low","medium","high","urgent"]},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["priority"],"additionalProperties":false}}}}}},"/api/v1/tickets/{id}/assign":{"post":{"operationId":"tickets.assign","summary":"Asignar","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"expectedRev":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["assigneeEmail"],"additionalProperties":false}}}}}},"/api/v1/tickets/{id}/comments":{"post":{"operationId":"tickets.comment","summary":"Comentar","description":"Nota interna o registro de una respuesta (`kind: reply`); no envía nada al cliente.","tags":["Tickets"],"x-scope":"tickets:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"commentId":{"type":"string"},"ticket":{"type":"object","properties":{"id":{"type":"string"},"number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"subject":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["open","in_progress","waiting_customer","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigneeName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"slaDueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"slaBreached":{"type":"boolean"},"firstResponseAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"reopenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","number","subject","description","status","priority","channel","category","tags","leadId","leadName","leadEmail","assigneeEmail","assigneeName","conversationId","source","slaDueAt","slaBreached","firstResponseAt","lastMessageAt","resolvedAt","reopenCount","rev","createdAt","updatedAt"]}},"required":["commentId","ticket"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":20000},"kind":{"type":"string","enum":["reply","internal_note"]},"attachments":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"},"size":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"type":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["name","url"],"additionalProperties":false}}},"required":["text"],"additionalProperties":false}}}}}},"/api/v1/meetings":{"get":{"operationId":"meetings.list","summary":"Listar reuniones","description":"Las agendadas con el servicio de reservas, por fecha de inicio. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).","tags":["Reuniones"],"x-scope":"meetings:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Desde (inicio de la reunión).","schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"to","in":"query","required":false,"description":"Hasta (inicio de la reunión).","schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"limit","in":"query","required":false,"description":"Elementos por página (1–100, por defecto 50).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` de la página anterior (opaco).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["confirmed","canceled"]},"source":{"type":"string"},"startAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"endAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"timeZone":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"dealId":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingTypeId":{"anyOf":[{"type":"string"},{"type":"null"}]},"attendee":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email","phone"]},{"type":"null"}]},"meetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","status","source","startAt","endAt","timeZone","hostEmail","hostName","leadId","dealId","conversationId","bookingTypeId","attendee","meetUrl","createdAt","updatedAt","canceledAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/meetings/{id}":{"get":{"operationId":"meetings.get","summary":"Leer una reunión","tags":["Reuniones"],"x-scope":"meetings:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["confirmed","canceled"]},"source":{"type":"string"},"startAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"endAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"timeZone":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostName":{"anyOf":[{"type":"string"},{"type":"null"}]},"leadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"dealId":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string"},{"type":"null"}]},"bookingTypeId":{"anyOf":[{"type":"string"},{"type":"null"}]},"attendee":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email","phone"]},{"type":"null"}]},"meetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","status","source","startAt","endAt","timeZone","hostEmail","hostName","leadId","dealId","conversationId","bookingTypeId","attendee","meetUrl","createdAt","updatedAt","canceledAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/meetings/{id}/reschedule":{"post":{"operationId":"meetings.reschedule","summary":"Mover","tags":["Reuniones"],"x-scope":"meetings:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"meetingId":{"type":"string"},"status":{"type":"string","enum":["confirmed","canceled"]},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"unchanged":{"type":"boolean"}},"required":["meetingId","status","startAt","endAt","unchanged"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startAt":{"type":"string","format":"date-time"}},"required":["startAt"],"additionalProperties":false}}}}}},"/api/v1/meetings/{id}/cancel":{"post":{"operationId":"meetings.cancel","summary":"Cancelar","description":"Idempotente: cancelar otra vez responde `unchanged: true`.","tags":["Reuniones"],"x-scope":"meetings:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"meetingId":{"type":"string"},"status":{"type":"string","enum":["confirmed","canceled"]},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"unchanged":{"type":"boolean"}},"required":["meetingId","status","startAt","endAt","unchanged"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}}}},"/api/v1/booking-types":{"get":{"operationId":"bookingTypes.list","summary":"Tipos de cita","tags":["Reuniones"],"x-scope":"meetings:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"durationMin":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active":{"type":"boolean"},"location":{"type":"string"},"hostMode":{"type":"string","enum":["owner","fixed"]},"windowDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"minNoticeMin":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","name","durationMin","active","location","hostMode","windowDays","minNoticeMin"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/booking-types/{id}/slots":{"get":{"operationId":"bookingTypes.slots","summary":"Huecos libres","description":"`id` = el tipo de cita o `default`. Hasta 6 huecos del anfitrión del contacto.","tags":["Reuniones"],"x-scope":"meetings:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"contactId","in":"query","required":true,"description":"Contacto que reserva (define el anfitrión si el tipo es «del dueño»).","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["es","en","pt"]}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"bookingTypeId":{"type":"string"},"hostEmail":{"type":"string"},"hostName":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeZone":{"type":"string"},"durationMin":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"slots":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string","description":"Opaco: se manda tal cual a `book`."},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"label":{"type":"string"}},"required":["slotId","startAt","endAt","label"]}}},"required":["bookingTypeId","hostEmail","hostName","timeZone","durationMin","slots"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`invalid_state`: Operación no válida en el estado actual.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Servicio no disponible temporalmente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/booking-types/{id}/book":{"post":{"operationId":"bookingTypes.book","summary":"Reservar","description":"Con un `slotId` de `slots`. 409 `conflict` (con `alternatives`) si el hueco se ocupó. Con `Idempotency-Key`, un reintento devuelve la misma reunión (200). `conversationId`: una conversación del workspace (si no, 404) y del mismo contacto (si no, 400).","tags":["Reuniones"],"x-scope":"meetings:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"meetingId":{"type":"string"},"alreadyBooked":{"type":"boolean"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"label":{"type":"string"},"timeZone":{"type":"string"},"hostEmail":{"type":"string"},"hostName":{"anyOf":[{"type":"string"},{"type":"null"}]},"attendeeEmail":{"anyOf":[{"type":"string"},{"type":"null"}]},"meetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"confirmation":{"type":"string"}},"required":["meetingId","alreadyBooked","startAt","endAt","label","timeZone","hostEmail","hostName","attendeeEmail","meetUrl","confirmation"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`unavailable`: Servicio no disponible temporalmente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},"slotId":{"type":"string","minLength":1,"maxLength":200},"attendeeEmail":{"description":"Ausente = el correo del contacto; `null` = sin invitación de Google.","anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"conversationId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"},{"type":"null"}]},"locale":{"type":"string","enum":["es","en","pt"]}},"required":["contactId","slotId"],"additionalProperties":false}}}}}},"/api/v1/webhooks":{"get":{"operationId":"webhooks.list","summary":"Listar destinos","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secretSuffix":{"type":"string","description":"Últimos 4 caracteres del secreto de firma."},"failureCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastEventAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","url","description","events","active","secretSuffix","failureCount","lastEventAt","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"webhooks.create","summary":"Crear un destino","description":"La URL pasa la guarda SSRF (https en producción). El secreto de firma solo se devuelve aquí. Como mucho 20 destinos por workspace (409 `conflict`).","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secretSuffix":{"type":"string","description":"Últimos 4 caracteres del secreto de firma."},"failureCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastEventAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"secret":{"type":"string","description":"Secreto de firma (HMAC-SHA256). Solo se devuelve aquí."}},"required":["id","name","url","description","events","active","secretSuffix","failureCount","lastEventAt","createdAt","updatedAt","secret"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","maxLength":2000,"format":"uri"},"description":{"type":"string","maxLength":500},"events":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Ids del catálogo (`GET /api/v1/webhooks/events`)."},"active":{"type":"boolean"}},"required":["name","url","events"],"additionalProperties":false}}}}}},"/api/v1/webhooks/{id}":{"patch":{"operationId":"webhooks.update","summary":"Actualizar un destino","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secretSuffix":{"type":"string","description":"Últimos 4 caracteres del secreto de firma."},"failureCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastEventAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","url","description","events","active","secretSuffix","failureCount","lastEventAt","createdAt","updatedAt"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","maxLength":2000,"format":"uri"},"description":{"type":"string","maxLength":500},"events":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"active":{"type":"boolean"}},"additionalProperties":false}}}}},"delete":{"operationId":"webhooks.delete","summary":"Borrar un destino","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"webhooks.test","summary":"Enviar una prueba","description":"Un evento `webhook.test` firmado, un intento. Queda en el registro de entregas. `error` dice el código HTTP que respondió el destino o que no respondió (nunca el error de red: no sirve para sondear puertos).","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^/]+$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"eventId":{"type":"string"}},"required":["ok","statusCode","error","eventId"]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No existe (o no es de este workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/events":{"get":{"operationId":"webhooks.events","summary":"Catálogo de eventos","tags":["Webhooks"],"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"group":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"available":{"type":"boolean","description":"`false` = todavía no se emite (próximamente)."}},"required":["id","group","label","description","available"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: Falta la clave, no existe, está revocada o caducó.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: La clave no tiene el alcance que exige la ruta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`: Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clave v1 (`bcrm_…`). Alcances: contacts:read, contacts:write, contacts:delete, emails:send, emails:read, deals:read, deals:write, activities:read, activities:write, conversations:read, conversations:write, tickets:read, tickets:write, meetings:read, meetings:write, webhooks:manage."}},"schemas":{"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","insufficient_scope","forbidden","feature_disabled","not_found","method_not_allowed","conflict","rev_mismatch","invalid_state","unknown_outcome","idempotency_in_progress","idempotency_key_reused","payload_too_large","quota_exceeded","contact_limit_exceeded","plan_required","rate_limited","unavailable","internal"]},"message":{"type":"string"},"details":{"type":"object"}}},"requestId":{"type":"string"}}}}}}
```