Paginación y filtros

Dos estilos de paginación

La paginación por cursor la usan las listas grandes: GET /v1/processes, GET /v1/actions y GET /v1/defendants.

Parámetro / campo	Significado
`page_size` (solicitud)	Filas por página. Por defecto `25`, máximo `100`.
`cursor` (solicitud)	El `next_cursor` de la página anterior. Omítelo en la primera página.
`next_cursor` (respuesta)	Cadena opaca para la siguiente página; `null` en la última.
`has_more` (respuesta)	`true` mientras queden filas.

Los cursores son opacos: devuélvelos sin modificar y no los construyas tú. Están pensados para usarse dentro de una misma pasada por la lista; para empezar de nuevo, omite el cursor y pide otra vez la primera página.

async function* processes(params: Record<string, string>) {
  let cursor: string | null = null;
  do {
    const url = new URL("https://api.legal.usecroma.com/v1/processes");
    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
    url.searchParams.set("page_size", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}` },
    });
    const body = await res.json();
    yield* body.data;
    cursor = body.has_more ? body.next_cursor : null;
  } while (cursor);
}

La paginación por número de página la usa la línea de tiempo de un solo proceso, GET /v1/processes/{process_id}/actions: page (desde 1) y page_size (por defecto 25, máximo 100), con el conteo total en la respuesta.

Paginar un portafolio completo para armar un archivo es el camino lento. Para el conjunto de datos completo, usa las Exportaciones: una solicitud, una descarga CSV o JSONL, hasta 100.000 filas.

Cómo identificar un proceso

Donde aparece un proceso en una ruta, ambas formas funcionan y resuelven al mismo proceso:

el id interno (un UUID) que devuelven los endpoints de lista, o
el número de radicado, por ejemplo 11001400300120240012300.

Los demandados se identifican por su id interno de GET /v1/defendants (también expuesto como defendant_uuid en el detalle de un proceso). El campo defendant_id de procesos y actuaciones es el número de identificación (cédula o NIT), no ese UUID.

Cómo coinciden los filtros

Los filtros de texto (q, defendant, defendant_id, office, name, content) son parciales y no distinguen mayúsculas: office=civil municipal coincide con JUZGADO 001 CIVIL MUNICIPAL DE BOGOTÁ.
Los enumerados (status, priority, since_mode, granularity) deben coincidir exactamente; un valor desconocido devuelve 400 invalid_param.
Los booleanos (has_actions) reciben true o false.
Las fechas son ISO 8601 (2026-08-01 o 2026-08-01T00:00:00Z). Una fecha que no se puede interpretar se ignora en lugar de rechazarse, así que revisa el formato si un filtro de fecha parece no tener efecto.
Los filtros se combinan con AND. Una lista sin coincidencias es un 200 con data vacío, nunca un 404.

q siempre coincide con el número de radicado: úsalo en procesos y en el feed de actuaciones. En demandados, q coincide con el número de identificación y name con el nombre.

Qué fecha es cuál

El portafolio tiene varias fechas; elegir la correcta importa para reportar y para sincronizar.

Campo	En	Significado
`registration_date`	proceso	Fecha de radicación. `date_from` / `date_to` filtran sobre ella.
`last_discovery_date`	proceso	Última vez que Croma revisó el proceso. Se actualiza aunque no haya novedades, así que no indica actividad procesal.
`tracking_since`	detalle del proceso	Cuándo entró el proceso al portafolio de tu organización.
`registration_date`	actuación	Fecha judicial de la actuación. Es la que mide actividad procesal; puede venir `null` en algunas actuaciones.
`action_created_at`	actuación	Cuándo registró Croma la actuación. Es la fecha para “qué hay de nuevo desde mi última sincronización”.

En el feed de actuaciones, since_mode elige cuál de las dos fechas de la actuación usan since / until y el orden:

discovered (por defecto): action_created_at.
judicial: registration_date.

Orden por defecto

Endpoint	Orden
`GET /v1/processes`	Revisados más recientemente primero (`last_discovery_date` desc).
`GET /v1/processes/{id}/actions`	Más recientes primero por fecha judicial.
`GET /v1/actions`	Más relevantes primero: un puntaje de relevancia sobre el texto de la actuación, luego fecha (según `since_mode`), luego id.
`GET /v1/defendants`	Registro de demandado más reciente primero.
`GET /v1/defendants/{id}/processes`	Proceso con actividad más reciente primero (fecha de la última actuación).

Receta: sincronización incremental de actuaciones

Para reflejar la actividad del portafolio en tu propio sistema, lee el feed por fecha de registro y guarda una marca de agua:

Recuerda cuándo empiezas

Captura now antes de la primera solicitud. Será el since de la siguiente corrida, así que lo que se registre mientras paginas se recoge la próxima vez.

Pagina todo lo registrado desde la última marca

curl "https://api.legal.usecroma.com/v1/actions?since=2026-08-20T06:00:00Z&since_mode=discovered&page_size=100" \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY"

Sigue next_cursor hasta que has_more sea false. Cada fila trae process_id y registration_number, así que puedes asociarla al proceso que ya tienes, o traer el proceso con GET /v1/processes/{process_id} si es nuevo para ti.

Avanza la marca de agua

Guarda el now que capturaste como el siguiente since. Como since es inclusivo, volver a correr con la misma marca es seguro: puedes ver otra vez las filas del borde, y su id te permite deduplicarlas.

Usa since_mode=judicial cuando la pregunta sea “qué actuaciones ocurrieron en el juzgado durante un periodo”, por ejemplo un informe semanal de actuaciones fechadas dentro de esa semana.

Siguiente: Límites de tasa

Cómo se agrupan las cuotas y cómo se reportan en cada respuesta.

Primeros pasos

Guías

Referencia de API

Paginación y filtros

Dos estilos de paginación

Cómo identificar un proceso

Cómo coinciden los filtros

Qué fecha es cuál

Orden por defecto

Receta: sincronización incremental de actuaciones

Siguiente: Límites de tasa

​Dos estilos de paginación

​Cómo identificar un proceso

​Cómo coinciden los filtros

​Qué fecha es cuál

​Orden por defecto

​Receta: sincronización incremental de actuaciones

Siguiente: Límites de tasa

Dos estilos de paginación

Cómo identificar un proceso

Cómo coinciden los filtros

Qué fecha es cuál

Orden por defecto

Receta: sincronización incremental de actuaciones