{ "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 ` (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" } } } } } }