{"openapi":"3.1.0","info":{"title":"UplabsAI API","description":"API REST multi-tenant del CRM y call-center de UplabsAI.\n\n**Autenticación.** Toda petición lleva `Authorization: Bearer <api_key>`. La key es de una empresa (se genera en el SaaS, en Configuración > API Keys) y la empresa se deduce de ella.\n\n**Datos reales.** No hay entorno de pruebas: `POST`, `PUT` y `DELETE` modifican los datos de la empresa de la key. Los `DELETE` son borrados lógicos: el registro deja de aparecer en las lecturas.\n\n**Permisos de la key.** Una API key puede ser total o estar limitada por área y nivel: cada área es un grupo de esta documentación (Contactos, Ventas, Cuotas...) y el nivel es lectura (`GET`) o escritura (`POST`, `PUT`, `PATCH`, `DELETE`, que incluye leer). Una key limitada que usa un endpoint de un área o nivel que no tiene responde 403 `SCOPE_DENIED` y el mensaje nombra el área y el nivel que faltan. `/status` está permitido a toda key. Los permisos se cambian en el SaaS (Configuración > API Keys) y rigen desde el pedido siguiente.\n\n**Ids.** Los ids de la ruta son UUID salvo que la operación diga otra cosa. Un recurso inexistente y uno de otra empresa responden igual: 404 `NOT_FOUND`.\n\n**Paginación.** Los listados paginados responden `{data, page, limit, total, has_more}` (`page` desde 1); si `has_more` es `true`, hay que pedir la página siguiente. Excepción: `GET /opportunities/search` y `GET /project-calls/detail` devuelven `pages` en lugar de `has_more`.\n\n**Errores.** Todos tienen la forma `{\"status\":\"error\",\"code\":\"...\",\"message\":\"...\"}`. El `code` es estable y es el que hay que mirar; `message` es para personas.\n\n| `code` | HTTP | Cuándo |\n|---|---|---|\n| `UNAUTHORIZED` | 401 | Falta la cabecera `Authorization: Bearer` |\n| `INVALID_KEY` | 403 | La API key no existe |\n| `KEY_REVOKED` / `KEY_EXPIRED` | 403 | La API key fue desactivada / venció (el mensaje dice la fecha) |\n| `SCOPE_DENIED` | 403 | La API key está limitada y no tiene permiso para el área o el nivel (lectura o escritura) del endpoint |\n| `INVALID_ID` | 400 | Un id de la ruta no es válido |\n| `INVALID_BODY` | 400 | El cuerpo no es JSON válido o no trae campos útiles |\n| `MISSING_FIELD` | 400 | Falta un campo o un parámetro obligatorio |\n| `INVALID_VALUE` | 400 | Un valor no es válido (tipo, formato, fecha o largo) |\n| `REFERENCE_NOT_FOUND` | 400 | Un id del cuerpo no existe o no es de la empresa |\n| `NOT_FOUND` | 404 | El recurso no existe o es de otra empresa, o la ruta no existe |\n| `METHOD_NOT_ALLOWED` | 405 | La ruta no admite ese método |\n| `NOT_ACCEPTABLE` | 406 | La cabecera `Accept` pide un formato que no es JSON |\n| `UNSUPPORTED_MEDIA_TYPE` | 415 | El `Content-Type` del cuerpo no es compatible con la operación |\n| `UNSUPPORTED_TYPE` | 415 | Extensión o MIME no permitido para un archivo |\n| `PAYLOAD_TOO_LARGE` | 413 | El archivo supera el tamaño máximo de la operación |\n| `DUPLICATE` | 409 | Ya existe un registro con esos datos |\n| `CONFLICT` | 409 | La operación choca con el estado actual del recurso |\n| `BUSINESS_RULE` | 422 | Una regla de negocio rechazó la operación; `message` dice cuál |\n| `OPENAI_CREDENTIAL_MISSING` | 422 | El proyecto no tiene una credencial OpenAI activa de su empresa |\n| `DB_UNAVAILABLE` | 503 | La base de datos no está disponible en este momento |\n| `STORAGE_UNAVAILABLE` | 503 | El almacenamiento FTP no está configurado o disponible |\n| `STORAGE_ERROR` | 502 | Falló una operación con el almacenamiento FTP |\n| `INTEGRATION_UNAVAILABLE` | 503 | Vapi, ElevenLabs u OpenAI no están configurados o no responden |\n| `INTEGRATION_ERROR` | 502 | Vapi, ElevenLabs u OpenAI rechazaron la solicitud o respondieron algo inválido |\n| `INTERNAL` | 500 | Error interno del servidor |\n","version":"1.35.1"},"servers":[{"url":"/","description":"Mismo origen que esta documentación"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Aprovisionamiento","description":"Estado del aprovisionamiento de los proyectos de Empleados IA (repositorio y flujos de n8n). Solo lectura."},{"name":"Archivos","description":"Subida autenticada de archivos al almacenamiento público"},{"name":"Calendario","description":"Usuarios habilitados como asesores de agenda"},{"name":"Calendario","description":"Citas y franjas de disponibilidad de la empresa autenticada"},{"name":"Campañas","description":"Gestión de campañas"},{"name":"Campos personalizados","description":"Campos personalizados de la empresa autenticada"},{"name":"Contactos","description":"Gestión de contactos"},{"name":"Conversaciones","description":"Actividad de conversación por oportunidad: mensajes pendientes, llamadas y última actividad"},{"name":"Credenciales","description":"Credenciales de proveedores propias de la empresa autenticada"},{"name":"Cuotas","description":"Cuotas de las ventas: listado, resumen, alta, edición, cobro, reversión, anulación e historial"},{"name":"Empleados IA","description":"Empleados IA de la empresa: listado, detalle, activar o desactivar, crear, editar, eliminar y sincronizar con Vapi, y voces de ElevenLabs. Crear, editar y sincronizar llaman a Vapi con el token de la credencial de la empresa; las voces usan la clave de ElevenLabs del servidor."},{"name":"Empleados IA","description":"Empleados IA de la empresa: listado, detalle, activar o desactivar, registro de los mensajes entrantes de WhatsApp (verify_from), crear, editar, eliminar y sincronizar con Vapi, y voces de ElevenLabs. Crear, editar y sincronizar llaman a Vapi con el token de la credencial de la empresa; las voces usan la clave de ElevenLabs del servidor."},{"name":"Empresa","description":"Gestión de la empresa autenticada"},{"name":"Estado","description":"Comprobar que la API responde y que la API key es válida"},{"name":"Etiquetas","description":"Gestión de etiquetas de los proyectos de la empresa y etiquetas globales de toda la empresa (igual que el SaaS v3)"},{"name":"Fuentes","description":"Fuentes de oportunidades: listar las visibles (globales y propias) y crear una propia"},{"name":"Ítems","description":"Gestión de ítems y tipos de ítem de la empresa"},{"name":"Leads","description":"Alta de un lead: contacto y oportunidad en un solo paso"},{"name":"Lista negra","description":"Lista negra: pausa del Empleado IA para un teléfono en un proyecto"},{"name":"Llamadas de proyecto","description":"Gestión de llamadas y contactos de proyectos"},{"name":"Memoria del Empleado IA","description":"Memoria conversacional que el Empleado IA usa como tool desde n8n: leer los últimos mensajes de una sesión, guardar un lote y reiniciarla por oportunidad, contacto o proyecto. Vive en `ai_memory.chat_memory`, separada del chat visible (`chat_histories`). Las rutas cuelgan de `/ai-employees/memory` por compatibilidad con n8n y el SaaS v3."},{"name":"Mensajes","description":"Historial de conversación de las oportunidades (chat_histories)"},{"name":"Monedas","description":"Gestión de monedas y monedas de la empresa"},{"name":"Multimedia","description":"Biblioteca de archivos y carpetas de la empresa autenticada"},{"name":"Oportunidades","description":"Gestión de oportunidades del sistema"},{"name":"Pipelines","description":"Gestión de pipelines del sistema"},{"name":"Proyectos","description":"Gestión de proyectos, sus estados y balance de minutos"},{"name":"Respuestas rápidas","description":"Atajos de texto (con archivo opcional) que la empresa usa para responder en el chat"},{"name":"Roles","description":"Gestión de roles de la empresa"},{"name":"Tickets","description":"Gestión de tickets (reclamos y solicitudes), métricas y navegación"},{"name":"Tickets","description":"Gestión de tickets de atención al cliente (ATC) por embudo: etapas y tipos propios de cada embudo, métricas y navegación"},{"name":"Usuarios","description":"Gestión de usuarios del sistema"},{"name":"Ventas","description":"Gestión de ventas y su detalle (las cuotas están en el grupo Cuotas)"}],"paths":{"/ventas/{ventaId}/detalle/{detalleId}":{"put":{"tags":["Ventas"],"summary":"Editar detalle de venta","description":"Actualiza item_id, cantidad o precio_unitario de un detalle y recalcula el total (cantidad × precio_unitario), como v3. 404 si el detalle no pertenece a esa venta o la venta es de otra empresa.","operationId":"updateDetalle","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"detalleId","in":"path","description":"UUID del detalle","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"cantidad":3,"precio_unitario":150.0}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Ventas"],"summary":"Eliminar detalle de venta","description":"Baja lógica del detalle (state = 0). 404 si el detalle no pertenece a esa venta o la venta es de otra empresa.","operationId":"deleteDetalle","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"detalleId","in":"path","description":"UUID del detalle","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detalle eliminado","content":{"application/json":{"example":{"status":"ok","id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890"}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}":{"put":{"tags":["Cuotas"],"summary":"Editar cuota","description":"Actualiza monto (> 0), fecha_vencimiento y metadata de una cuota pendiente. No cambia estado ni fecha de pago. 404 si la cuota no pertenece a esa venta o la venta es de otra empresa; 422 si la cuota no está pendiente.","operationId":"updateCuota","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","description":"UUID de la cuota","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"monto":350.0,"fecha_vencimiento":"2026-07-01"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Cuotas"],"summary":"Eliminar cuota","description":"Baja lógica de la cuota (state = 0). 404 si la cuota no pertenece a esa venta o la venta es de otra empresa; 422 si la cuota está pagada.","operationId":"deleteCuota","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","description":"UUID de la cuota","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cuota eliminada","content":{"application/json":{"example":{"status":"ok","id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891"}}}}}}},"/ventas/{id}":{"get":{"tags":["Ventas"],"summary":"Obtener venta por ID","description":"Retorna una venta específica con contacto, detalles y cuotas. 404 si no existe o es de otra empresa.","operationId":"getById","parameters":[{"name":"id","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}},"put":{"tags":["Ventas"],"summary":"Editar venta","description":"v3 actualiza contacto_id, nro_documento y fecha_venta. Esta API también acepta metadata para integraciones. No cambia la moneda ni el estado de anulación. 404 si la venta (o el contacto) no existe o es de otra empresa.","operationId":"update","parameters":[{"name":"id","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"nro_documento":"FAC-0001-B","fecha_venta":"2026-05-26T10:00:00+00:00"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Ventas"],"summary":"Eliminar venta","description":"Baja lógica (state = 0) de la venta y, en cascada, de sus detalles y cuotas. 404 si no existe o es de otra empresa.","operationId":"delete","parameters":[{"name":"id","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Venta eliminada","content":{"application/json":{"example":{"status":"ok","id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}}}}},"/users/{id}":{"get":{"tags":["Usuarios"],"summary":"Obtener usuario por ID","description":"Retorna un miembro activo de la empresa según su UUID. Si no existe o es de otra empresa responde 404. Nunca incluye hashed_password ni json_data.","operationId":"getById_1","parameters":[{"name":"id","in":"path","description":"UUID del usuario","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Usuario encontrado","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","state":1,"roles":[{"id":"rol-ventas","name":"Ventas","state":1}]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El usuario no existe o no es miembro activo de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Usuario no encontrado"}}}}}},"put":{"tags":["Usuarios"],"summary":"Editar usuario","description":"Actualiza el perfil de un miembro activo de la empresa. Solo se aceptan name, lastname, email y phone (el email se guarda en minúsculas y sin espacios); cualquier otro campo del cuerpo se ignora. Sin ningún campo permitido, o con name/email vacíos, responde 400; si el email (sin espacios ni mayúsculas) ya lo usa otro usuario responde 409 DUPLICATE y no modifica nada.","operationId":"update_1","parameters":[{"name":"id","in":"path","description":"UUID del usuario","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455"}}},"required":true},"responses":{"200":{"description":"Usuario actualizado","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","state":1,"roles":[{"id":"rol-ventas","name":"Ventas","state":1}]}}}},"400":{"description":"ID inválido, cuerpo sin campos editables, o name/email vacíos o de solo espacios","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"email es obligatorio"}}}},"409":{"description":"El email ya lo usa otro usuario","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe un usuario con ese email"}}}},"404":{"description":"El usuario no existe o no es miembro activo de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Usuario no encontrado"}}}}}},"delete":{"tags":["Usuarios"],"summary":"Quitar usuario de la empresa","description":"Quita al usuario como miembro de la empresa de la API key (companies_users.state = 0) y desactiva todos sus roles en esa empresa, tanto de módulo como de empresa. No modifica el usuario en sí: sigue activo en sus otras empresas.","operationId":"delete_1","parameters":[{"name":"id","in":"path","description":"UUID del usuario","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Miembro quitado","content":{"application/json":{"example":{"status":"ok","id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","roles_removed":2}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El usuario no existe o no es miembro activo de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Usuario no encontrado"}}}}}}},"/tickets/{id}":{"get":{"tags":["Tickets"],"summary":"Obtener ticket por ID","description":"Retorna un ticket específico de la empresa según su UUID, con `effective_pipeline_id`: el embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa), y con el responsable (`owner_id`, `owner_name`: nombre y apellido del usuario) y el origen (`source_id`, `source_name`), null si no tiene.","operationId":"getById_2","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"responses":{"200":{"description":"Ticket encontrado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}}}},"put":{"tags":["Tickets"],"summary":"Editar ticket","description":"Actualiza un ticket existente. Se aceptan `title` (si viene, no puede ser vacío; se guarda sin espacios sobrantes),\n`type`, `progress_state`, `project_id`, `contact_id`, `data` y los campos de integración `call_id`,\n`opportunity_id`, `external_id` y `nps`, además de `owner_id` y `source_id`. `id`, `company_id`, `state`, `created_at` y otras columnas se ignoran;\n`updated_at` se actualiza solo.\n\n**Embudo.** `type` y `progress_state` se validan, sin distinguir mayúsculas, contra los `ticket_type` y\n`ticket_stage` activos del embudo efectivo del ticket (si el cuerpo trae `project_id`, el del proyecto nuevo) y se\nguardan con la key de la tabla; una key de otro embudo responde 400 y no cambia nada. `type` y `progress_state`\nen `null` responden 400 (no se pueden vaciar). Este PUT **no** cambia el embudo: para eso `POST /tickets/{id}/move`.\n`contact_id` con `\"\"` se guarda como `null`. Las referencias deben ser de la empresa.\n\n**Responsable y origen.** `owner_id` (id de un miembro activo de la empresa, o su email, que se guarda como id; 400 si\nno es miembro) y `source_id` (origen global o de la empresa; 400 si es de otra). `null` o `\"\"` los quita. Un ticket\ncon `call_id` al que se le quita el origen vuelve a «Llamada» (lo hace la base).\n\n**`data`** se combina con el guardado, clave por clave y en un solo `UPDATE` (sin leer antes, así dos PUT con claves\ndistintas no se pisan): las claves que no se envían se conservan (adjuntos, prioridad, descripción y campos\npersonalizados), las que se envían reemplazan su valor y las que llegan con `null` se quitan; para vaciar un\ncampo personalizado se envía en `null`. `data: null` no cambia el `data` guardado y un `data` que no es objeto\nresponde 400. Si el `data` guardado no es un objeto JSON (texto, arreglo, `null`), el PUT lo reemplaza por\nun objeto con las claves enviadas. Un `data` con el escape `\\u0000` responde 400.\n\n**Aviso de claves desconocidas.** Igual que en `POST /tickets`: las claves de `data` con valor que no son un campo\ndefinido de la empresa (grupo `ticket` o `global`) ni reservadas se guardan y salen en `warnings` de la respuesta\n(`\"warnings\": [\"fasdf\"]`). Una clave en `null` (quitar) no avisa.\n","operationId":"update_2","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"examples":{"Editar datos y un campo personalizado":{"description":"Editar datos y un campo personalizado","value":{"title":"Reclamo por facturación duplicada","type":"RECLAMO","progress_state":"en_gestion","project_id":"b7c8d9e0-1234-5678-9abc-def012345678","owner_id":"9e1b7c52-4d3a-4f6e-8a21-5b0c7d9e3f11","source_id":"5c0e8f5a-1b7e-4a52-9a43-0f1c8b6f0001","data":{"formalizacion":"Texto actualizado","sentimiento":"NEUTRO","region":"Norte"}}},"Quitar responsable y origen":{"description":"Quitar responsable y origen","value":{"owner_id":null,"source_id":null}},"Vaciar un campo personalizado":{"description":"Vaciar un campo personalizado","value":{"data":{"region":null}}}}}},"required":true},"responses":{"200":{"description":"Ticket actualizado; con `warnings` si `data` trae claves que no son campos definidos ni reservadas","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Cuerpo inválido, type/progress_state nulos o que el embudo del ticket no tiene, o project_id/contact_id/opportunity_id/source_id que no son de la empresa u owner_id que no es miembro activo","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"progress_state inválido para el embudo del ticket. Valores permitidos: nuevo, en_gestion, resuelto, desestimado"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Tickets"],"summary":"Eliminar ticket","description":"Realiza un soft delete del ticket (state = 0); el registro no se borra de la base de datos. Es idempotente: repetir la llamada sobre un ticket ya eliminado de la empresa responde 200 sin cambios.","operationId":"delete_2","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"responses":{"200":{"description":"Ticket eliminado","content":{"application/json":{"example":{"status":"ok","id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}}}},"404":{"description":"Ticket no encontrado o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/{id}/tags":{"get":{"tags":["Tickets"],"summary":"Listar tags de un ticket","description":"Retorna las etiquetas activas asociadas a un ticket de la empresa autenticada. Si el ticket no existe, está eliminado o es de otra empresa, responde 404.","operationId":"listTags","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"responses":{"200":{"description":"Lista de tags","content":{"application/json":{"example":[{"ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"VIP","color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Ticket no encontrado (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ticket no encontrado"}}}}}},"put":{"tags":["Tickets"],"summary":"Reemplazar los tags de un ticket","description":"Deja exactamente la lista `tag_ids` como etiquetas activas del ticket, igual que el SaaS con `saas_update_ticket_tags`: las que salen quedan con `state = 0` (la fila no se borra), las que entran se insertan o se reactivan, y repetir la misma lista no duplica nada. Los ids repetidos se tratan como uno. **Lista vacía (`[]`): quita todas las etiquetas del ticket.** Cada etiqueta debe estar activa en el catálogo de tickets de la empresa; si alguna no lo está, responde 400 `REFERENCE_NOT_FOUND` y no cambia nada. Ticket inexistente, eliminado o de otra empresa: 404. Responde 200 con la lista resultante, con la misma forma que `GET /tickets/{id}/tags`.","operationId":"replaceTags","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tag_ids":["c3d4e5f6-a7b8-9012-cdef-123456789012"]}}},"required":true},"responses":{"200":{"description":"Tags resultantes","content":{"application/json":{"examples":{"Con tags":{"description":"Con tags","value":[{"ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"VIP","color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}]},"Lista vacía":{"description":"Lista vacía","value":[]}}}}},"400":{"description":"ID inválido, cuerpo inválido o etiqueta que no está activa en el catálogo de la empresa","content":{"application/json":{"examples":{"INVALID_ID":{"description":"INVALID_ID","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"INVALID_BODY":{"description":"INVALID_BODY","value":{"status":"error","code":"INVALID_BODY","message":"tag_ids debe ser un arreglo de UUID"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"tag_id no pertenece a la empresa"}}}}}},"404":{"description":"Ticket no encontrado (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ticket no encontrado"}}}}}}},"/tickets/{id}/notes/{noteId}":{"put":{"tags":["Tickets"],"summary":"Editar nota del ticket","description":"Reemplaza el título y el texto de la nota (como v3): `description` es obligatoria y un `title` omitido o vacío deja la nota sin título. El autor no cambia. La nota debe ser activa y de ese ticket.","operationId":"update_3","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"},{"name":"noteId","in":"path","description":"UUID de la nota","required":true,"schema":{"type":"string"},"example":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"title":"Llamada de seguimiento","description":"Texto corregido de la nota."}}},"required":true},"responses":{"200":{"description":"Nota actualizada","content":{"application/json":{"example":{"id":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35","ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","title":"Llamada de seguimiento","description":"El cliente confirmó que el cobro duplicado se revirtió.","state":1,"created_by":null,"author_name":null,"created_at":"2026-10-29T18:20:11.512345-04:00","updated_at":"2026-10-29T18:20:11.512345-04:00"}}}},"400":{"description":"Cuerpo inválido o `description` vacía","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"La descripción de la nota es obligatoria"}}}},"404":{"description":"Ticket o nota no encontrados (también si la nota es de otro ticket o ya se eliminó)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Nota no encontrada"}}}}}},"delete":{"tags":["Tickets"],"summary":"Eliminar nota del ticket","description":"Borrado lógico (`state = 0`) con `saas_delete_ticket_note`. Es idempotente: repetir la llamada sobre una nota ya eliminada de ese ticket responde 200 sin cambios. Una nota inexistente, de otro ticket o de otra empresa responde 404 con el mismo mensaje.","operationId":"delete_3","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"},{"name":"noteId","in":"path","description":"UUID de la nota","required":true,"schema":{"type":"string"},"example":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35"}],"responses":{"200":{"description":"Nota eliminada","content":{"application/json":{"example":{"status":"ok","id":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35"}}}},"404":{"description":"Ticket o nota no encontrados","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Nota no encontrada"}}}}}}},"/tags/{id}":{"get":{"tags":["Etiquetas"],"summary":"Obtener tag por ID","description":"Retorna un tag de un proyecto activo de la empresa o un tag global de la empresa, con la misma proyección que el listado (project_name, scope y usage_count)","operationId":"getById_3","parameters":[{"name":"id","in":"path","description":"UUID del tag","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Tag encontrado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"VIP","state":1,"color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","project_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","project_name":"Calificación leads","scope":"project","usage_count":3}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Tag inexistente, dado de baja o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tag no encontrado"}}}}}},"put":{"tags":["Etiquetas"],"summary":"Editar tag","description":"Edita name (se recorta) de un tag de un proyecto activo de la empresa autenticada o de un tag global de la empresa. Cualquier otro campo del cuerpo (incluido color, project_id, company_id, state e id) se ignora: un tag no cambia de alcance. Si cambia el nombre, no puede chocar con otra etiqueta (409 `DUPLICATE`, mismas reglas que al crear).","operationId":"update_4","parameters":[{"name":"id","in":"path","description":"UUID del tag","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Premium"}}},"required":true},"responses":{"200":{"description":"Tag actualizado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Premium","state":1,"color":"#28A745","created_at":"2026-05-25T10:00:00.000000+00:00","project_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","project_name":"Calificación leads","scope":"project","usage_count":3}}}},"400":{"description":"Nombre vacío","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"El nombre es obligatorio"}}}},"404":{"description":"Tag inexistente, dado de baja o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tag no encontrado"}}}},"409":{"description":"El nombre choca con otra etiqueta de la empresa","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe una etiqueta de toda la empresa con ese nombre"}}}}}},"delete":{"tags":["Etiquetas"],"summary":"Eliminar tag","description":"Realiza un soft delete del tag (state = 0), de proyecto o global. Solo si ninguna oportunidad activa lo usa, como en v3.","operationId":"delete_4","parameters":[{"name":"id","in":"path","description":"UUID del tag","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Tag eliminado","content":{"application/json":{"example":{"status":"ok","id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Tag inexistente, dado de baja o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tag no encontrado"}}}},"409":{"description":"Tag en uso por oportunidades activas","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"El tag está en uso por 3 oportunidades"}}}}}}},"/roles/{id}":{"get":{"tags":["Roles"],"summary":"Obtener rol por ID","description":"Retorna un rol específico según su ID","operationId":"getById_4","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"404":{"description":"Rol inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Rol no encontrado"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"200":{"description":"Rol encontrado","content":{"application/json":{"example":{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Administrador","description":"Acceso total al sistema","state":1,"origin":"user","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","module":"crm","module_id":null,"companies_modules_id":null,"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2025-01-01T00:00:00.000000+00:00"}}}}}},"put":{"tags":["Roles"],"summary":"Editar rol","description":"Actualiza name y description de un rol de la empresa autenticada. `id`, `company_id`, `state`, `companies_modules_id`, `module_id`, `origin` y `created_at` se ignoran si vienen en el cuerpo; `updated_at` se actualiza automáticamente.","operationId":"update_5","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Administrador actualizado","description":"Acceso actualizado"}}},"required":true},"responses":{"404":{"description":"Rol inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Rol no encontrado"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"200":{"description":"Rol actualizado","content":{"application/json":{"example":{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Administrador","description":"Acceso total al sistema","state":1,"origin":"user","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","module":"crm","module_id":null,"companies_modules_id":null,"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2025-01-01T00:00:00.000000+00:00"}}}}}},"delete":{"tags":["Roles"],"summary":"Eliminar rol","description":"Realiza un soft delete del rol (state = 0), no elimina el registro de la base de datos. Solo sobre roles de la empresa autenticada.","operationId":"delete_5","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Rol eliminado","content":{"application/json":{"example":{"status":"ok","id":"550e8400-e29b-41d4-a716-446655440000"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Rol inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/quick-replies/{id}":{"get":{"tags":["Respuestas rápidas"],"summary":"Obtener una respuesta rápida","description":"Devuelve una respuesta rápida activa de la empresa de la API key. Si no existe, fue borrada o es de otra empresa: 404.","operationId":"get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"La respuesta rápida","content":{"application/json":{"example":{"id":"b1c2d3e4-0000-4000-8000-000000000002","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","shortcut":"precios","message":"Te dejo la lista de precios","media_id":"5a0c0f6e-0000-4000-8000-0000000000aa","media":{"id":"5a0c0f6e-0000-4000-8000-0000000000aa","name":"Lista de precios","file_name":"precios.pdf","mime_type":"application/pdf","size_bytes":48213,"storage_path":"media_library/971d296d/precios-abc123.pdf","url":"https://files.example.com/media_library/971d296d/precios-abc123.pdf"},"user_id":null,"state":1,"created_at":"2026-11-16T15:05:00.000000+00:00","updated_at":"2026-11-16T15:05:00.000000+00:00"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe, fue borrada o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"La respuesta rápida no existe, fue borrada o no pertenece a la empresa"}}}}}},"put":{"tags":["Respuestas rápidas"],"summary":"Editar una respuesta rápida","description":"Reemplaza el atajo, el texto y el archivo de una respuesta rápida de la empresa de la API key. Mismo cuerpo y reglas que el alta; un `media_id` ausente, null o vacío deja la respuesta sin archivo. Cualquier `company_id` del cuerpo se ignora. Devuelve la fila editada.","operationId":"update_6","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"shortcut":"saludo","message":"Hola ${nombre}, ¿en qué te ayudo? 👋","media_id":null}}},"required":true},"responses":{"200":{"description":"Respuesta rápida editada","content":{"application/json":{"example":{"id":"b1c2d3e4-0000-4000-8000-000000000001","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","shortcut":"saludo","message":"Hola ${nombre}, ¿en qué te ayudo? 👋","media_id":null,"media":null,"user_id":null,"state":1,"created_at":"2026-11-16T15:00:00.000000+00:00","updated_at":"2026-11-16T15:00:00.000000+00:00"}}}},"400":{"description":"ID inválido (`INVALID_ID`) o cuerpo inválido (mismos casos que el alta)","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"El texto es obligatorio"}}}},"404":{"description":"No existe, fue borrada o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"La respuesta rápida no existe, fue borrada o no pertenece a la empresa"}}}},"409":{"description":"Otra respuesta rápida activa ya usa ese atajo","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe una respuesta rápida con el atajo \"/saludo\""}}}}}},"delete":{"tags":["Respuestas rápidas"],"summary":"Borrar una respuesta rápida","description":"Borrado lógico (`state = 0`) de una respuesta rápida de la empresa de la API key; el atajo queda libre para volver a usarse. Devuelve el id borrado.","operationId":"delete_6","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta rápida borrada","content":{"application/json":{"example":{"id":"b1c2d3e4-0000-4000-8000-000000000001"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe, ya fue borrada o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"La respuesta rápida no existe, fue borrada o no pertenece a la empresa"}}}}}}},"/projects/{projectId}/status/{statusId}":{"put":{"tags":["Proyectos"],"summary":"Editar estado de proyecto","description":"Actualiza name, key, color, order, contact_method, data, webhook, webhook2 o next_status_id de un estado del proyecto; otras columnas se ignoran. En los estados de sistema (key pending, ongoing, completed, failed, webhook) no se puede cambiar `key` ni `contact_method`.","operationId":"updateStatus","parameters":[{"name":"projectId","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}},{"name":"statusId","in":"path","description":"ID del estado","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Muy interesado","color":"#007BFF","order":3}}},"required":true},"responses":{"200":{"description":"Estado actualizado (sin webhook ni webhook2)","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"ID o JSON inválido, cuerpo sin campos válidos o next_status_id que no es un estado del proyecto","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"next_status_id ajeno":{"description":"next_status_id ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"next_status_id no es un estado activo del proyecto"}}}}}},"404":{"description":"El proyecto o el estado no existen o no son de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Estado no encontrado"}}}},"409":{"description":"Se intentó cambiar key o contact_method de un estado de sistema","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"No se puede cambiar key ni contact_method de un estado de sistema"}}}}}},"delete":{"tags":["Proyectos"],"summary":"Eliminar estado de proyecto","description":"Soft delete del estado (state = 0). Responde 409 si el estado tiene project_calls activas asociadas.","operationId":"deleteStatus","parameters":[{"name":"projectId","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}},{"name":"statusId","in":"path","description":"ID del estado","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Estado eliminado","content":{"application/json":{"example":{"status":"ok","id":"stat-001"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto o el estado no existen o no son de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Estado no encontrado"}}}},"409":{"description":"El estado tiene llamadas activas","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"No se puede eliminar el estado: tiene llamadas asociadas. Muévalas o elimínelas primero"}}}}}}},"/projects/{id}":{"get":{"tags":["Proyectos"],"summary":"Obtener proyecto por ID","description":"Retorna un proyecto específico con sus estados (sin webhook ni webhook2) y sin credenciales","operationId":"getById_5","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Proyecto encontrado","content":{"application/json":{"example":{"id":"proj-001","name":"Bot de ventas","state":1,"statuses":[{"id":"stat-001","name":"Pendiente","key":"pending","color":"#FFC107","order":1}]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}},"put":{"tags":["Proyectos"],"summary":"Editar proyecto","description":"Actualiza un proyecto de la empresa autenticada. Solo se aplican name, phone, end_call_hook, webhook_interaccion_humana, webhook_campaign, allowed_times, companies_channels_numbers_id, webhook_recontacto, max_concurrent_calls, is_active e is_active_sms; priority_method_call (Assistant o Squad); el resto de claves se ignora. ai_employee_id no se edita aquí porque el DTO de actualización de v3 no lo envía. companies_channels_numbers_id, si viene, debe ser un número de canal de la empresa. Cambiar is_active / is_active_sms arranca o detiene la cola de llamadas del proyecto.","operationId":"update_7","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Bot de ventas actualizado","priority_method_call":"Squad"}}},"required":true},"responses":{"200":{"description":"Proyecto actualizado (sin credenciales ni hooks)","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"ID inválido, JSON inválido, sin campos editables, prioridad inválida (INVALID_VALUE), valor demasiado largo o companies_channels_numbers_id ajeno","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"Prioridad inválida":{"description":"Prioridad inválida","value":{"status":"error","code":"INVALID_VALUE","message":"priority_method_call debe ser Assistant o Squad"}},"Referencia ajena":{"description":"Referencia ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"companies_channels_numbers_id no existe o no es de la empresa"}},"Valor demasiado largo":{"description":"Valor demasiado largo","value":{"status":"error","code":"INVALID_VALUE","message":"Un valor del cuerpo es demasiado largo para su campo"}}}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}},"delete":{"tags":["Proyectos"],"summary":"Eliminar proyecto","description":"Soft delete del proyecto (state = 0). No modifica is_active: la cola no se detiene por este medio.","operationId":"delete_7","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Proyecto eliminado","content":{"application/json":{"example":{"status":"ok","id":"proj-001"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe, ya estaba eliminado o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/project-calls/{id}":{"get":{"tags":["Llamadas de proyecto"],"summary":"Obtener llamada por ID","description":"Retorna el registro completo de una llamada/contacto","operationId":"getById_6","parameters":[{"name":"id","in":"path","description":"ID de la llamada","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Llamada encontrada","content":{"application/json":{"example":{"id":"abc123","project_id":"proj-001","contact_name":"Juan Pérez","contact_phone":"+59171234567","status":"stat-001","contact_method":"call","state":1,"call_date":"2026-05-25T10:00:00","summary":null,"json_data":{},"call_response":null,"opportunities_id":null,"register_date":"2026-05-25T10:00:00","updated_at":"2026-05-25T10:00:00"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La llamada no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}},"put":{"tags":["Llamadas de proyecto"],"summary":"Editar llamada","description":"Actualiza contact_name, contact_phone, summary, json_data, status, call_date u opportunities_id de una llamada de la empresa. `opportunities_id`, si viene, debe ser una oportunidad de la empresa. Las demás claves se ignoran. `status` debe ser un estado activo del mismo proyecto.","operationId":"update_8","parameters":[{"name":"id","in":"path","description":"ID de la llamada","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"status":"stat-002","summary":"El cliente mostró interés, llamar mañana","opportunities_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}},"required":true},"responses":{"200":{"description":"Llamada actualizada","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"ID o JSON inválido, cuerpo sin campos editables, valor demasiado largo u opportunities_id ajeno","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"Oportunidad ajena":{"description":"Oportunidad ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"opportunities_id no existe o no es de la empresa"}}}}}},"404":{"description":"La llamada no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}},"delete":{"tags":["Llamadas de proyecto"],"summary":"Eliminar llamada","description":"Soft delete de la llamada (state = 0)","operationId":"delete_8","parameters":[{"name":"id","in":"path","description":"ID de la llamada","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Llamada eliminada","content":{"application/json":{"example":{"status":"ok","id":"abc123"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La llamada no existe, ya estaba eliminada o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}}},"/pipeline/{pipelineId}/stage/{stageId}":{"put":{"tags":["Pipelines"],"summary":"Editar etapa de pipeline","description":"Actualiza name, position, pipeline_stage_status_id o status_name de una etapa. El trigger trigger_set_status puede sobrescribir pipeline_stage_status_id cuando cambia name; el resto se ignora.","operationId":"updateStage","parameters":[{"name":"pipelineId","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"2db9050a-67ac-40b1-a50c-3bfa05badbab"},{"name":"stageId","in":"path","description":"UUID de la etapa","required":true,"schema":{"type":"string"},"example":"b11f6e38-9e9d-4194-b660-a69ce4cc8350"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"En Progreso","position":1}}},"required":true},"responses":{"200":{"description":"Etapa actualizada","content":{"application/json":{"example":{"id":"b11f6e38-9e9d-4194-b660-a69ce4cc8350","name":"En revisión","position":1,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.201434+00:00","updated_at":"2026-05-15T17:24:05.201434+00:00","pipeline_stage_status_id":"af27b809-58c9-4b43-876a-321cf6fdfe69"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Etapa inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Etapa no encontrada"}}}}}},"delete":{"tags":["Pipelines"],"summary":"Eliminar etapa de pipeline","description":"Realiza un soft delete de la etapa (state = 0). El pipeline debe ser de la empresa y la etapa de ese pipeline.","operationId":"deleteStage","parameters":[{"name":"pipelineId","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"2db9050a-67ac-40b1-a50c-3bfa05badbab"},{"name":"stageId","in":"path","description":"UUID de la etapa","required":true,"schema":{"type":"string"},"example":"b11f6e38-9e9d-4194-b660-a69ce4cc8350"}],"responses":{"200":{"description":"Etapa eliminada","content":{"application/json":{"example":{"status":"ok","id":"b11f6e38-9e9d-4194-b660-a69ce4cc8350"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Etapa inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Etapa no encontrada"}}}}}}},"/pipeline/{id}":{"get":{"tags":["Pipelines"],"summary":"Obtener pipeline por ID","description":"Retorna un pipeline específico según su UUID, incluyendo sus etapas","operationId":"getById_7","parameters":[{"name":"id","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Pipeline encontrado","content":{"application/json":{"example":{"id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","name":"Segundo Pipeline","state":1,"companies_modules_id":267,"created_at":"2026-05-15T17:24:05.194772+00:00","updated_at":"2026-05-15T17:24:05.194772+00:00","project_id":null,"type":"IA","ocultar":null,"stages":[{"id":"b11f6e38-9e9d-4194-b660-a69ce4cc8350","name":"Pendiente","position":1,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.201434+00:00","updated_at":"2026-05-15T17:24:05.201434+00:00","pipeline_stage_status_id":"af27b809-58c9-4b43-876a-321cf6fdfe69","status_name":"En Progreso"},{"id":"fdaf5508-5062-42e7-84f3-4c8dd5e29aab","name":"Ganado","position":2,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.209844+00:00","updated_at":"2026-05-15T17:24:05.209844+00:00","pipeline_stage_status_id":"7ef1073e-fa88-4452-8956-28d04d16a963","status_name":"Ganado"},{"id":"f174cac4-b567-46bd-906c-7900efc289b0","name":"Perdido","position":3,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.215897+00:00","updated_at":"2026-05-15T17:24:05.215897+00:00","pipeline_stage_status_id":"438ab019-2ca7-4e10-869a-dced01fdf05a","status_name":"Perdido"}]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Pipeline inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Pipeline no encontrado"}}}}}},"put":{"tags":["Pipelines"],"summary":"Editar pipeline","description":"Actualiza name, type o project_id de un pipeline de la empresa autenticada; otras columnas, incluidas company_id, companies_modules_id, id, state y ocultar, se ignoran. project_id, si viene, debe ser un proyecto de la empresa. No modifica las etapas: usar los endpoints de /stage.","operationId":"update_9","parameters":[{"name":"id","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Pipeline ventas actualizado","type":"HUMAN"}}},"required":true},"responses":{"200":{"description":"Pipeline actualizado","content":{"application/json":{"example":{"id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","name":"Segundo Pipeline actualizado","state":1,"companies_modules_id":267,"created_at":"2026-05-15T17:24:05.194772+00:00","updated_at":"2026-05-15T17:24:05.194772+00:00","project_id":null,"type":"HUMAN"}}}},"400":{"description":"ID inválido, project_id ajeno o valor demasiado largo","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"Proyecto ajeno":{"description":"Proyecto ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"project_id no existe o no es de la empresa"}},"Valor demasiado largo":{"description":"Valor demasiado largo","value":{"status":"error","code":"INVALID_VALUE","message":"Un valor del cuerpo es demasiado largo para su campo"}}}}}},"404":{"description":"Pipeline inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Pipeline no encontrado"}}}}}},"delete":{"tags":["Pipelines"],"summary":"Eliminar pipeline","description":"Realiza un soft delete del pipeline y de sus etapas (state = 0), con las mismas reglas que el SaaS (SP saas_delete_pipeline). No elimina si el pipeline tiene un proyecto asignado, oportunidades activas, campañas activas o configuraciones de resultado de Empleado IA que apunten a sus etapas: responde 409 CONFLICT y no cambia nada.","operationId":"delete_9","parameters":[{"name":"id","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Pipeline eliminado","content":{"application/json":{"example":{"status":"ok","id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Pipeline inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Pipeline no encontrado"}}}},"409":{"description":"El pipeline está en uso (proyecto, oportunidades, campañas o resultados de Empleado IA)","content":{"application/json":{"examples":{"Con oportunidades":{"description":"Con oportunidades","value":{"status":"error","code":"CONFLICT","message":"El embudo tiene 12 oportunidades activas. Muévelas a otro embudo antes de eliminarlo"}},"Con proyecto":{"description":"Con proyecto","value":{"status":"error","code":"CONFLICT","message":"El embudo está asignado a un proyecto. Quítalo con PUT /pipeline/{id} y project_id null antes de eliminarlo"}}}}}}}}},"/phones/{id}":{"get":{"tags":["Empleados IA"],"summary":"Ver un teléfono registrado","operationId":"get_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Teléfono","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000002","phone_id":"4f1b7c0a-23de-4a58-9c6e-81d5a0b7e3f2","used_by":[]}}}},"404":{"description":"No encontrado","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Teléfono no encontrado"}}}}}},"put":{"tags":["Empleados IA"],"summary":"Editar nombre de teléfono","operationId":"update_10","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Recepción","display_name":"Ventas"}}},"required":true},"responses":{"200":{"description":"Actualizado","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000002","phone_id":"4f1b7c0a-23de-4a58-9c6e-81d5a0b7e3f2"}}}},"400":{"description":"Cuerpo inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_BODY","message":"No hay campos válidos para actualizar"}}}}}},"delete":{"tags":["Empleados IA"],"summary":"Dar de baja un teléfono","operationId":"delete_10","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dado de baja","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000002","state":0}}}},"409":{"description":"Usado por un proyecto","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"El teléfono está siendo usado por un proyecto activo"}}}}}}},"/opportunities/{opportunityId}/tags":{"put":{"tags":["Oportunidades"],"summary":"Reemplazar los tags de una oportunidad","description":"Deja exactamente la lista `tag_ids` como tags activos de la oportunidad, como hace v3 con `saas_update_opportunity_tags`: los que salen quedan con `state = 0` (la fila no se borra), los que entran se insertan o se reactivan, y repetir la misma lista no duplica nada. Los ids repetidos dentro de la lista se tratan como uno. **Lista vacía (`[]`): quita todos los tags de la oportunidad.** Todos los tags deben ser activos de la empresa (`company_id` de la empresa o de un proyecto de la empresa); si alguno no lo es, responde 400 `REFERENCE_NOT_FOUND` y no cambia nada. Oportunidad inexistente, eliminada o de otra empresa: 404. Responde 200 con la lista resultante, con la misma forma que `GET /opportunities/{opportunityId}/tag`.","operationId":"replaceTags_1","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tag_ids":["c3d4e5f6-a7b8-9012-cdef-123456789012"]}}},"required":true},"responses":{"200":{"description":"Tags resultantes","content":{"application/json":{"examples":{"Con tags":{"description":"Con tags","value":[{"opportunity_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"VIP","color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}]},"Lista vacía":{"description":"Lista vacía","value":[]}}}}},"400":{"description":"ID inválido, cuerpo inválido o tag que no es de la empresa","content":{"application/json":{"examples":{"INVALID_ID":{"description":"INVALID_ID","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"INVALID_BODY":{"description":"INVALID_BODY","value":{"status":"error","code":"INVALID_BODY","message":"tag_ids debe ser un arreglo de UUID"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"tag_id no pertenece a la empresa"}}}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/{opportunityId}/note/{noteId}":{"put":{"tags":["Oportunidades"],"summary":"Editar nota","description":"Actualiza `title` y/o `description` de una nota de la oportunidad indicada. `description` es obligatoria y no puede ser vacía (como en v3 y en `POST`): sin ella responde 400 `MISSING_FIELD`. Si la oportunidad o la nota no existen, o son de otra empresa, responde 404.","operationId":"updateNote","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"noteId","in":"path","description":"UUID de la nota","required":true,"schema":{"type":"string"},"example":"d1e2f3a4-b5c6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"title":"Seguimiento","description":"El cliente confirmó la reunión"}}},"required":true},"responses":{"200":{"description":"Nota actualizada","content":{"application/json":{"example":{"id":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","title":"Seguimiento","description":"El cliente confirmó la reunión","state":1,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","created_at":"2026-05-21T10:00:00.000000+00:00","updated_at":"2026-05-21T12:00:00.000000+00:00"}}}},"400":{"description":"ID inválido, cuerpo sin campos editables o `description` ausente o vacía","content":{"application/json":{"examples":{"INVALID_ID":{"description":"INVALID_ID","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"MISSING_FIELD":{"description":"MISSING_FIELD","value":{"status":"error","code":"MISSING_FIELD","message":"description es obligatorio"}}}}}},"404":{"description":"Oportunidad o nota no encontrada","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Nota no encontrada"}}}}}},"delete":{"tags":["Oportunidades"],"summary":"Eliminar nota","description":"Realiza un soft delete de la nota (state = 0). Si la oportunidad o la nota no existen, o son de otra empresa, responde 404.","operationId":"deleteNote","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"noteId","in":"path","description":"UUID de la nota","required":true,"schema":{"type":"string"},"example":"d1e2f3a4-b5c6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Nota eliminada","content":{"application/json":{"example":{"status":"ok","id":"d1e2f3a4-b5c6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Nota no encontrada","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Nota no encontrada"}}}}}}},"/opportunities/{opportunityId}/file/{fileId}":{"put":{"tags":["Oportunidades"],"summary":"Editar archivo","description":"Actualiza la URL de un archivo de la oportunidad indicada. Si la oportunidad o el archivo no existen, o son de otra empresa, responde 404.","operationId":"updateFile","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"fileId","in":"path","description":"UUID del archivo","required":true,"schema":{"type":"string"},"example":"e1f2a3b4-c5d6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"url":"https://storage.example.com/files/documento-v2.pdf"}}},"required":true},"responses":{"200":{"description":"Archivo actualizado","content":{"application/json":{"example":{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","url":"https://storage.example.com/files/documento-v2.pdf","uploaded_at":"2026-05-21T10:00:00.000000+00:00","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"created_at":"2026-05-21T10:00:00.000000+00:00","updated_at":"2026-05-21T12:00:00.000000+00:00"}}}},"400":{"description":"ID inválido o falta `url`","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad o archivo no encontrado","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Archivo no encontrado"}}}}}},"delete":{"tags":["Oportunidades"],"summary":"Eliminar archivo","description":"Realiza un soft delete del archivo (state = 0). Si la oportunidad o el archivo no existen, o son de otra empresa, responde 404.","operationId":"deleteFile","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"fileId","in":"path","description":"UUID del archivo","required":true,"schema":{"type":"string"},"example":"e1f2a3b4-c5d6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Archivo eliminado","content":{"application/json":{"example":{"status":"ok","id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Archivo no encontrado","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Archivo no encontrado"}}}}}}},"/opportunities/{id}":{"get":{"tags":["Oportunidades"],"summary":"Obtener oportunidad por ID","description":"Retorna una oportunidad de la empresa autenticada, con el contenido de `saas_get_opportunities_detail_v2` y los objetos `pipeline` y `company` (`id`, `name`). Una oportunidad inexistente, eliminada o de otra empresa responde 404.","operationId":"getById_8","parameters":[{"name":"id","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Oportunidad encontrada","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Franco Torres","state":1,"value":0.0,"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","source_id":null,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-03-04T02:35:16.890128+00:00","data":null,"owner":null,"update_user_id":"1ca4690e-6aab-499b-932c-f653fc647fb8","opportunitie_status_id":null,"campaign_id":null,"project_id":null,"contact":{"id":"71f6c859-5739-4345-9e1b-393c7ed78896","name":"Franco Torres","email":"franco@example.com","phone":null},"contact_list":null,"pipeline_stage":{"id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","name":"Pendiente","position":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab"},"pipeline":{"id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","name":"Gestión comercial"},"company":{"id":"13a9d0f1-29f2-4708-971b-060dd4a7bdb7","name":"Empresa de ejemplo"},"tags":null,"calls":[]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}},"put":{"tags":["Oportunidades"],"summary":"Editar oportunidad","description":"Actualiza una oportunidad de la empresa autenticada, igual que el SaaS v3. Solo se aceptan `name`, `pipeline_stage_id`, `contact_id`, `value`, `source_id`, `owner`, `project_id` y `data`. `data` se reemplaza completo, pero se conserva su `venta_ids` actual. `project_id` solo se asigna si la oportunidad aún no tiene proyecto; si ya tiene, se ignora. La etapa, el contacto y el proyecto nuevos deben ser de la empresa (400 si no). Una oportunidad inexistente, eliminada o de otra empresa responde 404.","operationId":"update_11","parameters":[{"name":"id","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Franco Torres","pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","value":"5000.00","owner":null}}},"required":true},"responses":{"200":{"description":"Oportunidad actualizada","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Franco Torres","state":1,"value":5000.0,"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","source_id":null,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-05-21T10:00:00.000000+00:00","data":null,"owner":null,"update_user_id":"1ca4690e-6aab-499b-932c-f653fc647fb8","opportunitie_status_id":null,"campaign_id":null,"project_id":null}}}},"400":{"description":"ID inválido, cuerpo sin campos editables o referencia que no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}},"delete":{"tags":["Oportunidades"],"summary":"Eliminar oportunidad","description":"Realiza un soft delete de la oportunidad (state = 0, updated_at = now()), no elimina el registro de la base de datos. Si no existe, ya estaba eliminada o es de otra empresa, responde 404.","operationId":"delete_11","parameters":[{"name":"id","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Oportunidad eliminada","content":{"application/json":{"example":{"status":"ok","id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/{id}/move":{"put":{"tags":["Oportunidades"],"summary":"Mover oportunidad de etapa","description":"Cambia la etapa (`pipeline_stage_id`) de una oportunidad de la empresa autenticada, igual que `PUT /opportunities/{opportunity_id}/move` de v1 y que el SaaS v3 (`jsonUpdate` de `opportunities`). Es un UPDATE real de la fila, así que el trigger `opportunities_update_history` escribe una fila en `opportunities_history` con `data` (estado anterior) y `data_change` (campos que cambiaron, incluido `pipeline_stage_id`). Mover a la etapa en que ya está responde 200 igual y también escribe historial (el UPDATE ocurre y cambia `updated_at`; `data_change` solo trae `updated_at`), como en v3. La etapa debe estar activa y ser de la empresa (400 `REFERENCE_NOT_FOUND`). Responde con la oportunidad actualizada, la misma forma que `PUT /opportunities/{id}`.","operationId":"move","parameters":[{"name":"id","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"pipeline_stage_id":"4c1d8e52-7a3b-4f0e-9d21-5b6a7c8d9e01"}}},"required":true},"responses":{"200":{"description":"Oportunidad movida","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Franco Torres","state":1,"value":5000.0,"pipeline_stage_id":"4c1d8e52-7a3b-4f0e-9d21-5b6a7c8d9e01","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","source_id":null,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-10-01T10:00:00.000000+00:00","data":null,"owner":null,"update_user_id":"1ca4690e-6aab-499b-932c-f653fc647fb8","opportunitie_status_id":null,"campaign_id":null,"project_id":null}}}},"400":{"description":"ID inválido (`INVALID_ID`), cuerpo no JSON (`INVALID_BODY`), falta `pipeline_stage_id` (`MISSING_FIELD`) o la etapa no es de la empresa (`REFERENCE_NOT_FOUND`)","content":{"application/json":{"examples":{"INVALID_ID":{"description":"INVALID_ID","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"MISSING_FIELD":{"description":"MISSING_FIELD","value":{"status":"error","code":"MISSING_FIELD","message":"pipeline_stage_id es obligatorio"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"pipeline_stage_id no pertenece a la empresa"}}}}}},"404":{"description":"Oportunidad no encontrada (inexistente, eliminada o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/multimedia/{id}":{"put":{"tags":["Multimedia"],"summary":"Editar archivo multimedia","description":"Renombra, actualiza la descripción o reemplaza el archivo manteniendo el enlace público existente. Se pueden enviar los campos de metadatos, el archivo o ambos.","operationId":"edit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"description","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Archivo actualizado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Archivo inexistente o ajeno","content":{"application/json":{"schema":{"type":"string"}}}},"413":{"description":"El archivo supera el máximo permitido","content":{"application/json":{"schema":{"type":"string"}}}},"415":{"description":"Extensión o MIME no permitido","content":{"application/json":{"schema":{"type":"string"}}}},"503":{"description":"El FTP no está configurado o disponible","content":{"application/json":{"schema":{"type":"string"}}}},"502":{"description":"Falló la escritura o verificación FTP","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/multimedia/{id}/state":{"put":{"tags":["Multimedia"],"summary":"Dar de baja o reactivar archivo multimedia","description":"Cambia `state` a 0 o 1. El archivo del FTP no se elimina.","operationId":"setState","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"active":false}}},"required":true},"responses":{"200":{"description":"Estado actualizado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Archivo inexistente o ajeno","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/multimedia/move":{"put":{"tags":["Multimedia"],"summary":"Mover archivos y carpetas","description":"Mueve en lote ids propios a una carpeta propia activa o a la raíz (`target_folder_id: null`). Envíe al menos un id de archivo o carpeta.","operationId":"move_1","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"target_folder_id":null,"media_ids":["UUID"],"folder_ids":[]}}},"required":true},"responses":{"200":{"description":"Conteo de recursos movidos","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Algún recurso o destino no existe o es ajeno","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/multimedia/folders/{id}":{"put":{"tags":["Multimedia"],"summary":"Renombrar carpeta multimedia","description":"Actualiza el nombre de una carpeta propia; no mueve archivos ni subcarpetas.","operationId":"renameFolder","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Campañas 2026"}}},"required":true},"responses":{"200":{"description":"Carpeta renombrada","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Carpeta inexistente o ajena","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/multimedia/folders/{id}/state":{"put":{"tags":["Multimedia"],"summary":"Dar de baja o reactivar carpeta","description":"Baja lógica (`active=false`) o reactivación (`active=true`). No se puede dar de baja una carpeta que tenga archivos o subcarpetas activos.","operationId":"setFolderState","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"active":false}}},"required":true},"responses":{"200":{"description":"Estado actualizado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Carpeta inexistente o ajena","content":{"application/json":{"schema":{"type":"string"}}}},"409":{"description":"La carpeta contiene recursos activos","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/moneda/base/{id}":{"put":{"tags":["Monedas"],"summary":"Marcar un registro como moneda base","description":"v3 no edita la moneda base: la cambia con saas_upsert_company_moneda_base. Este endpoint marca como base el registro company_moneda indicado (de la empresa autenticada) usando ese mismo SP; el cuerpo se ignora y el tipo_cambio no se modifica. Equivale a POST /moneda/base con la moneda_id de ese registro.","operationId":"updateMonedaBase","parameters":[{"name":"id","in":"path","description":"ID del registro company_moneda","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Moneda base actualizada","content":{"application/json":{"example":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","tipo_cambio":1,"is_base":true,"created_at":"2026-09-29T12:00:00.000000-04:00","updated_at":"2026-09-29T12:00:00.000000-04:00"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El registro no existe o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Moneda de la empresa no encontrada"}}}}}}},"/moneda/adicional/{id}":{"put":{"tags":["Monedas"],"summary":"Editar moneda adicional","description":"Actualiza el tipo de cambio (> 0) de una moneda adicional de la empresa, igual que v3. Solo se aplica tipo_cambio: company_id, moneda_id e is_base del cuerpo se ignoran. No sirve para la moneda base (responde 404).","operationId":"updateMonedaAdicional","parameters":[{"name":"id","in":"path","description":"ID del registro company_moneda","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"tipo_cambio":1.15}}},"required":true},"responses":{"200":{"description":"Moneda adicional actualizada","content":{"application/json":{"example":{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tipo_cambio":1.15,"is_base":false,"created_at":"2026-09-29T12:00:00.000000-04:00","updated_at":"2026-09-29T13:00:00.000000-04:00"}}}},"400":{"description":"ID inválido o tipo_cambio no es un número mayor que 0","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe, es de otra empresa o es la moneda base","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Moneda adicional no encontrada"}}}}}}},"/messages/status":{"put":{"tags":["Mensajes"],"summary":"Registrar el acuse de un mensaje (entregado, leído o fallido)","description":"Reemplaza a los nodos `select by message_id` + `update` de los flujos que procesan los estados de WhatsApp. Busca por `message_id` las filas activas de `chat_histories` **de oportunidades de la empresa de la key** y las actualiza con `RETURNING`: `delivered` fija `date_delivered`, `read` fija `date_read` y `failed` fija `data_error` (no toca las fechas). `timestamp` (ISO-8601 con zona, o sin ella = UTC) es obligatorio para `delivered` y `read`, y se ignora en `failed`. `error` es opcional y solo se usa con `failed`: un objeto se guarda tal cual; un texto se guarda como `{\"message\": \"...\"}`; sin `error` se guarda `{\"message\": \"failed\"}`. Si hay varias filas con el mismo `message_id` (duplicados históricos) se actualizan todas y se devuelve una. Sin ninguna fila: 404 (mismo mensaje para inexistente y ajeno).","operationId":"updateStatus_1","requestBody":{"description":"message_id y status son obligatorios. timestamp es obligatorio para delivered y read; error solo se usa con failed.","content":{"application/json":{"schema":{"type":"string"},"example":{"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","status":"delivered","timestamp":"2026-10-06T14:00:03Z"}}},"required":true},"responses":{"200":{"description":"Acuse registrado","content":{"application/json":{"example":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","date_delivered":"2026-10-01T14:00:03.000000Z","date_read":null,"data_error":null,"updated":true}}}},"400":{"description":"`INVALID_BODY` (no es JSON), `MISSING_FIELD` (`message_id`, `status`, o `timestamp` en delivered/read) o `INVALID_VALUE` (`message_id`, `status`, `timestamp` o `error` inválidos)","content":{"application/json":{"examples":{"Estado inválido":{"description":"Estado inválido","value":{"status":"error","code":"INVALID_VALUE","message":"status debe ser delivered, read o failed"}},"Falta timestamp":{"description":"Falta timestamp","value":{"status":"error","code":"MISSING_FIELD","message":"timestamp es obligatorio para delivered y read"}}}}}},"404":{"description":"Ningún mensaje activo de la empresa tiene ese `message_id` (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Mensaje no encontrado"}}}}}}},"/items/{id}":{"get":{"tags":["Ítems"],"summary":"Obtener ítem por ID","description":"Retorna un ítem específico según su UUID, incluyendo su tipo y el array 'media' con su galería completa (primario primero, luego por 'orden'). Array vacío si no tiene medios.","operationId":"getById_9","parameters":[{"name":"id","in":"path","description":"UUID del ítem","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Ítem encontrado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nombre":"Consultoría inicial","descripcion":"Sesión de consultoría de 1 hora","sku":"CONS-001","precio":150.0,"stock":12,"tiempo_entrega":"24h","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","company_moneda_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","tipo_item_id":"d4e5f6a7-b8c9-0123-defa-234567890123","metadata":{},"data":null,"state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","updated_at":"2026-05-25T10:00:00.000000+00:00","tipo":{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","tipo":"servicio","descripcion":"Servicios profesionales"},"media":[{"id":"e5f6a7b8-c9d0-1234-efab-345678901234","url":"https://ftp.uplabsai.com/items/a1b2c3d4/frontal.png","type":"image","media_key":"frontal","descripcion":"Vista frontal","is_primary":true,"orden":0,"size_bytes":154320,"created_at":"2026-07-28T09:00:00.000000+00:00","updated_at":"2026-07-28T09:00:00.000000+00:00"}]}}}},"404":{"description":"Ítem inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ítem no encontrado"}}}}}},"put":{"tags":["Ítems"],"summary":"Editar ítem","description":"Actualiza los datos de un ítem existente según su UUID y fija 'updated_at'. Se aceptan nombre, sku, descripcion, precio, company_moneda_id, tipo_item_id, stock y data; 'tiempo_entrega' y otras columnas se ignoran. Un 'sku' vacío lo deja en NULL; uno repetido responde 409. El campo 'stock' (entero) es opcional y acepta null: representa la cantidad disponible, es informativo — no se descuenta automáticamente al vender. Debe ser >= 0. El campo 'data' (opcional, objeto libre de pares string→string) son los 'campos personalizados' definidos por el usuario final desde la UI del CRM; la API no los valida ni los interpreta. ATENCIÓN: 'data' se reemplaza entero, no se fusiona. Enviar {} BORRA todos los campos personalizados del ítem — omitilo del payload si no querés tocarlos.","operationId":"update_12","parameters":[{"name":"id","in":"path","description":"UUID del ítem","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"nombre":"Consultoría avanzada","precio":200.0,"stock":25,"data":{"Sucursal":"Centro"}}}},"required":true},"responses":{"200":{"description":"Ítem actualizado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nombre":"Consultoría avanzada","precio":200.0,"stock":25,"state":1,"updated_at":"2026-05-25T12:00:00.000000+00:00"}}}},"400":{"description":"Payload inválido (p. ej. 'stock' negativo o no entero, tipo o moneda que no son de la empresa, sin campos)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El campo 'stock' debe ser un número entero (sin decimales)"}}}},"404":{"description":"Ítem inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ítem no encontrado"}}}},"409":{"description":"El SKU ya está en uso (es único en toda la base; la respuesta no revela a quién pertenece)","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"El SKU ya está en uso"}}}}}},"delete":{"tags":["Ítems"],"summary":"Eliminar ítem","description":"Realiza un soft delete del ítem (state = 0) y fija 'updated_at'. Su SKU sigue reservado.","operationId":"delete_12","parameters":[{"name":"id","in":"path","description":"UUID del ítem","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Ítem eliminado","content":{"application/json":{"example":{"status":"ok","id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"404":{"description":"Ítem inexistente, ya eliminado o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ítem no encontrado"}}}}}}},"/items/{id}/reactivate":{"put":{"tags":["Ítems"],"summary":"Reactivar ítem","description":"Reactiva un ítem dado de baja de la empresa autenticada.","operationId":"reactivateItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ítem reactivado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ítem inexistente, activo o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"UUID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}}}}},"/items/{id}/media/{mediaId}":{"put":{"tags":["Ítems"],"summary":"Editar medio de un ítem","description":"Actualiza media_key, descripcion, orden y/o is_primary del medio. El medio y el ítem deben pertenecer a la empresa autenticada.","operationId":"updateMedia","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"media_key":"frontal","descripcion":"Vista frontal","orden":1,"is_primary":true}}},"required":true},"responses":{"200":{"description":"Medio actualizado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ítem o medio inexistente, inactivo o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Medio no encontrado"}}}},"400":{"description":"UUID, cuerpo o valores inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El campo 'is_primary' debe ser booleano"}}}}}},"delete":{"tags":["Ítems"],"summary":"Eliminar medio de un ítem","description":"Da de baja lógicamente el medio (state = 0). El ítem y el medio deben pertenecer a la empresa autenticada.","operationId":"deleteMedia","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Medio eliminado","content":{"application/json":{"example":{"status":"ok","id":"e5f6a7b8-c9d0-1234-efab-345678901234"}}}},"404":{"description":"Ítem o medio inexistente, inactivo o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"UUID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}}}}},"/items/tipos/{id}":{"put":{"tags":["Ítems"],"summary":"Editar tipo de ítem","description":"Actualiza tipo y/o descripcion de un tipo de ítem según su UUID; se ignoran otras columnas.","operationId":"updateTipo","parameters":[{"name":"id","in":"path","description":"UUID del tipo","required":true,"schema":{"type":"string"},"example":"d4e5f6a7-b8c9-0123-defa-234567890123"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tipo":"producto","descripcion":"Productos físicos"}}},"required":true},"responses":{"400":{"description":"'tipo' inválido, 'descripcion' vacía o sin campos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El campo 'tipo' debe ser 'producto' o 'servicio'"}}}},"404":{"description":"Tipo inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tipo de ítem no encontrado"}}}}}},"delete":{"tags":["Ítems"],"summary":"Eliminar tipo de ítem","description":"Realiza un soft delete del tipo de ítem (state = 0)","operationId":"deleteTipo","parameters":[{"name":"id","in":"path","description":"UUID del tipo","required":true,"schema":{"type":"string"},"example":"d4e5f6a7-b8c9-0123-defa-234567890123"}],"responses":{"200":{"description":"Tipo eliminado","content":{"application/json":{"example":{"status":"ok","id":"d4e5f6a7-b8c9-0123-defa-234567890123"}}}},"404":{"description":"Tipo inexistente, ya eliminado o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tipo de ítem no encontrado"}}}}}}},"/custom-fields/{id}":{"put":{"tags":["Campos personalizados"],"summary":"Editar campo personalizado","description":"Actualiza solo grupo, type, name y order del campo activo de la empresa autenticada. El cambio de name no renombra claves históricas en data/json_data. `grupo` admite `global` (toda la empresa). Si cambia el nombre o el grupo, el resultado no puede chocar con otro campo (409 `DUPLICATE`) ni ser un nombre reservado de dato del ticket en `ticket` o `global` (400 `INVALID_VALUE`); mismas reglas que al crear.","operationId":"update_13","parameters":[{"name":"id","in":"path","description":"UUID del campo","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Solo se actualizan los campos enviados de grupo, type, name y order. name se normaliza a minúsculas ASCII con guion bajo.","content":{"application/json":{"schema":{"type":"string"},"example":{"name":"nombre_cliente","type":"text","order":1}}},"required":true},"responses":{"200":{"description":"Campo actualizado","content":{"application/json":{"example":{"id":"550e8400-e29b-41d4-a716-446655440000","grupo":"contact","type":"text","name":"nombre_cliente","order":1,"state":1}}}},"400":{"description":"ID, cuerpo o valores inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"grupo inválido"}}}},"404":{"description":"Campo inexistente, inactivo o ajeno","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Campo personalizado no encontrado"}}}},"409":{"description":"El nombre o grupo nuevo chocaría con otro campo","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe un campo con ese nombre en este grupo o como campo global"}}}}}},"delete":{"tags":["Campos personalizados"],"summary":"Dar de baja un campo personalizado","description":"Marca state = 0 en el campo activo de la empresa autenticada (borrado lógico).","operationId":"delete_13","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campo dado de baja","content":{"application/json":{"example":{"status":"ok","id":"550e8400-e29b-41d4-a716-446655440000"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Campo inexistente, inactivo o ajeno","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Campo personalizado no encontrado"}}}}}}},"/credentials/{id}":{"get":{"tags":["Credenciales"],"summary":"Ver una credencial","description":"Devuelve metadatos públicos; el secreto nunca sale de la API.","operationId":"get_2","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credencial","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000001","type":"vapi","name":"Llamadas","last4":"1234","source":"manual","n8n_synced":true,"used_by":[]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Credencial no encontrada"}}}}}},"put":{"tags":["Credenciales"],"summary":"Editar credencial","description":"Permite cambiar name o rotar secret; account_sid no es editable.","operationId":"update_14","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"Renombrar":{"description":"Renombrar","value":{"name":"OpenAI producción"}},"Rotar secreto":{"description":"Rotar secreto","value":{"secret":"sk-..."}}}}},"required":true},"responses":{"200":{"description":"Editada","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000001"}}}},"400":{"description":"ID o cuerpo inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Credencial no encontrada"}}}},"409":{"description":"Duplicada","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"La empresa ya tiene esta credencial"}}}}}},"delete":{"tags":["Credenciales"],"summary":"Dar de baja credencial","description":"Aplica la baja lógica en la base y después borra la credencial en n8n en best-effort: si n8n falla, la baja ya quedó hecha, se responde 200 y solo se registra el tipo de error. Credenciales en uso o de Meta no se eliminan.","operationId":"delete_14","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Baja lógica","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000001"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Credencial no encontrada"}}}},"409":{"description":"Está en uso","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La credencial está en uso"}}}}}}},"/contacts/{id}":{"get":{"tags":["Contactos"],"summary":"Obtener contacto por ID","description":"Retorna el contacto completo según su UUID, incluido `status` (`null` significa sin estado).","operationId":"getById_10","parameters":[{"name":"id","in":"path","description":"UUID del contacto","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"400":{"description":"ID inválido","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Contacto inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}},"200":{"description":"Contacto encontrado","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","contact_list_id":null,"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"+591 22334455","json_data":{},"created_at":"2025-07-17T14:00:47.876668","updated_at":"2025-07-17T14:00:47.876668","state":1,"status":"ganado","owner":null,"update_user_id":null,"documento_identidad":null}}}}}},"put":{"tags":["Contactos"],"summary":"Editar contacto","description":"Actualiza name, lastname, email, phone, country_code, documento_identidad, owner, json_data y status del contacto de la empresa. `status` admite prospecto, ganado, inactivo o null/cadena vacía para sin estado; si se omite no cambia. El sistema asigna el estado según oportunidades y ventas; solo avanza y el estado inactivo se asigna únicamente de forma manual. Las claves protegidas se ignoran y `updated_at` se actualiza automáticamente.","operationId":"update_15","parameters":[{"name":"id","in":"path","description":"UUID del contacto","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"22334455","documento_identidad":"12345678","status":"ganado","json_data":{}}}},"required":true},"responses":{"200":{"description":"Contacto actualizado","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","contact_list_id":null,"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"22334455","json_data":{},"created_at":"2025-07-17T14:00:47.876668","updated_at":"2025-07-18T09:12:31.120344","state":1,"status":"ganado","owner":null,"update_user_id":null,"documento_identidad":"12345678"}}}},"400":{"description":"ID, phone, country_code, json_data o status inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"status debe ser prospecto, ganado, inactivo o null (sin estado)"}}}},"404":{"description":"Contacto inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Contactos"],"summary":"Eliminar contacto","description":"Realiza un soft delete del contacto (state = 0) y actualiza updated_at; no elimina el registro de la base de datos. Solo sobre contactos de la empresa autenticada.","operationId":"delete_15","parameters":[{"name":"id","in":"path","description":"UUID del contacto","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Contacto eliminado","content":{"application/json":{"example":{"status":"ok","id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Contacto inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/company":{"get":{"tags":["Empresa"],"summary":"Obtener mi empresa","description":"Retorna los datos de la empresa autenticada","operationId":"getCompany","responses":{"200":{"description":"Datos de la empresa","content":{"application/json":{"example":{"id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","name":"Uplabs AI","nit":"1023456789","description":"Software para call centers","state":1,"category_data":{"industry":"Software","size":"11-50"},"contact_data":{"email":"contact@uplabs.ai","phone":"70000000","phone_code":"+591","web_site":"https://uplabs.ai"},"location_data":{"city":"La Paz","country":"Bolivia","postal_code":""},"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2025-01-01T00:00:00.000000+00:00"}}}},"404":{"description":"La empresa no existe o está dada de baja","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empresa no encontrada"}}}}}},"put":{"tags":["Empresa"],"summary":"Editar mi empresa","description":"Actualiza la empresa de la API key. Solo se aceptan name, nit, description, category_data, contact_data y location_data; cualquier otro campo del cuerpo (id, state, stripe_customer_id, group_id, name_slug, themes...) se ignora. Los tres objetos se fusionan clave a clave con lo guardado, igual que en el SaaS v3: basta con enviar las claves que cambian. updated_at se fija al momento de la edición. Sin ningún campo permitido responde 400.","operationId":"updateCompany","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Uplabs AI","contact_data":{"email":"contact@uplabs.ai","phone":"70000000"}}}},"required":true},"responses":{"200":{"description":"Empresa actualizada","content":{"application/json":{"example":{"id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","name":"Uplabs AI","nit":"1023456789","description":"Software para call centers","state":1,"category_data":{"industry":"Software","size":"11-50"},"contact_data":{"email":"contact@uplabs.ai","phone":"70000000","phone_code":"+591","web_site":"https://uplabs.ai"},"location_data":{"city":"La Paz","country":"Bolivia","postal_code":""},"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2026-09-30T12:00:00.000000+00:00"}}}},"400":{"description":"Cuerpo inválido, sin campos editables o name vacío","content":{"application/json":{"example":{"status":"error","code":"INVALID_BODY","message":"No hay campos para actualizar (name, nit, description, category_data, contact_data, location_data)"}}}},"404":{"description":"La empresa no existe o está dada de baja","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empresa no encontrada"}}}}}}},"/calendar/availability/rules/{id}":{"put":{"tags":["Calendario"],"summary":"Actualizar franja de disponibilidad","description":"Actualización parcial de una franja de la empresa de la API key (asesor con agenda y franja activa). Las validaciones del alta se aplican sobre el valor resultante (lo nuevo combinado con lo existente). La escritura es una sola sentencia atómica y actualiza updated_at.","operationId":"updateRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Actualización parcial: solo cambia lo que viene en el cuerpo. Campos editables: day_of_week (1-7), start_minute, end_minute (0-1440, múltiplos de 5, start < end sobre el valor resultante), timezone, project_id (null explícito = la franja aplica a todos los proyectos) y metadata (objeto). user_id no es editable: si viene debe ser el del dueño de la franja (para cambiar de asesor se borra y se crea otra).","content":{"application/json":{"schema":{"type":"string"},"example":{"day_of_week":2,"start_minute":600,"end_minute":1080,"project_id":null}}}},"responses":{"200":{"description":"Franja actualizada (fila completa, igual que el alta)","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","company_id":"0f1e2d3c-4b5a-4968-8777-665544332211","project_id":null,"user_id":"b2c3d4e5-f6a7-4890-9234-56789abcdef0","day_of_week":2,"start_minute":600,"end_minute":1080,"timezone":"America/La_Paz","state":1,"metadata":{},"updated_at":"2026-11-12T15:04:05.123456+00:00"}}}},"400":{"description":"Entrada inválida o referencia fuera de la empresa","content":{"application/json":{"examples":{"INVALID_VALUE":{"description":"INVALID_VALUE","value":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado en la empresa"}}}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}},"delete":{"tags":["Calendario"],"summary":"Eliminar lógicamente franja de disponibilidad","description":"Solo modifica franjas cuyo usuario sea asesor activo de la empresa de la API key.","operationId":"deleteRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"400":{"description":"Entrada inválida o referencia fuera de la empresa","content":{"application/json":{"examples":{"INVALID_VALUE":{"description":"INVALID_VALUE","value":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado en la empresa"}}}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/calendar/appointments/{id}":{"put":{"tags":["Calendario"],"summary":"Actualizar o reprogramar cita","description":"Solo actualiza eventos de la empresa de la API key; los ids ajenos y no existentes responden el mismo 404.","operationId":"update_16","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Cuerpo opcional; se actualizan solo los campos enviados. Campos comunes: starts_at, duration_minutes, user_id, status y timezone.","content":{"application/json":{"schema":{"type":"string"},"example":{"starts_at":"2026-10-08T11:00","duration_minutes":60,"status":"confirmed","timezone":"America/La_Paz"}}}},"responses":{"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"400":{"description":"ID o valores inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"status inválido"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/blacklist":{"get":{"tags":["Lista negra"],"summary":"Consultar la lista negra (por teléfono + proyecto, o por oportunidad)","description":"Dice si el Empleado IA está pausado. La pausa es por **(proyecto, teléfono en dígitos)**, no por oportunidad: pausar un número en un proyecto lo pausa en todas sus oportunidades de ese proyecto. Los parámetros eligen cómo se resuelve esa clave:\n- `phone` + `project_id`: directo (lo que hacen los nodos de n8n en cada mensaje entrante).\n- `opportunity_id` solo: el proyecto es el **propio de la oportunidad** (`opportunities.project_id`) y, si no tiene, el de su pipeline (`pipelines.project_id`); el propio va primero porque hay pipelines compartidos por varios proyectos. El teléfono sale de su contacto (`country_code` + `phone`, sin duplicar el código si `phone` ya lo trae). Sin proyecto en ninguno de los dos, o sin teléfono válido: 409.\n- Cualquier otra combinación (un solo `phone`, un solo `project_id`, nada): 400.\nEl teléfono se normaliza a dígitos (6 a 20) y se compara por **igualdad**, no por subcadena. Sin fila responde 200 con `found: false`. `paused` es verdadero si alguna fila activa del par tiene `on_off = true`; `on_off` repite ese valor con el nombre de la columna (lo leen los nodos de n8n). `resolved_from` dice qué selector produjo la clave (`phone` u `opportunity`). Nunca lee filas sin proyecto.","operationId":"get_3","parameters":[{"name":"phone","in":"query","description":"Teléfono; se normaliza a dígitos (`+591 7123-4567` = `59171234567`). Va junto con `project_id`","required":false,"schema":{"type":"string"},"example":59171234567},{"name":"project_id","in":"query","description":"Id del proyecto (varchar, no siempre UUID). Va junto con `phone`","required":false,"schema":{"type":"string"},"example":"2e3aa19d-fa4b-4d15-9467-383df3d79920"},{"name":"opportunity_id","in":"query","description":"UUID de la oportunidad. Solo, resuelve proyecto y teléfono; con `phone` + `project_id` es solo trazabilidad","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Estado de la lista negra","content":{"application/json":{"examples":{"Pausado":{"description":"Pausado","value":{"phone":"59171234567","project_id":"2e3aa19d-fa4b-4d15-9467-383df3d79920","found":true,"paused":true,"on_off":true,"updated_at":"2026-10-01T14:03:11.12","resolved_from":"phone"}},"Por oportunidad":{"description":"Por oportunidad","value":{"phone":"59171234567","project_id":"2e3aa19d-fa4b-4d15-9467-383df3d79920","found":true,"paused":true,"on_off":true,"updated_at":"2026-10-01T14:03:11.12","resolved_from":"opportunity","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"Sin fila":{"description":"Sin fila","value":{"phone":"59171234567","project_id":"2e3aa19d-fa4b-4d15-9467-383df3d79920","found":false,"paused":false,"on_off":false,"resolved_from":"phone"}}}}}},"400":{"description":"Combinación de selectores incompleta o ambigua (MISSING_FIELD); teléfono sin dígitos o fuera de 6 a 20, `project_id` con caracteres no permitidos u `opportunity_id` que no es UUID (INVALID_VALUE)","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"phone es obligatorio junto con project_id (o enviá solo opportunity_id)"}}}},"404":{"description":"El proyecto o la oportunidad no existen, están dados de baja o son de otra empresa (mismo mensaje)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}},"409":{"description":"Con `opportunity_id` solo: la oportunidad no tiene proyecto (ni propio ni en su pipeline), o su contacto no tiene un teléfono válido (CONFLICT)","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La oportunidad no tiene proyecto (ni propio ni en su pipeline); usá phone y project_id"}}}}}},"put":{"tags":["Lista negra"],"summary":"Pausar o reactivar al agente (por teléfono + proyecto, o por oportunidad)","description":"Reemplaza a `saas_set_black_list` y a los inserts directos de los flujos. La clave es **(proyecto, teléfono en dígitos)**; se elige con el cuerpo, igual que en `GET /blacklist`: `phone` + `project_id` (+ `opportunity_id` opcional de trazabilidad), o `opportunity_id` solo (proyecto propio de la oportunidad o, si no tiene, el de su pipeline, y teléfono de su contacto; sin proyecto o sin teléfono válido: 409). Llama a `saas_set_black_list_v2`: **rechaza teléfonos vacíos**, valida proyecto y oportunidad contra la empresa, serializa por (proyecto, número) para no duplicar filas, compara por igualdad y fija `updated_at`. `paused: true` pausa; `paused: false` despausa y conserva la fila; para retirarla de la lista usa `DELETE /blacklist/{id}` (borrado lógico). Idempotente: repetir la misma llamada actualiza la misma fila (`created: false`). `resolved_from` dice qué selector produjo la clave.","operationId":"put","requestBody":{"description":"`paused` (booleano) es obligatorio. Selector: `phone` + `project_id` (`phone` acepta texto o número; `project_id` es el identificador de proyecto, varchar, no necesariamente UUID) con `opportunity_id` opcional, o `opportunity_id` solo.","content":{"application/json":{"schema":{"type":"string"},"examples":{"Por teléfono y proyecto":{"description":"Por teléfono y proyecto","value":{"phone":"59171234567","project_id":"PRJ-0042","paused":true}},"Por oportunidad":{"description":"Por oportunidad","value":{"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","paused":true}}}}},"required":true},"responses":{"200":{"description":"Fila resultante. `created` es true si se insertó una fila nueva. `on_off` repite `paused`","content":{"application/json":{"example":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","phone":"59171234567","project_id":"2e3aa19d-fa4b-4d15-9467-383df3d79920","paused":true,"on_off":true,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","created":false,"updated_at":"2026-10-01T14:03:11.12","resolved_from":"opportunity"}}}},"400":{"description":"`MISSING_FIELD` (`paused`, o combinación de selectores incompleta o ambigua), `INVALID_VALUE` (teléfono sin dígitos o fuera de 6 a 20, `paused` que no es booleano, ids mal formados), `REFERENCE_NOT_FOUND` (proyecto u oportunidad que no son de la empresa) o `INVALID_BODY` (no es JSON)","content":{"application/json":{"examples":{"Falta phone":{"description":"Falta phone","value":{"status":"error","code":"MISSING_FIELD","message":"phone es obligatorio junto con project_id (o enviá solo opportunity_id)"}},"Proyecto ajeno":{"description":"Proyecto ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"project_id no existe o no es de la empresa"}},"Teléfono vacío":{"description":"Teléfono vacío","value":{"status":"error","code":"INVALID_VALUE","message":"El teléfono debe tener entre 6 y 20 dígitos"}},"Cuerpo inválido":{"description":"Cuerpo inválido","value":{"status":"error","code":"INVALID_BODY","message":"El cuerpo no es un JSON válido"}}}}}},"404":{"description":"Con `opportunity_id` solo: la oportunidad no existe, está eliminada o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"409":{"description":"Con `opportunity_id` solo: la oportunidad no tiene proyecto (ni propio ni en su pipeline), o su contacto no tiene un teléfono válido (CONFLICT)","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La oportunidad no tiene proyecto (ni propio ni en su pipeline); usá phone y project_id"}}}}}}},"/ai-employees/{id}":{"get":{"tags":["Empleados IA"],"summary":"Obtener Empleado IA por ID","description":"Detalle de un Empleado IA de la empresa de la key, con el mismo contenido que el listado. Inexistente, borrado o de otra empresa responden igual (404).","operationId":"getById_11","parameters":[{"name":"id","in":"path","description":"ID del Empleado IA","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Empleado IA encontrado","content":{"application/json":{"example":{"id":"5f7af145-bd88-4652-aad8-03925c207c1d","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","name":"Empleado de texto","prompt":"Responde por WhatsApp.","text_prompt":"Responde por WhatsApp.","first_greeting":"Hola","vapi_assistant_id":null,"id_companies_modules":457,"channel_type":"text","state":1,"is_active":true,"project":null}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empleado IA no encontrado"}}}}}},"put":{"tags":["Empleados IA"],"summary":"Editar un Empleado IA","description":"Equivale a `editar` de v3. Acepta `name`, `prompt` (voz, se espeja a Vapi), `text_prompt` (texto, solo en la base: editarlo no llama a Vapi; vacío lo limpia y n8n vuelve a usar `prompt`), `first_greeting`, `voice_config` (`voice_id`, `speed`, `style`, `stability`, `similarityBoost`, `language`), `transcriber_config.language` y `vapi_credential_id` (para cambiar de credencial; debe ser una credencial de Vapi de la empresa y dar acceso al asistente del empleado). Si el empleado tiene asistente en Vapi, lo actualiza leyendo el actual y fusionando solo lo enviado; luego guarda la fila. Si la base falla, la API restituye en Vapi los valores anteriores. No se pueden cambiar `company_id`, `state`, `channel_type`, `id_companies_modules` ni el token (el cliente no envía tokens). La empresa sale de la key.","operationId":"update_17","parameters":[{"name":"id","in":"path","description":"ID del Empleado IA","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"prompt":"Eres un asistente de ventas. Responde con brevedad.","text_prompt":"Responde por WhatsApp con tono cordial y breve.","first_greeting":"Hola, ¿en qué te ayudo?","voice_config":{"voice_id":"htFfPSZGJwjBv1CL0aMD","speed":1.0}}}},"required":true},"responses":{"200":{"description":"Empleado IA actualizado (mismo contenido que el detalle)","content":{"application/json":{"example":{"id":"b6d4755f-f494-410d-b183-46fa2c8ed02e","name":"Homero","prompt":"Eres un asistente de ventas. Responde con brevedad.","text_prompt":"Responde por WhatsApp con tono cordial y breve.","first_greeting":"Hola, ¿en qué te ayudo?","vapi_assistant_id":"0d8f2b6e-7c1a-4f35-9a4e-3b5d1c2e8f10","voice_config":{"provider":"11labs","voice_id":"htFfPSZGJwjBv1CL0aMD","speed":1.0},"channel_type":"omni","state":1,"is_active":true}}}},"400":{"description":"ID o cuerpo inválido, sin credencial de Vapi o credencial que no corresponde al asistente","content":{"application/json":{"examples":{"Sin credencial":{"description":"Sin credencial","value":{"status":"error","code":"MISSING_FIELD","message":"El campo vapi_credential_id es obligatorio: el empleado no tiene credencial de Vapi"}},"Sin campos":{"description":"Sin campos","value":{"status":"error","code":"INVALID_BODY","message":"No hay campos editables en el cuerpo"}}}}}},"404":{"description":"No existe, está borrado o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empleado IA no encontrado"}}}},"502":{"description":"Vapi rechazó la solicitud","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"Vapi rechazó la solicitud"}}}}}},"delete":{"tags":["Empleados IA"],"summary":"Eliminar un Empleado IA","description":"Borrado lógico (`is_delete = true`, `state = 0`), como `eliminar` de v3. **No llama a Vapi**: el asistente queda en Vapi y solo se desvincula (política: no destruir lo que la API no creó en esta petición; se puede borrar a mano en el panel de Vapi). Tampoco cambia el proyecto al que esté asignado (v3 igual). Un empleado ajeno, ya borrado o inexistente responde igual (404).","operationId":"delete_16","parameters":[{"name":"id","in":"path","description":"ID del Empleado IA","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Empleado IA eliminado","content":{"application/json":{"example":{"status":"ok","id":"b6d4755f-f494-410d-b183-46fa2c8ed02e"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empleado IA no encontrado"}}}}}}},"/ai-employees/{id}/active":{"put":{"tags":["Empleados IA"],"summary":"Activar o desactivar un Empleado IA","description":"Equivale al interruptor del SaaS: escribe `state` (`1` activo, `0` inactivo) y `updated_at` del Empleado IA de la empresa de la key, y devuelve el registro actualizado. No llama a Vapi ni cambia proyectos: igual que v3, desactivar un empleado asignado a un proyecto activo está permitido. No sirve para borrar. `active` debe ser un booleano.","operationId":"setActive","parameters":[{"name":"id","in":"path","description":"ID del Empleado IA","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"active":false}}},"required":true},"responses":{"200":{"description":"Empleado IA actualizado","content":{"application/json":{"example":{"id":"5f7af145-bd88-4652-aad8-03925c207c1d","name":"Empleado de texto","channel_type":"text","state":0,"is_active":false,"project":null}}}},"400":{"description":"ID o cuerpo inválido","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"Falta active":{"description":"Falta active","value":{"status":"error","code":"MISSING_FIELD","message":"El campo active es obligatorio"}},"active no booleano":{"description":"active no booleano","value":{"status":"error","code":"INVALID_VALUE","message":"active debe ser true o false"}}}}}},"404":{"description":"No existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empleado IA no encontrado"}}}}}}},"/advisor-calls/{id}":{"get":{"tags":["Llamadas de asesor"],"summary":"Consultar una llamada de asesor","description":"Devuelve la llamada con el mismo formato que recibe el webhook del número (`id`, `company_id`, `status`, `phone`, `contact`, `opportunity_id`, `user`, `number`, fechas, `duration_sec`, `end_cause`, `recording_url`) más `summary`, `transcript` y `webhook_error`. Solo llamadas de la empresa de la clave: otra empresa, 404 `NOT_FOUND`.","operationId":"get_4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Llamada","content":{"application/json":{"example":{"id":"3f0f4f0e-2d57-4c5e-9d1f-6b0a8c2d7e11","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","status":"completed","phone":"59171234567","contact":{"id":"c3d3e782-2148-449c-9224-c35d39760375","name":"Juan Pérez"},"opportunity_id":null,"user":{"id":"0b6a6c3e-9d6f-4d57-8a3e-1f5b2f3c9a10","name":"Ana Gómez","email":"ana@empresa.com"},"number":{"id":"31530e7b-1fea-4b3a-b30d-fb6fdc5fcb2d","identifier":"59170000077"},"started_at":"2026-11-13T14:00:00Z","answered_at":"2026-11-13T14:00:07Z","ended_at":"2026-11-13T14:02:12Z","duration_sec":125,"end_cause":"normal","recording_url":"https://crm.uplabsai.com/audio/971d296d-ec86-43dc-a559-a8df4f164e39/3f0f4f0e-2d57-4c5e-9d1f-6b0a8c2d7e11.wav","summary":"El cliente pidió una cotización.","transcript":[{"role":"bot","message":"Hola","time":0.5}],"webhook_error":null}}}},"404":{"description":"Llamada inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}},"put":{"tags":["Llamadas de asesor"],"summary":"Guardar resumen y transcripción de una llamada de asesor","description":"Lo llama el webhook del número con la API key de la empresa. Solo acepta `summary` (texto) y `transcript` (arreglo de `{role: \"bot\"|\"user\", message, time?}`, donde `time` es un número opcional); cualquier otro campo se ignora. Si el cuerpo no trae ninguno de los dos, 400. La llamada tiene que ser de la empresa de la clave: si no, 404 `NOT_FOUND` (mismo mensaje para inexistente y ajena). Devuelve la llamada actualizada, igual que el GET.","operationId":"update_18","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"summary":"El cliente pidió una cotización.","transcript":[{"role":"bot","message":"Hola, ¿en qué te ayudo?","time":0.5},{"role":"user","message":"Quiero una cotización"}]}}},"required":true},"responses":{"200":{"description":"Llamada actualizada","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"`INVALID_ID`, `INVALID_BODY` o `INVALID_VALUE`","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"transcript[0].role debe ser bot o user"}}}},"404":{"description":"Llamada inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}}},"/ventas":{"get":{"tags":["Ventas"],"summary":"Obtener todas las ventas","description":"Retorna las ventas activas de la empresa con contacto, detalles y cuotas, de la más recientemente actualizada a la más antigua. Sin `page` devuelve el arreglo completo (sin tope). Con `page` (desde 1; `limit` por defecto 50, de 1 a 200) devuelve el sobre `{data, page, limit, total, has_more}` con el mismo orden y desempate por `id`; si `has_more` es true pedí la página siguiente. Ejemplo con page: `{\"data\": [ ...ventas como en el arreglo... ], \"page\": 1, \"limit\": 50, \"total\": 123, \"has_more\": true}`.","operationId":"getAll","parameters":[{"name":"page","in":"query","description":"Página (desde 1). Si se omite, devuelve todas las ventas como arreglo","required":false,"schema":{"type":"string"},"example":1},{"name":"limit","in":"query","description":"Ventas por página (1 a 200, por defecto 50); solo con page","required":false,"schema":{"type":"string"},"example":50}],"responses":{"400":{"description":"page o limit inválidos","content":{"application/json":{"schema":{"type":"string"}}}},"200":{"description":"Lista de ventas (arreglo sin `page`; sobre con `page`)","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","contacto_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","project_id":null,"nro_documento":"FAC-0001","fecha_venta":"2026-05-25T10:00:00.000000+00:00","estado":"activa","motivo_anulacion":null,"fecha_anulacion":null,"anulada_por_user_id":null,"company_moneda_id":"d4e5f6a7-b8c9-0123-defa-234567890123","metadata":{},"state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","update_at":"2026-05-25T10:00:00.000000+00:00","contacto":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"Juan Pérez"},"detalles":[{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","item_id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","cantidad":2,"precio_unitario":150.0,"total":300.0,"item":{"id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","nombre":"Consultoría"}}],"cuotas":[{"id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891","monto":300.0,"estado":"pendiente","fecha_vencimiento":"2026-06-25"}]}]}}}}},"post":{"tags":["Ventas"],"summary":"Crear venta","description":"Registra una nueva venta con estado 'activa'. Obligatorios: contacto_id (de la empresa) y nro_documento. Si no se envía company_moneda_id se usa la moneda base de la empresa (400 si no tiene). Solo se aceptan contacto_id, nro_documento, fecha_venta, company_moneda_id, project_id y metadata; metadata.source se fija en 'api'. Si el contacto no tiene documento_identidad se completa con nro_documento, como hace v3. Contacto, moneda o proyecto ajenos: 404.","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"contacto_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","nro_documento":"FAC-0001","fecha_venta":"2026-05-25T10:00:00+00:00","company_moneda_id":"d4e5f6a7-b8c9-0123-defa-234567890123"}}},"required":true},"responses":{"201":{"description":"Venta creada","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","contacto_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","nro_documento":"FAC-0001","fecha_venta":"2026-05-25T10:00:00.000000+00:00","estado":"activa","state":1,"created_at":"2026-05-25T10:00:00.000000+00:00"}}}}}}},"/ventas/{ventaId}/detalle":{"get":{"tags":["Ventas"],"summary":"Listar detalles de venta","description":"Retorna los ítems incluidos en una venta; item trae id, nombre, sku, precio y descripcion. 404 si la venta no existe o es de otra empresa.","operationId":"listDetalles","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Lista de detalles","content":{"application/json":{"example":[{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","item_id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","cantidad":2,"precio_unitario":150.0,"total":300.0,"id_moneda_item_original":"d4e5f6a7-b8c9-0123-defa-234567890123","metadata":{"source":"api"},"state":1,"item":{"id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","nombre":"Consultoría","sku":"CON-01","precio":150.0,"descripcion":null}}]}}}}},"post":{"tags":["Ventas"],"summary":"Agregar detalle a venta","description":"Añade un ítem de la empresa a la venta. Obligatorio item_id; cantidad (entero > 0, por defecto 1) y precio_unitario (por defecto 0). El total se calcula como cantidad × precio_unitario y id_moneda_item_original toma la moneda de la venta, como v3. 404 si la venta o el ítem no existen o son de otra empresa.","operationId":"createDetalle","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"item_id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","cantidad":2,"precio_unitario":150.0,"metadata":{}}}},"required":true},"responses":{"201":{"description":"Detalle creado","content":{"application/json":{"example":{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","item_id":"f2a3b4c5-d6e7-8901-bcde-f12345678901","cantidad":2,"precio_unitario":150.0,"total":300.0,"state":1}}}}}}},"/ventas/{ventaId}/cuota":{"get":{"tags":["Cuotas"],"summary":"Listar cuotas de una venta","description":"Retorna las cuotas activas de una venta, por fecha de vencimiento descendente como v3. 404 si la venta no existe o es de otra empresa.","operationId":"listCuotas","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Lista de cuotas","content":{"application/json":{"example":[{"id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891","venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","monto":300.0,"monto_en_moneda_venta":300.0,"estado":"pendiente","fecha_vencimiento":"2026-06-25","fecha_pago_real":null,"company_moneda_id":"d4e5f6a7-b8c9-0123-defa-234567890123","id_moneda_venta":null,"metadata":{},"state":1}]}}}}},"post":{"tags":["Cuotas"],"summary":"Crear cuota","description":"Registra una cuota 'pendiente' en una venta de la empresa. Obligatorios: monto (> 0) y fecha_vencimiento (AAAA-MM-DD). company_moneda_id, id_moneda_venta y monto_en_moneda_venta toman por defecto los de la venta. Si la empresa sincroniza con la pasarela COCOA responde 409 y no crea nada (la sincronización la hace el WS de v3). 404 si la venta o la moneda no existen o son de otra empresa.","operationId":"createCuota","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"monto":300.0,"fecha_vencimiento":"2026-06-25","company_moneda_id":"d4e5f6a7-b8c9-0123-defa-234567890123","monto_en_moneda_venta":300.0,"id_moneda_venta":null,"metadata":{}}}},"required":true},"responses":{"409":{"description":"La empresa sincroniza sus cuotas con Cocoa","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"Esta empresa sincroniza sus cuotas con Cocoa: por ahora las cuotas se crean desde el SaaS"}}}},"201":{"description":"Cuota creada","content":{"application/json":{"example":{"id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891","venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","monto":300.0,"estado":"pendiente","fecha_vencimiento":"2026-06-25","state":1}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}/revertir-pago":{"post":{"tags":["Cuotas"],"summary":"Revertir pago de cuota","description":"Invoca saas_revertir_pago_cuota; user_id/user_email son opcionales y user_id, si se envía, debe ser miembro activo.","operationId":"revertirPagoCuota","parameters":[{"name":"ventaId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"motivo es obligatorio. user_id y user_email son opcionales.","content":{"application/json":{"schema":{"type":"string"},"example":{"motivo":"Pago duplicado"}}},"required":true},"responses":{"200":{"description":"Pago revertido","content":{"application/json":{"example":[{"success":true,"cuota_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}]}}},"400":{"description":"ID, cuerpo o campos inválidos","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"motivo es obligatorio"}}}},"404":{"description":"Venta o cuota no encontrada","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cuota no encontrado"}}}},"422":{"description":"Regla de negocio del SP","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Solo se puede revertir el pago de cuotas en estado pagado"}}}},"409":{"description":"La venta no está activa (igual que v3)","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La venta no está activa: no se puede revertir el pago"}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}/pagar":{"post":{"tags":["Cuotas"],"summary":"Registrar pago de cuota","description":"Invoca saas_marcar_cuota_pagada con tipo_pago amortizacion_comercial; user_id/user_email son opcionales y user_id, si se envía, debe ser miembro activo.","operationId":"pagarCuota","parameters":[{"name":"ventaId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"fecha_pago_real y motivo son obligatorios. user_id y user_email son opcionales.","content":{"application/json":{"schema":{"type":"string"},"example":{"fecha_pago_real":"2026-10-06","motivo":"Pago recibido"}}},"required":true},"responses":{"200":{"description":"Pago registrado","content":{"application/json":{"example":[{"success":true,"cuota_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}]}}},"422":{"description":"Regla de negocio del SP","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"No se puede marcar como pagada una cuota anulada"}}}},"400":{"description":"ID, cuerpo o campos inválidos","content":{"application/json":{"examples":{"Falta fecha_pago_real":{"description":"Falta fecha_pago_real","value":{"status":"error","code":"MISSING_FIELD","message":"fecha_pago_real es obligatorio"}},"Fecha inválida":{"description":"Fecha inválida","value":{"status":"error","code":"INVALID_VALUE","message":"Fecha inválida, se espera AAAA-MM-DD"}}}}}},"404":{"description":"Venta o cuota no encontrada","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cuota no encontrado"}}}},"409":{"description":"La cuota no está pendiente o la venta no está activa (igual que v3)","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"Solo se puede pagar una cuota pendiente (estado actual: pagado)"}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}/desanular":{"post":{"tags":["Cuotas"],"summary":"Desanular cuota","description":"Revierte la anulación de una cuota, restaurando su estado previo. El motivo es obligatorio y user_id, si se envía, debe ser un UUID. 404 si la cuota no pertenece a esa venta o la venta es de otra empresa; 422 si no está anulada.","operationId":"desanularCuota","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","description":"UUID de la cuota","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"motivo":"Reversión autorizada","user_id":"e5f6a7b8-c9d0-1234-efab-567890123456","user_email":"admin@empresa.com"}}},"required":true},"responses":{"200":{"description":"Cuota desanulada","content":{"application/json":{"example":{"success":true,"cuota_id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891"}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}/anular":{"post":{"tags":["Cuotas"],"summary":"Anular cuota","description":"Cambia el estado de la cuota a 'anulada' y deja historial. El motivo es obligatorio y user_id, si se envía, debe ser un UUID. 404 si la cuota no pertenece a esa venta o la venta es de otra empresa; 422 si ya está anulada.","operationId":"anularCuota","parameters":[{"name":"ventaId","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","description":"UUID de la cuota","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"motivo":"Cuota duplicada","user_id":"e5f6a7b8-c9d0-1234-efab-567890123456","user_email":"admin@empresa.com"}}},"required":true},"responses":{"200":{"description":"Cuota anulada","content":{"application/json":{"example":{"success":true,"cuota_id":"a2b3c4d5-e6f7-8901-abcd-ef1234567891"}}}}}}},"/ventas/{id}/desanular":{"post":{"tags":["Ventas"],"summary":"Desanular venta","description":"Revierte la anulación de una venta. El motivo es obligatorio y user_id, si se envía, debe ser un UUID. 404 si la venta no existe o es de otra empresa; 422 si no está anulada o falta el motivo.","operationId":"desanular","parameters":[{"name":"id","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"motivo":"Reactivación autorizada por gerencia","user_id":"e5f6a7b8-c9d0-1234-efab-567890123456","user_email":"admin@empresa.com"}}},"required":true},"responses":{"200":{"description":"Venta desanulada","content":{"application/json":{"example":[{"success":true,"venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}]}}}}}},"/ventas/{id}/anular":{"post":{"tags":["Ventas"],"summary":"Anular venta","description":"Cambia el estado de la venta a 'anulada' y deja historial. El motivo es obligatorio y user_id, si se envía, debe ser un UUID. 404 si la venta no existe o es de otra empresa; 422 si ya está anulada o falta el motivo.","operationId":"anular","parameters":[{"name":"id","in":"path","description":"UUID de la venta","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"motivo":"Error en la facturación","user_id":"e5f6a7b8-c9d0-1234-efab-567890123456","user_email":"admin@empresa.com"}}},"required":true},"responses":{"200":{"description":"Venta anulada","content":{"application/json":{"example":[{"success":true,"venta_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}]}}}}}},"/users":{"get":{"tags":["Usuarios"],"summary":"Obtener los usuarios de la empresa","description":"Retorna los miembros activos de la empresa de la API key, con sus roles en esa empresa. Nunca incluye hashed_password ni json_data.","operationId":"getAll_1","responses":{"200":{"description":"Lista de usuarios","content":{"application/json":{"example":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","state":1,"roles":[{"id":"rol-ventas","name":"Ventas","state":1}]}]}}}}},"post":{"tags":["Usuarios"],"summary":"Crear usuario","description":"Registra un usuario y lo agrega como miembro de la empresa de la API key, en una sola operación atómica. Solo se aceptan name, lastname, email, phone y password; el resto del cuerpo se ignora. name, email y password (mínimo 8 caracteres) son obligatorios. La contraseña se guarda con BCrypt, igual que en el SaaS v3; el email se guarda en minúsculas y sin espacios. Si ya existe un usuario con ese email responde 409 y no crea nada. La respuesta nunca incluye hashed_password.","operationId":"create_1","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","password":"secreta123"}}},"required":true},"responses":{"201":{"description":"Usuario creado exitosamente","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","state":1,"created_at":"2025-07-17T14:00:47.876668+00:00","updated_at":"2025-07-17T14:00:47.876668+00:00"}}}},"400":{"description":"Cuerpo inválido, falta name, email o password, o la contraseña tiene menos de 8 caracteres","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"password debe tener al menos 8 caracteres"}}}},"409":{"description":"Ya existe un usuario con ese email","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe un usuario con ese email"}}}}}}},"/tickets":{"get":{"tags":["Tickets"],"summary":"Obtener todos los tickets","description":"Retorna todos los tickets activos de la empresa (`saas_get_tickets_v2`), ordenados del más reciente al más antiguo, con el nombre del proyecto y del contacto asociados, el `effective_pipeline_id` (embudo efectivo: el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa) y el responsable y el origen (`owner_id`, `owner_name`, `source_id`, `source_name`; null si no tiene). Con `pipeline_id` solo devuelve los tickets de ese embudo efectivo. Sin `page` devuelve el arreglo completo (sin tope). Con `page` (desde 1; `limit` por defecto 50, de 1 a 200) devuelve el sobre `{data, page, limit, total, has_more}`, con el mismo orden y desempate por `id`; si `has_more` es true pedí la página siguiente.","operationId":"getAll_2","parameters":[{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Página (desde 1). Si se omite, devuelve todos los tickets como arreglo","required":false,"schema":{"type":"string"},"example":1},{"name":"limit","in":"query","description":"Tickets por página (1 a 200, por defecto 50); solo con page","required":false,"schema":{"type":"string"},"example":50}],"responses":{"400":{"description":"page o limit inválidos, o pipeline_id inválido","content":{"application/json":{"schema":{"type":"string"}}}},"200":{"description":"Lista de tickets (arreglo sin `page`; sobre `{data, page, limit, total, has_more}` con `page`)","content":{"application/json":{"example":[{"id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","company_id":"895e5a32-258b-46cf-b942-e6ee1e211d0a","title":"Reclamo por facturación duplicada","type":"RECLAMO","progress_state":"nuevo","pipeline_id":null,"effective_pipeline_id":"5d1c9d42-6f0e-4d7e-9c55-0a1f6f3b2a10","owner_id":"9e1b7c52-4d3a-4f6e-8a21-5b0c7d9e3f11","owner_name":"Ana Pérez","source_id":"5c0e8f5a-1b7e-4a52-9a43-0f1c8b6f0002","source_name":"Llamada","project_id":"b7c8d9e0-1234-5678-9abc-def012345678","project_name":"Cobranzas","contact_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","contact_name":"Juan Perez","phone":"+591 70000000","documento_identidad":"1234567","call_id":null,"opportunity_id":null,"external_id":null,"nps":8,"data":{"formalizacion":"El cliente reporta un cobro duplicado...","sentimiento":"NEGATIVO","emocion":"molestia","resumen":"Cobro duplicado en factura de julio","tipo":"RECLAMO"},"state":1,"created_at":"2026-08-19T16:01:10.003350","updated_at":null}]}}}}},"post":{"tags":["Tickets"],"summary":"Crear ticket","description":"Registra un ticket en un embudo de ATC. Campos: `title` (obligatorio), `pipeline_id`, `project_id`, `contact_id`,\n`type`, `progress_state`, `data`, `owner_id` y `source_id`; `call_id`, `opportunity_id`, `external_id` y `nps` se conservan para integraciones.\n`id`, `company_id`, `state` y `created_at` se asignan solos y las otras columnas se ignoran.\n\n**Embudo.** `pipeline_id` debe ser un embudo activo de la empresa (400 `REFERENCE_NOT_FOUND` si no). Sin él, el\nticket queda en el embudo efectivo: el por defecto del proyecto o, si no tiene, el de la empresa (se guarda\n`pipeline_id` null, como hace el SaaS). `type` y `progress_state` dependen del embudo: se validan, sin distinguir\nmayúsculas, contra los `ticket_type` y `ticket_stage` activos de ese embudo y se guardan con la key de la tabla\n(consúltalas en `GET /tickets/pipelines`). Sin `progress_state` (o en `null`) se usa la primera etapa `open` por\nposición y sin `type` (o en `null`) el primer tipo del embudo por `position`. `project_id`, `contact_id` y `opportunity_id`, si vienen, deben ser de la empresa.\n\n**Responsable.** `owner_id` es el id de un usuario que sea miembro activo de la empresa (`companies_users`) o su\nemail, que se convierte al id (así el ticket sigue asignado si la persona cambia su email). Si no es miembro, 400\n`REFERENCE_NOT_FOUND`. Sin él (o en `null`) el ticket queda sin responsable.\n\n**Origen.** `source_id` es un origen global o de la empresa (`GET /tickets/sources`); uno de otra empresa responde 400\n`REFERENCE_NOT_FOUND`. Un ticket que entra con `call_id` y sin `source_id` queda en «Llamada» (lo hace la base).\n`external_id` no es un origen.\n\n**Campos personalizados.** Los de la empresa (grupo `ticket` o `global`, ver `GET /custom-fields`) van dentro de\n`data`, con el nombre del campo como clave. Los nombres de datos propios del ticket (`priority`, `formalizacion`,\n`attachments`…) están reservados: `formalizacion`, `aclaracion`, `sentimiento`, `emocion`, `resumen`,\n`transcripcion`, `phone`, `proveedor`, `poliza`, `rubro`, `ejecutivo`, `motivo_desestimacion`,\n`observacion_resolucion`, `priority`, `attachments`, `tipo`, `datos_extraidos`, `deteccion`, `historial` e\n`issue_type`. Para quitar un campo después, `PUT` con esa clave en `null`.\n\n**Aviso de claves desconocidas.** Una clave de `data` que no es un campo personalizado definido de la empresa\n(grupo `ticket` o `global`) ni una clave reservada **se guarda igual** (n8n escribe claves propias), y la respuesta\ntrae `warnings`: el arreglo con esas claves, por ejemplo `\"warnings\": [\"fasdf\"]`. Sin claves desconocidas, la\nrespuesta no trae `warnings`.\n","operationId":"create_2","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"title":"Reclamo por facturación duplicada","pipeline_id":"5d1c9d42-6f0e-4d7e-9c55-0a1f6f3b2a10","type":"RECLAMO","progress_state":"nuevo","project_id":"b7c8d9e0-1234-5678-9abc-def012345678","contact_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","owner_id":"ana.perez@empresa.com","source_id":"5c0e8f5a-1b7e-4a52-9a43-0f1c8b6f0002","data":{"formalizacion":"El cliente reporta un cobro duplicado...","sentimiento":"NEGATIVO","region":"Norte"}}}},"required":true},"responses":{"201":{"description":"Ticket creado; con `warnings` si `data` trae claves que no son campos definidos ni reservadas","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Cuerpo inválido, type/progress_state que el embudo no tiene, o pipeline_id/project_id/contact_id/opportunity_id/source_id que no son de la empresa u owner_id que no es miembro activo","content":{"application/json":{"example":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"pipeline_id no existe en la empresa"}}}},"409":{"description":"El embudo no tiene una etapa abierta (`open`) para crear el ticket","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"El embudo del ticket no tiene una etapa abierta (open)"}}}}}}},"/tickets/{id}/tag":{"post":{"tags":["Tickets"],"summary":"Agregar tag a un ticket","description":"Asocia una etiqueta a un ticket de la empresa autenticada. La etiqueta debe estar activa en el catálogo de tickets de la empresa (`ticket_tag_catalog`). Si la asociación ya existe, la devuelve sin duplicarla; si había sido quitada (state = 0), la reactiva. Ticket inexistente o de otra empresa: 404; etiqueta inexistente, desactivada o de otra empresa: 400.","operationId":"addTag","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012"}}},"required":true},"responses":{"201":{"description":"Tag asociado","content":{"application/json":{"example":{"ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}}}},"400":{"description":"ID inválido, JSON inválido o etiqueta que no está activa en el catálogo de la empresa","content":{"application/json":{"example":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"tag_id no pertenece a la empresa"}}}},"404":{"description":"Ticket no encontrado (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ticket no encontrado"}}}}}}},"/tickets/{id}/resolver":{"post":{"tags":["Tickets"],"summary":"Resolver ticket","description":"Lleva el ticket a la etapa `resolved` de su embudo (la de menor `position` con `outcome = 'resolved'`; en el embudo por defecto, `resuelto`). Opcionalmente admite una `observacion` que se guarda en `data.observacion_resolucion`. Si el embudo no tiene una etapa `resolved`, responde 409.","operationId":"resolver","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"observacion":"Se emitió la nota de crédito correspondiente."}}}},"responses":{"200":{"description":"Ticket resuelto","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}},"409":{"description":"El embudo del ticket no tiene etapa con outcome resolved","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/{id}/notes":{"get":{"tags":["Tickets"],"summary":"Listar notas del ticket","description":"Notas internas activas del ticket, de la más nueva a la más antigua. `author_name` es el nombre del usuario del SaaS que la creó (`null` si se creó por la API sin `user_id`). Ticket inexistente, eliminado o de otra empresa: 404.","operationId":"list","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"responses":{"200":{"description":"Lista de notas (vacía si no hay)","content":{"application/json":{"example":[{"id":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35","ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","title":"Llamada de seguimiento","description":"El cliente confirmó que el cobro duplicado se revirtió.","state":1,"created_by":null,"author_name":null,"created_at":"2026-10-29T18:20:11.512345-04:00","updated_at":"2026-10-29T18:20:11.512345-04:00"}]}}},"400":{"description":"ID mal formado","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Ticket no encontrado o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ticket no encontrado"}}}}}},"post":{"tags":["Tickets"],"summary":"Crear nota del ticket","description":"Agrega una nota interna al ticket con `saas_save_ticket_note`. `description` es obligatoria y no puede quedar vacía; `title` es opcional. `user_id` (opcional) es el usuario del SaaS que figura como autor: debe pertenecer a la empresa de la key; sin él la nota queda sin autor (`created_by` y `author_name` en `null`). Se ignoran otras claves.","operationId":"create_3","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"title":"Llamada de seguimiento","description":"El cliente confirmó que el cobro duplicado se revirtió.","user_id":"a1b2c3d4-e5f6-4789-8abc-def012345678"}}},"required":true},"responses":{"201":{"description":"Nota creada","content":{"application/json":{"example":{"id":"5e1a7c42-3b0d-4f6e-8a21-9c4d7e0b1f35","ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","title":"Llamada de seguimiento","description":"El cliente confirmó que el cobro duplicado se revirtió.","state":1,"created_by":null,"author_name":null,"created_at":"2026-10-29T18:20:11.512345-04:00","updated_at":"2026-10-29T18:20:11.512345-04:00"}}}},"400":{"description":"Cuerpo inválido, `description` ausente o vacía, o `user_id` que no es de la empresa","content":{"application/json":{"examples":{"description vacía":{"description":"description vacía","value":{"status":"error","code":"MISSING_FIELD","message":"La descripción de la nota es obligatoria"}},"user_id ajeno":{"description":"user_id ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"user_id no existe en la empresa"}}}}}},"404":{"description":"Ticket no encontrado o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ticket no encontrado"}}}}}}},"/tickets/{id}/move":{"post":{"tags":["Tickets"],"summary":"Mover ticket a otro embudo","description":"Pasa el ticket a otro embudo de ATC de la empresa con `saas_move_ticket_to_pipeline`, el mismo SP que usa el SaaS.\n`pipeline_id` es obligatorio. `progress_state` y `type` son las keys destino y se validan contra las etapas y\ntipos del embudo destino (400 si no existen allí). Si no vienen: la etapa se conserva cuando el embudo destino la\ntiene y, si no, pasa a su primera etapa `open`; el tipo se conserva cuando existe allí y, si no, pasa al primero por\nposición. Mover al embudo por defecto de la empresa deja `pipeline_id` en null. `data` no cambia.\nResponde el ticket completo (con `effective_pipeline_id`).\n","operationId":"move_2","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"pipeline_id":"7e2b4a10-3c55-4b0f-9a12-5f6d8c9e0b31","progress_state":"kick_off","type":"ONBOARDING"}}},"required":true},"responses":{"200":{"description":"Ticket movido","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"pipeline_id ausente o que no es de la empresa; progress_state/type que el embudo destino no tiene","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}},"409":{"description":"El embudo destino no tiene etapa abierta (open) a la que pasar el ticket","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/{id}/desestimar":{"post":{"tags":["Tickets"],"summary":"Desestimar ticket","description":"Lleva el ticket a la etapa `dismissed` de su embudo (la de menor `position` con `outcome = 'dismissed'`;\nen el embudo por defecto, `desestimado`) y guarda el motivo dentro de `data.motivo_desestimacion`, en una sola\noperación atómica. El motivo debe tener al menos 10 caracteres. Si el embudo no tiene una etapa `dismissed`, responde 409.\n","operationId":"desestimar","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"motivo":"El cliente confirmó que el cobro sí correspondía."}}},"required":true},"responses":{"200":{"description":"Ticket desestimado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}},"409":{"description":"El embudo del ticket no tiene etapa con outcome dismissed","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/tag-catalog":{"get":{"tags":["Tickets"],"summary":"Catálogo de etiquetas de tickets","description":"Etiquetas activas del catálogo de tickets de la empresa autenticada, ordenadas por nombre (SP `saas_get_ticket_tag_catalog`). El catálogo es propio de los tickets, por empresa y sin proyecto; no es el de oportunidades (`/tags`). `usage_count` cuenta los tickets activos que la usan.","operationId":"tagCatalog","responses":{"200":{"description":"Catálogo","content":{"application/json":{"example":[{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","company_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"VIP","color":"#FF5733","state":1,"created_at":"2026-11-04T10:00:00.000000+00:00","updated_at":"2026-11-04T10:00:00.000000+00:00","usage_count":3}]}}}}},"post":{"tags":["Tickets"],"summary":"Crear etiqueta del catálogo de tickets","description":"Crea una etiqueta en el catálogo de tickets de la empresa autenticada (SP `saas_create_ticket_tag`). `name` es obligatorio, de hasta 100 caracteres y único en la empresa sin distinguir mayúsculas; `color` es opcional (hasta 50 caracteres). Si el SP rechaza el valor (nombre vacío, largo o repetido), responde 400 con el mensaje del SP.","operationId":"createCatalogTag","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"VIP","color":"#FF5733"}}},"required":true},"responses":{"201":{"description":"Etiqueta creada","content":{"application/json":{"example":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","company_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"VIP","color":"#FF5733","state":1,"created_at":"2026-11-04T10:00:00.000000+00:00","updated_at":"2026-11-04T10:00:00.000000+00:00"}}}},"400":{"description":"Cuerpo inválido o nombre rechazado por el SP","content":{"application/json":{"examples":{"Nombre repetido":{"description":"Nombre repetido","value":{"status":"error","code":"INVALID_VALUE","message":"Ya existe una etiqueta llamada \"VIP\""}},"Nombre vacío":{"description":"Nombre vacío","value":{"status":"error","code":"INVALID_VALUE","message":"El nombre de la etiqueta es obligatorio"}}}}}}}}},"/tickets/sources":{"get":{"tags":["Tickets"],"summary":"Orígenes de tickets","description":"Orígenes que puede usar la empresa en `source_id` (`saas_get_ticket_sources`): los globales (`company_id` null, `is_global` true: Llamada, WhatsApp, Correo, Web) y los propios de la empresa, activos y ordenados por nombre. Es un catálogo propio de tickets, distinto de las fuentes de oportunidades.","operationId":"getSources","responses":{"200":{"description":"Lista de orígenes","content":{"application/json":{"example":[{"id":"5c0e8f5a-1b7e-4a52-9a43-0f1c8b6f0001","company_id":null,"name":"Correo","state":1,"created_at":"2026-11-04T10:00:00-05:00","updated_at":"2026-11-04T10:00:00-05:00","is_global":true},{"id":"5c0e8f5a-1b7e-4a52-9a43-0f1c8b6f0002","company_id":null,"name":"Llamada","state":1,"created_at":"2026-11-04T10:00:00-05:00","updated_at":"2026-11-04T10:00:00-05:00","is_global":true},{"id":"7d21a9c4-3e55-4d0b-8a77-2b6f4c9e1a10","company_id":"895e5a32-258b-46cf-b942-e6ee1e211d0a","name":"Redes sociales","state":1,"created_at":"2026-11-04T11:30:00-05:00","updated_at":"2026-11-04T11:30:00-05:00","is_global":false}]}}}}},"post":{"tags":["Tickets"],"summary":"Crear origen de tickets","description":"Crea un origen propio de la empresa (`saas_create_ticket_source`) para usarlo en `source_id`. `name` es obligatorio, hasta 100 caracteres; se guarda sin espacios sobrantes. El nombre no puede repetirse, sin distinguir mayúsculas, entre los globales y los de la empresa (409 `DUPLICATE`). Solo se ve en la empresa de la API key.","operationId":"createSource","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Redes sociales"}}},"required":true},"responses":{"201":{"description":"Origen creado","content":{"application/json":{"example":{"id":"7d21a9c4-3e55-4d0b-8a77-2b6f4c9e1a10","company_id":"895e5a32-258b-46cf-b942-e6ee1e211d0a","name":"Redes sociales","state":1,"created_at":"2026-11-04T11:30:00-05:00","updated_at":"2026-11-04T11:30:00-05:00","is_global":false}}}},"400":{"description":"Nombre vacío, demasiado largo o cuerpo inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El nombre del origen es obligatorio"}}}},"409":{"description":"Ya existe un origen con ese nombre (global o de la empresa)","content":{"application/json":{"example":"    {\"status\":\"error\",\"code\":\"DUPLICATE\",\"message\":\"Ya existe un origen llamado \"Web\"\"}\n"}}}}}},"/tags":{"get":{"tags":["Etiquetas"],"summary":"Obtener todos los tags","description":"Lista los tags activos de la empresa autenticada, igual que v3 (saas_get_tags_by_company): los de sus proyectos activos y los globales de toda la empresa, con project_name, scope y usage_count. Cada tag trae `scope`: `project` (de un proyecto) o `global` (de toda la empresa, con project_id y project_name nulos). Orden: globales primero, luego por proyecto y nombre. Con project_id se filtra por un proyecto de la empresa y solo trae los de ese proyecto (sin globales).","operationId":"getAll_3","parameters":[{"name":"project_id","in":"query","description":"Filtra por un proyecto activo de la empresa","required":false,"schema":{"type":"string"},"example":"c3d4e5f6-a7b8-9012-cdef-123456789012"}],"responses":{"200":{"description":"Lista de tags ([] si no hay)","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"VIP","state":1,"color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","project_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","project_name":"Calificación leads","scope":"project","usage_count":3}]}}},"400":{"description":"project_id con formato inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}}}},"404":{"description":"project_id de un proyecto inexistente, dado de baja o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}},"post":{"tags":["Etiquetas"],"summary":"Crear tag","description":"Crea un tag en la empresa autenticada. Con `project_id` es un tag de ese proyecto activo, como v3: id, name, project_id y state 1 (company_id queda en NULL). **Sin `project_id` (omitido, nulo o vacío) es un tag global de toda la empresa**: se guarda sin proyecto y con company_id, y lo ofrecen todos los proyectos y embudos. Se leen name (obligatorio, se recorta) y project_id (opcional); el resto del cuerpo se ignora. `color` no se escribe porque v3 no lo envía. Un global no puede repetir el nombre de ninguna etiqueta de la empresa, y uno de proyecto no puede repetir el de un global (409 `DUPLICATE`, sin distinguir mayúsculas).","operationId":"create_4","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"De un proyecto":{"description":"De un proyecto","value":{"name":"VIP","project_id":"c3d4e5f6-a7b8-9012-cdef-123456789012"}},"Global (toda la empresa)":{"description":"Global (toda la empresa)","value":{"name":"VIP"}}}}},"required":true},"responses":{"201":{"description":"Tag creado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"VIP","state":1,"color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","project_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","project_name":"Calificación leads","scope":"project","usage_count":0}}}},"400":{"description":"project_id de un proyecto inexistente, dado de baja o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado"}}}},"409":{"description":"El nombre choca con otra etiqueta de la empresa","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe una etiqueta con ese nombre en la empresa"}}}}}}},"/sources":{"get":{"tags":["Fuentes"],"summary":"Listar fuentes visibles","description":"Incluye fuentes globales y las privadas de la empresa de la key.","operationId":"getSources_1","responses":{"200":{"description":"Fuentes","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","name":"Web"}]}}},"503":{"description":"Base no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"Base de datos no disponible"}}}}}},"post":{"tags":["Fuentes"],"summary":"Crear fuente","description":"Crea o recupera la fuente visible con ese nombre. company_id siempre se fuerza desde la API key.","operationId":"createSource_1","requestBody":{"description":"Solo acepta name, obligatorio y no vacío. company_id se deriva de la API key.","content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Web"}}},"required":true},"responses":{"201":{"description":"Fuente creada o existente","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","name":"Web"}]}}},"400":{"description":"Cuerpo no JSON","content":{"application/json":{"example":{"status":"error","code":"INVALID_BODY","message":"El cuerpo no es un JSON válido"}}}}}}},"/roles":{"get":{"tags":["Roles"],"summary":"Obtener todos los roles","description":"Retorna la lista de roles de la empresa autenticada","operationId":"getAll_4","responses":{"200":{"description":"Lista de roles","content":{"application/json":{"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Administrador","description":"Acceso total al sistema","state":1,"origin":"user","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","module":"crm","module_id":null,"companies_modules_id":null,"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2025-01-01T00:00:00.000000+00:00"}]}}}}},"post":{"tags":["Roles"],"summary":"Crear rol","description":"Crea un nuevo rol para la empresa autenticada. Solo acepta name, description y companies_modules_id; el resto se ignora. `name` es obligatorio. El ID siempre se genera en el servidor (si se envía, solo se valida su formato), `company_id` y `state` salen de la API key, `origin` siempre es `user` y `module_id` se deriva de `companies_modules_id`, que debe ser un módulo contratado por la empresa.","operationId":"create_5","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Administrador","description":"Acceso total al sistema"}}},"required":true},"responses":{"201":{"description":"Rol creado exitosamente","content":{"application/json":{"example":{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Administrador","description":"Acceso total al sistema","state":1,"origin":"user","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","module":"crm","module_id":null,"companies_modules_id":null,"created_at":"2025-01-01T00:00:00.000000+00:00","updated_at":"2025-01-01T00:00:00.000000+00:00"}}}},"400":{"description":"name ausente o vacío, id o companies_modules_id inválidos","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"companies_modules_id no pertenece a la empresa","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/roles/{id}/permissions":{"get":{"tags":["Roles"],"summary":"Obtener permisos del rol","description":"Retorna todos los permisos disponibles para la empresa, indicando cuáles están asignados al rol","operationId":"getPermissions","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"404":{"description":"Rol inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"type":"string"}}}},"200":{"description":"Lista de permisos con su asignación al rol","content":{"application/json":{"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Ver usuarios","module_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"roles_permission":{"id":"9d1f0c52-3a0b-4c1e-8f8e-2b6a7c1d4e55","rol_id":"550e8400-e29b-41d4-a716-446655440000","permission_id":"550e8400-e29b-41d4-a716-446655440000","state":1}}]}}}}},"post":{"tags":["Roles"],"summary":"Asignar permiso al rol","description":"Asigna un permiso a un rol de la empresa. Si la asignación ya existe con state = 0 la reactiva; si ya está activa no hace nada (idempotente). El permiso debe existir y ser general o de un módulo contratado por la empresa.","operationId":"assignPermission","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"permission_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}},"required":true},"responses":{"201":{"description":"Permiso asignado","content":{"application/json":{"example":{"status":"ok","rol_id":"550e8400-e29b-41d4-a716-446655440000","permission_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido o permission_id ausente","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Rol inexistente o de otra empresa, o permiso inexistente / de un módulo no contratado","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/quick-replies":{"get":{"tags":["Respuestas rápidas"],"summary":"Listar respuestas rápidas","description":"Devuelve las respuestas rápidas activas de la empresa de la API key, ordenadas por atajo. `search` busca en el atajo (se ignora la «/») o en el texto, sin distinguir mayúsculas. Sin resultados devuelve `[]`. El atajo se guarda sin la «/».","operationId":"list_1","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Arreglo de respuestas rápidas (`media` es null si no tiene archivo o ya no está activo en Multimedia)","content":{"application/json":{"example":[{"id":"b1c2d3e4-0000-4000-8000-000000000001","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","shortcut":"saludo","message":"Hola ${nombre}, ¿en qué te ayudo? 👋","media_id":null,"media":null,"user_id":null,"state":1,"created_at":"2026-11-16T15:00:00.000000+00:00","updated_at":"2026-11-16T15:00:00.000000+00:00"},{"id":"b1c2d3e4-0000-4000-8000-000000000002","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","shortcut":"precios","message":"Te dejo la lista de precios","media_id":"5a0c0f6e-0000-4000-8000-0000000000aa","media":{"id":"5a0c0f6e-0000-4000-8000-0000000000aa","name":"Lista de precios","file_name":"precios.pdf","mime_type":"application/pdf","size_bytes":48213,"storage_path":"media_library/971d296d/precios-abc123.pdf","url":"https://files.example.com/media_library/971d296d/precios-abc123.pdf"},"user_id":null,"state":1,"created_at":"2026-11-16T15:05:00.000000+00:00","updated_at":"2026-11-16T15:05:00.000000+00:00"}]}}}}},"post":{"tags":["Respuestas rápidas"],"summary":"Crear una respuesta rápida","description":"Crea una respuesta rápida en la empresa de la API key. `shortcut` (obligatorio, sin espacios, hasta 25 caracteres; la «/» inicial no se guarda) es único entre las activas sin distinguir mayúsculas; `message` es obligatorio (hasta 4096 caracteres) y se guarda tal cual, con comillas, `${variables}` y emojis; `media_id` es opcional: un archivo activo de Multimedia de la misma empresa. Cualquier `company_id` del cuerpo se ignora. Devuelve la fila creada.","operationId":"create_6","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"shortcut":"saludo","message":"Hola ${nombre}, ¿en qué te ayudo? 👋","media_id":null}}},"required":true},"responses":{"201":{"description":"Respuesta rápida creada","content":{"application/json":{"example":{"id":"b1c2d3e4-0000-4000-8000-000000000001","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","shortcut":"saludo","message":"Hola ${nombre}, ¿en qué te ayudo? 👋","media_id":null,"media":null,"user_id":null,"state":1,"created_at":"2026-11-16T15:00:00.000000+00:00","updated_at":"2026-11-16T15:00:00.000000+00:00"}}}},"400":{"description":"Cuerpo no JSON (`INVALID_BODY`), atajo o texto vacíos (`MISSING_FIELD`), atajo con espacios o de más de 25, texto de más de 4096 o campo que no es texto (`INVALID_VALUE`), archivo inexistente o de otra empresa (`REFERENCE_NOT_FOUND`)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El atajo no puede tener espacios"}}}},"409":{"description":"Ya existe una respuesta rápida activa con ese atajo (sin distinguir mayúsculas)","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe una respuesta rápida con el atajo \"/saludo\""}}}}}}},"/projects":{"get":{"tags":["Proyectos"],"summary":"Obtener todos los proyectos","description":"Retorna los proyectos activos de la empresa autenticada, ordenados por nombre. No incluye credenciales ni hooks (vapi_token, device_id, trunk, *_hook, webhook_*). Filtro opcional por módulo.","operationId":"getAll_5","parameters":[{"name":"id_companies_modules","in":"query","description":"Filtra por companies_modules.id","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Lista de proyectos","content":{"application/json":{"example":[{"id":"proj-001","name":"Bot de ventas","code":"BOT-VENTAS","project_type":"outbound","is_active":1,"is_active_sms":0,"phone":"+59171234567","max_concurrent_calls":2,"company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","state":1,"register_date":"2026-05-25T10:00:00.000000","updated_at":"2026-05-25T10:00:00.000000"}]}}}}},"post":{"tags":["Proyectos"],"summary":"Crear proyecto","description":"Crea solo la fila del proyecto para la empresa autenticada; no crea estados y NO aprovisiona flujos de n8n (el backend v2 lo hace; queda pendiente decidir cómo delegarlo). Solo se aplican las claves del ejemplo y las editables: name, phone, hooks, allowed_times, code, project_type, assistant_id, agent_type, id_companies_modules, max_concurrent_calls, is_active, is_active_sms, priority_method_call y ai_employee_id. code, project_type, assistant_id, agent_type, max_concurrent_calls, is_active e is_active_sms se conservan como extensiones para integraciones. priority_method_call acepta Assistant o Squad; ai_employee_id debe existir en la empresa, no estar borrado (is_delete) ni asignado a otro proyecto activo. statuses, openai_credential_id y skip_provisioning se ignoran. prj_slug no se admite porque la tabla exige también prj_number y esta API no asigna ese par. La respuesta no incluye credenciales ni hooks.","operationId":"create_7","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Bot de ventas","id_companies_modules":267,"ai_employee_id":"ab12cd34-ef56-4789-8123-456789abcdef","priority_method_call":"Assistant"}}},"required":true},"responses":{"201":{"description":"Proyecto creado","content":{"application/json":{"example":{"id":"proj-001","name":"Bot de ventas","state":1}}}},"400":{"description":"JSON inválido, is_active fuera de 0/1, prioridad inválida (INVALID_VALUE), valor demasiado largo (INVALID_VALUE) o referencia ajena (REFERENCE_NOT_FOUND)","content":{"application/json":{"examples":{"Referencia ajena":{"description":"Referencia ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"id_companies_modules no existe o no es de la empresa"}},"Empleado IA inexistente o ajeno":{"description":"Empleado IA inexistente o ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"ai_employee_id no existe o no es de la empresa"}},"Prioridad inválida":{"description":"Prioridad inválida","value":{"status":"error","code":"INVALID_VALUE","message":"priority_method_call debe ser Assistant o Squad"}},"Valor demasiado largo":{"description":"Valor demasiado largo","value":{"status":"error","code":"INVALID_VALUE","message":"Un valor del cuerpo es demasiado largo para su campo"}},"is_active inválido":{"description":"is_active inválido","value":{"status":"error","code":"INVALID_VALUE","message":"is_active e is_active_sms deben ser 0 o 1"}}}}}},"409":{"description":"El Empleado IA ya está asignado a otro proyecto activo","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"Este agente ya está asignado a otro proyecto activo"}}}}}}},"/projects/{projectId}/status":{"get":{"tags":["Proyectos"],"summary":"Listar estados del proyecto","description":"Retorna los estados activos del proyecto ordenados por 'order'. No incluye webhook ni webhook2.","operationId":"listStatuses","parameters":[{"name":"projectId","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de estados","content":{"application/json":{"example":[{"id":"stat-001","project_id":"proj-001","contact_method":"call","name":"Pendiente","key":"pending","color":"#FFC107","order":1,"state":1}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}},"post":{"tags":["Proyectos"],"summary":"Crear estado de proyecto","description":"Registra un estado para un proyecto de la empresa. Solo acepta name, key, color, order, contact_method, data, webhook, webhook2 y next_status_id; el resto se ignora. `contact_method` es `call` si no se envía (o `sms`); `order` es el siguiente al máximo actual si no se envía.","operationId":"createStatus","parameters":[{"name":"projectId","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Interesado","key":"interested","color":"#28A745","order":2,"contact_method":"call"}}},"required":true},"responses":{"201":{"description":"Estado creado (sin webhook ni webhook2)","content":{"application/json":{"example":{"id":"stat-001","project_id":"proj-001","name":"Interesado","key":"interested","color":"#28A745","order":2,"contact_method":"call","state":1}}}},"400":{"description":"ID o JSON inválido, contact_method distinto de call/sms o next_status_id que no es un estado del proyecto","content":{"application/json":{"examples":{"contact_method":{"description":"contact_method","value":{"status":"error","code":"INVALID_VALUE","message":"contact_method debe ser call o sms"}},"next_status_id ajeno":{"description":"next_status_id ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"next_status_id no es un estado activo del proyecto"}}}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/project-calls":{"get":{"tags":["Llamadas de proyecto"],"summary":"Listar llamadas con filtros","description":"Retorna llamadas paginadas usando `saas_get_calls`. Todos los filtros son opcionales. Solo lista llamadas con `contact_method = call` y respuesta registrada (no las encoladas ni en curso). `page` >= 1 y `page_size` entre 1 y 200; `desde`/`hasta` con formato YYYY-MM-DD.","operationId":"getAll_6","parameters":[{"name":"proyecto","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"project_status","in":"query","description":"Estado del proyecto (1=activo, 0=inactivo)","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha desde (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha hasta (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"id","in":"query","description":"ID de la llamada","required":false,"schema":{"type":"string"}},{"name":"campaign","in":"query","description":"ID de campaña","required":false,"schema":{"type":"string"}},{"name":"contact_name","in":"query","description":"Nombre del contacto","required":false,"schema":{"type":"string"}},{"name":"phone","in":"query","description":"Teléfono","required":false,"schema":{"type":"string"}},{"name":"end_reason","in":"query","description":"Razón de fin","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Key del estado (ej: pending)","required":false,"schema":{"type":"string"}},{"name":"cost_min","in":"query","description":"Costo mínimo","required":false,"schema":{"type":"number","format":"double"}},{"name":"cost_max","in":"query","description":"Costo máximo","required":false,"schema":{"type":"number","format":"double"}},{"name":"duration_min_ms","in":"query","description":"Duración mínima en ms","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"duration_max_ms","in":"query","description":"Duración máxima en ms","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"q","in":"query","description":"Búsqueda general","required":false,"schema":{"type":"string"}},{"name":"rol_id","in":"query","description":"ID del rol","required":false,"schema":{"type":"string"}},{"name":"companies_modules_id","in":"query","description":"ID del companies_modules","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page","in":"query","description":"Página (default 1)","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"page_size","in":"query","description":"Registros por página (default 25, máximo 200)","required":false,"schema":{"type":"integer","format":"int32","default":25}},{"name":"pipeline_stage_id","in":"query","description":"ID de la etapa de pipeline","required":false,"schema":{"type":"string"}},{"name":"pipeline_id","in":"query","description":"ID del pipeline","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista paginada de llamadas","content":{"application/json":{"example":[{"project_call_id":"abc123","project_name":"Bot de ventas","contact_name":"Juan Pérez","contact_phone":"+59171234567","ended_reason":"customer-ended-call","updated_at":"2026-05-25T10:00:00","duration":"02:30","costo":0.38,"questions_answered":4,"tipo_nps":"promotor","status":"pending","opportunity_name":"","pipeline_stage_name":"","pipeline_stage_position":0,"pipeline_name":"","pipeline_stage_status_name":""}]}}},"400":{"description":"page, page_size o fechas inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"page debe ser >= 1 y page_size entre 1 y 200"}}}}}},"post":{"tags":["Llamadas de proyecto"],"summary":"Crear llamada / contacto","description":"Agenda una nueva llamada o contacto SMS en un proyecto de la empresa. `project_id`, `contact_name` y `status` son obligatorios; `status` debe ser un estado activo del mismo proyecto. `contact_method` es `call` si no se envía (o `sms`). `opportunities_id`, si viene, debe ser una oportunidad de la empresa. Solo se aplican las claves del ejemplo. Esta operación no notifica a la cola de llamadas.","operationId":"create_8","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"proj-001","contact_name":"Juan Pérez","contact_phone":"+59171234567","status":"stat-001","contact_method":"call","json_data":{}}}},"required":true},"responses":{"201":{"description":"Llamada creada","content":{"application/json":{"example":{"id":"abc123","project_id":"proj-001","contact_name":"Juan Pérez","contact_phone":"+59171234567","status":"stat-001","contact_method":"call","state":1}}}},"400":{"description":"JSON inválido, faltan project_id, contact_name o status, valor demasiado largo u opportunities_id ajeno","content":{"application/json":{"examples":{"Campos obligatorios":{"description":"Campos obligatorios","value":{"status":"error","code":"MISSING_FIELD","message":"Faltan campos obligatorios: project_id, contact_name, status"}},"Oportunidad ajena":{"description":"Oportunidad ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"opportunities_id no existe o no es de la empresa"}},"Valor demasiado largo":{"description":"Valor demasiado largo","value":{"status":"error","code":"INVALID_VALUE","message":"Un valor del cuerpo es demasiado largo para su campo"}}}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/pipeline":{"get":{"tags":["Pipelines"],"summary":"Obtener todos los pipelines","description":"Retorna la lista completa de pipelines de la empresa autenticada, incluyendo sus etapas","operationId":"getAll_7","responses":{"200":{"description":"Lista de pipelines","content":{"application/json":{"example":[{"id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","name":"Segundo Pipeline","state":1,"companies_modules_id":267,"created_at":"2026-05-15T17:24:05.194772+00:00","updated_at":"2026-05-15T17:24:05.194772+00:00","project_id":null,"type":"IA","ocultar":null,"stages":[{"id":"b11f6e38-9e9d-4194-b660-a69ce4cc8350","name":"Pendiente","position":1,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.201434+00:00","updated_at":"2026-05-15T17:24:05.201434+00:00","pipeline_stage_status_id":"af27b809-58c9-4b43-876a-321cf6fdfe69","status_name":"En Progreso"},{"id":"fdaf5508-5062-42e7-84f3-4c8dd5e29aab","name":"Ganado","position":2,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.209844+00:00","updated_at":"2026-05-15T17:24:05.209844+00:00","pipeline_stage_status_id":"7ef1073e-fa88-4452-8956-28d04d16a963","status_name":"Ganado"},{"id":"f174cac4-b567-46bd-906c-7900efc289b0","name":"Perdido","position":3,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.215897+00:00","updated_at":"2026-05-15T17:24:05.215897+00:00","pipeline_stage_status_id":"438ab019-2ca7-4e10-869a-dced01fdf05a","status_name":"Perdido"}]}]}}}}},"post":{"tags":["Pipelines"],"summary":"Crear pipeline","description":"Registra un nuevo pipeline. Solo acepta name, companies_modules_id, type y project_id; el resto se ignora. El ID y el state se generan automáticamente. companies_modules_id debe ser un módulo de la empresa autenticada. project_id, si viene, debe ser un proyecto de la empresa (400 REFERENCE_NOT_FOUND si no). No crea etapas: usar POST /pipeline/{pipelineId}/stage.","operationId":"create_9","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Pipeline ventas","companies_modules_id":267,"type":"IA"}}},"required":true},"responses":{"201":{"description":"Pipeline creado exitosamente","content":{"application/json":{"example":{"id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","name":"Segundo Pipeline","state":1,"companies_modules_id":267,"created_at":"2026-05-15T17:24:05.194772+00:00","updated_at":"2026-05-15T17:24:05.194772+00:00","project_id":null,"type":"IA","ocultar":null}}}},"404":{"description":"El companies_modules_id no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Módulo de la empresa no encontrado"}}}},"400":{"description":"companies_modules_id ausente o inválido, project_id ajeno o valor demasiado largo","content":{"application/json":{"examples":{"Módulo ausente":{"description":"Módulo ausente","value":{"status":"error","code":"MISSING_FIELD","message":"companies_modules_id es obligatorio"}},"Proyecto ajeno":{"description":"Proyecto ajeno","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"project_id no existe o no es de la empresa"}},"Valor demasiado largo":{"description":"Valor demasiado largo","value":{"status":"error","code":"INVALID_VALUE","message":"Un valor del cuerpo es demasiado largo para su campo"}}}}}}}}},"/pipeline/{pipelineId}/stage":{"post":{"tags":["Pipelines"],"summary":"Agregar etapa a pipeline","description":"Crea una etapa para un pipeline. Solo acepta name, position, pipeline_stage_status_id (como v3) y status_name (alias de esta API); el resto se ignora. El trigger trigger_set_status puede sobrescribir pipeline_stage_status_id según name.","operationId":"createStage","parameters":[{"name":"pipelineId","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"},"example":"2db9050a-67ac-40b1-a50c-3bfa05badbab"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"En Progreso","position":1}}},"required":true},"responses":{"201":{"description":"Etapa creada","content":{"application/json":{"example":{"id":"b11f6e38-9e9d-4194-b660-a69ce4cc8350","name":"Pendiente","position":1,"state":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab","created_at":"2026-05-15T17:24:05.201434+00:00","updated_at":"2026-05-15T17:24:05.201434+00:00","pipeline_stage_status_id":"af27b809-58c9-4b43-876a-321cf6fdfe69"}}}},"400":{"description":"Estado de etapa inexistente (status_name)","content":{"application/json":{"example":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Estado de etapa no encontrado"}}}},"404":{"description":"Pipeline inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Pipeline no encontrado"}}}}}}},"/phones":{"get":{"tags":["Empleados IA"],"summary":"Listar teléfonos","description":"Combina registros activos de la empresa con el listado en vivo de Vapi. Una cuenta de Vapi caída se marca listed=false.","operationId":"list_2","responses":{"200":{"description":"Teléfonos agrupados por credencial","content":{"application/json":{"example":[{"credential_id":"00000000-0000-0000-0000-000000000001","credential_name":"Vapi","listed":true,"numbers":[]}]}}},"503":{"description":"Base no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}},"post":{"tags":["Empleados IA"],"summary":"Crear un teléfono SIP en Vapi","description":"Equivale a `createCredential` + `createPhone` de v3 en una sola llamada: crea en Vapi una credencial SIP (`byo-sip-trunk`) y un número (`byo-phone-number`) asociado a ella. El token de Vapi sale de la credencial de la empresa (`vapi_credential_id`, tipo `vapi`) o, si se envía `ai_employee_id`, del token guardado de ese empleado de la empresa; nunca del cuerpo. `password` se acepta pero no se devuelve ni se registra. Tras crear en Vapi, registra el número en la base (`saas_register_vapi_number`, como v3) y devuelve también `registry_id`; el `phone_id` se guarda en `project.phone` desde el proyecto. Si falla la creación del número o el registro en la base, la API borra en Vapi lo recién creado (compensación). Si la empresa no tiene canal `sip` responde 409.","operationId":"create_10","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"vapi_credential_id":"9a3c1d52-6f0e-4b7a-8d21-5c4e7f90ab12","name":"Troncal Bolivia","ip":"203.0.113.10","port":5060,"user":"troncal01","password":"secreto-del-troncal","number":"+59170000000","numberE164CheckEnabled":false}}},"required":true},"responses":{"201":{"description":"Teléfono creado","content":{"application/json":{"example":{"phone_id":"4f1b7c0a-23de-4a58-9c6e-81d5a0b7e3f2","credential_id":"c7e29a14-5b3d-4e08-a6f1-92d4b8e0c315","number":"+59170000000","name":"Troncal Bolivia","registry_id":"1d7e7699-8f47-441e-b94a-919aaf1cf18b"}}}},"409":{"description":"El identificador ya está en uso o la empresa no tiene canal `sip`","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"El identificador del teléfono ya está en uso"}}}},"400":{"description":"Cuerpo inválido, sin credencial de Vapi o credencial de otra empresa","content":{"application/json":{"examples":{"Falta un campo":{"description":"Falta un campo","value":{"status":"error","code":"MISSING_FIELD","message":"El campo ip es obligatorio"}},"Credencial de otra empresa":{"description":"Credencial de otra empresa","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"La credencial de Vapi no existe en la empresa"}}}}}},"502":{"description":"Vapi rechazó la solicitud (mensaje fijo, sin el cuerpo de Vapi)","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"Vapi rechazó la solicitud"}}}},"503":{"description":"Vapi no responde","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_UNAVAILABLE","message":"Vapi no responde"}}}}}}},"/opportunities":{"get":{"tags":["Oportunidades"],"summary":"Listar oportunidades","description":"Lista oportunidades activas de la empresa autenticada. Admite filtros combinables `phone` (solo dígitos; número local o con código de país), `pipeline_id`, `stage_id`, `campaign_id` y `open`. `open=true` incluye etapas con estado `En Progreso`; `open=false`, etapas Ganado/Perdido u otros estados activos. Sin filtros ni paginación conserva el arreglo actual. Al enviar `page` o `limit`, devuelve `{data,page,limit,total,has_more}`; page empieza en 1 y limit se limita a 200.","operationId":"getAll_8","parameters":[{"name":"phone","in":"query","description":"Teléfono en dígitos: número local o código de país + número","required":false,"schema":{"type":"string"},"example":59171234567},{"name":"pipeline_id","in":"query","description":"UUID del pipeline de la empresa","required":false,"schema":{"type":"string"}},{"name":"stage_id","in":"query","description":"UUID de la etapa de la empresa","required":false,"schema":{"type":"string"}},{"name":"campaign_id","in":"query","description":"UUID de campaña","required":false,"schema":{"type":"string"}},{"name":"open","in":"query","description":"true: estado En Progreso; false: otros estados activos","required":false,"schema":{"type":"boolean"}},{"name":"page","in":"query","description":"Página base 1; activa paginación","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"limit","in":"query","description":"Tamaño de página (máximo 200); activa paginación","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Lista de oportunidades","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Franco Torres","state":1,"value":0.0,"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","source_id":null,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-03-04T02:35:16.890128+00:00","data":null,"owner":null,"update_user_id":"1ca4690e-6aab-499b-932c-f653fc647fb8","opportunitie_status_id":null,"campaign_id":null,"stage":{"id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","name":"Pendiente","position":1,"pipeline_id":"2db9050a-67ac-40b1-a50c-3bfa05badbab"},"contact":{"id":"71f6c859-5739-4345-9e1b-393c7ed78896","name":"Franco Torres","email":"franco@example.com","phone":null},"source":null,"status":null,"notes":[{"id":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","title":"Primera llamada","description":"El cliente mostró interés en el producto","state":1,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-03-04T02:35:16.890128+00:00"}],"files":[{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","url":"https://storage.example.com/files/documento.pdf","uploaded_at":"2026-03-04T02:35:16.890128+00:00","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-03-04T02:35:16.890128+00:00"}]}]}}},"400":{"description":"`INVALID_ID` para pipeline, etapa o campaña inválidos; `INVALID_VALUE` si el teléfono contiene caracteres distintos de dígitos","content":{"application/json":{"examples":{"id inválido":{"description":"id inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"teléfono inválido":{"description":"teléfono inválido","value":{"status":"error","code":"INVALID_VALUE","message":"phone debe contener solo dígitos"}}}}}}}},"post":{"tags":["Oportunidades"],"summary":"Crear oportunidad","description":"Registra una nueva oportunidad, igual que el SaaS v3. Solo se aceptan `name`, `pipeline_stage_id`, `contact_id`, `value`, `source_id`, `owner`, `project_id` y `data`; cualquier otra clave se ignora. `name`, `pipeline_stage_id` y `contact_id` son obligatorios. La etapa, el contacto y el proyecto deben ser de la empresa autenticada, si no responde 400. El id, el state y las fechas los genera la base.","operationId":"create_11","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Franco Torres","pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","value":0.0,"data":{"canal":"whatsapp"}}}},"required":true},"responses":{"201":{"description":"Oportunidad creada exitosamente","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Franco Torres","state":1,"value":0.0,"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"71f6c859-5739-4345-9e1b-393c7ed78896","source_id":null,"created_at":"2026-03-04T02:35:16.890128+00:00","updated_at":"2026-03-04T02:35:16.890128+00:00","data":null,"owner":null,"update_user_id":null,"opportunitie_status_id":null,"campaign_id":null,"project_id":null}}}},"400":{"description":"Falta un campo obligatorio, un ID es inválido o la etapa, el contacto o el proyecto no son de la empresa","content":{"application/json":{"example":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"pipeline_stage_id no pertenece a la empresa"}}}}}}},"/opportunities/{opportunityId}/tag":{"get":{"tags":["Oportunidades"],"summary":"Listar tags de una oportunidad","description":"Retorna los tags activos asociados a una oportunidad de la empresa autenticada. Si la oportunidad no existe o es de otra empresa, responde 404.","operationId":"listTags_1","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Lista de tags","content":{"application/json":{"example":[{"opportunity_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"VIP","color":"#FF5733","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}},"post":{"tags":["Oportunidades"],"summary":"Agregar tag a oportunidad","description":"Asocia un tag de la empresa a una oportunidad de la empresa autenticada. Si la asociación ya existe, la devuelve sin duplicarla; si había sido quitada (state = 0), la reactiva. Oportunidad inexistente o de otra empresa: 404; tag inexistente o de otra empresa: 400.","operationId":"addTag_1","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012"}}},"required":true},"responses":{"201":{"description":"Tag asociado","content":{"application/json":{"example":{"opportunity_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","created_at":"2026-05-25T10:00:00.000000+00:00","state":1,"updated_at":"2026-05-25T10:00:00.000000+00:00"}}}},"400":{"description":"ID inválido o tag que no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/{opportunityId}/note":{"get":{"tags":["Oportunidades"],"summary":"Listar notas de una oportunidad","description":"Devuelve las notas activas en orden de creación descendente usando saas_get_notes_by_opportunity, igual que el SaaS v3.","operationId":"getOpportunityNotes","parameters":[{"name":"opportunityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Notas activas ([] si no hay filas)","content":{"application/json":{"example":[{"id":"f1a2b3c4-d5e6-7890-abcd-ef1234567890","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","title":"Seguimiento","description":"Llamar mañana","state":1}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o ajena)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"Base de datos no disponible"}}}}}},"post":{"tags":["Oportunidades"],"summary":"Agregar nota a oportunidad","description":"Crea una nota dentro de una oportunidad de la empresa autenticada. Solo se aceptan `title` y `description`; `description` es obligatoria y no puede ser vacía ni solo espacios (400 `MISSING_FIELD`), como en v3. Si la oportunidad no existe o es de otra empresa, responde 404.","operationId":"createNote","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"title":"Primera llamada","description":"El cliente mostró interés en el producto"}}},"required":true},"responses":{"201":{"description":"Nota creada","content":{"application/json":{"example":{"id":"d1e2f3a4-b5c6-7890-abcd-ef1234567890","title":"Primera llamada","description":"El cliente mostró interés en el producto","state":1,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","created_at":"2026-05-21T10:00:00.000000+00:00","updated_at":"2026-05-21T10:00:00.000000+00:00"}}}},"400":{"description":"ID inválido (`INVALID_ID`) o `description` vacía (`MISSING_FIELD`)","content":{"application/json":{"examples":{"INVALID_ID":{"description":"INVALID_ID","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"MISSING_FIELD":{"description":"MISSING_FIELD","value":{"status":"error","code":"MISSING_FIELD","message":"description es obligatorio"}}}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/{opportunityId}/messages":{"get":{"tags":["Mensajes"],"summary":"Listar el historial de mensajes de una oportunidad","description":"Mensajes activos de la oportunidad, paginados: `page` desde 1 (por defecto 1), `limit` de 1 a 200 (por defecto 50) y `order` `asc` o `desc` (por defecto `desc`) sobre `created_at, id`. Responde el sobre `{data, page, limit, total, has_more}`. Las fechas salen en ISO-8601 UTC con `Z`. `format=chat` (por defecto) devuelve las columnas de `chat_histories`; `format=langchain` devuelve solo los mensajes de `type = 'text'` con cuerpo, como `[{\"type\":\"human\"|\"ai\",\"content\":\"...\",\"additional_kwargs\":{}}]` (`from_me = false` -> `human`, `true` -> `ai`), y `total` cuenta esos mismos mensajes. Para la memoria de un agente, pedí `order=asc`. El endpoint viejo `GET /opportunities/{id}/chat-history` no cambia.","operationId":"list_3","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"page","in":"query","description":"Página (desde 1)","required":false,"schema":{"type":"string","default":"1"},"example":1},{"name":"limit","in":"query","description":"Mensajes por página (1 a 200)","required":false,"schema":{"type":"string","default":"50"},"example":50},{"name":"order","in":"query","description":"Orden por created_at, id: `asc` o `desc`","required":false,"schema":{"type":"string","default":"desc"},"example":"desc"},{"name":"format","in":"query","description":"`chat` (columnas de la tabla) o `langchain` (solo texto, {type, content, additional_kwargs})","required":false,"schema":{"type":"string","default":"chat"},"example":"chat"}],"responses":{"200":{"description":"Página de mensajes","content":{"application/json":{"examples":{"format=chat":{"description":"format=chat","value":{"data":[{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","project_call_id":null,"pipeline_stage_id":null,"phone":"59171234567","from_me":true,"date_send":"2026-10-01T14:00:00.000000Z","type":"text","type_sender":"ai","body":"Hola, te cuento de la propiedad…","caption":null,"mime_type":null,"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","media_id":null,"filename":null,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"date_delivered":"2026-10-01T14:00:03.000000Z","date_read":null,"data_error":null,"created_at":"2026-10-01T14:00:00.512345Z"}],"page":1,"limit":50,"total":120,"has_more":true}},"format=langchain":{"description":"format=langchain","value":{"data":[{"type":"ai","content":"Hola, te cuento de la propiedad…","additional_kwargs":{}}],"page":1,"limit":50,"total":120,"has_more":true}}}}}},"400":{"description":"`INVALID_ID` (id de la ruta) o `INVALID_VALUE` (`page`, `limit`, `order` o `format` fuera de rango)","content":{"application/json":{"examples":{"ID inválido":{"description":"ID inválido","value":{"status":"error","code":"INVALID_ID","message":"ID inválido"}},"limit fuera de rango":{"description":"limit fuera de rango","value":{"status":"error","code":"INVALID_VALUE","message":"limit debe ser un entero entre 1 y 200"}}}}}},"404":{"description":"Oportunidad inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}},"post":{"tags":["Mensajes"],"summary":"Insertar un mensaje en el historial de una oportunidad","description":"Reemplaza a los inserts directos a `chat_histories` de los flujos de n8n y de v3 (`saas_json_insert`, con `state = 1`). Obligatorios: `type_sender` (`ai`, `human` o `template`; `IA` en cualquier capitalización se normaliza a `ai`) y `body` o `media_id`. Opcionales: `from_me` (booleano, por defecto `false`), `type` (por defecto `text`), `phone`, `caption`, `mime_type`, `message_id` (`^[A-Za-z0-9._=-]{1,255}$`), `media_id`, `filename`, `date_send` (ISO-8601 con zona o sin ella, que se toma como UTC; por defecto, la hora actual), `pipeline_stage_id` y `project_call_id` (deben ser de la empresa). `body` admite hasta 20 000 caracteres. Se ignoran `id`, `state`, `created_at`, `date_delivered`, `date_read`, `data_error` y `opportunity_id` (sale de la ruta). **Idempotente por `message_id`:** si la oportunidad ya tiene una fila activa con ese `message_id` (reintento del webhook de WhatsApp) responde 200 con la fila existente y `duplicate: true`, sin insertar; si inserta, responde 201 con `duplicate: false`. Las fechas salen en ISO-8601 UTC con `Z`.","operationId":"create_12","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"description":"Acepta type_sender (ai, human o template) y body o media_id. Los campos opcionales del SaaS incluyen from_me, type, phone, caption, mime_type, message_id, filename y date_send.","content":{"application/json":{"schema":{"type":"string"},"example":{"type_sender":"ai","body":"Hola, ¿en qué puedo ayudarte?","from_me":true,"type":"text","message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","date_send":"2026-10-06T14:00:00Z"}}},"required":true},"responses":{"201":{"description":"Mensaje insertado","content":{"application/json":{"example":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","project_call_id":null,"pipeline_stage_id":null,"phone":"59171234567","from_me":true,"date_send":"2026-10-01T14:00:00.000000Z","type":"text","type_sender":"ai","body":"Hola, te cuento de la propiedad…","caption":null,"mime_type":null,"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","media_id":null,"filename":null,"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"date_delivered":null,"date_read":null,"data_error":null,"created_at":"2026-10-01T14:00:00.512345Z","duplicate":false}}}},"200":{"description":"Ya existía un mensaje activo de la oportunidad con ese `message_id`: se devuelve la fila existente (`duplicate: true`) y no se inserta nada","content":{"application/json":{"example":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","type_sender":"ai","from_me":true,"type":"text","body":"Hola, te cuento de la propiedad…","message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"created_at":"2026-10-01T14:00:00.512345Z","duplicate":true}}}},"400":{"description":"Falta type_sender, o body y media_id","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"type_sender es obligatorio"}}}},"404":{"description":"Oportunidad inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/{opportunityId}/file":{"get":{"tags":["Oportunidades"],"summary":"Listar archivos de una oportunidad","description":"Devuelve los archivos activos en orden de creación descendente usando saas_get_files_by_opportunity, igual que el SaaS v3.","operationId":"getOpportunityFiles","parameters":[{"name":"opportunityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Archivos activos ([] si no hay filas)","content":{"application/json":{"example":[{"id":"f1a2b3c4-d5e6-7890-abcd-ef1234567890","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","url":"https://example.com/doc.pdf","state":1}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o ajena)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"Base de datos no disponible"}}}}}},"post":{"tags":["Oportunidades"],"summary":"Agregar archivo a oportunidad","description":"Registra la URL de un archivo ya subido y la asocia a una oportunidad de la empresa autenticada. `url` es obligatoria; cualquier otra clave se ignora. Este endpoint no sube el binario. Si la oportunidad no existe o es de otra empresa, responde 404.","operationId":"createFile","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"url":"https://storage.example.com/files/documento.pdf"}}},"required":true},"responses":{"201":{"description":"Archivo creado","content":{"application/json":{"example":{"id":"e1f2a3b4-c5d6-7890-abcd-ef1234567890","url":"https://storage.example.com/files/documento.pdf","uploaded_at":"2026-05-21T10:00:00.000000+00:00","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"created_at":"2026-05-21T10:00:00.000000+00:00","updated_at":"2026-05-21T10:00:00.000000+00:00"}}}},"400":{"description":"ID inválido o falta `url`","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/multimedia":{"get":{"tags":["Multimedia"],"summary":"Listar archivos multimedia","description":"Lista archivos de la empresa con filtros, paginación y facetas. `all_folders=false` limita el resultado a `folder_id`; un folder_id nulo representa la raíz. Las fechas usan AAAA-MM-DD.","operationId":"list_4","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string","default":"1"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","default":"24"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"desde","in":"query","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","required":false,"schema":{"type":"string"}},{"name":"folder_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"all_folders","in":"query","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Archivos y facetas","content":{"application/json":{"example":{"data":[],"total":0,"page":1,"limit":24,"pages":1,"facets":{"image":0,"video":0,"audio":0,"document":0,"other":0}}}}}}},"post":{"tags":["Multimedia"],"summary":"Subir archivo multimedia","description":"Sube un archivo al FTP y lo registra en la biblioteca. El id, la empresa, la ruta y la URL los genera la API.","operationId":"upload","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"description","in":"query","required":false,"schema":{"type":"string"}},{"name":"folder_id","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Archivo registrado","content":{"application/json":{"example":{"estado":"ok","data":{"id":"UUID","name":"Manual","storage_path":"media_library/EMPRESA/manual-abcdef.pdf","category":"document","state":1}}}}},"404":{"description":"Carpeta inexistente o ajena","content":{"application/json":{"schema":{"type":"string"}}}},"413":{"description":"El archivo supera el máximo permitido","content":{"application/json":{"schema":{"type":"string"}}}},"415":{"description":"Extensión o MIME no permitido","content":{"application/json":{"schema":{"type":"string"}}}},"503":{"description":"El FTP no está configurado o disponible","content":{"application/json":{"schema":{"type":"string"}}}},"502":{"description":"Falló la escritura o verificación FTP","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/multimedia/folders":{"get":{"tags":["Multimedia"],"summary":"Listar carpetas multimedia","description":"Devuelve las carpetas activas de la empresa, en una lista plana con sus conteos directos.","operationId":"folders","responses":{"200":{"description":"Carpetas","content":{"application/json":{"example":[]}}}}},"post":{"tags":["Multimedia"],"summary":"Crear carpeta multimedia","description":"Crea una carpeta virtual. `parent_id` puede omitirse para crearla en la raíz.","operationId":"createFolder","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Campañas","parent_id":null}}},"required":true},"responses":{"201":{"description":"Carpeta creada","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/moneda/base":{"post":{"tags":["Monedas"],"summary":"Configurar moneda base","description":"Establece la moneda base de la empresa con el mismo SP que usa el SaaS v3 (saas_upsert_company_moneda_base): desmarca la base anterior y marca la indicada, sin borrar ninguna fila. Si la moneda ya estaba habilitada como adicional, pasa a ser la base (tipo_cambio se conserva). Si es nueva, se crea con tipo_cambio 1. Responde 200 porque puede actualizar una fila existente.","operationId":"setMonedaBase","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"moneda_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}},"required":true},"responses":{"200":{"description":"Moneda base configurada","content":{"application/json":{"example":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","tipo_cambio":1,"is_base":true,"created_at":"2026-09-29T12:00:00.000000-04:00","updated_at":"2026-09-29T12:00:00.000000-04:00"}}}},"400":{"description":"moneda_id ausente o no es un UUID","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"moneda_id inválido"}}}},"404":{"description":"La moneda no existe en el catálogo o no está activa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Moneda no encontrada"}}}}}}},"/moneda/adicional":{"post":{"tags":["Monedas"],"summary":"Agregar moneda adicional","description":"Agrega una moneda alternativa con su tipo de cambio respecto a la moneda base. moneda_id (UUID de una moneda activa del catálogo) y tipo_cambio (> 0) son obligatorios. Cualquier otro campo del cuerpo se ignora.","operationId":"addMonedaAdicional","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"moneda_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tipo_cambio":1.08}}},"required":true},"responses":{"201":{"description":"Moneda adicional agregada","content":{"application/json":{"example":{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tipo_cambio":1.08,"is_base":false,"created_at":"2026-09-29T12:00:00.000000-04:00","updated_at":"2026-09-29T12:00:00.000000-04:00"}}}},"400":{"description":"moneda_id no es un UUID o tipo_cambio no es un número mayor que 0","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"tipo_cambio debe ser un número mayor que 0"}}}},"404":{"description":"La moneda no existe en el catálogo o no está activa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Moneda no encontrada"}}}},"409":{"description":"La moneda ya está habilitada para la empresa","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"La moneda ya está habilitada para la empresa"}}}}}}},"/leads":{"post":{"tags":["Leads"],"summary":"Crear lead (contacto + oportunidad)","description":"Reemplaza la cadena buscar contacto → crear contacto → crear oportunidad de los flujos. En una sola sentencia SQL (todo o nada): busca el contacto de la empresa por teléfono con la regla de v3 (`saas_find_contact_by_phone`, la misma de `GET /contacts/by-phone`: solo cuentan los dígitos y se acepta con o sin prefijo de país); si no existe lo crea con `saas_insert_contact` (y lo agrega a `contact_list_id` con `saas_update_contact_list_contacts`, como v3); y crea la oportunidad con `saas_json_insert` con los mismos campos y validaciones que `POST /opportunities`. Si el contacto ya existe se reutiliza sin modificarlo (nombre, lista y demás campos de `contact` se ignoran). Dos altas simultáneas del mismo teléfono crean un solo contacto. La etapa, la fuente, el proyecto y la lista deben ser de la empresa: si no, 400 REFERENCE_NOT_FOUND y no se crea nada, ni el contacto. Límite: la serialización de altas simultáneas es por proceso (una instancia de la API); ver docs/paridad-v3/propuestas/saas_create_lead.md.","operationId":"create_13","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"contact":{"phone":"22334455","name":"Juan","lastname":"Perez","country_code":"+591","contact_list_id":"9b1c2d3e-4f50-4a6b-8c7d-0e1f2a3b4c5d"},"opportunity":{"name":"Juan Perez","pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","value":0,"data":{"canal":"whatsapp"}}}}},"required":true},"responses":{"201":{"description":"Lead creado. `contact_created` indica si el contacto se creó (true) o se reutilizó (false)","content":{"application/json":{"example":{"contact":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","contact_list_id":"9b1c2d3e-4f50-4a6b-8c7d-0e1f2a3b4c5d","name":"Juan","lastname":"Perez","email":null,"country_code":"+591","phone":"22334455","json_data":{},"state":1,"owner":null},"opportunity":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Juan Perez","state":1,"value":0.0,"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200","contact_id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","source_id":null,"data":{"canal":"whatsapp"},"project_id":null},"contact_created":true}}}},"400":{"description":"Cuerpo inválido (INVALID_BODY), campo obligatorio ausente o phone vacío (MISSING_FIELD), valor inválido (INVALID_VALUE, INVALID_ID) o stage, fuente, proyecto o lista que no son de la empresa (REFERENCE_NOT_FOUND)","content":{"application/json":{"examples":{"Etapa ajena":{"description":"Etapa ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"pipeline_stage_id no pertenece a la empresa"}},"Lista ajena":{"description":"Lista ajena","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"contact_list_id no pertenece a la empresa"}},"Teléfono vacío":{"description":"Teléfono vacío","value":{"status":"error","code":"MISSING_FIELD","message":"contact.phone es obligatorio"}}}}}},"409":{"description":"Otra alta del mismo teléfono tardó más de 30 s (CONFLICT): reintentar","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"Hay otra alta del mismo teléfono en curso, reintentá"}}}}}}},"/items":{"get":{"tags":["Ítems"],"summary":"Listar ítems","description":"Retorna los ítems activos de la empresa, paginados (por defecto del más reciente al más antiguo; order_by permite ordenar por created_at, updated_at, nombre, precio o sku; siempre descendente, como v3), con la misma forma que el listado de la app (SP saas_get_items_v2): el tipo viene plano en 'tipo_item_nombre' ('producto' o 'servicio') y 'tipo_item_descripcion', y se incluyen el medio primario ('primary_media_url', 'primary_media_type') y 'media_count'; usar GET /items/{id}/media para la galería completa. La respuesta es un objeto con 'data', 'page', 'limit', 'total' (cantidad de resultados con esos mismos filtros) y 'has_more'. Si has_more es true hay más resultados: pedí la página siguiente o usá q para buscar.","operationId":"getAll_9","parameters":[{"name":"page","in":"query","description":"Página (desde 1)","required":false,"schema":{"type":"string","default":"1"},"example":1},{"name":"limit","in":"query","description":"Ítems por página (1 a 200)","required":false,"schema":{"type":"string","default":"50"},"example":50},{"name":"q","in":"query","description":"Texto a buscar (sin distinguir mayúsculas) en nombre, sku y descripción","required":false,"schema":{"type":"string"}},{"name":"tipo_item_id","in":"query","description":"UUID del tipo de ítem (ver GET /items/tipos)","required":false,"schema":{"type":"string"}},{"name":"tipo_categoria","in":"query","description":"Categoría del tipo: 'producto' o 'servicio'","required":false,"schema":{"type":"string"}},{"name":"stock_estado","in":"query","description":"Estado de stock: 'con_stock' (>0), 'sin_stock' (=0), 'bajo' (1 a 5) o 'saludable' (>5)","required":false,"schema":{"type":"string"}},{"name":"solo_incompletos","in":"query","description":"true: solo ítems con precio 0, sin sku o sin tipo","required":false,"schema":{"type":"string"}},{"name":"company_moneda_id","in":"query","description":"UUID de la moneda de la empresa (company_moneda_id)","required":false,"schema":{"type":"string"}},{"name":"order_by","in":"query","description":"Campo de orden (siempre descendente): 'created_at' (por defecto), 'updated_at', 'nombre', 'precio' o 'sku'","required":false,"schema":{"type":"string","default":"created_at"},"example":"created_at"}],"responses":{"400":{"description":"page, limit o algún filtro inválido","content":{"application/json":{"schema":{"type":"string"}}}},"200":{"description":"Página de ítems","content":{"application/json":{"example":{"data":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","updated_at":"2026-05-25T10:00:00.000000+00:00","precio":150.0,"descripcion":"Sesión de consultoría de 1 hora","sku":"CONS-001","nombre":"Consultoría inicial","data":null,"company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","company_moneda_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","tipo_item_id":"d4e5f6a7-b8c9-0123-defa-234567890123","tiempo_entrega":"24h","stock":12,"tipo_item_nombre":"servicio","tipo_item_descripcion":"Servicios profesionales","primary_media_url":"https://ftp.uplabsai.com/items/a1b2c3d4/frontal.png","primary_media_type":"image","media_count":3}],"page":1,"limit":50,"total":123,"has_more":true}}}}}},"post":{"tags":["Ítems"],"summary":"Crear ítem","description":"Registra un nuevo ítem para la empresa autenticada. Obligatorios: 'nombre', 'tipo_item_id' y 'company_moneda_id' (deben ser de la empresa); 'precio' es opcional y >= 0. Se aceptan nombre, sku, descripcion, precio, company_moneda_id, tipo_item_id, stock y data; 'tiempo_entrega' y otras columnas se ignoran. El 'sku' es único en toda la base: uno repetido responde 409 sin revelar de quién es; un 'sku' vacío se ignora. El campo 'stock' (entero) es opcional y acepta null: representa la cantidad disponible, es informativo — no se descuenta automáticamente al vender. Debe ser >= 0. El campo 'data' (opcional, objeto libre de pares string→string) son los 'campos personalizados' que el usuario final define desde la UI del CRM: no tiene claves esperadas, y la API no los valida ni los interpreta. Distinto de 'metadata', que es procedencia del sistema (importadores y sincronizaciones: 'source', 'origen', 'corrected_by'...) y no debería escribirse desde aquí.","operationId":"create_14","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"nombre":"Consultoría inicial","descripcion":"Sesión de consultoría de 1 hora","sku":"CONS-001","precio":150.0,"stock":12,"company_moneda_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","tipo_item_id":"d4e5f6a7-b8c9-0123-defa-234567890123","data":{"Sucursal":"Centro"}}}},"required":true},"responses":{"201":{"description":"Ítem creado","content":{"application/json":{"example":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nombre":"Consultoría inicial","descripcion":"Sesión de consultoría de 1 hora","sku":"CONS-001","precio":150.0,"stock":12,"tiempo_entrega":"24h","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","company_moneda_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","tipo_item_id":"d4e5f6a7-b8c9-0123-defa-234567890123","metadata":{},"data":null,"state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","updated_at":"2026-05-25T10:00:00.000000+00:00"}}}},"400":{"description":"Payload inválido: falta 'nombre', 'tipo_item_id' o 'company_moneda_id', 'precio' o 'stock' negativos, o tipo/moneda que no son de la empresa","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El campo 'stock' no puede ser negativo"}}}},"409":{"description":"El SKU ya está en uso (es único en toda la base; la respuesta no revela a quién pertenece)","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"El SKU ya está en uso"}}}}}}},"/items/{id}/media":{"get":{"tags":["Ítems"],"summary":"Obtener medios de un ítem","description":"Retorna la galería de medios activos del ítem (imágenes, videos y archivos), ordenada: el primario primero, luego por 'orden'. Array vacío si el ítem no tiene medios. El ítem debe pertenecer a la empresa autenticada.","operationId":"getMedia","parameters":[{"name":"id","in":"path","description":"UUID del ítem","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Lista de medios","content":{"application/json":{"example":[{"id":"e5f6a7b8-c9d0-1234-efab-345678901234","item_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","url":"https://ftp.uplabsai.com/items/a1b2c3d4/frontal.png","type":"image","media_key":"frontal","descripcion":"Vista frontal","is_primary":true,"orden":0,"size_bytes":154320,"created_at":"2026-07-28T09:00:00.000000+00:00","updated_at":"2026-07-28T09:00:00.000000+00:00"}]}}},"404":{"description":"Ítem inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Ítem no encontrado"}}}}}},"post":{"tags":["Ítems"],"summary":"Subir imagen a un ítem","description":"Sube una imagen y registra su URL pública en el ítem de la empresa autenticada. Se permiten hasta cinco medios activos por ítem.","operationId":"addMedia","parameters":[{"name":"id","in":"path","description":"UUID del ítem","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"is_primary","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"media_key","in":"query","required":false,"schema":{"type":"string"}},{"name":"descripcion","in":"query","required":false,"schema":{"type":"string"}},{"name":"orden","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Imagen subida y registrada","content":{"application/json":{"example":{"id":"e5f6a7b8-c9d0-1234-efab-345678901234","item_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","url":"https://files.example.test/items/a1b2c3d4-e5f6-7890-abcd-ef1234567890/media-1791392400000-frontal.png","type":"image","is_primary":false,"size_bytes":12000,"state":1}}}},"404":{"description":"Ítem inexistente o de otra empresa","content":{"application/json":{"schema":{"type":"string"}}}},"409":{"description":"El ítem ya tiene cinco medios activos","content":{"application/json":{"schema":{"type":"string"}}}},"413":{"description":"La imagen supera 5 MB","content":{"application/json":{"schema":{"type":"string"}}}},"415":{"description":"Formato de imagen no permitido","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/items/tipos":{"get":{"tags":["Ítems"],"summary":"Obtener todos los tipos de ítem","description":"Retorna la lista de tipos de ítem activos de la empresa","operationId":"getAllTipos","responses":{"200":{"description":"Lista de tipos","content":{"application/json":{"example":[{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","tipo":"servicio","descripcion":"Servicios profesionales","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","update_at":"2026-05-25T10:00:00.000000+00:00"}]}}}}},"post":{"tags":["Ítems"],"summary":"Crear tipo de ítem","description":"Registra un nuevo tipo de ítem. 'descripcion' y 'tipo' son obligatorios; 'tipo' acepta: 'servicio' o 'producto'","operationId":"createTipo","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"tipo":"servicio","descripcion":"Servicios profesionales"}}},"required":true},"responses":{"201":{"description":"Tipo creado","content":{"application/json":{"example":{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","tipo":"servicio","descripcion":"Servicios profesionales","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","state":1,"created_at":"2026-05-25T10:00:00.000000+00:00","update_at":"2026-05-25T10:00:00.000000+00:00"}}}},"400":{"description":"Falta 'descripcion' o 'tipo' no es 'producto'/'servicio'","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"El campo 'tipo' debe ser 'producto' o 'servicio'"}}}}}}},"/files/upload":{"post":{"tags":["Archivos"],"summary":"Subir archivo","description":"Sube un archivo a una ruta relativa elegida por el cliente. Acepta imágenes, documentos y video; la empresa se obtiene de la API key.","operationId":"upload_1","parameters":[{"name":"path","in":"query","description":"Ruta relativa del archivo dentro de la raíz FTP","required":true,"schema":{"type":"string"},"example":"/media_library/empresa/documento.pdf"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Archivo subido","content":{"application/json":{"example":{"status":"ok","path":"media_library/empresa/documento.pdf","url":"https://files.example.test/media_library/empresa/documento.pdf","size":12000,"content_type":"application/pdf"}}}},"400":{"description":"Ruta inválida o sin archivo","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"La ruta del archivo no es válida"}}}},"413":{"description":"El archivo supera el máximo permitido","content":{"application/json":{"schema":{"type":"string"}}}},"415":{"description":"Extensión o MIME no permitido","content":{"application/json":{"schema":{"type":"string"}}}},"503":{"description":"FTP sin configurar o no disponible","content":{"application/json":{"schema":{"type":"string"}}}},"502":{"description":"Falló la operación FTP","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/custom-fields":{"get":{"tags":["Campos personalizados"],"summary":"Listar campos personalizados","description":"Lista todos los campos activos de la empresa autenticada, ordenados como saas_get_custom_fields. Cada campo trae su `grupo`: la tabla a la que pertenece (contact, opportunities, ticket, item, venta o cuota) o `global` si es de toda la empresa y aparece en todas las tablas. No hay filtro por grupo: se filtra del lado del cliente. Renombrar un campo no migra valores ya almacenados en data/json_data.","operationId":"list_5","responses":{"200":{"description":"Campos personalizados","content":{"application/json":{"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","grupo":"contact","type":"text","name":"nombre_cliente","order":0,"state":1},{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","grupo":"global","type":"text","name":"origen_cliente","order":0,"state":1}]}}}}},"post":{"tags":["Campos personalizados"],"summary":"Crear campo personalizado","description":"Crea un campo en la empresa autenticada. Solo grupo, type, name y order se aceptan; id, company_id y state siempre los fija la API. El nombre se normaliza a minúsculas ASCII con guiones bajos, como en v3. Con `grupo: \"global\"` el campo es de toda la empresa y aparece en todas las tablas. En `ticket` y `global` el nombre no puede ser el de un dato propio del ticket (400 `INVALID_VALUE`): formalizacion, aclaracion, sentimiento, emocion, resumen, transcripcion, phone, proveedor, poliza, rubro, ejecutivo, motivo_desestimacion, observacion_resolucion, priority, attachments, tipo, datos_extraidos, deteccion, historial e issue_type. El nombre no puede repetirse: un campo global choca con cualquier campo de la empresa y uno de tabla con los de su tabla y con los globales (409 `DUPLICATE`).","operationId":"create_15","requestBody":{"description":"Campos aceptados: grupo, type, name y order. grupo: contact, opportunities, ticket, item, venta, cuota o global (toda la empresa); type: text, number, boolean o json; name se normaliza a minúsculas ASCII con guion bajo.","content":{"application/json":{"schema":{"type":"string"},"examples":{"De una tabla":{"description":"De una tabla","value":{"grupo":"contact","type":"text","name":"nombre_cliente","order":0}},"Global (toda la empresa)":{"description":"Global (toda la empresa)","value":{"grupo":"global","type":"text","name":"origen_cliente","order":0}}}}},"required":true},"responses":{"201":{"description":"Campo creado","content":{"application/json":{"example":{"id":"550e8400-e29b-41d4-a716-446655440000","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","grupo":"contact","type":"text","name":"nombre_cliente","order":0,"state":1}}}},"400":{"description":"Cuerpo inválido, grupo/type fuera de lista, nombre vacío tras normalizar o nombre reservado de un dato del ticket (grupo ticket o global)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"type inválido"}}}},"409":{"description":"Ya existe un campo con ese nombre que chocaría con el nuevo","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"Ya existe un campo con ese nombre en este grupo o como campo global"}}}}}}},"/credentials":{"get":{"tags":["Credenciales"],"summary":"Listar credenciales activas","description":"Devuelve solo metadatos públicos y referencias de la empresa autenticada.","operationId":"list_6","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credenciales","content":{"application/json":{"example":[{"id":"00000000-0000-0000-0000-000000000001","type":"openai","name":"Principal","last4":"1234","source":"manual","n8n_synced":true,"used_by":[]}]}}},"400":{"description":"Tipo inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"Tipo de credencial inválido"}}}}}},"post":{"tags":["Credenciales"],"summary":"Crear credencial","description":"Valida el proveedor y sincroniza n8n cuando corresponde.","operationId":"create_16","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"OpenAI":{"description":"OpenAI","value":{"type":"openai","name":"OpenAI principal","secret":"sk-..."}},"Twilio":{"description":"Twilio","value":{"type":"twilio","name":"Twilio ventas","secret":"<auth token>","account_sid":"AC00000000000000000000000000000000"}}}}},"required":true},"responses":{"201":{"description":"Creada","content":{"application/json":{"example":{"id":"00000000-0000-0000-0000-000000000001","last4":"1234"}}}},"400":{"description":"Cuerpo o credencial inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"Tipo de credencial inválido"}}}},"409":{"description":"Secreto duplicado","content":{"application/json":{"example":{"status":"error","code":"DUPLICATE","message":"La empresa ya tiene esta credencial"}}}},"503":{"description":"n8n o cifrado no configurado","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_UNAVAILABLE","message":"n8n no está configurado"}}}}}}},"/conversations/{id}/messages":{"post":{"tags":["Conversaciones"],"summary":"Enviar un mensaje por WhatsApp en una conversación","description":"Envía por WhatsApp un texto, un archivo o una plantilla en una **conversación** (un número de WhatsApp de la empresa + un contacto) y **guarda la fila en `chat_histories`**. No necesita oportunidad, proyecto ni Empleado IA. Lo llama el SaaS cuando un asesor responde desde la bandeja de conversaciones.\n1. **Conversación**: tiene que ser de la empresa de la API key y estar activa; si no, 404 `NOT_FOUND` (mismo mensaje para inexistente y ajena).\n2. **Número emisor**: el número de la conversación. El token sale de Canales. Sin token (número dado de baja o sin credencial), 422 `WHATSAPP_NOT_CONNECTED`.\n3. **Destinatario**: el teléfono de la conversación (`contact_phone`, en dígitos). Nunca se acepta un teléfono en el cuerpo.\n4. **Ventana de 24 h**: texto o archivo cuando el cliente nunca escribió o escribió hace más de 24 h dan 422 `WHATSAPP_WINDOW_CLOSED` **sin llamar a Meta** ni guardar fila. Las plantillas sí salen. Si Meta devuelve 131047 (ventana cerrada) también es 422 `WHATSAPP_WINDOW_CLOSED`.\n5. **Texto** (`sent_template: false` y sin `file_url`): `body` obligatorio, hasta 4096 caracteres.\n6. **Archivo** (`file_url`, `type` image, video, audio o document): solo URLs `https` del FTP de la plataforma (el host y la ruta de `FTP_PUBLIC_URL`); cualquier otra, 400. Se envía a Meta por enlace, con `body` como pie (el audio no lleva pie), y se guarda una copia en `/chat_history/<media_id>`.\n7. **Plantilla** (`sent_template: true`): se reenvía `template` (`name`, `language`, `components`) tal cual. `header_media.url`, si viene, debe ser del FTP de la plataforma o un media id de Meta y solo deja la imagen en el historial.\n8. **Guardado**, después del envío: `from_me = true`, `type_sender = 'human'` (`'template'` con plantilla, con `body = template_text` o «📨 Plantilla de recontacto enviada»), `conversation_id`, `companies_channels_numbers_id`, `phone` = el de la conversación y `send_status = 'sent'`. Si la conversación tiene oportunidades activas, la fila lleva `opportunity_id` y `pipeline_stage_id` de la más reciente (por `updated_at`); si no, quedan nulos. El resumen de la conversación (último mensaje, no leídos) lo actualiza la base. Si el INSERT falla, 200 con `saved: false` y el wamid en el log.\n9. `request_id` (hasta 200 caracteres) y `sender_user_id` (uuid del asesor) son opcionales y por ahora solo van al log. La API **no deduplica**: la protección contra el doble envío va en el front.","operationId":"send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"Texto":{"description":"Texto","value":{"request_id":"5f1d3c1e-0b8e-4f6e-9a55-6f2f0b3a7c10","sender_user_id":"0b6a6c3e-9d6f-4d57-8a3e-1f5b2f3c9a10","type":"text","body":"Hola Juan, te escribo yo.","file_url":null,"mime_type":null,"filename":null,"sent_template":false,"template":null,"template_text":null,"header_media":null}},"Archivo":{"description":"Archivo","value":{"type":"document","body":"Aquí está la propuesta","file_url":"https://files.uplabsai.com/assets/propuesta.pdf","mime_type":"application/pdf","filename":"propuesta.pdf","sent_template":false}},"Plantilla":{"description":"Plantilla","value":{"request_id":"a1","type":"text","body":"","sent_template":true,"template":{"name":"recontacto","language":{"code":"es"},"components":[{"type":"body","parameters":[{"type":"text","text":"Juan"}]}]},"template_text":"Hola Juan, ¿sigues interesado?"}}}}},"required":true},"responses":{"200":{"description":"Enviado. `saved` dice si quedó en `chat_histories` (si no, `chat_history_id` es null)","content":{"application/json":{"examples":{"Enviado":{"description":"Enviado","value":{"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgARGBI5","chat_history_id":"3f0f4f0e-2d57-4c5e-9d1f-6b0a8c2d7e11","conversation_id":"c8d3a0f2-77b1-4a35-9c0e-5a1f2b6d9e44","phone":"59171234567","send_status":"sent","saved":true}}}}}},"400":{"description":"`INVALID_ID`, `INVALID_BODY`, `MISSING_FIELD` o `INVALID_VALUE` (`request_id`, `sender_user_id`, `body`, `type`, `file_url` que no es del FTP de la plataforma o no existe, `template`, `header_media`)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"file_url no es un archivo de la plataforma"}}}},"404":{"description":"Conversación inexistente, inactiva o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Conversación no encontrada"}}}},"422":{"description":"`WHATSAPP_NOT_CONNECTED`, `WHATSAPP_WINDOW_CLOSED` o `WHATSAPP_REJECTED`. No se guardó fila","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_WINDOW_CLOSED","message":"Pasaron más de 24 horas desde el último mensaje del cliente"}}}},"502":{"description":"`STORAGE_ERROR`: no se pudo leer o guardar el archivo en el FTP","content":{"application/json":{"example":{"status":"error","code":"STORAGE_ERROR","message":"No se pudo leer el archivo"}}}},"503":{"description":"`WHATSAPP_UNAVAILABLE` (Meta caído, timeout o 429), `STORAGE_UNAVAILABLE` o `DB_UNAVAILABLE`","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_UNAVAILABLE","message":"WhatsApp no está disponible"}}}}}}},"/contacts":{"get":{"tags":["Contactos"],"summary":"Obtener todos los contactos","description":"Retorna los contactos de la empresa, paginados (`page` desde 1, `limit` por defecto 500 y máximo 1000) con saas_get_contacts_v2_paginado. Cada contacto incluye `status` y `contact_lists`. Sin búsqueda se ordena por nombre; con `q` se ordena por relevancia y se agrega `similarity_score`. `list_id` filtra por lista y `status` por prospecto, ganado, inactivo o sin_estado (status nulo). La respuesta incluye `data`, `page`, `limit`, `total` filtrado y `has_more`. Si hay más resultados, solicite la página siguiente. El sistema asigna el estado según oportunidades y ventas; solo avanza y el estado inactivo se asigna únicamente de forma manual.","operationId":"getAll_10","parameters":[{"name":"page","in":"query","description":"Página (desde 1)","required":false,"schema":{"type":"string","default":"1"},"example":1},{"name":"limit","in":"query","description":"Contactos por página (1 a 1000)","required":false,"schema":{"type":"string","default":"500"},"example":500},{"name":"list_id","in":"query","description":"UUID de una lista de contactos: solo los contactos de esa lista","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Texto a buscar por similitud en nombre, apellido, email, teléfono y código de país","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Estado del contacto: prospecto, ganado, inactivo o sin_estado (status nulo)","required":false,"schema":{"type":"string"},"example":"prospecto"}],"responses":{"400":{"description":"page, limit, list_id, q o status inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"status debe ser prospecto, ganado, inactivo o sin_estado"}}}},"200":{"description":"Página de contactos","content":{"application/json":{"example":{"data":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","contact_list_id":null,"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"+591 22334455","json_data":{},"created_at":"2025-07-17T14:00:47.876668","updated_at":"2025-07-17T14:00:47.876668","state":1,"status":"prospecto","owner":null,"update_user_id":null,"documento_identidad":null,"contact_lists":[{"id":"9b1c2d3e-4f50-4a6b-8c7d-0e1f2a3b4c5d","name":"Clientes VIP"}],"similarity_score":null}],"page":1,"limit":500,"total":1234,"has_more":true}}}}}},"post":{"tags":["Contactos"],"summary":"Crear contacto","description":"Registra un contacto con `saas_insert_contact`, igual que el SaaS v3. `phone` es obligatorio. El ID lo genera la API, `company_id` sale de la API key y `state` es siempre 1. Acepta name, lastname, email, documento_identidad, country_code, phone, json_data, owner, contact_list_id y status. `status` admite prospecto, ganado, inactivo o null/cadena vacía para sin estado. La lista debe pertenecer a la empresa y se registra también en `contact_list_contacts`. El sistema asigna el estado según oportunidades y ventas; solo avanza y el estado inactivo se asigna únicamente de forma manual.","operationId":"create_17","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"22334455","documento_identidad":"12345678","status":"prospecto","json_data":{}}}},"required":true},"responses":{"201":{"description":"Contacto creado exitosamente","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","contact_list_id":null,"name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"+591","phone":"22334455","json_data":{},"created_at":"2025-07-17T14:00:47.876668","updated_at":"2025-07-17T14:00:47.876668","state":1,"status":"prospecto","owner":null,"update_user_id":null,"documento_identidad":"12345678"}}}},"400":{"description":"phone, json_data, contact_list_id o status inválidos","content":{"application/json":{"examples":{"Referencia inválida":{"description":"Referencia inválida","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"contact_list_id no pertenece a la empresa"}},"Estado inválido":{"description":"Estado inválido","value":{"status":"error","code":"INVALID_VALUE","message":"status debe ser prospecto, ganado, inactivo o null (sin estado)"}}}}}},"409":{"description":"Registro duplicado","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/calendar/availability/search":{"post":{"tags":["Calendario"],"summary":"Buscar disponibilidad","description":"Usa saas_calendar_search_availability_v2 con proyecto y assignment_key de la configuración de la empresa. Nunca usa defaults de otra empresa.","operationId":"search","requestBody":{"description":"Cuerpo opcional. project_id es obligatorio en la operación; date, time, duration_minutes y timezone acotan la búsqueda.","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"PRJ-0042","date":"2026-10-08","time":"10:00","duration_minutes":60,"timezone":"America/La_Paz"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"ok":true,"available":true,"slot":{"starts_at":"2026-10-08 10:00","ends_at":"2026-10-08 11:00"},"advisor":{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","email":"asesor@example.com"}}}}},"400":{"description":"Falta project_id o hay un valor inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/calendar/availability/rules":{"get":{"tags":["Calendario"],"summary":"Listar franjas de disponibilidad","description":"La respuesta siempre queda filtrada por la empresa de la API key.","operationId":"rules","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"400":{"description":"Entrada inválida o referencia fuera de la empresa","content":{"application/json":{"examples":{"INVALID_VALUE":{"description":"INVALID_VALUE","value":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado en la empresa"}}}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}},"post":{"tags":["Calendario"],"summary":"Crear franja de disponibilidad","description":"Valida asesor y proyecto dentro de la empresa autenticada; day_of_week es ISO 1-7 y los minutos son múltiplos de 5.","operationId":"createRule","requestBody":{"description":"Cuerpo opcional a nivel HTTP, pero requiere user_id, day_of_week (1-7), start_minute y end_minute. project_id (varchar), timezone y metadata son opcionales.","content":{"application/json":{"schema":{"type":"string"},"example":{"user_id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","project_id":"PRJ-0042","day_of_week":4,"start_minute":540,"end_minute":1020,"timezone":"America/La_Paz"}}}},"responses":{"400":{"description":"Falta un campo obligatorio o hay un valor inválido","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"Falta el campo obligatorio user_id"}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/calendar/appointments":{"get":{"tags":["Calendario"],"summary":"Listar citas y bloqueos","description":"Lista eventos del calendario de la empresa de la API key. date_from/date_to usan ISO-8601. project_id se valida contra la empresa.","operationId":"list_7","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string"}},{"name":"opportunity_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"user_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"project_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"ok":true,"status":"success","total":1,"limit":100,"offset":0,"data":[{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","project_id":"PRJ-0042","status":"scheduled","event_type":"appointment","starts_at_local":"2026-10-07 10:00"}]}}}},"400":{"description":"Entrada inválida o referencia fuera de la empresa","content":{"application/json":{"examples":{"INVALID_VALUE":{"description":"INVALID_VALUE","value":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado en la empresa"}}}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}},"post":{"tags":["Calendario"],"summary":"Reservar cita o crear bloqueo","description":"Usa saas_calendar_book_appointment_v2. Para citas exige proyecto y oportunidad; para bloqueos, asesor y rango horario. Con user_id la cita se agenda aunque el asesor ya tenga otra a esa hora; sin user_id se asigna un asesor con ese horario libre. La hora de inicio puede ser cualquier múltiplo de 5 minutos. company_id del cuerpo se ignora.","operationId":"create_18","requestBody":{"description":"Cuerpo opcional. Para una cita se requieren project_id y opportunity_id; para un bloqueo event_type=blocked, user_id, starts_at y ends_at. project_id conserva el formato varchar del proyecto.","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"PRJ-0042","opportunity_id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","starts_at":"2026-10-08T10:00","duration_minutes":60,"timezone":"America/La_Paz"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"ok":true,"available":true,"event_type":"appointment","calendar_event":{"id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","starts_at":"2026-10-08T10:00:00-04:00"}}}}},"400":{"description":"Falta opportunity_id en una cita o hay un valor inválido","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"opportunity_id es obligatorio"}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/calendar/appointments/{id}/cancel":{"post":{"tags":["Calendario"],"summary":"Cancelar cita","description":"Soft cancel del evento propio. Se ignora hard_delete para impedir borrados físicos y se comprueba la empresa antes del SP legado.","operationId":"cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Cuerpo opcional; solo `reason` (motivo de la cancelación). La API siempre fuerza hard_delete=false.","content":{"application/json":{"schema":{"type":"string"},"example":{"reason":"El cliente pidió cancelar"}}}},"responses":{"400":{"description":"ID o JSON inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/ai-employees":{"get":{"tags":["Empleados IA"],"summary":"Listar Empleados IA","description":"Empleados IA de la empresa de la key (con `prompt`, el de voz, y `text_prompt`, el de texto, cuando la base ya tiene la columna), incluidos los desactivados (`state = 0`, `is_active = false`); los borrados no salen. `project` es el proyecto activo al que está asignado, o `null`. Nunca incluye el token de Vapi. Filtros opcionales: `id_companies_modules` (módulo) y `free_only=true` para los que no están asignados a ningún proyecto activo (`include_agent_id` mantiene en la lista a ese empleado aunque esté asignado, para editar un proyecto).","operationId":"getAll_11","parameters":[{"name":"id_companies_modules","in":"query","description":"Filtra por companies_modules.id","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"free_only","in":"query","description":"Solo empleados sin proyecto activo asignado","required":false,"schema":{"type":"boolean","default":false}},{"name":"include_agent_id","in":"query","description":"Con free_only, id de un empleado que se conserva en la lista aunque esté asignado","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de Empleados IA","content":{"application/json":{"example":[{"id":"b6d4755f-f494-410d-b183-46fa2c8ed02e","company_id":"30e2bc47-d232-4552-a398-377a80ffff5e","name":"Homero","prompt":"Eres un asistente de ventas.","text_prompt":"Responde por WhatsApp con tono cordial y breve.","first_greeting":"Hola, ¿en qué te ayudo?","vapi_assistant_id":"0d8f2b6e-7c1a-4f35-9a4e-3b5d1c2e8f10","voice_config":{"voice_id":"htFfPSZGJwjBv1CL0aMD","language":"es","speed":1.1},"transcriber_config":{"provider":"deepgram","model":"nova-2","language":"es-419"},"id_companies_modules":469,"channel_type":"omni","state":1,"is_active":true,"created_at":"2026-09-01T10:00:00","updated_at":"2026-09-01T10:00:00","project":{"id":"proj-001","name":"Bot de ventas","state":1}}]}}},"400":{"description":"Parámetro inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}}}},"post":{"tags":["Empleados IA"],"summary":"Crear un Empleado IA","description":"Equivale a `registro` de v3. Acepta `prompt` (voz, se espeja a Vapi) y `text_prompt` (texto, solo en la base: **nunca se envía a Vapi**; n8n recibe `COALESCE(text_prompt, prompt)` en `/ai-employees/turn`). Como en v3, el prompt que hace falta depende del canal (`voice`: `prompt`; `text`: `text_prompt`; `omni`: ambos), pero la API no lo exige: la validación de longitud mínima es del front. Hasta aplicar `sql/empleado-ia-text-prompt/`, mandar `text_prompt` responde 503. Para `channel_type` `voice` (default) u `omni` crea primero el asistente en Vapi (OpenAI gpt-4o-mini, voz ElevenLabs `eleven_flash_v2_5`, transcriptor Deepgram `nova-2-general`, como v3) y luego guarda la fila; para `text` no llama a Vapi. **El token de Vapi nunca va en el cuerpo**: se indica `vapi_credential_id`, una credencial de tipo `vapi` de la empresa de la key (de otra empresa o inexistente: 400 `REFERENCE_NOT_FOUND`). Si la base falla después de crear el asistente, la API lo borra en Vapi (compensación) para no dejarlo huérfano; si Vapi falla no se escribe ninguna fila. Los campos que no son de la lista se ignoran; la empresa sale de la key. La respuesta nunca incluye el token.","operationId":"create_19","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"name":"Homero","prompt":"Eres un asistente de ventas.","text_prompt":"Responde por WhatsApp con tono cordial y breve.","first_greeting":"Hola, ¿en qué te ayudo?","channel_type":"omni","id_companies_modules":469,"vapi_credential_id":"9a3c1d52-6f0e-4b7a-8d21-5c4e7f90ab12","voice_config":{"voice_id":"htFfPSZGJwjBv1CL0aMD","language":"es","speed":1.1,"stability":0.8},"transcriber_config":{"language":"es-419"}}}},"required":true},"responses":{"201":{"description":"Empleado IA creado","content":{"application/json":{"example":{"id":"b6d4755f-f494-410d-b183-46fa2c8ed02e","company_id":"30e2bc47-d232-4552-a398-377a80ffff5e","name":"Homero","prompt":"Eres un asistente de ventas.","text_prompt":"Responde por WhatsApp con tono cordial y breve.","first_greeting":"Hola, ¿en qué te ayudo?","vapi_assistant_id":"0d8f2b6e-7c1a-4f35-9a4e-3b5d1c2e8f10","voice_config":{"provider":"11labs","voice_id":"htFfPSZGJwjBv1CL0aMD","language":"es","speed":1.1},"transcriber_config":{"provider":"deepgram","model":"nova-2-general","language":"es-419"},"id_companies_modules":469,"channel_type":"omni","state":1,"is_active":true,"project":null}}}},"400":{"description":"Cuerpo inválido, credencial faltante o de otra empresa","content":{"application/json":{"examples":{"Falta la credencial":{"description":"Falta la credencial","value":{"status":"error","code":"MISSING_FIELD","message":"El campo vapi_credential_id es obligatorio para empleados de voz u omni"}},"Credencial de otra empresa":{"description":"Credencial de otra empresa","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"La credencial de Vapi no existe en la empresa"}}}}}},"502":{"description":"Vapi rechazó la solicitud (mensaje fijo, sin el cuerpo de Vapi)","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"Vapi rechazó la solicitud"}}}},"503":{"description":"Vapi no responde o las credenciales de la empresa no están disponibles","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_UNAVAILABLE","message":"Vapi no responde"}}}}}}},"/ai-employees/{id}/sync":{"post":{"tags":["Empleados IA"],"summary":"Sincronizar un Empleado IA desde Vapi","description":"Equivale a `sync_from_vapi` de v3: lee el asistente en Vapi (con el token guardado del empleado), lo compara con la fila y actualiza solo lo que difiere (`name`, `first_greeting`, `prompt`, `voice_config`, `transcriber_config`). Sin cuerpo. Devuelve el empleado y la lista `changed_fields`. No crea ni borra nada en Vapi. Sin asistente o sin token guardado no puede sincronizar.","operationId":"sync","parameters":[{"name":"id","in":"path","description":"ID del Empleado IA","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Empleado sincronizado","content":{"application/json":{"example":{"data":{"id":"b6d4755f-f494-410d-b183-46fa2c8ed02e","name":"Homero","first_greeting":"Hola, ¿en qué te ayudo?","vapi_assistant_id":"0d8f2b6e-7c1a-4f35-9a4e-3b5d1c2e8f10","channel_type":"voice","state":1,"is_active":true},"changed_fields":["first_greeting"]}}}},"400":{"description":"ID inválido o el empleado no tiene token de Vapi guardado","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"El empleado no tiene credencial de Vapi guardada: edítalo con vapi_credential_id"}}}},"404":{"description":"No existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Empleado IA no encontrado"}}}},"409":{"description":"El empleado no tiene asistente en Vapi","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"El empleado no tiene un asistente en Vapi"}}}},"502":{"description":"Vapi rechazó la solicitud o ya no tiene el asistente","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"El recurso no existe en Vapi"}}}}}}},"/ai-employees/template-message":{"post":{"tags":["Empleados IA"],"summary":"Enviar una plantilla de WhatsApp del Empleado IA","description":"Valida que la oportunidad pertenezca al proyecto y a la empresa, comprueba la pausa del contacto y envía una\nplantilla aprobada al teléfono de la oportunidad con el número y token de Canales de la empresa. Se admiten\n`llamar_mas_tarde` (`url`, `numero`) e `interesado_properties` (`name`, `agent_name`, `query_properties`),\ncon el idioma indicado por el workflow. `request_id` evita que un reintento vuelva a enviar la plantilla.\nLa respuesta incluye un `body` descriptivo y el `wamid` de Meta en `messages`; este endpoint **no escribe**\nen `chat_histories`, porque el workflow lo registra después.\n","operationId":"templateMessage","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"Seguimiento":{"description":"Seguimiento","value":{"project_id":"project-1","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","request_id":"event-1:llamar_mas_tarde","template_name":"llamar_mas_tarde","language":"es_PE","parameters":{"url":"https://empresa.example","numero":"59170000000"},"type_sender":"ai"}},"Propiedades":{"description":"Propiedades","value":{"project_id":"project-1","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","request_id":"event-1:interesado_properties","template_name":"interesado_properties","language":"es_PE","parameters":{"name":"Juan","agent_name":"Ana","query_properties":"Casa de 3 dormitorios"},"type_sender":"ai"}}}}},"required":true},"responses":{"200":{"description":"Plantilla enviada o respuesta idempotente","content":{"application/json":{"example":{"body":"📨 Plantilla de WhatsApp enviada: llamar_mas_tarde","messages":[{"id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgARGBI5"}]}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD` o `INVALID_VALUE`","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"request_id es obligatorio"}}}},"404":{"description":"Proyecto u oportunidad inexistente, ajena o de otro proyecto","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"409":{"description":"`PAUSED` o solicitud con el mismo `request_id` todavía en curso","content":{"application/json":{"example":{"status":"error","code":"PAUSED","message":"El Empleado IA está pausado para este contacto"}}}},"422":{"description":"`WHATSAPP_NOT_CONNECTED`, teléfono no válido o Meta rechazó la plantilla","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_NOT_CONNECTED","message":"WhatsApp no está conectado para este proyecto"}}}},"503":{"description":"Meta no respondió o la base no está disponible","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_UNAVAILABLE","message":"WhatsApp no está disponible"}}}}}}},"/ai-employees/outcome":{"post":{"tags":["Empleados IA"],"summary":"Aplicar el resultado de la conversación de un Empleado IA","description":"Lo llama el workflow `main` del Empleado IA cuando el modelo decide `interested`, `not_interested` o `handoff` (transferir a un humano). Reemplaza a los workflows de n8n `interesados`, `no_interesados`, `transferencia_humana` y `asignacion_ciclica`. **En una sola transacción**, según la fila activa de `ai_outcome_config` del proyecto y el resultado (se carga a mano):\nLa configuración recomendada de `interested` solo registra interés: stage y rol NULL, sin aviso y con pausa NULL. `handoff` es la derivación: mueve stage, asigna, avisa y pausa.\n1. Mueve la oportunidad al stage de la config si `pipeline_stage_id` no es null. Con null conserva el stage actual.\n2. Crea la nota del `summary`: título `INTERESADO`, `Resumen de conversación` (handoff) o `NO-INTERESADO`. Con `interested` y `handoff`, una nota por cada elemento de `properties`: título `PROPIEDAD <id>` y descripción `\\nNombre: <title>\\nAgente: <agente>`.\n3. Pone los tags de la config (solo los activos de la empresa).\n4. Completa `name` y `lastname` del contacto solo si están vacíos (un nombre que son solo dígitos, como el teléfono con que `inbound-message` crea el contacto sin `profile_name`, cuenta como vacío). Nunca pisa un dato real.\n5. Si la config tiene `assign_role_id` y la oportunidad **no tiene dueño**: asigna por turno al siguiente usuario activo de la empresa con ese rol (ordenados por email, a continuación del último asignado del proyecto) y fija `opportunities.owner` con su email. Una oportunidad que ya tiene dueño conserva el suyo: no se reasigna ni avanza la rueda, pero el aviso va al dueño actual (se busca por email entre los usuarios activos de la empresa; si no se encuentra o no tiene teléfono, `EXECUTIVE_WITHOUT_PHONE`).\n6. `pause_employee = null` pausa solo en `handoff`; true o false explícitos prevalecen. Si pausa, registra al Empleado IA en `black_list` dentro de la misma transacción. Usa el teléfono del último mensaje del cliente o, si no hay mensaje, el del contacto. Si no tiene de 6 a 20 dígitos, aplica el resultado y responde `paused: false` con `pause_error: NO_VALID_PHONE`.\n\n**Aviso al ejecutivo.** Después del commit, sin retener una conexión del pool, si la llamada aplicó algo, la config asigna y la config tiene `notify_executive`, manda por WhatsApp la plantilla `alerta_transferencia_humana` (idioma `es`; parámetros del cuerpo `client_name`, `created_at` en `America/La_Paz` con formato `dd-mm-yyyy HH:mm` y `url` a la oportunidad en el SaaS) al `users.phone` del ejecutivo, desde el número de WhatsApp del proyecto y con el token de Canales de la empresa. Si falla **no se deshace nada**: responde 200 con `notified: false` y `notify_error`: `EXECUTIVE_WITHOUT_PHONE`, `WHATSAPP_NOT_CONNECTED` (token vencido, rechazado o sin número conectado), `TEMPLATE_NOT_AVAILABLE` (la plantilla no existe o no está aprobada en la WABA de la empresa: es un requisito para cada empresa nueva), `WHATSAPP_UNAVAILABLE`, `WHATSAPP_REJECTED` o `NOTIFICATION_NOT_CONFIGURED` (falta `SAAS_FRONT_URL` o el proyecto no tiene módulo).\n\n**Idempotencia.** Durante 30 minutos, repetir el mismo resultado para una oportunidad devuelve `already_applied: true` aunque cambie el resumen: no escribe, no reasigna ni reenvía el aviso. Cambiar de resultado sí se aplica. El chequeo previo de stage, nota y dueño sigue como respaldo.\n\nObligatorios: `project_id`, `opportunity_id`, `outcome`. `motivo` es opcional (hasta 1000 caracteres); en `handoff` precede al resumen como `Motivo: <motivo>\\n\\n<summary>` y en otros resultados se ignora. `summary` hasta 20 000 caracteres; los demás textos, hasta 1000; `properties` debe ser un arreglo de hasta 50 elementos; los que no son objeto, no traen `id` o traen textos inválidos se saltan sin error.","operationId":"outcome","requestBody":{"description":"Resultado tal como lo manda el workflow `main` del Empleado IA","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","outcome":"handoff","motivo":"Pide hablar con una persona","summary":"Busca casa de 3 dormitorios en Equipetrol, presupuesto USD 150 mil","name":"Juan","lastname":"Pérez","properties":[{"id":123,"title":"Casa Equipetrol","agente":"Juan / 59171234567"}]}}},"required":true},"responses":{"200":{"description":"Aplicado (o ya estaba aplicado). `assigned_user_id` solo viene si esta llamada asignó al ejecutivo; `notified` dice si salió el aviso; `paused` dice si esta llamada pausó al Empleado IA","content":{"application/json":{"examples":{"Aplicado y avisado":{"description":"Aplicado y avisado","value":{"ok":true,"outcome":"interested","already_applied":false,"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","owner":null},"assigned_user_id":null,"paused":false,"pause_error":null,"notified":false,"notify_error":null}},"Aplicado, el aviso falló":{"description":"Aplicado, el aviso falló","value":{"ok":true,"outcome":"handoff","already_applied":false,"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","owner":"ana@empresa.com"},"assigned_user_id":"3f6b2c1e-8a4d-4e2f-9c7b-1d5e6f7a8b9c","paused":true,"pause_error":null,"notified":false,"notify_error":"TEMPLATE_NOT_AVAILABLE"}},"Ya estaba aplicado":{"description":"Ya estaba aplicado","value":{"ok":true,"outcome":"interested","already_applied":true,"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","owner":null},"assigned_user_id":null,"paused":false,"pause_error":null,"notified":false,"notify_error":null}},"No interesado sin pausa":{"description":"No interesado sin pausa","value":{"ok":true,"outcome":"not_interested","already_applied":false,"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","owner":null},"assigned_user_id":null,"paused":false,"pause_error":null,"notified":false,"notify_error":null}},"Sin teléfono válido para pausar":{"description":"Sin teléfono válido para pausar","value":{"ok":true,"outcome":"handoff","already_applied":false,"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","owner":null},"assigned_user_id":null,"paused":false,"pause_error":"NO_VALID_PHONE","notified":false,"notify_error":null}}}}}},"400":{"description":"`INVALID_BODY` (no es JSON), `MISSING_FIELD` (`project_id`, `opportunity_id` u `outcome`) o `INVALID_VALUE` (formato de ids, `outcome` fuera de `interested`/`not_interested`/`handoff`, `properties` que no es un arreglo o textos demasiado largos)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"outcome debe ser interested, not_interested o handoff"}}}},"404":{"description":"Proyecto inexistente, inactivo o de otra empresa; u oportunidad que no existe, es de otra empresa o no es de un pipeline del proyecto","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"422":{"description":"No se escribió nada. `OUTCOME_NOT_CONFIGURED`: no hay fila activa en `ai_outcome_config` para el proyecto y el resultado. `ASSIGNMENT_NO_USERS`: la config asigna y el rol no tiene usuarios activos con email en la empresa","content":{"application/json":{"examples":{"Sin config":{"description":"Sin config","value":{"status":"error","code":"OUTCOME_NOT_CONFIGURED","message":"El proyecto no tiene configurado el resultado interested"}},"Rol sin usuarios":{"description":"Rol sin usuarios","value":{"status":"error","code":"ASSIGNMENT_NO_USERS","message":"El rol de asignación no tiene usuarios activos"}}}}}}}}},"/ai-employees/outbound-message":{"post":{"tags":["Empleados IA"],"summary":"Enviar una parte de la respuesta del Empleado IA por WhatsApp","description":"Lo llama `main` una vez por cada parte de la respuesta (hasta 5 de ~420 caracteres, con 5 s entre una y otra). **n8n no reintenta este endpoint.**\n1. Comprueba y suelta la conexión: proyecto, oportunidad (de un pipeline del proyecto), `phone_number_id` (número activo de Canales de la empresa; es el número que recibió el mensaje, que puede servir a varios proyectos) y `after_message_id` (un mensaje del cliente de esa oportunidad). **El destinatario es el `phone` de esa fila de `chat_histories`** (los dígitos con los que escribió el cliente); nunca se acepta un teléfono en el cuerpo. Si el cliente escribió después de `after_message_id`, responde 409 `SUPERSEDED` y no envía (corta la respuesta vieja). Si el Empleado IA está pausado, responde 409 `PAUSED` antes de enviar y no inserta.\nReacciones y los tipos `unsupported`, `unknown`, `system`, `ephemeral` y `request_welcome` posteriores no cancelan la respuesta; siguen visibles en el historial.\n2. Manda el texto a Meta (`type: text`, sin vista previa de enlaces) con el token de Canales del número o, si no, el de la empresa.\n3. Solo entonces inserta en `chat_histories`: `from_me = true`, `type_sender = 'ai'`, `type = 'text'`, el `message_id` que devolvió Meta (clave con la que `PUT /messages/status` marca entregado y leído), el stage actual de la oportunidad y `date_send = now()`.\nSi Meta lo envió y el INSERT falla (se reintenta una vez), responde 201 igual porque el mensaje salió, con `saved: false`; el wamid queda en el log del servidor para reconciliar. Un fallo de Meta no guarda ninguna fila: `WHATSAPP_WINDOW_CLOSED` (131047, fuera de las 24 h), `WHATSAPP_NOT_CONNECTED` (sin token, vencido o rechazado) y `WHATSAPP_REJECTED` (422), `WHATSAPP_UNAVAILABLE` (503: caído, timeout o 429).","operationId":"outboundMessage","requestBody":{"description":"Una parte de la respuesta del Empleado IA","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","phone_number_id":"109876543210987","body":"Hola Juan, con gusto te cuento de la casa.","after_message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz"}}},"required":true},"responses":{"201":{"description":"Enviado. `saved` dice si quedó en `chat_histories`","content":{"application/json":{"example":{"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgARGBI5","saved":true}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD` o `INVALID_VALUE` (`body` vacío o de más de 4096 caracteres, ids con formato inválido)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"body no puede pasar de 4096 caracteres"}}}},"404":{"description":"Proyecto, oportunidad, número de WhatsApp o `after_message_id` inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Número de WhatsApp no encontrado"}}}},"409":{"description":"`SUPERSEDED` o `PAUSED`: no se envió nada","content":{"application/json":{}}},"422":{"description":"`WHATSAPP_WINDOW_CLOSED`, `WHATSAPP_NOT_CONNECTED` o `WHATSAPP_REJECTED`. No se guardó la fila","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_WINDOW_CLOSED","message":"Pasaron más de 24 horas desde el último mensaje del cliente"}}}},"503":{"description":"`WHATSAPP_UNAVAILABLE`: Meta caído, timeout o 429. No se guardó la fila","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_UNAVAILABLE","message":"WhatsApp no está disponible"}}}}}}},"/ai-employees/memory":{"get":{"tags":["Memoria del Empleado IA"],"summary":"Leer la memoria del Empleado IA","description":"Devuelve los últimos mensajes activos de la sesión, ordenados del más antiguo al más reciente.\nLa memoria vive en `ai_memory.chat_memory`, separada de `public.chat_histories`.\n`phone` se normaliza a 8–15 dígitos; `limit` vale 48 por defecto y admite 1–100.\nUn proyecto inexistente o de otra empresa devuelve el mismo 404.","operationId":"get_5","parameters":[{"name":"project_id","in":"query","description":"UUID del proyecto","required":false,"schema":{"type":"string"},"example":"fc7002bc-9b72-4923-865e-66882e255779"},{"name":"phone","in":"query","description":"Teléfono tal como llega de n8n","required":false,"schema":{"type":"string"},"example":"+591 7123-4567"},{"name":"limit","in":"query","description":"Últimos mensajes, de 1 a 100","required":false,"schema":{"type":"string"},"example":48}],"responses":{"200":{"description":"Mensajes activos; una sesión vacía devuelve []","content":{"application/json":{"example":[{"id":123,"type":"human","content":"Hola","created_at":"2026-10-28T12:00:00-04:00"},{"id":124,"type":"ai","content":"Hola, ¿en qué puedo ayudarte?","created_at":"2026-10-28T12:00:01-04:00"}]}}},"400":{"description":"`MISSING_FIELD`, `INVALID_ID` o `INVALID_VALUE`","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"limit debe estar entre 1 y 100"}}}},"404":{"description":"Proyecto inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}},"post":{"tags":["Memoria del Empleado IA"],"summary":"Guardar mensajes de memoria del Empleado IA","description":"Valida todo el lote antes de escribir e inserta 1–20 mensajes en orden y en una transacción.\n`type` admite `human` o `ai`; `content` debe ser texto no vacío. El JSON guardado sigue\nel formato plano de LangChain. La empresa sale únicamente de la API key.","operationId":"save","requestBody":{"description":"Mensajes que se agregan a la memoria","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","phone":"+591 7123-4567","messages":[{"type":"human","content":"Hola"},{"type":"ai","content":"Hola, ¿en qué puedo ayudarte?"}]}}},"required":true},"responses":{"201":{"description":"IDs creados en el orden recibido","content":{"application/json":{"example":{"ids":[123,124]}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD`, `INVALID_ID` o `INVALID_VALUE`; no se inserta el lote","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"messages[0].type debe ser human o ai"}}}},"404":{"description":"Proyecto inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/ai-employees/memory/reset":{"post":{"tags":["Memoria del Empleado IA"],"summary":"Reiniciar la memoria del Empleado IA","description":"Marca `state = 0` y actualiza `updated_at` para todos los mensajes activos del contacto (soft delete).\nEl alcance se elige con el cuerpo: `opportunity_id` solo (el contacto de esa oportunidad; el proyecto es\nel propio de la oportunidad o, si no tiene, el de su pipeline, igual que en `/blacklist`), `project_id` +\n`phone` (un contacto) o `project_id` solo (todos los contactos del proyecto). Es idempotente y no borra\nfilas ni modifica `public.chat_histories`. Solo aplica a proyectos nuevos con memoria en `ai_memory`.","operationId":"reset","requestBody":{"description":"opportunity_id solo, project_id + phone, o project_id solo para todo el proyecto","content":{"application/json":{"schema":{"type":"string"},"examples":{"Por oportunidad":{"description":"Por oportunidad","value":{"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"Un contacto":{"description":"Un contacto","value":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","phone":"+591 7123-4567"}},"Todo el proyecto":{"description":"Todo el proyecto","value":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779"}}}}},"required":true},"responses":{"200":{"description":"Cantidad de mensajes reiniciados y el proyecto afectado","content":{"application/json":{"example":{"reset":2,"project_id":"fc7002bc-9b72-4923-865e-66882e255779"}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD`, `INVALID_ID` o `INVALID_VALUE` (también si `opportunity_id` viene junto con `project_id` o `phone`)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"phone debe contener entre 8 y 15 dígitos"}}}},"404":{"description":"Proyecto u oportunidad inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}},"409":{"description":"Con `opportunity_id`: la oportunidad no tiene proyecto, o su contacto no tiene un teléfono válido","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La oportunidad no tiene un contacto con teléfono válido"}}}}}}},"/ai-employees/lead-data":{"post":{"tags":["Empleados IA"],"summary":"Guardar datos confirmados por un lead","description":"Actualiza nombre y apellido del contacto y mezcla fields en opportunities.data en una transacción. Los nombres no vacíos reemplazan el valor anterior. fields admite hasta 20 claves; null borra una clave. Las claves reservadas o inválidas y los valores inválidos se omiten y figuran en ignored.","operationId":"leadData","requestBody":{"description":"Datos confirmados por el cliente","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"proyecto-1","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","name":"Juan","lastname":"Pérez","fields":{"ciudad":"Santa Cruz","producto_interes":"melamina"}}}},"required":true},"responses":{"200":{"description":"Datos guardados","content":{"application/json":{"example":"{\"ok\":true,\"contact_updated\":[\"name\"],\"fields_updated\":[\"ciudad\"],\"ignored\":[{\"key\":\"canal\",\"reason\":\"reserved\"}]"}}},"400":{"description":"Cuerpo o identificadores inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"fields no puede tener más de 20 claves"}}}},"404":{"description":"Proyecto u oportunidad no encontrados en esta empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/ai-employees/knowledge/search":{"post":{"tags":["Empleados IA"],"summary":"Buscar en la base de conocimiento del Empleado IA","description":"Genera un embedding text-embedding-3-small (1536 dimensiones) y busca en pgvector por distancia coseno. k: 1 a 10, por defecto 5. Un proyecto sin base devuelve results vacío.","operationId":"search_1","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"p-123","query":"¿Cuáles son los horarios?","k":5}}},"required":true},"responses":{"200":{"description":"Resultados ordenados por score descendente","content":{"application/json":{"examples":{"Con resultados":{"description":"Con resultados","value":{"results":[{"content":"Abrimos de lunes a viernes.","score":0.91,"source":"horarios.pdf"}]}},"Sin base":{"description":"Sin base","value":{"results":[]}}}}}},"400":{"description":"query o k inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"k debe estar entre 1 y 10"}}}},"404":{"description":"Proyecto ajeno o inexistente","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}},"422":{"description":"Sin credencial de OpenAI","content":{"application/json":{"example":{"status":"error","code":"OPENAI_CREDENTIAL_MISSING","message":"El proyecto no tiene una credencial de OpenAI activa"}}}},"502":{"description":"OpenAI rechazó la solicitud o respondió algo inválido","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"OpenAI respondió algo inesperado"}}}},"503":{"description":"OpenAI o la base no están disponibles","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_UNAVAILABLE","message":"OpenAI no responde"}}}}}}},"/ai-employees/inbound-message":{"post":{"tags":["Empleados IA"],"summary":"Registrar un mensaje entrante de WhatsApp","description":"Lo llama el workflow `verify_from` de un Empleado IA por cada mensaje que llega de WhatsApp. Reemplaza a sus consultas directas a la base y a las altas por la API v1, **en una sola transacción**:\n1. Si el `message.message_id` ya está guardado en una oportunidad de la empresa (Meta reintenta el webhook), responde 200 con lo que ya existe, `message.duplicate: true` y `created` en false, sin escribir nada.\n2. Busca el contacto de la empresa por teléfono con la misma regla que `GET /contacts/by-phone`. Si no existe, lo crea (nombre = `profile_name`, o el teléfono; el SaaS separa el código de país) y, si el proyecto tiene `id_list_contact`, lo agrega a esa lista.\n3. Toma la oportunidad \"En Progreso\" más reciente del contacto en los pipelines del proyecto. Si no hay, crea una en el **primer stage del único pipeline IA activo enlazado al proyecto**, con `value` 0 y `data = {\"canal\":\"whatsapp\",\"ad_id\":referral_source_id}`. Si el proyecto no tiene ese pipeline, o tiene más de uno, responde 422 `IA_PIPELINE_MISSING` o `IA_PIPELINE_AMBIGUOUS` y no guarda nada.\n4. Guarda el mensaje en el historial (`from_me: false`, `type_sender: human`, `date_send` = `timestamp` o la hora actual).\n5. Devuelve `paused` si una fila activa de lista negra de cualquier proyecto activo de la empresa coincide con el teléfono entrante o una variante verificada del contacto (mínimo 6 dígitos; nunca filas sin proyecto). El mensaje se guarda igual, para que lo vea un humano. Devuelve también `quoted` (`body` y `type` del mensaje citado por `context_message_id`, buscado entre las oportunidades del contacto; `null` si no hay).\n\nMensajes simultáneos del mismo teléfono se procesan de a uno: no se duplican contactos ni oportunidades. Obligatorios: `project_id`, `phone` (de 6 a 20 dígitos; se descartan los demás caracteres) y `message.message_id`. `message.body` admite hasta 20 000 caracteres; los demás textos, hasta 1000. 201 si guardó el mensaje, 200 si era un reintento.","operationId":"inboundMessage","requestBody":{"description":"Mensaje entrante tal como lo normaliza n8n desde el webhook de Meta","content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"8debaf2c-15e2-43b0-9c0b-20defaba626b","phone":"59171234567","profile_name":"Juan","message":{"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgASGBQz","type":"text","body":"Hola, quiero información","media_id":null,"mime_type":null,"filename":null,"timestamp":"2026-10-08T15:00:00Z","context_message_id":null,"referral_source_id":null}}}},"required":true},"responses":{"201":{"description":"Mensaje guardado. `created` dice si se crearon el contacto o la oportunidad","content":{"application/json":{"example":{"contact":{"id":"3f6b2c1e-8a4d-4e2f-9c7b-1d5e6f7a8b9c","name":"Juan","lastname":null,"phone":"71234567","country_code":"+591"},"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10"},"created":{"contact":true,"opportunity":true},"message":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","duplicate":false},"paused":false,"quoted":null}}}},"200":{"description":"Reintento: el `message_id` ya estaba guardado. No se escribió nada","content":{"application/json":{"example":{"contact":{"id":"3f6b2c1e-8a4d-4e2f-9c7b-1d5e6f7a8b9c","name":"Juan","lastname":null,"phone":"71234567","country_code":"+591"},"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10"},"created":{"contact":false,"opportunity":false},"message":{"id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","duplicate":true},"paused":false,"quoted":null}}}},"400":{"description":"`INVALID_BODY` (no es JSON), `MISSING_FIELD` (`project_id`, `phone`, `message` o `message.message_id`) o `INVALID_VALUE` (formato de `project_id`, `phone`, `message_id` o `timestamp`, o texto demasiado largo)","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"message.message_id es obligatorio"}}}},"404":{"description":"Proyecto inexistente, inactivo o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}},"422":{"description":"Hacía falta crear una oportunidad y el proyecto no tiene un único pipeline IA activo enlazado. No se guardó nada","content":{"application/json":{"examples":{"Sin pipeline IA":{"description":"Sin pipeline IA","value":{"status":"error","code":"IA_PIPELINE_MISSING","message":"El proyecto no tiene un pipeline IA activo con stages; enlaza uno al proyecto"}},"Varios pipelines IA":{"description":"Varios pipelines IA","value":{"status":"error","code":"IA_PIPELINE_AMBIGUOUS","message":"El proyecto tiene 2 pipelines IA activos; debe quedar uno solo enlazado"}}}}}}}}},"/ai-employees/inbound-media":{"post":{"tags":["Empleados IA"],"summary":"Guardar y, si corresponde, describir media del cliente","description":"Valida que el media pertenezca a un mensaje entrante del proyecto y de la empresa. Guarda el archivo en /chat_history/<media_id>; describe imágenes con gpt-4o y transcribe audio con whisper-1 cuando describe=true. El texto se guarda en ai_text; body queda intacto. Audios mayores de 25 MB y video, documento o sticker devuelven text:null.","operationId":"inboundMedia","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"p-123","message_id":"wamid.abc","phone_number_id":"109876543210987","media_id":"123456789","type":"image","mime_type":"image/jpeg","describe":true}}},"required":true},"responses":{"200":{"description":"Archivo guardado","content":{"application/json":{"examples":{"Imagen descrita":{"description":"Imagen descrita","value":{"media_id":"123456789","stored":true,"text":"Una casa blanca con jardín."}},"Video o sin descripción":{"description":"Video o sin descripción","value":{"media_id":"123456789","stored":true,"text":null}}}}}},"400":{"description":"Cuerpo inválido","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"media_id es obligatorio"}}}},"404":{"description":"Media, mensaje o proyecto ajeno o inexistente","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Media no encontrada"}}}},"422":{"description":"Sin WhatsApp u OpenAI (el archivo puede ya estar guardado)","content":{"application/json":{}}},"502":{"description":"Falló FTP u OpenAI rechazó la solicitud","content":{"application/json":{"example":{"status":"error","code":"STORAGE_ERROR","message":"No se pudo guardar el archivo"}}}},"503":{"description":"Meta, FTP, OpenAI o la base no están disponibles","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_UNAVAILABLE","message":"WhatsApp no está disponible"}}}}}}},"/ai-employees/human-message":{"post":{"tags":["Empleados IA"],"summary":"Enviar el mensaje de un asesor humano al cliente","description":"            Lo llama el workflow `send_human` cuando un asesor responde desde el chat del SaaS a un cliente de un Empleado             IA. Envía por WhatsApp un texto, un archivo o una plantilla de recontacto y **guarda la fila en             `chat_histories`** (`saved_by_api: true`: quien llama no debe guardarla otra vez).\n            1. **Sin deduplicación**: `request_id` es opcional (hasta 200 caracteres); si viene, solo se valida el largo y se             escribe en el log, no se guarda. La API **no deduplica**: la protección contra el doble envío va en el front             (botón desactivado mientras se envía). `duplicate` es siempre `false`, por compatibilidad con `send_human`.\n            2. **Oportunidad** de un pipeline del proyecto y de la empresa; si no, 404.\n            3. **Número emisor**: `phone_number_id` si es un número activo de WhatsApp de la empresa; si no viene o no             lo es, el número del proyecto. El token sale de Canales. Sin número o sin token, 422 `WHATSAPP_NOT_CONNECTED`.\n            4. **Destinatario**: el `phone` del último mensaje del cliente de la oportunidad (`from_me = false`); si no hay,             `country_code` + `phone` del contacto, en dígitos. Debe tener entre 6 y 20 dígitos (422 `BUSINESS_RULE`).             Nunca se acepta un teléfono en el cuerpo.\n            5. **Texto** (`sent_template: false` y sin `file_url`): `body` obligatorio, hasta 4096 caracteres.\n            6. **Archivo** (`file_url`, `type` image, video, audio o document): solo URLs `https` del FTP de la plataforma             (el host y la ruta de `FTP_PUBLIC_URL`); cualquier otra, 400. Se lee del FTP (hasta 100 MB), se envía a Meta             **por enlace** con esa misma URL pública (no se sube a Meta: es más simple y Meta lo admite), con `body` como             pie (el audio no lleva pie) y se guarda una copia en `/chat_history/<media_id>` con un `media_id` generado.\n            7. **Plantilla** (`sent_template: true`): se reenvía `template` (`name`, `language`, `components`) tal cual.             `header_media.url`, si viene, debe ser del FTP de la plataforma o un media id de Meta. No cambia lo que se envía a Meta (la cabecera va en `template`): solo deja la imagen en el historial (fila con `type` image, video o document y `media_id` con la URL).\n            8. **Ventana de 24 h**: texto o archivo fuera de ella (Meta 131047) dan 422 `WHATSAPP_WINDOW_CLOSED` sin guardar             fila. Las plantillas sí salen.\n            9. **Guardado**, después del envío: texto o archivo con `from_me = true`, `type_sender = 'human'`; plantilla con             `type_sender = 'template'`, `type = 'text'` y `body = template_text` (o «📨 Plantilla de recontacto enviada»),             que es la fila que usa el cooldown del reenvío. Si el INSERT falla, 200 con `saved: false` y el wamid en el log.\n            `body` de la respuesta es el texto guardado (para la memoria del Empleado IA); en un duplicado `body` y `phone` vienen null y no hay que escribir la memoria.","operationId":"humanMessage","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"examples":{"Texto":{"description":"Texto","value":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","request_id":"5f1d3c1e-0b8e-4f6e-9a55-6f2f0b3a7c10","phone_number_id":null,"body":"Hola Juan, te escribo yo.","type":"text","file_url":null,"mime_type":null,"filename":null,"sent_template":false,"template":null,"template_text":null,"header_media":null}},"Plantilla":{"description":"Plantilla","value":{"project_id":"fc7002bc-9b72-4923-865e-66882e255779","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","request_id":"a1","body":"","type":"text","sent_template":true,"template":{"name":"recontacto","language":{"code":"es"},"components":[{"type":"body","parameters":[{"type":"text","text":"Juan"}]}]},"template_text":"Hola Juan, ¿sigues interesado?"}}}}},"required":true},"responses":{"200":{"description":"Enviado (o duplicado). `saved` dice si quedó en `chat_histories`","content":{"application/json":{"examples":{"Enviado":{"description":"Enviado","value":{"message_id":"wamid.HBgLNTkxNzEyMzQ1NjcVAgARGBI5","body":"Hola Juan, te escribo yo.","phone":"59171234567","duplicate":false,"saved":true,"saved_by_api":true}}}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD` o `INVALID_VALUE` (`request_id`, `body`, `type`, `file_url` que no es del FTP de la plataforma o no existe, `template`, `header_media`)","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"file_url no es un archivo de la plataforma"}}}},"404":{"description":"Proyecto u oportunidad inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"422":{"description":"`WHATSAPP_NOT_CONNECTED`, `WHATSAPP_WINDOW_CLOSED`, `WHATSAPP_REJECTED` o `BUSINESS_RULE` (destinatario sin teléfono válido). No se guardó fila","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_WINDOW_CLOSED","message":"Pasaron más de 24 horas desde el último mensaje del cliente"}}}},"502":{"description":"`STORAGE_ERROR`: no se pudo leer o guardar el archivo en el FTP","content":{"application/json":{"example":{"status":"error","code":"STORAGE_ERROR","message":"No se pudo leer el archivo"}}}},"503":{"description":"`WHATSAPP_UNAVAILABLE` (Meta caído, timeout o 429), `STORAGE_UNAVAILABLE` o `DB_UNAVAILABLE`. La reserva quedó libre","content":{"application/json":{"example":{"status":"error","code":"WHATSAPP_UNAVAILABLE","message":"WhatsApp no está disponible"}}}}}}},"/ai-employees/assignment":{"post":{"tags":["Empleados IA"],"summary":"Asignar un ejecutivo por turno","description":"Usa `assign_role_id` de la fila `handoff` activa de `ai_outcome_config` y los usuarios activos de ese rol,\nordenados por correo y siguiendo la misma rueda de `outcome`. La asignación y el registro de `request_id`\nocurren en una transacción. Repetir el mismo `request_id` devuelve el mismo ejecutivo y no avanza la rueda.\nSi la oportunidad ya tiene dueño, lo conserva y el aviso, si se pidió, va a ese dueño.\nCon `notify: true`, después del commit se envía `alerta_transferencia_humana` desde Canales de la empresa;\nuna falla deja la asignación aplicada y devuelve `notified: false` con `notify_error`.\n","operationId":"assignment","requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"project_id":"project-1","opportunity_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","notify":true,"request_id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11:assignment"}}},"required":true},"responses":{"200":{"description":"Ejecutivo asignado (o respuesta idempotente)","content":{"application/json":{"example":{"assigned_user_id":"3f6b2c1e-8a4d-4e2f-9c7b-1d5e6f7a8b9c","owner_email":"ana@empresa.com","notified":true,"notify_error":null}}}},"400":{"description":"`INVALID_BODY`, `MISSING_FIELD` o `INVALID_VALUE`","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"request_id es obligatorio"}}}},"404":{"description":"Proyecto u oportunidad inexistente, ajena o de otro proyecto","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"422":{"description":"No hay rol configurado o usuarios activos para asignar","content":{"application/json":{"example":{"status":"error","code":"ASSIGNMENT_NOT_CONFIGURED","message":"El proyecto no tiene un rol de asignación con usuarios activos"}}}}}}},"/advisor-calls/{id}/end":{"post":{"tags":["Llamadas de asesor"],"summary":"Informar el fin de una llamada de asesor (solo telefonía)","description":"Lo llama **solo el servidor de telefonía** cuando el asesor cuelga. No usa API key de empresa: se autentica con la cabecera `X-Internal-Token`, un secreto compartido (propiedad `telephony.internal-token`). Sin token configurado en la API, 503 `TELEPHONY_UNAVAILABLE`; token ausente o incorrecto, 401 `UNAUTHORIZED`.\nSi la llamada está `ongoing`, pasa a `completed` cuando `status` es `answered` y a `failed` en cualquier otro caso. Guarda `end_cause` (`cause`, o `status` si no hay), `sip_call_id`, `duration_sec`, `answered_at` y `ended_at` (ahora, si falta). Con `recorded: true` guarda `recording_url` = `<base>/<company_id>/<id>.wav`. Después hace un POST JSON (`advisor_call.ended`, timeout de 10 s, sin reintentos) al `end_call_webhook` del número, si lo tiene; si falla (no 2xx, timeout, URL inválida o que apunta a una dirección interna: loopback, red privada, link-local) deja el motivo en `webhook_error` y responde 200 igual.\n**Idempotente:** si la llamada ya no está `ongoing` responde 200 sin cambiar nada ni volver a llamar al webhook. Excepción: una llamada `failed` con `end_cause` `abandoned` (la cerró el sistema al iniciar otra) sí acepta el fin real.","operationId":"end","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","description":"Secreto compartido con el servidor de telefonía","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"},"example":{"status":"answered","cause":"normal","sip_call_id":"a84b4c76e66710","recorded":true,"duration_sec":125,"started_at":"2026-11-13T14:00:00Z","answered_at":"2026-11-13T14:00:07Z","ended_at":"2026-11-13T14:02:12Z"}}},"required":true},"responses":{"200":{"description":"`webhook`: `sent`, `failed` o `none` (sin webhook, o llamada que ya estaba cerrada)","content":{"application/json":{"example":{"id":"3f0f4f0e-2d57-4c5e-9d1f-6b0a8c2d7e11","status":"completed","webhook":"sent"}}}},"400":{"description":"`INVALID_ID`, `INVALID_BODY` o `INVALID_VALUE`","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"duration_sec debe ser un entero"}}}},"401":{"description":"`UNAUTHORIZED`: falta `X-Internal-Token` o no coincide","content":{"application/json":{"example":{"status":"error","code":"UNAUTHORIZED","message":"Token interno inválido"}}}},"404":{"description":"La llamada no existe","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}},"503":{"description":"`TELEPHONY_UNAVAILABLE` (la API no tiene token configurado) o `DB_UNAVAILABLE`","content":{"application/json":{"example":{"status":"error","code":"TELEPHONY_UNAVAILABLE","message":"La integración con telefonía no está configurada"}}}}},"security":[]}},"/tickets/{id}/progress-state":{"patch":{"tags":["Tickets"],"summary":"Cambiar estado de avance","description":"Mueve el ticket a otra etapa de su embudo efectivo (columna del tablero). `progress_state` debe ser una key de `ticket_stage` activa de ese embudo, sin distinguir mayúsculas; `null` o una etapa de otro embudo responde 400. Para cambiar de embudo usa `POST /tickets/{id}/move`.","operationId":"updateProgressState","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"progress_state":"en_gestion"}}},"required":true},"responses":{"200":{"description":"Estado actualizado","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"progress_state ausente, nulo o que el embudo del ticket no tiene","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Ticket no encontrado","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/ventas/{ventaId}/cuota/{cuotaId}/history":{"get":{"tags":["Cuotas"],"summary":"Historial de cuota","description":"Devuelve el historial de la cuota después de comprobar que pertenece a la venta y empresa.","operationId":"historialCuota","parameters":[{"name":"ventaId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cuotaId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Historial","content":{"application/json":{"example":[]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Venta o cuota no encontrada","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cuota no encontrado"}}}},"422":{"description":"Regla de negocio","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"La operación fue rechazada por una regla de negocio"}}}}}}},"/users/count":{"get":{"tags":["Usuarios"],"summary":"Contar usuarios","description":"Retorna el número de miembros activos de la empresa (los mismos que devuelve GET /users)","operationId":"getCount","responses":{"200":{"description":"Total de usuarios","content":{"application/json":{"example":42}}}}}},"/users/by-role":{"get":{"tags":["Usuarios"],"summary":"Obtener usuarios por rol","description":"Retorna miembros activos asignados a un rol de la empresa de la API key. La búsqueda del nombre del rol no distingue mayúsculas y la respuesta mínima contiene id, name, lastname, email y phone (el email lo usa la asignación cíclica actual). Ignora cualquier company_id enviado por query.","operationId":"getByRole","parameters":[{"name":"roleName","in":"query","description":"Nombre del rol","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usuarios del rol","content":{"application/json":{"example":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455"}]}}},"400":{"description":"roleName requerido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"roleName es obligatorio"}}}}}}},"/tickets/{id}/position":{"get":{"tags":["Tickets"],"summary":"Posición del ticket en el listado","description":"Retorna la posición (base 1) del ticket dentro del listado filtrado y el total de tickets que cumplen los filtros (`saas_get_ticket_position_v2`). `position` es null si el ticket no pertenece al conjunto filtrado. Con `pipeline_id` el conjunto se limita a ese embudo efectivo.","operationId":"getPosition","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Posición y total","content":{"application/json":{"example":{"position":3,"total":172}}}}}}},"/tickets/{id}/adjacent":{"get":{"tags":["Tickets"],"summary":"Ticket anterior o siguiente","description":"Retorna el ticket adyacente al indicado dentro del listado ordenado por fecha de creación\ndescendente (`saas_get_adjacent_ticket_v2`). `direction=prev` devuelve el más reciente y\n`direction=next` el más antiguo. Con `pipeline_id` solo considera los tickets de ese embudo efectivo.\n","operationId":"getAdjacent","parameters":[{"name":"id","in":"path","description":"UUID del ticket actual","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"},{"name":"direction","in":"query","description":"Dirección: prev o next","required":false,"schema":{"type":"string","default":"next"},"example":"next"},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket adyacente","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"No hay ticket adyacente","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/types":{"get":{"tags":["Tickets"],"summary":"Tipos de ticket disponibles","description":"Catálogo de valores válidos para el campo `type` en un embudo (`ticket_type` activos, por `position`). Con `pipeline_id` devuelve los tipos de ese embudo (400 `REFERENCE_NOT_FOUND` si no es de la empresa); sin él, los del embudo por defecto de la empresa. Cada tipo trae `key`, `name` y `position`; `value` y `label` repiten `key` y `name` para quien leía el catálogo anterior.","operationId":"getTypes","parameters":[{"name":"pipeline_id","in":"query","description":"UUID del embudo. Sin él, el embudo por defecto de la empresa","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de tipos","content":{"application/json":{"example":[{"key":"RECLAMO","name":"Reclamo","position":1,"value":"RECLAMO","label":"Reclamo"},{"key":"SOLICITUD","name":"Solicitud","position":2,"value":"SOLICITUD","label":"Solicitud"}]}}}}}},"/tickets/tendencia":{"get":{"tags":["Tickets"],"summary":"Tendencia diaria de tickets","description":"Serie por día con la cantidad de tickets generados y resueltos (`saas_get_ticket_tendencia_v2`). Sin fechas, devuelve los últimos 7 días. Con `pipeline_id` solo cuenta los tickets de ese embudo efectivo.","operationId":"getTendencia","parameters":[{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-08-13"},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-08-19"},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Serie diaria","content":{"application/json":{"example":[{"day":"2026-08-13","generados":4,"resueltos":1},{"day":"2026-08-14","generados":7,"resueltos":3}]}}}}}},"/tickets/search":{"get":{"tags":["Tickets"],"summary":"Buscar tickets","description":"Búsqueda paginada con filtros combinables, ordenada del más reciente al más antiguo (a igual fecha, por `id`).\nEl parámetro `q` busca en título, tipo, estado, id externo, nombre del proyecto, nombre del contacto y en los\ncampos `formalizacion`, `resumen`, `sentimiento` y `emocion` del JSON `data`. `pipeline_id` filtra por embudo\nefectivo y `outcome` por el resultado de la etapa del ticket (`open`, `resolved` o `dismissed`).\n`owner_id` filtra por responsable (UUID del usuario, o `none` para los sin asignar) y `source_id` por origen\n(`GET /tickets/sources`). Cada ticket trae `effective_pipeline_id`, `owner_id`, `owner_name`, `source_id` y\n`source_name`. `/tickets/count` acepta los mismos filtros.\n","operationId":"search_2","parameters":[{"name":"q","in":"query","description":"Texto libre a buscar","required":false,"schema":{"type":"string"},"example":"facturación"},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"project_id","in":"query","description":"UUID del proyecto","required":false,"schema":{"type":"string"}},{"name":"contact_id","in":"query","description":"UUID del contacto","required":false,"schema":{"type":"string"}},{"name":"call_id","in":"query","description":"ID de la llamada asociada","required":false,"schema":{"type":"string"}},{"name":"opportunity_id","in":"query","description":"UUID de la oportunidad asociada","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-12-31"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","description":"Resultado de la etapa del ticket: `open` (en curso), `resolved` o `dismissed`","required":false,"schema":{"type":"string"},"example":"open"},{"name":"owner_id","in":"query","description":"UUID del responsable (usuario de la empresa) o `none` para los tickets sin asignar","required":false,"schema":{"type":"string"},"example":"none"},{"name":"source_id","in":"query","description":"UUID del origen del ticket (`GET /tickets/sources`)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Página (base 1)","required":false,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"limit","in":"query","description":"Registros por página (máx. 200)","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":20}],"responses":{"200":{"description":"Resultado paginado","content":{"application/json":{"example":{"total":45,"page":1,"limit":20,"pages":3,"data":[]}}}}}}},"/tickets/progress-states":{"get":{"tags":["Tickets"],"summary":"Estados de avance disponibles","description":"Catálogo de valores válidos para el campo `progress_state` en un embudo (`ticket_stage` activas, por `position`). Con `pipeline_id` devuelve las etapas de ese embudo (400 `REFERENCE_NOT_FOUND` si no es de la empresa); sin él, las del embudo por defecto de la empresa. Cada etapa trae `key`, `name`, `position` y `outcome` (`open`, `resolved` o `dismissed`); `value` y `label` repiten `key` y `name` para quien leía el catálogo anterior.","operationId":"getProgressStates","parameters":[{"name":"pipeline_id","in":"query","description":"UUID del embudo. Sin él, el embudo por defecto de la empresa","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de estados","content":{"application/json":{"example":[{"key":"nuevo","name":"Nuevo","position":1,"outcome":"open","value":"nuevo","label":"Nuevo"},{"key":"en_gestion","name":"En gestión","position":3,"outcome":"open","value":"en_gestion","label":"En gestión"},{"key":"resuelto","name":"Resuelto","position":5,"outcome":"resolved","value":"resuelto","label":"Resuelto"},{"key":"desestimado","name":"Desestimado","position":6,"outcome":"dismissed","value":"desestimado","label":"Desestimado"}]}}}}}},"/tickets/pipelines":{"get":{"tags":["Tickets"],"summary":"Embudos de tickets","description":"Embudos de ATC activos de la empresa (`saas_get_ticket_pipelines`), cada uno con sus `stages` (etapas: `key`, `name`, `position`, `outcome`) y sus `types` (tipos: `key`, `name`, `position`). `type` y `progress_state` de un ticket se validan contra el embudo efectivo del ticket.","operationId":"getPipelines","responses":{"200":{"description":"Embudos con etapas y tipos","content":{"application/json":{"example":[{"id":"5d1c9d42-6f0e-4d7e-9c55-0a1f6f3b2a10","company_id":"895e5a32-258b-46cf-b942-e6ee1e211d0a","project_id":null,"name":"Atención al cliente","is_default":true,"position":1,"stages":[{"id":"0a6f9d1e-1111-4c1b-8e2a-000000000001","key":"nuevo","name":"Nuevo","position":1,"outcome":"open"},{"id":"0a6f9d1e-1111-4c1b-8e2a-000000000002","key":"resuelto","name":"Resuelto","position":5,"outcome":"resolved"},{"id":"0a6f9d1e-1111-4c1b-8e2a-000000000003","key":"desestimado","name":"Desestimado","position":6,"outcome":"dismissed"}],"types":[{"id":"0a6f9d1e-2222-4c1b-8e2a-000000000001","key":"RECLAMO","name":"Reclamo","position":1},{"id":"0a6f9d1e-2222-4c1b-8e2a-000000000002","key":"SOLICITUD","name":"Solicitud","position":2}]}]}}}}}},"/tickets/metrics":{"get":{"tags":["Tickets"],"summary":"Métricas de tickets","description":"Totales por estado, por tipo y por sentimiento, más el total del período anterior (`total_prev`) para calcular la tendencia.\nUsa `saas_get_ticket_metrics_v2`: además de los contadores de siempre devuelve `abiertos`, `by_stage` y `by_type`\n(por embudo, con `pipeline_id`, `key`, `name` y `count`), y `resueltos`/`desestimados` cuentan por el `outcome` de la etapa.\nCon `pipeline_id` solo cuenta los tickets de ese embudo efectivo.\n","operationId":"getMetrics","parameters":[{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-12-31"},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Métricas","content":{"application/json":{"example":{"total":172,"total_prev":140,"pendientes":35,"en_gestion":1,"esperando_cliente":1,"escalados":0,"resueltos":16,"desestimados":120,"reclamos":128,"solicitudes":44,"sentiment_positivo":15,"sentiment_negativo":103,"sentiment_neutro":47,"abiertos":36,"by_stage":[{"pipeline_id":"5d1c9d42-6f0e-4d7e-9c55-0a1f6f3b2a10","key":"nuevo","name":"Nuevo","outcome":"open","position":1,"count":35}],"by_type":[{"pipeline_id":"5d1c9d42-6f0e-4d7e-9c55-0a1f6f3b2a10","key":"RECLAMO","name":"Reclamo","position":1,"count":128}]}}}}}}},"/tickets/first":{"get":{"tags":["Tickets"],"summary":"Primer ticket del listado","description":"Retorna el ticket más reciente que cumple los filtros (`saas_get_first_ticket_v2`). Con `pipeline_id` solo considera los tickets de ese embudo efectivo.","operationId":"getFirst","parameters":[{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket encontrado","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"No hay tickets que cumplan los filtros","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/tickets/distribution":{"get":{"tags":["Tickets"],"summary":"Distribución por tipo y sentimiento","description":"Conteo de tickets agrupados por `type` y por el `sentimiento` detectado en el JSON `data`, respetando los filtros indicados. Con `pipeline_id` solo cuenta los tickets de ese embudo efectivo.","operationId":"getDistribution","parameters":[{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"project_id","in":"query","description":"UUID del proyecto","required":false,"schema":{"type":"string"}},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Distribución","content":{"application/json":{"example":{"by_type":[{"key":"RECLAMO","total":128},{"key":"SOLICITUD","total":44}],"by_progress_state":[{"key":"desestimado","total":120},{"key":"nuevo","total":35}],"by_sentimiento":[{"key":"NEGATIVO","total":103},{"key":"NEUTRO","total":47}]}}}}}}},"/tickets/count":{"get":{"tags":["Tickets"],"summary":"Contar tickets","description":"Retorna el número de tickets activos que coinciden con los filtros indicados, los mismos que `/tickets/search` (incluidos `contact_id`, `call_id`, `opportunity_id`, `pipeline_id`, `outcome`, `owner_id` —UUID o `none`— y `source_id`). Sin filtros, devuelve el total de la empresa.","operationId":"getCount_1","parameters":[{"name":"q","in":"query","description":"Texto libre a buscar","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"project_id","in":"query","description":"UUID del proyecto","required":false,"schema":{"type":"string"}},{"name":"contact_id","in":"query","description":"UUID del contacto","required":false,"schema":{"type":"string"}},{"name":"call_id","in":"query","description":"ID de la llamada asociada","required":false,"schema":{"type":"string"}},{"name":"opportunity_id","in":"query","description":"UUID de la oportunidad asociada","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","description":"Resultado de la etapa del ticket: `open` (en curso), `resolved` o `dismissed`","required":false,"schema":{"type":"string"},"example":"open"},{"name":"owner_id","in":"query","description":"UUID del responsable (usuario de la empresa) o `none` para los tickets sin asignar","required":false,"schema":{"type":"string"},"example":"none"},{"name":"source_id","in":"query","description":"UUID del origen del ticket (`GET /tickets/sources`)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Total de tickets","content":{"application/json":{"example":172}}}}}},"/tickets/by-project":{"get":{"tags":["Tickets"],"summary":"Tickets por proyecto","description":"Distribución de tickets agrupados por proyecto, ordenada de mayor a menor (`saas_get_tickets_by_project_v2`). Los tickets sin proyecto se agrupan como `Sin proyecto`. Con `pipeline_id` solo cuenta los tickets de ese embudo efectivo.","operationId":"getByProject","parameters":[{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Tipo de ticket (key del embudo)","required":false,"schema":{"type":"string"},"example":"RECLAMO"},{"name":"progress_state","in":"query","description":"Etapa (key del embudo)","required":false,"schema":{"type":"string"},"example":"nuevo"},{"name":"pipeline_id","in":"query","description":"UUID del embudo: solo tickets de ese embudo efectivo (el `pipeline_id` del ticket o, si es null, el embudo por defecto de su proyecto o de la empresa)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Distribución por proyecto","content":{"application/json":{"example":[{"project_id":"b7c8d9e0-1234-5678-9abc-def012345678","project_name":"Cobranzas","total":88},{"project_id":null,"project_name":"Sin proyecto","total":12}]}}}}}},"/status":{"get":{"tags":["Estado"],"summary":"Estado de la API","description":"Responde 200 `{\"status\":\"ok\",\"message\":\"API is running\"}` si la API está arriba. Pide API key como cualquier otra ruta, así que también sirve para probar la key: 401 sin cabecera, 403 si la key no es válida y 503 `DB_UNAVAILABLE` si la base no responde (la key se valida contra la base).","operationId":"status","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/roles/permissions/all":{"get":{"tags":["Roles"],"summary":"Listar todos los permisos disponibles","description":"Retorna todos los permisos existentes en el sistema, sin filtrar por rol, con el módulo anidado (`module`) y ordenados por nombre descendente, como `saas_get_permissions_all` de v3","operationId":"getAllPermissions","responses":{"200":{"description":"Lista de permisos","content":{"application/json":{"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Ver usuarios","module_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","state":1,"module":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"CRM"}}]}}}}}},"/roles/count":{"get":{"tags":["Roles"],"summary":"Contar roles","description":"Retorna el número total de roles de la empresa autenticada","operationId":"getCount_2","responses":{"200":{"description":"Total de roles","content":{"application/json":{"example":5}}}}}},"/provisioning/batches":{"get":{"tags":["Aprovisionamiento"],"summary":"Listar lotes de aprovisionamiento","description":"Lotes de aprovisionamiento de la empresa de la key, del más reciente al más antiguo, sin los pasos (están en el detalle). Filtros opcionales: `project_id` y `status` (`pending`, `running`, `ok`, `failed`, `blocked`, `skipped`). Respuesta paginada `{data, page, limit, total, has_more}`; `page` >= 1 y `limit` entre 1 y 100.","operationId":"getBatches","parameters":[{"name":"project_id","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Estado del lote","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Página (desde 1)","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"limit","in":"query","description":"Registros por página (1 a 100)","required":false,"schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"Página de lotes","content":{"application/json":{"example":{"data":[{"id":"f1c6d0a4-2b7e-4c0f-9d58-6a1b3e7c9a20","project_id":"d4e5f6a7-0b1c-4d2e-8f3a-9b0c1d2e3f4a","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","prj_id":"prj_0042","github_repo":"empleado-ventas","channel":"voice","status":"failed","error":"el run de provision.yml termino con conclusion=failure","created_at":"2026-09-20T15:04:05.123456+00:00","updated_at":"2026-09-20T15:09:41.654321+00:00"}],"page":1,"limit":50,"total":1,"has_more":false}}}},"400":{"description":"Paginación o filtros inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"page debe ser >= 1 y limit entre 1 y 100"}}}}}}},"/provisioning/batches/{id}":{"get":{"tags":["Aprovisionamiento"],"summary":"Obtener lote de aprovisionamiento con sus pasos","description":"Detalle de un lote de la empresa de la key, con sus pasos ordenados (`steps`). Cada paso trae nombre, orden, estado, intentos y fechas; el campo `detail` de la tabla (respuestas crudas de GitHub y n8n) no se expone. Inexistente, dado de baja o de otra empresa responden igual (404).","operationId":"getBatch","parameters":[{"name":"id","in":"path","description":"ID del lote","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lote encontrado","content":{"application/json":{"example":{"id":"f1c6d0a4-2b7e-4c0f-9d58-6a1b3e7c9a20","project_id":"d4e5f6a7-0b1c-4d2e-8f3a-9b0c1d2e3f4a","company_id":"971d296d-ec86-43dc-a559-a8df4f164e39","prj_id":"prj_0042","github_repo":"empleado-ventas","channel":"voice","status":"failed","error":"el run de provision.yml termino con conclusion=failure","created_at":"2026-09-20T15:04:05.123456+00:00","updated_at":"2026-09-20T15:09:41.654321+00:00","steps":[{"step_name":"crear_repo_github","step_order":1,"status":"ok","attempt":1,"started_at":"2026-09-20T15:04:06+00:00","finished_at":"2026-09-20T15:04:09+00:00"},{"step_name":"dispatch_workflow","step_order":2,"status":"failed","attempt":1,"started_at":"2026-09-20T15:04:10+00:00","finished_at":"2026-09-20T15:09:41+00:00"}]}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"No existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Lote de aprovisionamiento no encontrado"}}}}}}},"/projects/{projectId}/whatsapp-numbers":{"get":{"tags":["Proyectos"],"summary":"Obtener número de WhatsApp del proyecto","description":"Devuelve los números configurados para el proyecto de la empresa de la key; no expone tokens ni secretos.","operationId":"whatsappNumbers","parameters":[{"name":"projectId","in":"path","description":"ID varchar del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Números de WhatsApp","content":{"application/json":{"example":[{"project_id":"proyecto_1","companies_channels_numbers_id":"a1b2c3d4-e5f6-4789-8123-456789abcdef","identifier":"+15551234567","display_name":"Ventas"}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Proyecto inexistente o ajeno","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/projects/{id}/transactions":{"get":{"tags":["Proyectos"],"summary":"Historial de transacciones","description":"Retorna el historial de movimientos de minutos del proyecto. `limit` se acota a 1–200.","operationId":"getTransactions","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Límite de registros (default 50, entre 1 y 200)","required":false,"schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"Lista de transacciones","content":{"application/json":{"example":[{"detail_id":"det-001","project_call_id":"call-abc","previous_balance":60.0,"cost":2.5,"new_balance":57.5,"transaction_date":"2026-05-25T10:00:00+00:00"}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/projects/{id}/balance":{"get":{"tags":["Proyectos"],"summary":"Balance del proyecto","description":"Retorna el balance de minutos del proyecto con detalle de costos. Responde `null` si el proyecto no tiene minutos.","operationId":"getBalance","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Balance","content":{"application/json":{"example":{"project_id":"proj-001","minutes":100,"elapsed_minutes":42.5,"available_minutes":57.5,"total_cost":6.375}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/projects/{id}/balance/simple":{"get":{"tags":["Proyectos"],"summary":"Balance simple del proyecto","description":"Retorna los minutos disponibles como número (`null` si el proyecto no tiene minutos)","operationId":"getBalanceSimple","parameters":[{"name":"id","in":"path","description":"ID del proyecto","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Minutos disponibles","content":{"application/json":{"example":57.5}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"El proyecto no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/projects/full":{"get":{"tags":["Proyectos"],"summary":"Obtener todos los proyectos con conteo de llamadas y SMS","description":"Como `GET /projects`, con `project_call_count` y `project_sms_count` (filas de cola de contact_method `call` y `sms` de cada proyecto, que es lo que usa la lista de proyectos de los Empleados IA en el SaaS). Usa `saas_get_projects_by_company_full`, que devuelve toda la fila del proyecto; la API deja pasar solo las mismas columnas que `GET /projects`, sin credenciales ni hooks (vapi_token, device_id, trunk, *_hook, webhook_*, n8n_prefix). Filtro opcional por módulo.","operationId":"getAllFull","parameters":[{"name":"id_companies_modules","in":"query","description":"Filtra por companies_modules.id","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Lista de proyectos con conteos","content":{"application/json":{"example":[{"id":"proj-001","name":"Bot de ventas","state":1,"is_active":1,"phone":"+59171234567","ai_employee_id":"b6d4755f-f494-410d-b183-46fa2c8ed02e","company_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","id_companies_modules":469,"project_call_count":120,"project_sms_count":0}]}}}}}},"/project-calls/{id}/summary":{"get":{"tags":["Llamadas de proyecto"],"summary":"Resumen de una llamada","description":"Lo que muestra v3 al abrir una llamada (`saas_get_call_resumen`): resumen, `json_data`, audio, transcripción (`chat`), duración, sentimiento, `structured_data` y la encuesta del proyecto con sus preguntas. Se suma a `/{id}/detail`, que se mantiene sin cambios.","operationId":"getSummary","parameters":[{"name":"id","in":"path","description":"ID de la llamada","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resumen de la llamada","content":{"application/json":{"example":{"id":"aa1111f2-d5f1-4b2d-ac92-be1beceba103","contact_name":"Juan Marcos","contact_phone":"69467767","contact_method":"call","summary":"El cliente reportó demora de la grúa...","json_data":{"Rubro":"Automotor"},"audio":"https://crm.uplabsai.com/audio/proj-001/aa1111f2-d5f1-4b2d-ac92-be1beceba103.wav","audio_vapi":"https://storage.vapi.ai/...","ended_reason":"assistant-ended-call","project_name":"Encuesta NPS","chat":[{"role":"user","message":"Sí, dígame"}],"started_at":"2026-05-04T14:05:23.463Z","ended_at":"2026-05-04T14:12:29.316Z","duration":7.1,"structured_data":{"Pregunta_1":3},"sentimiento":"Neutral","emocion":"Buzon","survey_id":null,"survey_name":null,"survey_description":null,"survey_questions":null}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La llamada no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrado"}}}}}}},"/project-calls/{id}/detail":{"get":{"tags":["Llamadas de proyecto"],"summary":"Detalle completo de una llamada","description":"Retorna `json_data`, `summary` y el análisis de `call_response` (structuredData, transcript, URLs de grabación, sentiment y costo)","operationId":"getDetail","parameters":[{"name":"id","in":"path","description":"ID de la llamada","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detalle de la llamada","content":{"application/json":{"example":{"id":"aa1111f2-d5f1-4b2d-ac92-be1beceba103","contact_name":"Juan Marcos","contact_phone":"69467767","summary":"El cliente reportó demora de la grúa...","json_data":{"Rubro":"Automotor","Placa":"6494-DFP"},"analysis":{"summary":"Resumen del análisis...","structuredData":{"Pregunta_1":3,"Pregunta_2":"La grúa tardó casi una hora"},"successEvaluation":"false"},"transcript":"AI: Hola...\nUser: Sí...","recording_url":"https://storage.vapi.ai/...","stereo_recording_url":"https://storage.vapi.ai/...","duration_seconds":425.853,"cost":0.6537,"sentiment_analysis":{"sentimiento":"Neutral","emocion":"Buzon"},"ended_reason":"assistant-ended-call","call_date":"2026-05-04T14:05:23.463","updated_at":"2026-05-06T15:11:47.223649"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La llamada no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Llamada no encontrada"}}}}}}},"/project-calls/metrics":{"get":{"tags":["Llamadas de proyecto"],"summary":"Métricas de llamadas","description":"Totales del periodo y serie diaria, con los mismos filtros que el listado (`saas_get_calls_metrics`). Solo cuenta llamadas con `contact_method = call` y respuesta registrada. `desde`/`hasta` con formato YYYY-MM-DD. Devuelve un arreglo de un objeto, como la función de v3.","operationId":"metrics","parameters":[{"name":"proyecto","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"project_status","in":"query","description":"Estado del proyecto (1=activo, 0=inactivo)","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha desde (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha hasta (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"id","in":"query","description":"ID de la llamada","required":false,"schema":{"type":"string"}},{"name":"campaign","in":"query","description":"Nombre del proyecto (búsqueda parcial)","required":false,"schema":{"type":"string"}},{"name":"contact_name","in":"query","description":"Nombre del contacto","required":false,"schema":{"type":"string"}},{"name":"phone","in":"query","description":"Teléfono","required":false,"schema":{"type":"string"}},{"name":"end_reason","in":"query","description":"Razón de fin","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Key del estado (ej: pending)","required":false,"schema":{"type":"string"}},{"name":"cost_min","in":"query","description":"Costo mínimo","required":false,"schema":{"type":"number","format":"double"}},{"name":"cost_max","in":"query","description":"Costo máximo","required":false,"schema":{"type":"number","format":"double"}},{"name":"duration_min_ms","in":"query","description":"Duración mínima en ms","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"duration_max_ms","in":"query","description":"Duración máxima en ms","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"q","in":"query","description":"Búsqueda general","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Métricas de llamadas","content":{"application/json":{"example":[{"total_calls":120,"total_minutes":310.5,"total_cost":46.58,"successful_calls":80,"pending_calls":10,"failed_calls":30,"average_cost_per_call":0.39,"daily_metrics":[{"fecha":"2026-10-05","total_calls":12}]}]}}},"400":{"description":"Fechas o ids inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"desde y hasta deben tener formato YYYY-MM-DD"}}}}}}},"/project-calls/detail":{"get":{"tags":["Llamadas de proyecto"],"summary":"Listar llamadas con filtros y detalle","description":"Igual que el listado filtrado pero incluye `json_data`, `summary` y los campos extraídos de `call_response` (analysis, transcript, grabación, costo, sentiment).","operationId":"getAllWithDetail","parameters":[{"name":"proyecto","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha desde (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha hasta (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"contact_name","in":"query","description":"Nombre del contacto","required":false,"schema":{"type":"string"}},{"name":"phone","in":"query","description":"Teléfono","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Búsqueda general (nombre, teléfono, resumen)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Página (default 1)","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"page_size","in":"query","description":"Registros por página (default 25)","required":false,"schema":{"type":"integer","format":"int32","default":25}}],"responses":{"200":{"description":"Lista paginada con detalle","content":{"application/json":{"example":{"total":10,"page":1,"limit":25,"pages":1,"data":[{"id":"aa1111f2-d5f1-4b2d-ac92-be1beceba103","project_id":"1f06d1ac-cd63-43c3-887e-2b680ad9389e","project_name":"Siniestros Automotor","contact_name":"Juan Marcos","contact_phone":"69467767","contact_method":"call","call_date":"2026-05-04T14:05:23.463","updated_at":"2026-05-06T15:11:47.223649","summary":"El cliente reportó demora de la grúa...","json_data":{"Placa":"6494-DFP"},"analysis":{"summary":"...","structuredData":{"Pregunta_1":3},"successEvaluation":"false"},"transcript":"AI: Hola...\nUser: Sí...","recording_url":"https://storage.vapi.ai/...","stereo_recording_url":"https://storage.vapi.ai/...","duration_seconds":425.853,"cost":0.6537,"sentiment_analysis":{"sentimiento":"Neutral","emocion":"Buzon"},"ended_reason":"assistant-ended-call","state":1}]}}}}}}},"/pipeline/{id}/owners":{"get":{"tags":["Pipelines"],"summary":"Listar owners del pipeline","description":"Devuelve responsables presentes en oportunidades activas y su cantidad. user_id opcional debe ser miembro activo; sin él, el SP aplica visibilidad sin usuario.","operationId":"getOwners","parameters":[{"name":"id","in":"path","description":"UUID del pipeline","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"query","description":"UUID de miembro activo opcional","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Owners","content":{"application/json":{"example":[{"owners":[{"owner":"ana@example.com","total":4}]}]}}},"400":{"description":"UUID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Pipeline inexistente o ajeno","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Pipeline no encontrado"}}}}}}},"/pipeline/stage-status":{"get":{"tags":["Pipelines"],"summary":"Obtener estados de etapa","description":"Retorna todos los estados disponibles para las etapas de pipeline","operationId":"getStageStatuses","responses":{"200":{"description":"Lista de estados","content":{"application/json":{"example":[{"id":"af27b809-58c9-4b43-876a-321cf6fdfe69","name":"En Progreso"},{"id":"7ef1073e-fa88-4452-8956-28d04d16a963","name":"Ganado"},{"id":"438ab019-2ca7-4e10-869a-dced01fdf05a","name":"Perdido"}]}}}}}},"/pipeline/count":{"get":{"tags":["Pipelines"],"summary":"Contar pipelines","description":"Retorna el número total de pipelines de la empresa autenticada","operationId":"getCount_3","responses":{"200":{"description":"Total de pipelines","content":{"application/json":{"example":5}}}}}},"/opportunities/{opportunityId}/history":{"get":{"tags":["Oportunidades"],"summary":"Listar historial de cambios de una oportunidad","description":"Devuelve las filas activas de opportunities_history, ordenadas por fecha descendente, igual que saas_get_opportunities_history del SaaS v3. data es el snapshot previo y data_change contiene los campos modificados.","operationId":"getOpportunityHistory","parameters":[{"name":"opportunityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Historial ([] si no hay filas)","content":{"application/json":{"example":[{"id":"f1a2b3c4-d5e6-7890-abcd-ef1234567890","state":1,"created_at":"2026-05-28T14:00:00Z","data":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Oportunidad inicial","pipeline_stage_id":"71f6c859-5739-4345-9e1b-393c7ed78896"},"opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","data_change":{"pipeline_stage_id":"9bb0e5cb-a225-48be-a5c3-8e06476ad200"}}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o ajena)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"Base de datos no disponible"}}}}}}},"/opportunities/{opportunityId}/chat-history":{"get":{"tags":["Oportunidades"],"summary":"Obtener historial de chats de una oportunidad","description":"Retorna todos los chats activos asociados a una oportunidad de la empresa autenticada, ordenados por fecha descendente. Si la oportunidad no existe o es de otra empresa, responde 404.","operationId":"getChatHistory","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Historial de chats","content":{"application/json":{"example":[{"id":"f1a2b3c4-d5e6-7890-abcd-ef1234567890","opportunity_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","message":"Hola, estoy interesado en el producto","sender":"contact","state":1,"created_at":"2026-05-28T14:00:00.000000"}]}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad no encontrada (inexistente o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Oportunidad no encontrada"}}}}}}},"/opportunities/search":{"get":{"tags":["Oportunidades"],"summary":"Listar oportunidades paginadas por rango de fechas","description":"Retorna oportunidades filtradas por fecha de creación con paginación. Parámetros: desde (YYYY-MM-DD), hasta (YYYY-MM-DD), page (base 1, default 1), limit (default 20). Una fecha con otro formato responde 400.","operationId":"search_3","parameters":[{"name":"desde","in":"query","description":"Fecha inicio (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"hasta","in":"query","description":"Fecha fin (YYYY-MM-DD)","required":false,"schema":{"type":"string"},"example":"2026-12-31"},{"name":"page","in":"query","description":"Página (base 1)","required":false,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"limit","in":"query","description":"Registros por página","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":20}],"responses":{"200":{"description":"Página de oportunidades","content":{"application/json":{"example":{"total":45,"page":1,"limit":20,"pages":3,"data":[]}}}}}}},"/opportunities/count":{"get":{"tags":["Oportunidades"],"summary":"Contar oportunidades","description":"Retorna el número total de oportunidades de la empresa autenticada","operationId":"getCount_4","responses":{"200":{"description":"Total de oportunidades","content":{"application/json":{"example":12}}}}}},"/moneda":{"get":{"tags":["Monedas"],"summary":"Listar todas las monedas","description":"Retorna el catálogo global de monedas disponibles en el sistema","operationId":"getAll_12","responses":{"200":{"description":"Lista de monedas","content":{"application/json":{"example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","nombre":"Dólar Estadounidense","codigo":"USD","simbolo":"$","state":1},{"id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","nombre":"Euro","codigo":"EUR","simbolo":"€","state":1}]}}}}}},"/moneda/company":{"get":{"tags":["Monedas"],"summary":"Listar monedas de la empresa","description":"Retorna las monedas configuradas para la empresa autenticada (base y adicionales)","operationId":"getAllCompanyMonedas","responses":{"200":{"description":"Lista de monedas de la empresa","content":{"application/json":{"example":[{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","is_base":true,"tipo_cambio":1.0,"state":1},{"id":"d4e5f6a7-b8c9-0123-defa-234567890123","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","moneda_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","is_base":false,"tipo_cambio":1.08,"state":1}]}}}}}},"/minutes/available":{"get":{"tags":["Proyectos"],"summary":"Minutos disponibles","description":"Minutos contratados, consumidos y disponibles de voz (`saas_get_minutos_disponibles_v2`, la versión que usa v3). Hay que indicar al menos `project_id` o `companies_modules_id`; ambos deben ser de la empresa de la API key. Con `companies_modules_id` suma los proyectos del módulo; con `project_id` solo ese proyecto. Si el proyecto no tiene minutos cargados, los tres totales son 0.","operationId":"available","parameters":[{"name":"project_id","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"companies_modules_id","in":"query","description":"ID del módulo de la empresa (companies_modules)","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Totales de minutos","content":{"application/json":{"example":{"total_minutes":1000,"total_elapsed_minutes":312.4,"total_available_minutes":687.6}}}},"400":{"description":"Falta project_id y companies_modules_id, o un valor es inválido","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"Indica project_id o companies_modules_id"}}}},"404":{"description":"El proyecto o el módulo no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}}}}},"/items/metrics":{"get":{"tags":["Ítems"],"summary":"Métricas del catálogo","description":"Devuelve los totales, el estado del stock, precios por moneda y los ítems incompletos de la empresa autenticada. Admite los mismos filtros que GET /items.","operationId":"metrics_1","parameters":[{"name":"tipo_item_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"tipo_categoria","in":"query","required":false,"schema":{"type":"string"}},{"name":"stock_estado","in":"query","required":false,"schema":{"type":"string"}},{"name":"solo_incompletos","in":"query","required":false,"schema":{"type":"string"}},{"name":"company_moneda_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Métricas del catálogo","content":{"application/json":{"example":{"total":12,"productos":8,"servicios":4,"sin_categoria":0,"stock":{"total_unidades":24,"items_con_stock":8,"items_total":12,"agotados":1,"bajo":2,"saludable":5,"salud_pct":63},"precios":[],"valor_inventario":[],"incompletos":{"sin_precio":1,"sin_sku":2,"sin_categoria":0,"total":2,"completo_pct":83},"por_categoria":[]}}}},"400":{"description":"Algún filtro tiene un formato inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"stock_estado inválido"}}}}}}},"/cuotas":{"get":{"tags":["Cuotas"],"summary":"Listar cuotas de la empresa","description":"Filtros de saas_get_cuotas; la empresa siempre proviene de la API key.","operationId":"list_8","parameters":[{"name":"page","in":"query","description":"Página, desde 1","required":false,"schema":{"type":"string","default":"1"},"example":1},{"name":"limit","in":"query","description":"Filas por página, máximo 200","required":false,"schema":{"type":"string","default":"20"},"example":20},{"name":"estado","in":"query","description":"Estado de la cuota","required":false,"schema":{"type":"string"},"example":"pendiente"},{"name":"id","in":"query","description":"UUID de cuota","required":false,"schema":{"type":"string"}},{"name":"venta_id","in":"query","description":"UUID de venta","required":false,"schema":{"type":"string"}},{"name":"contacto_id","in":"query","description":"UUID de contacto","required":false,"schema":{"type":"string"}},{"name":"nro_documento","in":"query","description":"Número de documento","required":false,"schema":{"type":"string"}},{"name":"fecha_from","in":"query","description":"Fecha inicial de creación de la cuota (ISO 8601, created_at)","required":false,"schema":{"type":"string"}},{"name":"fecha_to","in":"query","description":"Fecha final de creación de la cuota (ISO 8601, created_at)","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Texto de búsqueda","required":false,"schema":{"type":"string"}},{"name":"order_by","in":"query","description":"Orden: fecha_vencimiento, update_at, monto, estado o created_at","required":false,"schema":{"type":"string","default":"fecha_vencimiento"}}],"responses":{"200":{"description":"Página de cuotas","content":{"application/json":{"example":{"data":[],"page":1,"limit":20,"total":0,"has_more":false}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"Parámetros inválidos"}}}}}}},"/cuotas/resumen":{"get":{"tags":["Cuotas"],"summary":"Resumen de cuotas","description":"Resumen de cobranzas filtrado por contacto, documento, fecha de creación de la cuota (created_at) y texto.","operationId":"resumen","parameters":[{"name":"contacto_id","in":"query","description":"UUID de contacto","required":false,"schema":{"type":"string"}},{"name":"nro_documento","in":"query","description":"Número de documento","required":false,"schema":{"type":"string"}},{"name":"fecha_from","in":"query","description":"Fecha inicial de creación de la cuota (ISO 8601, created_at)","required":false,"schema":{"type":"string"}},{"name":"fecha_to","in":"query","description":"Fecha final de creación de la cuota (ISO 8601, created_at)","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Texto de búsqueda","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resumen por moneda","content":{"application/json":{"example":[]}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}}}}},"/conversations":{"get":{"tags":["Conversaciones"],"summary":"Listar conversaciones","description":"Una fila por oportunidad con su actividad, ordenada por la más reciente (`last_activity_at`). Incluye `message_count`, `pending_reply_count` (mensajes del cliente sin responder), `call_count` y el stage actual. Lista toda la empresa de la API key: no hay alcance por usuario ni por owner. Respuesta paginada `{data, page, limit, total, has_more}`; `page` >= 1 y `limit` entre 1 y 200. `desde`/`hasta` filtran por `updated_at` de la oportunidad (YYYY-MM-DD). `call_filter` es `with` o `without` (con o sin llamadas) y `pending_only=true` deja solo las que tienen mensajes sin responder. `number_ids` es una lista separada por comas de líneas de WhatsApp configuradas en el proyecto. Fechas en hora de Bolivia (America/La_Paz) sin zona, igual que v3. `total` es 0 si la página pedida está vacía.","operationId":"list_9","parameters":[{"name":"proyecto","in":"query","description":"ID del proyecto","required":false,"schema":{"type":"string"}},{"name":"project_status","in":"query","description":"Estado del pipeline (1 = activo, 0 = inactivo)","required":false,"schema":{"type":"string"}},{"name":"desde","in":"query","description":"Fecha desde (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"hasta","in":"query","description":"Fecha hasta (YYYY-MM-DD)","required":false,"schema":{"type":"string"}},{"name":"id","in":"query","description":"ID de la oportunidad","required":false,"schema":{"type":"string"}},{"name":"campaign","in":"query","description":"Nombre del pipeline (búsqueda parcial)","required":false,"schema":{"type":"string"}},{"name":"customer","in":"query","description":"Nombre del cliente (búsqueda parcial)","required":false,"schema":{"type":"string"}},{"name":"phone","in":"query","description":"Teléfono (búsqueda parcial)","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Estado del stage (nombre)","required":false,"schema":{"type":"string"}},{"name":"message_min","in":"query","description":"Mínimo de mensajes","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"message_max","in":"query","description":"Máximo de mensajes","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"q","in":"query","description":"Búsqueda general (cliente, teléfono, id o nombre de la oportunidad)","required":false,"schema":{"type":"string"}},{"name":"call_filter","in":"query","description":"`with` solo con llamadas, `without` solo sin llamadas","required":false,"schema":{"type":"string"}},{"name":"pending_only","in":"query","description":"Solo conversaciones con mensajes sin responder","required":false,"schema":{"type":"boolean","default":false}},{"name":"pipeline_id","in":"query","description":"ID del pipeline","required":false,"schema":{"type":"string"}},{"name":"number_ids","in":"query","description":"Líneas de WhatsApp del proyecto, separadas por comas","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Página (desde 1)","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"limit","in":"query","description":"Registros por página (1 a 200)","required":false,"schema":{"type":"integer","format":"int32","default":25}}],"responses":{"200":{"description":"Página de conversaciones","content":{"application/json":{"example":{"data":[{"opportunity_id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","project_name":"Calificación de leads","contact_name":"Juan Pérez","contact_phone":"59171234567","status":"Nuevo","created_at":"2026-10-01T09:12:00","last_activity_at":"2026-10-05T16:40:12","updated_at":"2026-10-05T16:40:12","message_count":14,"pending_reply_count":2,"call_count":1,"opportunity_name":"Departamento Sopocachi","pipeline_stage_name":"Contactado","pipeline_stage_position":2,"pipeline_name":"Ventas IA","pipeline_type":"IA","pipeline_stage_status_name":"Nuevo","total_count":57}],"page":1,"limit":25,"total":57,"has_more":true}}}},"400":{"description":"Paginación, fechas, ids o call_filter inválidos","content":{"application/json":{"example":{"status":"error","code":"INVALID_VALUE","message":"page debe ser >= 1 y limit entre 1 y 200"}}}}}}},"/contacts/{id}/opportunities":{"get":{"tags":["Contactos"],"summary":"Oportunidades de un contacto","description":"Devuelve el contacto con sus oportunidades activas, con la forma de v1 (`GET /contacts/{id}/opportunities`): los campos de `contact` en el nivel superior más `opportunities` (arreglo) y `opportunities_count`. Las oportunidades salen de `saas_get_opportunities_by_contact_v2` (SP del SaaS v3): todas las columnas de `opportunities` más `project_name`, de la más reciente a la más antigua por `created_at` (v1 ordenaba por `updated_at`). Con `opportunity_id` solo se devuelve esa oportunidad del contacto. No trae `tags`, `notes`, `files`, `pipeline_stage_name`, `pipeline_name` ni `source_name`, que v1 incluía y los flujos no leen. Contacto inexistente o de otra empresa: 404 con el mismo mensaje. Sin oportunidades: 200 con `opportunities: []`; con `opportunity_id` que no es del contacto: 404.","operationId":"getOpportunities","parameters":[{"name":"id","in":"path","description":"UUID del contacto","required":true,"schema":{"type":"string"},"example":"12f1bb38-fe00-44c6-9798-8d5d25a8c551"},{"name":"opportunity_id","in":"query","description":"UUID de una oportunidad: devuelve solo esa","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contacto con sus oportunidades","content":{"application/json":{"example":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"591","phone":"22334455","json_data":{"departamento":"La Paz"},"state":1,"status":"prospecto","opportunities":[{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","name":"Juan Perez","state":1,"value":0.0,"contact_id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","project_id":"8debaf2c-15e2-43b0-9c0b-20defaba626b","project_name":"Calificación de leads","created_at":"2026-09-01T14:00:47.876668+00:00","updated_at":"2026-09-02T10:12:00.000000+00:00"}],"opportunities_count":1}}}},"400":{"description":"id u opportunity_id que no son UUID","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Contacto inexistente o de otra empresa, u oportunidad que no es del contacto","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Contacto no encontrado"}}}}}}},"/contacts/find":{"get":{"tags":["Contactos"],"summary":"Buscar contactos","description":"Busca contactos por nombre, apellido, teléfono, email o documento de identidad usando el parámetro `q`, obligatorio (vacío o en blanco responde 400 MISSING_FIELD). Ordena por nombre y `id`. Sin `page` devuelve un arreglo con un tope de seguridad de 1000 contactos (el máximo de `limit`); para recorrer más, usá `page`. Con `page` (desde 1; `limit` por defecto 500, de 1 a 1000) devuelve el sobre `{data, page, limit, total, has_more}`.","operationId":"find","parameters":[{"name":"q","in":"query","description":"Texto a buscar (nombre, apellido, teléfono, email o CI); obligatorio","required":false,"schema":{"type":"string"},"example":"Juan"},{"name":"page","in":"query","description":"Página (desde 1). Si se omite, devuelve hasta 1000 contactos como arreglo","required":false,"schema":{"type":"string"},"example":1},{"name":"limit","in":"query","description":"Contactos por página (1 a 1000, por defecto 500); solo con page","required":false,"schema":{"type":"string"},"example":500}],"responses":{"400":{"description":"q vacío (MISSING_FIELD) o page/limit inválidos (INVALID_VALUE)","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"q es obligatorio"}}}},"200":{"description":"Resultados de la búsqueda (arreglo sin `page`; sobre `{data, page, limit, total, has_more}` con `page`)","content":{"application/json":{"examples":{"Sin page":{"description":"Sin page","value":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","status":"prospecto","documento_identidad":"12345678"}]},"Con page":{"description":"Con page","value":{"data":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","phone":"+591 22334455","status":"prospecto","documento_identidad":"12345678"}],"page":1,"limit":500,"total":1,"has_more":false}}}}}}}}},"/contacts/count":{"get":{"tags":["Contactos"],"summary":"Contar contactos","description":"Retorna el número total de contactos de la empresa","operationId":"getCount_5","responses":{"200":{"description":"Total de contactos","content":{"application/json":{"example":42}}}}}},"/contacts/by-phone":{"get":{"tags":["Contactos"],"summary":"Buscar contacto por teléfono","description":"Busca el contacto de la empresa por teléfono con la regla del SaaS v3 (`saas_find_contact_by_phone`): se comparan solo los dígitos y coincide si el `phone` guardado es igual al buscado, si `country_code` + `phone` es igual al buscado, o si el `phone` guardado ya trae el prefijo y el buscado no. **No** hay coincidencia por los últimos 8 dígitos ni por subcadena, que sí usaban los flujos de SQL directo: es más estricta (decisión del dueño). Con varios candidatos gana el de coincidencia más específica. Devuelve `{contact, opportunity}`: `opportunity` es la oportunidad **En Progreso** más recientemente actualizada del contacto (estado de etapa `af27b809-…`, como filtran los flujos), restringida a los pipelines de `project_id` si viene. **Si no hay contacto, responde 200 con `contact: null` y `opportunity: null` (no 404)**: los flujos usan esa ausencia para decidir si crean el contacto. Sin oportunidad en progreso, `opportunity` es `null`. `phone` vacío es 400; un `phone` sin dígitos no encuentra nada. En la oportunidad, `project_id` es el del pipeline (como el `project_id` de los flujos) y `opportunity_status_id` repite `opportunitie_status_id`.","operationId":"byPhone","parameters":[{"name":"phone","in":"query","description":"Teléfono a buscar, con o sin prefijo de país; solo cuentan los dígitos","required":false,"schema":{"type":"string"},"example":59122334455},{"name":"project_id","in":"query","description":"UUID de un proyecto de la empresa: la oportunidad se busca en los pipelines de ese proyecto","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contacto y oportunidad (ambos pueden ser null)","content":{"application/json":{"examples":{"Encontrado":{"description":"Encontrado","value":{"contact":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","company_id":"550e8400-e29b-41d4-a716-446655440000","name":"Juan","lastname":"Perez","email":"juan_perez@example.com","country_code":"591","phone":"22334455","json_data":{},"state":1,"status":"prospecto"},"opportunity":{"id":"7c0d9a52-3f0e-4c3e-9d57-0a1f6f0f1b11","name":"Juan Perez","state":1,"value":0.0,"contact_id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","pipeline_stage_id":"d4b7a1c0-61c2-4c2a-b5f0-2f7f3b1e9a10","pipeline_stage_name":"Nueva oportunidad","pipeline_id":"5e2a8d71-0b4c-4d0f-8a39-91c0f6b2e7aa","pipeline_name":"Gestión IA","project_id":"8debaf2c-15e2-43b0-9c0b-20defaba626b","opportunitie_status_id":null,"opportunity_status_id":null,"campaign_id":null,"owner":null,"data":{},"created_at":"2026-09-01T14:00:47.876668+00:00","updated_at":"2026-09-02T10:12:00.000000+00:00"}}},"Contacto sin oportunidad en progreso":{"description":"Contacto sin oportunidad en progreso","value":{"contact":{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan","phone":"22334455","status":null},"opportunity":null}},"No encontrado":{"description":"No encontrado","value":{"contact":null,"opportunity":null}}}}}},"400":{"description":"phone vacío (MISSING_FIELD), project_id que no es UUID (INVALID_VALUE) o que no es de la empresa (REFERENCE_NOT_FOUND)","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"phone es obligatorio"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"Base de datos no disponible"}}}}}}},"/company/modules":{"get":{"tags":["Empresa"],"summary":"Obtener módulos habilitados","description":"Retorna los módulos de la empresa autenticada. Excluye módulos y asignaciones dados de baja (state = 0).","operationId":"getModules","responses":{"200":{"description":"Lista de módulos habilitados para la empresa","content":{"application/json":{"example":[{"entry_url":"/dashboard","updated_at":"2025-09-11T06:48:56.008143","name":"Calificación Leads","description":"Módulo de  Calificación de leads","created_at":"2025-09-11T06:48:56.008143","company_module_id":267,"is_active":1,"id":"e208f9fe-f037-48b5-921f-4e49edb45802","state":1}]}}}}}},"/campaigns":{"get":{"tags":["Campañas"],"summary":"Listar campañas","description":"Retorna las campañas activas de la empresa de la API key, de la más nueva a la más antigua, con la cantidad de oportunidades activas de cada una (cantidad_opportunities). Usa el mismo SP que el SaaS v3 (saas_get_campaigns_v2): created_at y updated_at vienen en hora de La Paz. Sin campañas devuelve [].","operationId":"getAll_13","responses":{"200":{"description":"Lista de campañas","content":{"application/json":{"example":[{"id":"0f3c3b0e-6f0e-4d5e-9c56-0d6d0f6f6a11","company_id":"480b3513-9f7b-4633-b078-3bd52bf2c8cf","project_id":null,"name":"Reactivación octubre","state":1,"update_user_id":null,"pipeline_stage_id":null,"is_call_enabled":true,"created_at":"2026-09-01T08:30:00","updated_at":"2026-09-01T08:30:00","cantidad_opportunities":12}]}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/campaigns/{id}/opportunities":{"get":{"tags":["Campañas"],"summary":"Oportunidades de una campaña","description":"Retorna las oportunidades activas de la campaña indicada, con los datos básicos del contacto (contact). La campaña debe ser de la empresa de la API key: si no existe, está dada de baja o es de otra empresa responde 404. Una campaña sin oportunidades devuelve [].","operationId":"getOpportunities_1","parameters":[{"name":"id","in":"path","description":"UUID de la campaña","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de oportunidades","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La campaña no existe o no es de la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Campaña no encontrada"}}}}}}},"/calendar/settings":{"get":{"tags":["Calendario"],"summary":"Consultar configuración del calendario","operationId":"getSettings","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"400":{"description":"Entrada inválida o referencia fuera de la empresa","content":{"application/json":{"examples":{"INVALID_VALUE":{"description":"INVALID_VALUE","value":{"status":"error","code":"INVALID_VALUE","message":"project_id inválido"}},"REFERENCE_NOT_FOUND":{"description":"REFERENCE_NOT_FOUND","value":{"status":"error","code":"REFERENCE_NOT_FOUND","message":"Proyecto no encontrado en la empresa"}}}}}},"404":{"description":"Evento o franja no encontrados en la empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Cita no encontrada"}}}},"409":{"description":"La franja se solapa con otra","content":{"application/json":{"example":{"status":"error","code":"CONFLICT","message":"La franja se solapa con otra disponibilidad"}}}},"422":{"description":"Regla de negocio rechazada por el calendario","content":{"application/json":{"example":{"status":"error","code":"BUSINESS_RULE","message":"Ese horario ya no está disponible"}}}},"503":{"description":"Base de datos no disponible","content":{"application/json":{"example":{"status":"error","code":"DB_UNAVAILABLE","message":"La base de datos no está disponible"}}}}}}},"/calendar/agenda-users":{"get":{"tags":["Calendario"],"summary":"Listar asesores de agenda","description":"Devuelve id, nombre completo y email de los usuarios de la empresa autenticada con permiso activo /agenda, mediante saas_get_agenda_users.","operationId":"list_10","responses":{"200":{"description":"Asesores disponibles","content":{"application/json":{"example":[{"id":"12f1bb38-fe00-44c6-9798-8d5d25a8c551","name":"Juan Perez","email":"juan@example.com"}]}}}}}},"/ai-employees/voices":{"get":{"tags":["Empleados IA"],"summary":"Listar voces de ElevenLabs","description":"Voces que soportan español o inglés (`verified_languages`), con `voice_id`, `name`, `preview_url`, `labels` y `verified_languages`, como `getVoices` de v3. La clave de ElevenLabs sale de la variable de entorno `ELEVENLABS_API_KEY` del servidor; sin ella responde 503 `INTEGRATION_UNAVAILABLE`.","operationId":"voices","responses":{"200":{"description":"Voces","content":{"application/json":{"example":[{"voice_id":"htFfPSZGJwjBv1CL0aMD","name":"Valeria","preview_url":"https://example.com/preview/valeria.mp3","labels":{"accent":"latin american","gender":"female"},"verified_languages":[{"language":"es","model_id":"eleven_flash_v2_5","accent":"latam"}]}]}}},"502":{"description":"ElevenLabs rechazó la solicitud","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_ERROR","message":"ElevenLabs rechazó la credencial"}}}},"503":{"description":"ElevenLabs no está configurado o no responde","content":{"application/json":{"example":{"status":"error","code":"INTEGRATION_UNAVAILABLE","message":"ElevenLabs no está configurado"}}}}}}},"/ai-employees/turn":{"get":{"tags":["Empleados IA"],"summary":"Preparar el turno del Empleado IA de texto","description":"Lo llama el workflow `main` 12 s después de cada mensaje del cliente. Si varios mensajes llegan seguidos, cada uno dispara su propia ejecución y **solo la del último responde**: así se agrupan sin Redis. **Solo lectura** (se puede reintentar). La memoria del Empleado IA vive en su propia base; se entrega solo el tramo de `chat_histories` necesario para recuperar la conversación durante una pausa con asesor.\n- `latest`: `message_id` (el wamid del mensaje del cliente) es el último mensaje del cliente de la oportunidad, ordenado por `created_at, id` (llegada a la base). Los tipos `reaction`, `unsupported`, `unknown`, `system`, `ephemeral` y `request_welcome` no cuentan como mensaje conversacional: no desplazan `latest`, no entran en `input` ni `advisor_context` y no cambian `first_contact`; siguen visibles en el historial. Si es `false`, `main` termina y el resto de los campos viene vacío (no se valida el Empleado IA).\n- `input`: los mensajes del cliente posteriores a la última fila `from_me = true` de la oportunidad, en orden y unidos con salto de línea. Texto de cada uno: `ai_text`, o `body`, o `caption`, o `[tipo]`. No antepone citas: la cita del mensaje actual la agrega n8n con lo que devuelve `inbound-message`.\n- `advisor_context`: si hubo al menos un envío humano desde la última respuesta del Empleado IA, devuelve hasta los últimos 30 mensajes anteriores al primer mensaje de `input`, en orden cronológico. Cada uno tiene `from` (`asesor` o `cliente`), `text` (máximo 1000 caracteres; misma prioridad que `input`) y `date` (ISO-8601). Si no hubo envío humano, o `latest` es `false`, devuelve `[]`.\n- `employee`: `name`, `prompt` y `first_greeting` del Empleado IA de `project.ai_employee_id`. Su `prompt` sale de `COALESCE(ai_employees.text_prompt, ai_employees.prompt)`: el prompt de texto si tiene, el de voz si no (requiere el SQL de `sql/empleado-ia-text-prompt/`; sin él, sigue saliendo `prompt`). Tiene que estar activo y ser de texto (`channel_type` `text` u `omni`); si no, 422 `AI_EMPLOYEE_MISSING`.\n- `first_contact`: `true` si la oportunidad no tiene ningún envío conversacional (`from_me = true`) todavía; los tipos excluidos de arriba no lo cambian.\n- `paused`: `true` si el teléfono está pausado en cualquier proyecto activo de la empresa. Con `latest = false` es `false`.\n404 si el proyecto, la oportunidad (tiene que ser de un pipeline del proyecto) o el mensaje (del cliente, de esa oportunidad) no existen o son de otra empresa.","operationId":"turn","parameters":[{"name":"project_id","in":"query","description":"Id del proyecto","required":false,"schema":{"type":"string"},"example":"fc7002bc-9b72-4923-865e-66882e255779"},{"name":"opportunity_id","in":"query","description":"Oportunidad (UUID)","required":false,"schema":{"type":"string"}},{"name":"message_id","in":"query","description":"wamid del mensaje del cliente que disparó el turno","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Turno preparado","content":{"application/json":{"examples":{"Es el último mensaje":{"description":"Es el último mensaje","value":{"latest":true,"input":"Hola\nQuiero información de la casa","employee":{"name":"Ana","prompt":"Eres Ana, asesora inmobiliaria...","first_greeting":"Hola, soy Ana"},"first_contact":true,"advisor_context":[],"paused":false}},"Conversación con asesor":{"description":"Conversación con asesor","value":{"latest":true,"input":"Gracias, quiero agendar una visita","employee":{"name":"Ana","prompt":"Eres Ana, asesora inmobiliaria...","first_greeting":"Hola, soy Ana"},"first_contact":false,"advisor_context":[{"from":"cliente","text":"¿Está disponible mañana?","date":"2026-10-21T14:00:00-04:00"},{"from":"asesor","text":"Sí, a las 10:00","date":"2026-10-21T14:02:00-04:00"}],"paused":true}},"Llegó otro mensaje después":{"description":"Llegó otro mensaje después","value":{"latest":false,"input":"","employee":null,"first_contact":null,"advisor_context":[],"paused":false}}}}}},"400":{"description":"`MISSING_FIELD` o `INVALID_VALUE` en `project_id`, `opportunity_id` o `message_id`","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"message_id es obligatorio"}}}},"404":{"description":"Proyecto, oportunidad o mensaje inexistente o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Mensaje no encontrado"}}}},"422":{"description":"El proyecto no tiene un Empleado IA de texto activo","content":{"application/json":{"example":{"status":"error","code":"AI_EMPLOYEE_MISSING","message":"El proyecto no tiene un Empleado IA de texto activo"}}}}}}},"/ai-employees/context":{"get":{"tags":["Empleados IA"],"summary":"Leer el contexto público de un proyecto","description":"Devuelve los stages y la etiqueta de WhatsApp configurados en `ai_project_context`, más `business_website`,\n`business_whatsapp` y `employee_name`. Cada stage debe pertenecer a un pipeline activo de la empresa; la\netiqueta debe ser de la empresa. Si no existe una fila `employee_name`, usa el nombre del Empleado IA\nenlazado al proyecto. No devuelve tokens ni otros secretos.\n","operationId":"context","parameters":[{"name":"project_id","in":"query","description":"Id del proyecto","required":true,"schema":{"type":"string"},"example":"project-1"}],"responses":{"200":{"description":"Contexto completo del proyecto","content":{"application/json":{"example":{"project_id":"project-1","pipeline_stage_id_nueva_oportunidad_human":"4dcb9b96-c6c8-4335-a313-7c08f24ca850","pipeline_stage_id_no_interesado_ia":"4dcb9b96-c6c8-4335-a313-7c08f24ca851","pipeline_stage_id_conversacion_ia":"4dcb9b96-c6c8-4335-a313-7c08f24ca852","pipeline_stage_id_espera":"4dcb9b96-c6c8-4335-a313-7c08f24ca853","pipeline_stage_id_llamada_pendiente":"4dcb9b96-c6c8-4335-a313-7c08f24ca854","pipeline_stage_id_no_respondio_ia":"4dcb9b96-c6c8-4335-a313-7c08f24ca855","pipeline_stage_id_error_ia":"4dcb9b96-c6c8-4335-a313-7c08f24ca856","pipeline_stage_id_llamada_exitosa":"4dcb9b96-c6c8-4335-a313-7c08f24ca857","pipeline_stage_id_llamar_mas_tarde_ia":"4dcb9b96-c6c8-4335-a313-7c08f24ca858","tag_id_whatsapp":"a49df91c-6b47-4f91-ae29-90a2a3afcc01","business_website":"https://empresa.example","business_whatsapp":"59170000000","employee_name":"Ana"}}}},"400":{"description":"`MISSING_FIELD` o `INVALID_VALUE` en `project_id`","content":{"application/json":{"example":{"status":"error","code":"MISSING_FIELD","message":"project_id es obligatorio"}}}},"404":{"description":"Proyecto inexistente, inactivo o de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Proyecto no encontrado"}}}},"422":{"description":"Faltan claves públicas o algún stage/tag no es válido para la empresa","content":{"application/json":{"example":{"status":"error","code":"CONFIG_NOT_FOUND","message":"Faltan claves requeridas","missing":["business_website"]}}}}}}},"/tickets/{id}/tag/{tagId}":{"delete":{"tags":["Tickets"],"summary":"Quitar tag de un ticket","description":"Quita una etiqueta de un ticket de la empresa autenticada con borrado lógico (state = 0, updated_at = now()); la fila no se elimina y puede reactivarse con POST. Ticket inexistente o de otra empresa: 404; asociación inexistente o ya quitada: 404.","operationId":"removeTag","parameters":[{"name":"id","in":"path","description":"UUID del ticket","required":true,"schema":{"type":"string"},"example":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee"},{"name":"tagId","in":"path","description":"UUID del tag","required":true,"schema":{"type":"string"},"example":"c3d4e5f6-a7b8-9012-cdef-123456789012"}],"responses":{"200":{"description":"Tag quitado","content":{"application/json":{"example":{"status":"ok","ticket_id":"3af4b6cc-ad7a-4425-af4b-5e3bcf237aee","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Ticket o tag no encontrado (inexistente, ya quitado o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tag no encontrado"}}}}}}},"/roles/{id}/permissions/{permissionId}":{"delete":{"tags":["Roles"],"summary":"Quitar permiso del rol","description":"Realiza un soft delete de la asignación (state = 0). Solo sobre roles de la empresa; 404 si el rol no existe o el permiso no estaba asignado.","operationId":"removePermission","parameters":[{"name":"id","in":"path","description":"UUID del rol","required":true,"schema":{"type":"string"},"example":"550e8400-e29b-41d4-a716-446655440000"},{"name":"permissionId","in":"path","description":"UUID del permiso","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":{"200":{"description":"Permiso removido","content":{"application/json":{"example":{"status":"ok","rol_id":"550e8400-e29b-41d4-a716-446655440000","permission_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Rol inexistente o de otra empresa, o permiso no asignado al rol","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/opportunities/{opportunityId}/tag/{tagId}":{"delete":{"tags":["Oportunidades"],"summary":"Quitar tag de una oportunidad","description":"Quita un tag de una oportunidad de la empresa autenticada con borrado lógico (state = 0, updated_at = now()); la fila no se elimina y puede reactivarse con POST. Oportunidad inexistente, eliminada o de otra empresa: 404; asociación inexistente o ya quitada: 404.","operationId":"removeTag_1","parameters":[{"name":"opportunityId","in":"path","description":"UUID de la oportunidad","required":true,"schema":{"type":"string"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},{"name":"tagId","in":"path","description":"UUID del tag","required":true,"schema":{"type":"string"},"example":"c3d4e5f6-a7b8-9012-cdef-123456789012"}],"responses":{"200":{"description":"Tag quitado","content":{"application/json":{"example":{"status":"ok","opportunity_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","tag_id":"c3d4e5f6-a7b8-9012-cdef-123456789012"}}}},"400":{"description":"ID inválido","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"Oportunidad o tag no encontrado (inexistente, ya quitado o de otra empresa)","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Tag no encontrado"}}}}}}},"/blacklist/{id}":{"delete":{"tags":["Lista negra"],"summary":"Retirar una fila de la lista negra (borrado lógico)","description":"Da de baja la fila `id` de la lista negra: `state = 0` y `on_off = false`, así que el teléfono deja de aparecer pausado aunque un flujo lea la tabla sin filtrar por `state`. **No borra datos**: la fila se conserva y el trigger deja el cambio en `black_list_history`. El `id` es el que devuelve `PUT /blacklist`. Si solo quieres que el agente vuelva a responder y conservar la fila activa, usa `PUT /blacklist` con `paused: false`. Una fila inexistente, ya dada de baja o de otra empresa responde 404 con el mismo mensaje. Si después se vuelve a pausar el teléfono, `PUT /blacklist` crea una fila nueva.","operationId":"delete_17","parameters":[{"name":"id","in":"path","description":"Id de la fila de `black_list` (el `id` que devuelve `PUT /blacklist`)","required":true,"schema":{"type":"string"},"example":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11"}],"responses":{"200":{"description":"Fila dada de baja","content":{"application/json":{"example":{"status":"ok","id":"5c1f0a3e-9d1b-4f6e-8a55-0d6f5b0c7a11","phone":"59171234567","project_id":"2e3aa19d-fa4b-4d15-9467-383df3d79920","state":0,"paused":false,"on_off":false}}}},"400":{"description":"`id` inválido (INVALID_ID)","content":{"application/json":{"example":{"status":"error","code":"INVALID_ID","message":"ID inválido"}}}},"404":{"description":"La fila no existe, ya está dada de baja o es de otra empresa","content":{"application/json":{"example":{"status":"error","code":"NOT_FOUND","message":"Registro de lista negra no encontrado"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"API key de la empresa (Configuración > API Keys en el SaaS). Se envía como `Authorization: Bearer <api_key>`.","name":"bearerAuth","scheme":"bearer","bearerFormat":"API key"}}}}