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ón | operationId | Permiso |
|---|
GET /me | get_api_key_info | ninguno |
Devuelve el negocio y la clave de la petición (nombre, prefijo, permisos, vencimiento).
Clientes
| Operación | operationId | Permiso |
|---|
GET /clients | list_clients | clients:read |
GET /clients/{clientId} | get_client | clients: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ón | operationId | Permiso |
|---|
GET /work-orders | list_work_orders | work_orders:read |
GET /work-orders/{workOrderId} | get_work_order | work_orders:read |
GET /visits | list_visits | work_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ón | operationId | Permiso |
|---|
GET /work-orders/{workOrderId}/job-forms | list_work_order_job_forms | job_forms:read |
GET /job-form-templates | list_job_form_templates | job_forms:read |
GET /job-form-templates/{templateId}/submissions | list_job_form_submissions | job_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ón | operationId | Permiso |
|---|
GET /quotes | list_quotes | quotes:read |
GET /quotes/{quoteId} | get_quote | quotes:read |
GET /sale-notes | list_sale_notes | sale_notes:read |
GET /sale-notes/{saleNoteId} | get_sale_note | sale_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):
| Valor | Significado |
|---|
AWAITING_RESPONSE | Emitida, esperando respuesta del cliente. |
APPROVED | Aprobada. |
ARCHIVED | Archivada. Solo se lista con status=ARCHIVED; por id siempre se puede leer. |
DRAFT | En revisión después de haber sido emitida. Los montos son los de la última versión emitida. |
Nota de venta (status):
| Valor | Significado |
|---|
AWAITING_PAYMENT | Emitida, esperando pago. |
OVERDUE | Esperando pago, con saldo pendiente y la fecha de vencimiento pasada (se calcula al leer). |
PAID | Pagada. |
CLOSED_UNPAID | Cerrada sin registrar pago. Nunca cuenta como PAID. |
BAD_DEBT | Incobrable. |
NOT_REQUIRED | El trabajo tiene la nota de venta marcada como no requerida. |
DRAFT | En 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ón | operationId | Permiso |
|---|
GET /assets | list_assets | assets:read |
GET /assets/{assetId} | get_asset | assets:read |
GET /assets/{assetId}/history | get_asset_history | assets: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ón | operationId | Permiso |
|---|
GET /catalog-items | list_catalog_items | catalog:read |
GET /catalog-items/{itemId} | get_catalog_item | catalog: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ón | operationId | Permiso |
|---|
GET /team-members | list_team_members | team: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ón | operationId | Permiso |
|---|
GET /tickets | list_business_tickets | tickets:read |
GET /tickets/{ticketId} | get_business_ticket | tickets: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.