Revisiones

Cuando un análisis necesita que lo mire una persona, puedes resolverlo desde el panel o desde tu propio backend con estos endpoints. Guía paso a paso en Revisión humana desde tu backend.

Solo funcionan con una clave secreta (ck_test_… o ck_live_…). Con una clave publicable (pk_…) la respuesta es 403 publishable_key_not_allowed.

Cuándo un análisis queda pendiente de revisiónCopy Anchor Link

Un análisis con veredicto entra en la cola de revisión (review.status: "pending") cuando:

• su veredicto es review;
• su veredicto es invalid y la plantilla usada pide revisión humana para los inválidos;
• su veredicto es valid y la plantilla usada no aprueba solos los válidos.

Mientras está pendiente, verdict.final_status es null. Al decidir pasa a valid (aprobado) o invalid (rechazado). Sin expect no hay veredicto y el análisis no se puede revisar (409 not_reviewable).

El objeto review del análisis:

"review": {
  "status": "pending",
  "decision": null,
  "assignee": null,
  "reviewed_by": null,
  "reviewed_at": null,
  "reason": null,
  "note": null
}

review es null en los análisis que no necesitan revisión.

Listar revisionesCopy Anchor Link

GET /v1/reviews

Solo incluye análisis del modo de tu clave (test o live). Orden:

• pending: los más antiguos primero, como una cola: atiende primero lo que lleva más tiempo esperando.
• El resto: los más recientes primero.

{
  "object": "list",
  "data": [
    {
      "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3",
      "object": "analysis",
      "status": "completed",
      "verdict": { "status": "review", "final_status": null, "…": "…" },
      "review": { "status": "pending", "decision": null, "…": "…" },
      "storage": { "mode": "review", "kept": true, "reason": "pending_review", "expires_at": "2026-10-29T10:05:01Z", "file_deleted_at": null },
      "file_url": "https://api.constaia.com/v1/files/…",
      "metadata": { "registration_id": "124" }
    }
  ],
  "has_more": false,
  "url": "/v1/reviews"
}

Cada elemento es el objeto analysis completo. La paginación funciona como en el resto de listados: ver Paginación.

curl -G https://api.constaia.com/v1/reviews \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  --data-urlencode "status=pending" \
  --data-urlencode "metadata[event]=42" \
  --data-urlencode "limit=50"

Descargar el originalCopy Anchor Link

GET /v1/analyses/{id}/file

Devuelve el documento original tal como se subió, solo si sigue guardado (storage.kept: true). Con el modo de almacenamiento por defecto (review) eso ocurre mientras el análisis espera revisión y durante el margen posterior a la decisión. Ver Almacenamiento y privacidad.

Respuesta 200 con el binario:

Errores:

Alternativa sin clave: mientras el original está guardado, el campo file_url del análisis trae una URL firmada que caduca a los 15 minutos. Es útil para enseñar el documento en tu pantalla de revisión; no la guardes, pide el análisis de nuevo cuando necesites otra.

curl -o original.jpg \
  https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3/file \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Decidir una revisiónCopy Anchor Link

POST /v1/analyses/{id}/review

Responde 200 con el objeto analysis actualizado:

• review.status: approved o rejected; review.decision: approve o reject.
• review.reviewed_by: el id de la clave con la que decidiste (key_…); review.reviewed_at, review.reason y review.note.
• verdict.final_status: valid si apruebas, invalid si rechazas.
• storage.expires_at pasa a la hora de la decisión más review_retention_hours_after_decision (24 h por defecto). Si ese plazo es 0, el original se borra al decidir y storage.kept pasa a false.

Además se envía el webhook analysis.reviewed y la decisión queda en el registro de auditoría de la cuenta a nombre de la clave de API.

{
  "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3",
  "object": "analysis",
  "verdict": { "status": "review", "final_status": "valid", "…": "…" },
  "review": {
    "status": "approved",
    "decision": "approve",
    "assignee": null,
    "reviewed_by": "key_01J9Z8Q3K4M5N6P7Q8R9S0T1V9",
    "reviewed_at": "2026-09-30T08:12:40Z",
    "reason": "Datos coinciden con el formulario",
    "note": null
  },
  "storage": { "mode": "review", "kept": true, "reason": null, "expires_at": "2026-10-01T08:12:40Z", "file_deleted_at": null }
}

Reintentos segurosCopy Anchor Link

• Envía la cabecera Idempotency-Key: la misma clave con el mismo cuerpo devuelve la misma respuesta, con la cabecera Idempotent-Replayed: true. Ver Idempotencia.
• Repetir la misma decisión sobre un análisis ya decidido devuelve el análisis tal cual (200) y no envía otro webhook.
• Una decisión distinta sobre un análisis ya decidido devuelve 409 already_reviewed. Solo un propietario o administrador puede cambiarla, desde el panel.

ErroresCopy Anchor Link

curl https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3/review \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3" \
  -d '{ "decision": "approve", "reason": "Datos coinciden con el formulario" }'

Plantillas y plazosCopy Anchor Link

Si usas plantillas, cada una puede fijar su propio almacenamiento y sus plazos de revisión. El objeto template incluye siempre estos campos:

Los valores de la cuenta se cambian en el panel (Ajustes de la cuenta).

Siguientes pasosCopy Anchor Link