Exportaciones

Las listas paginan de a máximo 100 filas por solicitud, lo cual es correcto para una app y equivocado para una carga de BI. Las exportaciones producen un archivo con el conjunto de datos completo y filtrado de una entidad (procesos, actuaciones o demandados), hasta 100.000 filas, y te entregan una URL de descarga.

POST https://api.legal.usecroma.com/v1/exports

Como un portafolio grande tarda más de lo que una sola solicitud debería esperar, una exportación corre como trabajo asíncrono: la misma solicitud puede resolverse de tres maneras, y tú eliges cuál le conviene a tu app.

Las exportaciones pequeñas se sienten síncronas. Por defecto la solicitud espera hasta 20 segundos y, si el archivo está listo, devuelve 200 { data } con la URL. Los otros modos son opcionales, para cuando prefieras no mantener la conexión abierta.

La solicitud

{
  "entity": "processes",
  "format": "csv",
  "filters": { "status": "TRACKING", "date_from": "2024-01-01" }
}

Campo	Obligatorio	Significado
`entity`	sí	`processes`, `actions` o `defendants`.
`format`	no	`csv` (por defecto; UTF-8 con BOM para que Excel muestre las tildes) o `jsonl` (un objeto JSON por línea, ideal para scripts).
`filters`	no	Los mismos nombres que los parámetros de consulta de los endpoints de lista, en un solo objeto plano. Los filtros que no aplican a la entidad elegida se ignoran. Consulta ExportFilters.
`callback_url`	no	URL HTTPS pública a la que hacer `POST` con el resultado. Activa el modo callback.

Los campos desconocidos en el cuerpo (o dentro de filters) se rechazan con 400. El resultado, una vez existe el archivo:

{
  "data": {
    "url": "https://files.usecroma.com/legal-exports/processes-2026-08-21.csv",
    "entity": "processes",
    "format": "csv",
    "rows": 1280,
    "bytes": 418233,
    "truncated": false,
    "expires_at": "2026-08-22T14:03:10.000Z"
  }
}

url es imposible de adivinar pero no está autenticada: cualquiera que la tenga puede descargar el archivo. Está garantizada hasta expires_at (24 horas después de completarse) y se elimina poco después; descárgala pronto y no la publiques en ningún lugar público.
truncated: true significa que se alcanzó el tope de 100.000 filas y el archivo no es el conjunto completo. Acota los filtros (por ejemplo por rango de fechas) y exporta de nuevo.

Las tres formas de obtener el resultado

Modo	Envías	Recibes
Esperar en línea (por defecto)	nada extra, o `Prefer: wait=N`	`200 { data }` si termina a tiempo; si no, `202`
Polling	`Prefer: wait=0`	`202` de inmediato, luego `GET /jobs/:id` hasta terminar
Callback	`callback_url` en el cuerpo	`202` de inmediato, luego un `POST` a tu URL al terminar

Los tres están respaldados por el mismo trabajo, así que elige por solicitud.

Modo 1: Esperar en línea (por defecto)

Solo llama al endpoint. La solicitud se mantiene abierta hasta que el archivo está listo (hasta 20 segundos por defecto) y devuelve { data }.

curl -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity": "defendants", "format": "jsonl" }'

const res = await fetch("https://api.legal.usecroma.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ entity: "defendants", format: "jsonl" }),
});

if (res.status === 200) {
  const { data } = await res.json(); // data.url está lista para descargar
} else if (res.status === 202) {
  // no estuvo lista a tiempo; consulta la URL de estado (ver Modo 2)
}

Controla cuánto esperar con el encabezado estándar Prefer: wait=N (segundos, con tope en 55):

curl -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=50" \
  -d '{ "entity": "processes", "format": "csv" }'

200: listo. El cuerpo es { "data": … } como arriba.
202: no terminó dentro de la espera. El cuerpo es un sobre de trabajo; sigue su status_url para hacer polling. El encabezado X-Job-Id trae el id del trabajo.

Maneja siempre tanto 200 como 202. Un 202 no es un error; solo significa “todavía generando, vuelve por el resultado”. Un portafolio con decenas de miles de actuaciones normalmente tarda más que los 20 segundos de espera por defecto.

Modo 2: Polling

Envía Prefer: wait=0 para recibir un 202 de inmediato y luego haz GET al status_url del trabajo hasta que llegue a un estado terminal.

# 1. Inicia la exportación (devuelve 202 de inmediato)
curl -i -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=0" \
  -d '{ "entity": "actions", "filters": { "since": "2026-01-01" } }'

# 2. Consulta el status_url de la respuesta (o el encabezado Location)
curl https://api.legal.usecroma.com/jobs/run_abc123def456 \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY"

// 1. Inicia la exportación
const start = await fetch("https://api.legal.usecroma.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}`,
    "Content-Type": "application/json",
    Prefer: "wait=0",
  },
  body: JSON.stringify({ entity: "actions", filters: { since: "2026-01-01" } }),
});
const { job } = await start.json();

// 2. Haz polling hasta un estado terminal
async function poll(statusUrl: string) {
  while (true) {
    const res = await fetch(statusUrl, {
      headers: { Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}` },
    });
    const body = await res.json();
    if (body.job.status === "completed") return body.data;
    if (["failed", "canceled", "expired"].includes(body.job.status)) {
      throw new Error(body.error?.message ?? body.job.status);
    }
    // respeta Retry-After; por defecto 2 s mientras corre
    const wait = Number(res.headers.get("Retry-After") ?? 2) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

const { url } = await poll(job.status_url);

GET /jobs/:id siempre devuelve 200 con el sobre. Mientras el trabajo sigue corriendo incluye un encabezado Retry-After (segundos); úsalo para marcar el ritmo del polling. El polling tiene su propia cuota generosa. Los trabajos están limitados a tu organización; un trabajo de otra organización se lee como 404.

Modo 3: Callback (webhook)

Incluye un callback_url en el cuerpo de la solicitud. Recibes un 202 de inmediato y Croma hace POST con el resultado a tu URL cuando el archivo está listo, sin polling.

curl -i -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "entity": "processes",
        "format": "csv",
        "callback_url": "https://tu-app.com/webhooks/croma-legal"
      }'

callback_url debe ser una URL HTTPS absoluta en un host público (localhost y los rangos privados se rechazan). Cuando el trabajo termina, Croma envía un POST:

Cuerpo: el mismo sobre de trabajo del endpoint de polling.
x-croma-job-id: el id del trabajo.
x-croma-signature: sha256=<hmac>, un HMAC-SHA256 del cuerpo crudo de la solicitud, para que verifiques la integridad de la carga.

POST /webhooks/croma-legal HTTP/1.1
content-type: application/json
x-croma-job-id: run_abc123def456
x-croma-signature: sha256=9f86d081…

{ "job": { "id": "run_abc123def456", "status": "completed", … }, "data": { "url": "…" }, "error": null }

La verificación de la firma usa un secreto compartido emitido por Croma; contáctanos si quieres habilitarla para tus callbacks. Responde 2xx rápido; las respuestas distintas de 2xx se reintentan.

El sobre del trabajo

La respuesta 202, GET /jobs/:id y el cuerpo del callback comparten una misma forma:

{
  "job": {
    "id": "run_abc123def456",
    "status": "completed",
    "endpoint": "/v1/exports",
    "created_at": "2026-08-21T14:03:10.000Z",
    "finished_at": "2026-08-21T14:03:41.000Z",
    "status_url": "https://api.legal.usecroma.com/jobs/run_abc123def456"
  },
  "data": { "url": "…", "entity": "processes", "format": "csv", "rows": 1280, "bytes": 418233, "truncated": false, "expires_at": "2026-08-22T14:03:41.000Z" },
  "error": null
}

data solo viene poblado cuando status es completed. Si no, es null.
error solo viene poblado cuando el trabajo está en failed, como { "type", "code", "message" } con code: "job_failed".

Estados

`status`	¿Terminal?	Significado
`queued`	no	Aceptado, esperando para correr.
`running`	no	Generando el archivo.
`completed`	sí	Listo. Lee `data.url`.
`failed`	sí	La exportación falló. Lee `error`; créala de nuevo.
`canceled`	sí	La ejecución fue cancelada.
`expired`	sí	La ejecución expiró antes de completarse.

Qué trae el archivo

Las columnas son las mismas elijas csv o jsonl. Los valores anidados (metadata) se serializan como texto JSON en las celdas del CSV.

processes
actions
defendants

id, registration_number, plaintiff_name, defendant_name, defendant_id, office, status, registration_date, last_discovery_date, is_private, latest_action_message, latest_action_date, metadata.Las dos columnas latest_action_* traen la actuación más reciente de cada proceso, así que el archivo se lee como la vista de portafolio del dashboard.

id, process_id, registration_number, message, note, registration_date, action_created_at, source, publication_url, document_url, plaintiff_name, defendant_name, defendant_id, defender_name, office, priority, is_private, last_discovery_date, metadata.Es el conjunto más grande: filtra por since, date_from / date_to, office o defendant para mantenerte bajo el tope de filas.

id, identification_number, name, process_count, metadata, created_at.

Referencia de encabezados

Encabezado	Dónde	Significado
`Prefer: wait=N`	solicitud	Segundos a esperar en línea antes de devolver `202`. Por defecto 20, tope 55. `wait=0` devuelve `202` de inmediato.
`Preference-Applied: wait=N`	respuesta `200`	Repite la espera que se aplicó.
`Location`	respuesta `202`	El `status_url` del trabajo.
`Retry-After`	`202` / polling en curso	Segundos sugeridos antes de volver a consultar.
`X-Job-Id`	respuesta `202` / `200`	El id del trabajo.

POST /v1/exports

Esquema completo de solicitud y respuesta, con los filtros por entidad.

Errores

Cómo funcionan las fallas y el objeto error.

Primeros pasos

Guías

Referencia de API

La solicitud

Las tres formas de obtener el resultado

Modo 1: Esperar en línea (por defecto)

Modo 2: Polling

Modo 3: Callback (webhook)

El sobre del trabajo

Estados

Qué trae el archivo

Referencia de encabezados

POST /v1/exports

Errores

​La solicitud

​Las tres formas de obtener el resultado

​Modo 1: Esperar en línea (por defecto)

​Modo 2: Polling

​Modo 3: Callback (webhook)

​El sobre del trabajo

​Estados

​Qué trae el archivo

​Referencia de encabezados

POST /v1/exports

Errores

La solicitud

Las tres formas de obtener el resultado

Modo 1: Esperar en línea (por defecto)

Modo 2: Polling

Modo 3: Callback (webhook)

El sobre del trabajo

Estados

Qué trae el archivo

Referencia de encabezados