Está tardando más de lo normal. Tu conexión parece débil.
KelluDesarrolladores
Referencia interactivaOpenAPIManual UTCP

Guías

  • Inicio
  • Inicio rápido
  • Autenticación
  • Permisos
  • Paginación y errores
  • Recursos y operaciones
  • Webhooks
  • WhatsApp por webhook
  • Agentes de IA, OpenAPI y UTCP
  • Conector de IA (Claude y ChatGPT)
  • Guía: usar Kellu desde Claude y ChatGPT
  • Kellu AI connector: user guide (English)

Conector de IA (Claude y ChatGPT)

El conector de IA permite que un asistente como Claude o ChatGPT trabaje con tu negocio en Kellu: leer datos y, si lo apruebas al conectar, crear y editar clientes, trabajos, cotizaciones, notas de venta, recordatorios y tickets, y enviar cotizaciones, notas de venta y confirmaciones de visita a tus clientes.

  • Se conecta con tu cuenta, no con una clave. El asistente entra por OAuth: inicias sesión en Kellu, revisas los permisos que pide y los apruebas. Actúa como tú, con los mismos permisos de tu perfil, las mismas reglas y los mismos efectos que la web.
  • Lo habilita Kellu por negocio y solo lo pueden conectar usuarios de gestión (los técnicos no).
  • Las claves de API siguen siendo de solo lectura. Crear, editar y enviar solo es posible con el conector; las operaciones de escritura no son parte de la API pública (/api/v1, OpenAPI ni UTCP).

¿Buscas el paso a paso para usarlo? Ver la guía de usuario (English).

Conectarlo

  1. En Kellu, entra a Mi perfil → Mis conexiones y copia la URL del conector:

    https://api.kellu.co/mcp
    
  2. En Claude o ChatGPT, agrega un conector personalizado con esa URL.

  3. Inicia sesión en Kellu y revisa la pantalla de permisos. Lo que el asistente podrá ver se aprueba siempre; hacer cambios y enviar mensajes a tus clientes tienen cada uno su interruptor, apagado por defecto. Puedes conectarlo solo para leer, para leer y hacer cambios, y/o para enviar. Al aprobar, el asistente queda conectado con lo que elegiste.

Puedes desconectarlo cuando quieras desde Mi perfil. El dueño y los Administradores ven y pueden desconectar las conexiones de todo el equipo en Configuración → API y MCP → MCP.

Permisos

Además de los permisos de lectura de la API (ver Permisos), el conector puede pedir permisos de escritura y envío. El asistente solo ve las herramientas que cubren a la vez los permisos que aprobaste y los de tu perfil en Kellu: si tu perfil no puede editar clientes, el asistente tampoco, aunque lo hayas aprobado.

Qué puede hacer

ÁreaHerramientasPermiso
Clientescreate_client, update_client, add_client_contact, update_client_contact, add_client_location, update_client_locationclients:write
Trabajos y visitascreate_work_order, set_work_order_status, revert_work_order_status, mark_work_order_no_schedule_required, confirm_visit, add_work_order_notework_orders:write
Cotizaciones y notas de ventacreate_quote (quotes:write), create_sale_note (sale_notes:write), set_work_order_line_items (cualquiera de work_orders:write, quotes:write, sale_notes:write)según la herramienta
PDFget_document_preview_pdf (vista previa de un borrador), get_document_pdf (versión emitida)quotes:read o sale_notes:read
Recordatorioslist_client_reminders, list_asset_remindersreminders:read
create_client_reminder, update_client_reminder, create_asset_reminder, update_asset_reminderreminders:write
Ticketslist_tickets, get_tickettickets:read
create_ticket, set_ticket_status, add_ticket_message, assign_ticket, set_ticket_due_date, snooze_tickettickets:write
Envíos al clienteprepare_send_quote / send_quote, prepare_send_sale_note / send_sale_note, prepare_send_booking_confirmation / send_booking_confirmationmessages:send (ver abajo)
Estado de envíosget_message_deliveries: qué se envió, canal y estado de cada mensaje (enviado, entregado, leído, fallido); no incluye a quién se envió. El motivo de un fallo solo aparece si también puede ver los datos de contacto de los clientes (clients:read y tu perfil)work_orders:read

Además tiene las herramientas de lectura de la API (clientes, trabajos, visitas, informes, cotizaciones, notas de venta, equipos, catálogo y equipo). Los tickets los lee con sus propias herramientas (list_tickets, get_ticket), que ven solo los tickets que tu usuario ve en Kellu; las operaciones GET /tickets de la API son solo para claves.

Sobre los tickets:

  • list_tickets filtra por responsable (assignee: me, none o el id de list_team_members), texto (q: número, descripción o cliente), vencidos (overdue) y pospuestos (snoozed; por defecto los deja fuera). Cada ticket trae assignee, dueAt, isOverdue y snoozedUntil, y en el detalle cada mensaje dice si es una nota interna (internal).
  • add_ticket_message con internal: true agrega una nota interna: solo la ve tu equipo, el cliente nunca la recibe. Sin internal, aplica la regla del negocio (respuesta al cliente, salvo que la asignación de tickets esté activa y tu perfil no pueda responder al cliente).
  • assign_ticket cambia el responsable (solo con la asignación de tickets activa; avisa al nuevo responsable en la app), set_ticket_due_date fija o quita la fecha límite y snooze_ticket pospone el ticket hasta una fecha futura o quita la posposición. Ninguna de las tres avisa al cliente.

quotes:write y sale_notes:write permiten más que crear borradores: crear el trabajo que necesita el documento si no existe y reemplazar los ítems de cualquier trabajo. Y al crear una cotización, aplicar sus condiciones a las cotizaciones futuras cambia (o borra, si van vacías) las condiciones por defecto del negocio.

Cada herramienta describe al asistente sus efectos más allá del registro mismo, para que te los confirme: por ejemplo, que una cotización nueva reserva el siguiente número, o que cerrar un ticket avisa al cliente por correo. No puede borrar datos, registrar pagos, enviar informes de trabajo ni subir archivos.

Envíos: preparar y confirmar

Enviar una cotización, una nota de venta o una confirmación de visita son dos pasos:

  1. prepare_send_* devuelve exactamente lo que se enviará (canales, destinatarios, asunto, mensaje, adjuntos, si el documento queda emitido y el enlace al PDF) y un token de confirmación. El asistente debe mostrártelo todo y esperar un «sí» explícito.
  2. send_* envía, con el token y los mismos argumentos. El token vence a los 10 minutos, sirve una sola vez y solo si lo que se va a enviar no cambió desde la vista previa; si no, hay que preparar de nuevo.

El token prueba que hubo vista previa, no que aprobaste: Kellu no pide una confirmación aparte. La aprobación es la del asistente (según cómo lo tengas configurado, Claude y ChatGPT te piden aprobar las acciones que hacen cambios), así que revisa bien lo que se enviará.

Reglas de los envíos:

  • Destinatarios de correo: solo el correo del cliente, los de sus contactos, las direcciones «copiar siempre a» del negocio o el tuyo. Cualquier otra dirección se rechaza.
  • WhatsApp: siempre la plantilla de Kellu al teléfono del destinatario; el asistente no escribe el mensaje ni elige otro número.
  • Enviar una cotización o una nota de venta necesita messages:send, el permiso de escritura del documento (quotes:write o sale_notes:write) y clients:read. La confirmación de visita necesita messages:send y clients:read.
  • Responder un ticket al cliente (add_ticket_message sin nota interna) o cerrarlo (set_ticket_status a resuelto o descartado) avisa al cliente por correo sin paso de preparar: el asistente debe mostrarte el texto y a quién le llega antes de hacerlo. Una nota interna no sale del equipo.

Actividad y webhooks

  • Todo lo que hace el asistente queda en la actividad del negocio a tu nombre, marcado con la app: «Ana Pérez (vía Claude)». En los reportes personalizados de actividad puedes filtrar por ese nombre.
  • Los webhooks de esos cambios llevan "source": { "type": "connector", "clientId": "…" }.

Reintentos y límites

  • Reintentos sin duplicados: si el asistente repite exactamente la misma creación (cliente, trabajo, cotización, nota de venta, recordatorio o ticket) dentro de 2 minutos, recibe el resultado de la primera vez en vez de crear otro. Lo mismo con la misma respuesta en el mismo ticket: no sale un segundo correo.
  • Límites por usuario: 30 llamadas que escriben por minuto y 10 envíos al cliente cada 10 minutos, sumando todas tus apps conectadas (Claude y ChatGPT comparten el mismo límite). Cuenta toda llamada que escribe, también generar un PDF o una vista previa y los intentos que fallan. Al pasarlos, la herramienta responde un error y el asistente debe esperar.