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-DDy deben ser fechas reales (2026-02-31responde400). 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ámetro | Valores | Por defecto |
|---|---|---|
cursor | el pagination.nextCursor de la página anterior | sin cursor = primera página |
limit | 1 a 100 | 25 |
pagination.nextCursores el cursor de la página siguiente, onullsi esa fue la última.pagination.hasMoreestruemientrasnextCursorno seanull.- 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). Sololimitpuede 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_faileden todas las listas, incluidas las que no se paginan. En particular,pageya 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:
- Pide
sortBy=updatedAt&order=asc&updatedSince=<último updatedAt visto menos una ventana de solape>. La primera vez, omiteupdatedSince. Una ventana de unos minutos basta:updatedAtse 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. - Recorre todas las páginas con
cursorhasta quenextCursorseanull. - Guarda cada fila por
id(upsert): el solape repite filas y debe ser inocuo. - Recuerda el mayor
updatedAtvisto 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
updatedAtdel padre. - Los valores derivados que cambian sin mover
updatedAt: elstatusde una nota de venta, suamountPaidClpybalanceClp(pagos), y elsaleNoteStatusde 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.
| HTTP | code | Cuándo |
|---|---|---|
| 400 | validation_failed | Pará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. |
| 400 | invalid_cursor | El 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. |
| 401 | invalid_api_key | Clave ausente, mal formada, inexistente, revocada o vencida. |
| 403 | api_access_disabled | El acceso a la API del negocio está deshabilitado o el negocio está inactivo. |
| 403 | insufficient_scope | A la clave le falta el permiso de la operación (details.requiredScope). |
| 404 | not_found | El recurso no existe para tu negocio, o la ruta no existe. |
| 429 | rate_limited | Superaste un límite de uso. Ver abajo. |
| 500 | internal_error | Error 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 deRetry-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.