# La actividad de un proveedor, sin salir del copiloto La actividad de un proveedor con la herramienta suppliers: registrar conversaciones, adjuntar documentos, programar reuniones y leer el historial. Con la herramienta `suppliers` del servidor de Finanzas, un asistente lleva la pestaña de actividad de un proveedor: anota lo que se habla con él, le adjunta el documento del que trata, programa la siguiente reunión y lee el historial, con sus notas, llamadas, reuniones, correos y los gastos que se le registraron. Necesitas un token del servidor de Finanzas que lleve los scopes de actividad de proveedores. **La actividad de un proveedor en tres pasos** 1. **Registrar la conversación** (log_interaction): Nota, llamada, visita o correo que salió por otra vía, vinculada al gasto del que trata. 2. **Adjuntar el documento** (attach_to_interaction · Opcional): Por una dirección https, hasta 10 MB, o pegado en la llamada, hasta 2 MB. 3. **Programar la reunión** (schedule_meeting · Opcional): Con asistentes, invitados por correo y recordatorios. Sin Meet o Calendario, sale sin sala o sin evento. La herramienta no envía correos al proveedor: `send_email`, `reply_email` y `get_email_recipients` se retiraron el 7 de septiembre de 2026, sin sustituto. Para dejar constancia de un correo que salió por otra vía, usa `log_interaction` con `type: 'EMAIL'`. ## Antes de empezar La actividad del proveedor tiene dos scopes propios: | Scope | Qué concede | | - | - | | `finance:suppliers:interactions:read` | Leer el listado, el detalle, la conversación, el historial de cambios y los datos de los adjuntos. | | `finance:suppliers:interactions:manage` | Registrar, editar y borrar; adjuntar y quitar archivos; y programar, cerrar y cancelar reuniones. | > **Atención: Solo se conceden en el servidor de Finanzas** > > Ninguno de los dos está dentro de `finance:read` ni de `finance:write`: solo los concede `finance:full` o pedirlos por su nombre, porque la actividad incluye el contenido de correos. Y hace falta un token del servidor de Finanzas (`/api/mcp/finance`). Además del scope, necesitas el permiso `SUPPLIERS_INTERACTIONS_VIEW` o `SUPPLIERS_INTERACTIONS_MANAGE` y que tu organización tenga contratado Finanzas. Con alcance `OWN`, cada persona solo ve y toca la actividad que registró ella. Los SDK todavía no llegan a estas operaciones por el servidor de Finanzas. Invoca la herramienta por JSON-RPC en `https://os.utilia.ai/api/mcp/finance`, como en los ejemplos de esta página. ## Paso 1: registrar lo que se habla `log_interaction` anota una nota, una llamada, una visita o un correo que salió por otra vía. El proveedor sale del parámetro `id`, nunca del cuerpo de la interacción. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "suppliers", "arguments": { "operation": "log_interaction", "id": "", "interaction": { "type": "CALL", "direction": "OUTBOUND", "subject": "Confirmación del plazo de entrega", "description": "Dicen que sale el jueves y llega el lunes.", "duration": 12, "expenseIds": [""] } } } } ``` `type` admite `EMAIL`, `CALL`, `MEETING`, `NOTE`, `SMS`, `WHATSAPP` y `VISIT`. La respuesta trae `url`, el enlace a la ficha, para ofrecérselo a la persona. `expenseIds` vincula la conversación con los gastos o facturas del proveedor de los que trata, y es lo que después permite preguntar «¿qué se habló de esta factura?» con el filtro `expenseId`. Los identificadores se comprueban contra tu organización y contra el proveedor de la ficha: uno de otro proveedor se rechaza con un error `400` que lo dice expresamente. ### Hasta cincuenta de golpe `log_interactions_many` registra hasta 50 interacciones del mismo proveedor en una llamada; sirve para volcar el historial de un sistema antiguo. El lote va en `interactions`, no en `items`, que en esta herramienta es el lote de fichas de proveedor. Equivocar el nombre no da error: el lote llega vacío. Un elemento inválido no detiene al resto: sale en `failed` con su posición y su motivo, y los que entran salen en `succeeded`. Con `clientOperationId`, cada elemento queda reservado 24 horas: si reenvías el lote con las mismas claves, lo que ya entró no se vuelve a escribir y recibes el resultado original. Si una reserva queda en duda, la respuesta pide revisar la actividad antes de continuar (`MCP_IDEMPOTENCY_REVIEW_REQUIRED`); conserva la clave, porque cambiarla puede duplicar la anotación. ## Paso 2: adjuntar el documento del que se habla `attach_to_interaction` sube un archivo a una interacción por una de dos vías: una dirección `https` que descarga el servidor, hasta 10 MB, o el contenido pegado en la llamada, hasta 2 MB. Para archivos grandes, usa la dirección: el contenido pegado pasa por el modelo, y cuanto más grande es, más fácil es que llegue incompleto. El servidor rechaza los archivos que llegan rotos. ```json { "name": "suppliers", "arguments": { "operation": "attach_to_interaction", "id": "", "interactionId": "", "attachment": { "fileName": "factura-0231.pdf", "url": "https://portal-del-proveedor.example.com/facturas/0231.pdf" } } } ``` Se admiten PDF, Word, Excel, PowerPoint, texto, CSV, JPEG, PNG, GIF, WEBP, SVG, ZIP, RAR y 7z, la misma lista que acepta el gestor de archivos. `list_interaction_attachments` devuelve los datos de cada adjunto (nombre, tipo, tamaño y la dirección de descarga dentro del producto), sin el contenido. Para leer el contenido de un archivo está el gestor de archivos, con su propio permiso. `remove_interaction_attachment` quita un adjunto y exige `confirm: true`. El adjunto deja de estar en la interacción en el acto. Si el archivo no se usa en ningún otro sitio, pasa 30 días en «Eliminados recientemente» del gestor de archivos y después se borra para siempre; mientras tanto se puede restaurar con `fm_files_manage` (`restore`), pero vuelve al gestor, no a la interacción. Si tu organización no tiene la capacidad avanzada del gestor de archivos, el adjunto se guarda igual en la interacción; lo único que no ocurre es que aparezca en la carpeta del proveedor. ## Paso 3: programar una reunión `schedule_meeting` crea la reunión con sus asistentes internos, sus invitados externos por correo y sus recordatorios: ```json { "name": "suppliers", "arguments": { "operation": "schedule_meeting", "id": "", "meeting": { "subject": "Revisión de plazos del cuarto trimestre", "startTime": "2026-10-20T10:00:00.000Z", "endTime": "2026-10-20T11:00:00.000Z", "attendeeIds": ["", ""], "participants": ["comercial@proveedor.example.com"], "reminders": [{ "type": "PRESET", "offsetMinutes": 30, "notifyExternals": true }], "createMeetRoom": true, "expenseIds": [""] } } } ``` `createMeetRoom` necesita el aplicativo Meet y `createCalendarEvent`, el de Calendario. Si falta alguno, la reunión se programa igual, sin sala o sin evento, y la llamada devuelve éxito. Si tu integración necesita saber si hubo sala, mira `meetingUrl` en la interacción devuelta. `complete_meeting` cierra la reunión con su resultado y sus notas; `cancel_meeting` la cancela junto con su evento de calendario y su sala, y devuelve el resumen de lo deshecho. En una reunión cerrada o cancelada ya no se pueden cambiar la hora, el tipo ni los asistentes, aunque sí el resultado y las notas. ## Leer la conversación y su historial `get_interaction_thread` devuelve el hilo de correo de una interacción, acotado a este proveedor. Un mismo hilo puede tocar a la vez a un cliente y a un proveedor; desde aquí solo se ven los mensajes del proveedor, y la respuesta lo indica en `scopedToSupplier`. Si vas a enseñar el hilo a una persona, díselo, para que no tome media conversación por la conversación entera. La parte del cliente se lee desde el CRM, con sus permisos. `list_interaction_activities` devuelve el historial de cambios de la interacción: quién la tocó, cuándo y qué hizo. Es la respuesta a «¿quién movió esta reunión?». ## Lo que se anota solo Parte de la actividad no la escribe una persona: la ficha recoge también hitos automáticos. El campo `source` dice quién o qué escribió cada fila: | `source` | Qué anota | | - | - | | `MANUAL` | Lo que registra el equipo. | | `EMAIL_SYNC` | Correo traído del buzón sincronizado y emparejado con el proveedor. | | `FINANCE` | Gastos y facturas del proveedor y sus pagos. | | `MEETING` y `CALENDAR` | Videollamadas y sincronización del calendario. | | `INTEGRATION` | Aplicaciones externas que escriben por la API pública. | `list_interactions` admite los filtros `direction`, `status`, `source`, `excludeSources`, `search`, `expenseId` y `supplierContactId`. Para leer solo el trabajo del equipo, `source: 'MANUAL'`; para quitar los hitos de gastos y facturas, `excludeSources: ['FINANCE']`. Si envías los dos, se aplican ambos. `search` busca en el asunto, la descripción y las notas sin distinguir mayúsculas, pero sí tildes: «revision» no encuentra «revisión». ## Errores frecuentes | Error | Cuándo | Qué hacer | | - | - | - | | `403` con el error `-32600` «El aplicativo Finanzas no está habilitado para tu organización» | Tu organización no tiene contratado Finanzas. | Es una puerta del plan: ningún permiso la abre. | | Falta de scope | El token no es del servidor de Finanzas o no lleva el scope de actividad. | Autoriza el servidor de Finanzas pidiendo `finance:suppliers:interactions:read` o `:manage`. | | Proveedor no encontrado | El identificador no es de tu organización, o es una interacción que también toca a un cliente. | Las interacciones compartidas con un cliente se gestionan desde el CRM, con `INTERACTIONS_EDIT`. La respuesta no distingue los dos casos a propósito. | | «no es de este proveedor» | Un `expenseIds` de otro proveedor. | Comprueba de quién es el documento antes de vincularlo. | ## Siguiente paso La reunión programada aparece en el [calendario](https://os.utilia.ai/docs/guides/calendar/overview) de sus asistentes y, si pediste sala, en Meet. Lo que se habló queda vinculado a los gastos y facturas del proveedor, así que en la ficha del documento verás la conversación que lo acompaña. Los cambios de contrato de la herramienta `suppliers` están en la [referencia de herramientas MCP](https://os.utilia.ai/docs/developers/mcp/reference#cambios-de-contrato-de-septiembre-de-2026).