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)

Paginación y errores

Forma de las respuestas

Una respuesta exitosa trae el recurso en data. Las listas paginadas agregan pagination:

{
  "data": [ { "id": "cm…", "name": "Comercial Los Andes" } ],
  "pagination": { "nextCursor": "eyJ2IjoxLC…", "hasMore": true }
}

Las listas de trabajos y de visitas agregan además timeZone (zona horaria IANA del negocio, por ejemplo America/Santiago): startTime y endTime son horas locales HH:mm en esa zona.

Formatos:

  • Fechas con hora: ISO 8601 en UTC (2026-01-31T14:30:00.000Z).
  • Días (parámetros como from, to, dateFrom, dateTo): YYYY-MM-DD y deben ser fechas reales (2026-02-31 responde 400). Se interpretan en la zona horaria del negocio y ambos extremos se incluyen.

Paginación

Las listas usan paginación por cursor. No hay números de página ni total de elementos.

ParámetroValoresPor defecto
cursorel pagination.nextCursor de la página anteriorsin cursor = primera página
limit1 a 10025
  • pagination.nextCursor es el cursor de la página siguiente, o null si esa fue la última. pagination.hasMore es true mientras nextCursor no sea null.
  • El cursor es opaco: no lo interpretes ni lo construyas. Para pedir la página siguiente, repite la misma petición con cursor=<nextCursor> y los mismos demás parámetros (filtros, sortBy, order, updatedSince). Solo limit puede cambiar entre páginas.
  • Un cursor usado con otros filtros u otro orden, o en otra operación, responde 400 invalid_cursor. Un cursor ilegible también. Si te pasa, vuelve a empezar desde la primera página.
  • Un parámetro desconocido responde 400 validation_failed en todas las listas, incluidas las que no se paginan. En particular, page ya no existe.

Para recorrer una lista completa, sigue nextCursor hasta que sea null:

URL="https://api.kellu.co/api/v1/work-orders?limit=100"
CURSOR=""
while true; do
  if [ -z "$CURSOR" ]; then
    RESP=$(curl -s "$URL" -H "Authorization: Bearer kellu_sk_TU_CLAVE")
  else
    RESP=$(curl -s "$URL&cursor=$CURSOR" -H "Authorization: Bearer kellu_sk_TU_CLAVE")
  fi
  echo "$RESP" | jq -c '.data[]'
  CURSOR=$(echo "$RESP" | jq -r '.pagination.nextCursor // empty')
  [ -z "$CURSOR" ] && break
done

Tres listas no se paginan y devuelven todo en data: GET /team-members, GET /job-form-templates y GET /work-orders/{workOrderId}/job-forms. No aceptan cursor ni limit.

Sincronización incremental

updatedSince (fecha y hora ISO 8601 con zona, por ejemplo 2026-01-31T12:00:00Z o 2026-01-31T09:00:00-03:00; codifica el + como %2B) devuelve solo las filas con updatedAt >= updatedSince. Lo aceptan GET /clients, GET /work-orders, GET /quotes, GET /sale-notes, GET /assets y GET /catalog-items, y todas aceptan sortBy=updatedAt.

Receta para mantener una copia local:

  1. Pide sortBy=updatedAt&order=asc&updatedSince=<último updatedAt visto menos una ventana de solape>. La primera vez, omite updatedSince. Una ventana de unos minutos basta: updatedAt se marca antes de que el cambio quede confirmado, así que un cambio puede aparecer después de una lectura que ya pasó por su fecha.
  2. Recorre todas las páginas con cursor hasta que nextCursor sea null.
  3. Guarda cada fila por id (upsert): el solape repite filas y debe ser inocuo.
  4. Recuerda el mayor updatedAt visto y úsalo en la próxima sincronización.
curl -G "https://api.kellu.co/api/v1/clients" \
  --data-urlencode "sortBy=updatedAt" \
  --data-urlencode "order=asc" \
  --data-urlencode "updatedSince=2026-01-31T11:55:00Z" \
  --data-urlencode "limit=100" \
  -H "Authorization: Bearer kellu_sk_TU_CLAVE"

Límites: lo siguiente no aparece en una sincronización por updatedSince; usa los webhooks para enterarte:

  • Las eliminaciones: una fila borrada simplemente deja de aparecer.
  • Los cambios en un registro hijo que no modifican el updatedAt del padre.
  • Los valores derivados que cambian sin mover updatedAt: el status de una nota de venta, su amountPaidClp y balanceClp (pagos), y el saleNoteStatus de un trabajo.

Errores

Todo error responde con la misma forma:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the scope required by this operation.",
    "requestId": "8f0c3a5e-2b1d-4c9e-9a77-0d4f6c1e2b3a",
    "details": { "requiredScope": "quotes:read" }
  }
}

Decide siempre por code: message es un texto genérico en inglés que puede cambiar.

HTTPcodeCuándo
400validation_failedParámetros inválidos o desconocidos. details trae la lista de problemas. Un rechazo de transporte (405, 413, 415…) también responde validation_failed, con ese estado HTTP.
400invalid_cursorEl cursor es ilegible o se emitió para otros parámetros u otra operación. Vuelve a la primera página o repite los mismos parámetros.
401invalid_api_keyClave ausente, mal formada, inexistente, revocada o vencida.
403api_access_disabledEl acceso a la API del negocio está deshabilitado o el negocio está inactivo.
403insufficient_scopeA la clave le falta el permiso de la operación (details.requiredScope).
404not_foundEl recurso no existe para tu negocio, o la ruta no existe.
429rate_limitedSuperaste un límite de uso. Ver abajo.
500internal_errorError inesperado de Kellu.

X-Request-Id

Toda respuesta, exitosa o no, trae el encabezado X-Request-Id, el mismo valor que error.requestId. Guárdalo en tus registros: si necesitas ayuda con una petición, compártelo con Kellu.

Límites de uso (429)

Hay dos límites: 120 peticiones por minuto por clave y 300 por minuto por dirección IP. Al superarlos la API responde 429 rate_limited con:

  • el encabezado Retry-After, en segundos;
  • error.details.retryAfterSeconds, con el mismo valor.

Espera ese tiempo antes de reintentar. Si recorres listas grandes, usa limit=100 para hacer menos peticiones.

Reintentos recomendados

  • 429: reintenta después de Retry-After.
  • 500: reintenta con espera creciente (por ejemplo 1 s, 2 s, 4 s) y un máximo de intentos.
  • 400, 401, 403, 404: no reintentes sin cambiar la petición o la clave.