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)

Recursos y operaciones

La API tiene 21 operaciones, todas GET. Aquí está el resumen por recurso; los campos completos de cada respuesta están en la referencia interactiva. El operationId es el nombre de la operación en el documento OpenAPI y en el manual UTCP.

Las listas paginadas aceptan cursor y limit (Paginación y errores). Las que indican updatedSince aceptan además ese filtro para sincronizar cambios, junto con sortBy=updatedAt. Un parámetro desconocido responde 400. Los filtros search aceptan hasta 200 caracteres.

Clave

OperaciónoperationIdPermiso
GET /meget_api_key_infoninguno

Devuelve el negocio y la clave de la petición (nombre, prefijo, permisos, vencimiento).

Clientes

OperaciónoperationIdPermiso
GET /clientslist_clientsclients:read
GET /clients/{clientId}get_clientclients:read
  • Lista: filtros search (inicio de cualquier palabra del nombre, contacto o empresa, y dígitos del teléfono o RUT), status (ACTIVE, ARCHIVED, FOLLOW_UP), updatedSince, sortBy (name, createdAt, updatedAt) y order (asc, desc). Por defecto, los más nuevos primero.
  • Detalle: el cliente con sus direcciones activas (la principal primero) y sus contactos (el principal primero).

Trabajos y visitas

OperaciónoperationIdPermiso
GET /work-orderslist_work_orderswork_orders:read
GET /work-orders/{workOrderId}get_work_orderwork_orders:read
GET /visitslist_visitswork_orders:read
  • GET /work-orders lista todos los trabajos, en cualquier estado. Filtros: search (título, dirección, nombre del cliente o número), clientId, updatedSince, dateFrom y dateTo (día agendado; con un filtro de fecha se excluyen los trabajos sin agendar), sortBy (createdAt, updatedAt, scheduledAt) y order.
  • jobStatus se calcula al leer, por eso no se puede filtrar en la API: filtra de tu lado. Valores: UNSCHEDULED, UNASSIGNED, SCHEDULED, ON_MY_WAY, IN_PROGRESS, COMPLETED, NOT_REQUIRED.
  • El detalle trae visitas, ítems (sin precios), equipos vinculados e informes adjuntos. Cada visita tiene su status: SCHEDULED, ON_MY_WAY, IN_PROGRESS, COMPLETED.
  • El trabajo trae también quoteStatus y saleNoteStatus, el estado de su cotización y de su nota de venta.
  • GET /visits exige from y to (YYYY-MM-DD, máximo 31 días, ambos incluidos) y lista las visitas con fecha de ese rango, ordenadas por scheduledAt. No acepta updatedSince. No incluye tareas, visitas sin fecha ni trabajos marcados como no requeridos. Su status es el de planificación: UNASSIGNED (agendada sin técnico), SCHEDULED, ON_MY_WAY, IN_PROGRESS, COMPLETED.
  • startTime y endTime son horas locales HH:mm en la zona timeZone del negocio; null = sin hora.

Informes

OperaciónoperationIdPermiso
GET /work-orders/{workOrderId}/job-formslist_work_order_job_formsjob_forms:read
GET /job-form-templateslist_job_form_templatesjob_forms:read
GET /job-form-templates/{templateId}/submissionslist_job_form_submissionsjob_forms:read
  • Informes de un trabajo: todos, enviados o no, del más antiguo al más nuevo. Sin paginación.
  • Plantillas: todas, incluidas las archivadas (archivedAt), con sus campos respondibles. Sin paginación.
  • Respuestas de una plantilla: exige from y to (día de envío, máximo 31 días). columns es la unión de los campos vistos en el período y rows[].answers mapea id de columna → respuesta como texto. No incluye campos de imagen ni informes de seguimiento. Si el rango tiene más de 5 000 envíos, solo se consideran los 5 000 más recientes y truncated viene en true: acorta el rango. Se pagina con cursor y limit.

Cotizaciones y notas de venta

OperaciónoperationIdPermiso
GET /quoteslist_quotesquotes:read
GET /quotes/{quoteId}get_quotequotes:read
GET /sale-noteslist_sale_notessale_notes:read
GET /sale-notes/{saleNoteId}get_sale_notesale_notes:read

Solo documentos emitidos

La API solo muestra cotizaciones y notas de venta emitidas: enviadas desde Kellu o marcadas a mano por el negocio como enviadas (o, en la nota de venta, como esperando pago). Un documento que nunca se emitió no aparece en las listas y por id responde 404.

Los montos y las líneas son los de la versión emitida: la aprobada si la hay; si no, la última emitida. Solo se incluyen las líneas cobrables. sentAt es cuándo se envió esa versión desde Kellu, o null si se marcó a mano.

Estados

Cotización (status):

ValorSignificado
AWAITING_RESPONSEEmitida, esperando respuesta del cliente.
APPROVEDAprobada.
ARCHIVEDArchivada. Solo se lista con status=ARCHIVED; por id siempre se puede leer.
DRAFTEn revisión después de haber sido emitida. Los montos son los de la última versión emitida.

Nota de venta (status):

ValorSignificado
AWAITING_PAYMENTEmitida, esperando pago.
OVERDUEEsperando pago, con saldo pendiente y la fecha de vencimiento pasada (se calcula al leer).
PAIDPagada.
CLOSED_UNPAIDCerrada sin registrar pago. Nunca cuenta como PAID.
BAD_DEBTIncobrable.
NOT_REQUIREDEl trabajo tiene la nota de venta marcada como no requerida.
DRAFTEn revisión después de haber sido emitida. Los montos son los de la última versión emitida.

Filtros de las listas: status, clientId, workOrderId, dateFrom y dateTo (día de creación), updatedSince, sortBy (createdAt, updatedAt) y order. Sin status, la lista de cotizaciones excluye las archivadas.

Monedas

  • currency es CLP o UF y aplica a todos los montos del documento: total, subtotal, discount, tax, chargedExpensesTotal y el price de cada línea.
  • ufValue es el valor en pesos de 1 UF congelado al emitir el documento (null en CLP).
  • amountPaidClp (suma de pagos) y balanceClp (saldo pendiente) están siempre en CLP. Un total en UF se convierte con ufValue.
  • pricesIncludeIva: true si los precios de las líneas incluyen IVA.

Equipos

OperaciónoperationIdPermiso
GET /assetslist_assetsassets:read
GET /assets/{assetId}get_assetassets:read
GET /assets/{assetId}/historyget_asset_historyassets:read
  • Lista: filtros clientId, status (ACTIVE, RETIRED), healthStatus (OPERATIONAL, NEEDS_ATTENTION, OUT_OF_SERVICE, PENDING_REVIEW), search (nombre, número de serie y especificaciones), updatedSince, sortBy (createdAt, updatedAt) y order. Por defecto, los más nuevos primero.
  • Detalle: dirección, producto del catálogo, especificaciones y resumen de mantención (trabajos abiertos, próxima visita, último servicio).
  • Historial: los trabajos vinculados al equipo, del más nuevo al más antiguo, cada uno con sus informes enviados. Solo acepta cursor y limit.

Catálogo

OperaciónoperationIdPermiso
GET /catalog-itemslist_catalog_itemscatalog:read
GET /catalog-items/{itemId}get_catalog_itemcatalog:read
  • Todos los ítems del catálogo (servicios y productos, cobrables e internos: ver billable), del más antiguo al más nuevo. Filtros: search (nombre, descripción, SKU y etiquetas), itemType (SERVICE, PRODUCT), isBundle (true, false), updatedSince, sortBy (createdAt, updatedAt) y order (por defecto createdAt ascendente).
  • Los precios son los precios base de venta; los precios por cliente no se exponen.
  • El detalle de un paquete lista sus componentes (catalogItemId, nombre, cantidad, unidad).

Equipo

OperaciónoperationIdPermiso
GET /team-memberslist_team_membersteam:read

Los miembros activos del negocio y su dueño (isOwner), con su rol. El dueño no tiene id de miembro: su entrada tiene id: "owner" (salvo que además sea miembro). Sin paginación.

Tickets

OperaciónoperationIdPermiso
GET /ticketslist_business_ticketstickets:read
GET /tickets/{ticketId}get_business_tickettickets:read

Solo si el negocio tiene los tickets activados (si no, 404). Una clave es una credencial del negocio: ve todos los tickets, también los pospuestos, y las notas internas del equipo.

  • Lista: filtros status (OPEN, IN_REVIEW, CONVERTED_TO_WORK_ORDER, RESOLVED, DISMISSED), severity (LOW, MEDIUM, HIGH), clientId, assetId, updatedSince, sortBy (createdAt, updatedAt) y order. Por defecto, los más nuevos primero. Sin los mensajes.
  • Cada ticket trae number (el «#12» que ven el negocio y el cliente; puede ser null), status, severity, description, origin (STAFF = lo creó el negocio; PORTAL = lo reportó el cliente en el portal), client y asset ({id, name} o null), originWorkOrderId (trabajo desde el que se reportó), workOrderId (trabajo en que se convirtió), createdAt, updatedAt y resolvedAt.
  • assignee ({id, name}): el responsable. Su id es el de GET /team-members (owner para el dueño; null si no se puede asociar a un miembro). assignee es null si no tiene responsable o si el negocio tiene apagada la asignación de tickets.
  • dueAt: fecha límite; isOverdue es true si pasó y el ticket sigue OPEN o IN_REVIEW. snoozedUntil: pospuesto hasta ese instante (no es un estado).
  • Detalle: el ticket con sus messages, del más antiguo al más nuevo, cada uno con text, authorType (STAFF o PORTAL), authorName, createdAt e internal. Un mensaje con internal: true es una nota interna del equipo: el cliente nunca la ve ni la recibe por correo. No incluye fotos, correos ni ids de usuario.