> ## Documentation Index > Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Leer una verificación > Cómo consultar la información extraída de una verificación finalizada: listar verificaciones, leer por ID, consultar por sección y revisar el estado de documentos. Una vez que una verificación se finaliza (`status: "finished"`), puedes consultar la información extraída a través de la API. Trébol ofrece varias formas de acceder a los datos según lo que necesites. Los hallazgos de la [Síntesis de Dictamen](#sintesis-de-dictamen) son la excepción: una corrida `provisional` se puede leer antes de que la verificación quede `finished`. Los endpoints de lectura aplican a **todos los casos de uso** — KYB, Hipotecas, Nómina, etc. Lo que cambia es el contenido del reporte según los items que incluiste en la verificación. *** ## 1. Listar verificaciones Consulta todas las verificaciones de tu cuenta, opcionalmente filtrando por estado. Útil para obtener un listado general o para encontrar verificaciones en un estado específico. ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/verifications?status=finished&page_size=10" \ -H "x-api-key: {api_key}" ``` ### Parámetros de consulta | Parámetro | Tipo | Requerido | Descripción | | :---------- | :-------- | :-------- | :------------------------------------------------------------------------------------------ | | `status` | `string` | No | Filtra por estado de la verificación: `pending`, `finished`, `error`, `pending_validation`. | | `page_size` | `integer` | No | Cantidad de verificaciones por página. Por defecto `10`, máximo `20`. | | `next` | `string` | No | Token de paginación para obtener la siguiente página de resultados. | La respuesta incluye un arreglo `data` con las verificaciones y un campo `next` (si hay más páginas) que puedes usar como parámetro en la siguiente llamada. Para la estructura completa de la respuesta, consulta [Listar verificaciones de la cuenta](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/listar-verificaciones-de-la-cuenta) en el API Reference. *** ## 2. Obtener una verificación por ID Consulta una verificación específica usando su `verification_id` o el `tag` (etiqueta) que asignaste al crearla. ### Por `verification_id` ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/verifications/{verification_id}" \ -H "x-api-key: {api_key}" ``` ### Por etiqueta (`tag`) ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/companies/{etiqueta}" \ -H "x-api-key: {api_key}" ``` La respuesta incluye el estado de la verificación, sus items con su `item_status` y los `item_value` con la información extraída. Si la verificación tiene consultas a fuentes externas (SAT, RENAPO, INE, SIGER), la respuesta puede incluir `lookups_report` con una URL firmada para descargar el reporte PDF de auditoría. El campo se omite cuando no hay reporte. Ver [Consultas públicas externas](/docs/guia-devs/monitorear/consultas-publicas-externas).

Síntesis de Dictamen

`GET /verifications/{verification-id}` incluye además un bloque `findings` con los hallazgos de la Síntesis de Dictamen: lo que Trébol detecta como faltante o inconsistente en la documentación de la empresa. El listado `GET /verifications` no trae este campo. Para leer los hallazgos de una verificación, consúltala por su ID. El webhook entrega los mismos hallazgos con **otra forma**: ahí `findings` es el array de hallazgos y `source` / `computed_at` viajan a su lado, no dentro. Acá `findings` es un objeto y los hallazgos están en `findings.items`. Si reutilizas el mismo parser para las dos superficies, no compartas el acceso al campo. Ver [`verification.v2.findings.updated`](/docs/guia-devs/webhooks#verification-v2-findings-updated). ```json Respuesta theme={"dark"} { "findings": { "items": [ { "severity": "high", "message": "No se encontró el acta constitutiva; sin ella no es posible confirmar la razón social ni la fecha de constitución.", "missing_field": "razon_social" } ], "computed_at": "2026-06-16T18:12:00.000Z", "source": "provisional" } } ``` El bloque completo de la revisión. Es `null` mientras la revisión no haya corrido para esa verificación. Los hallazgos de la corrida. Lista vacía si la revisión no encontró nada. `high`, `medium` o `low`. Indica qué tan relevante es el hallazgo dentro de la revisión. Trébol no bloquea ni aprueba nada con base en este valor: qué hacer con cada nivel lo define tu proceso. Descripción del hallazgo en lenguaje natural, pensada para mostrarse a un analista. Se omite cuando el hallazgo no apunta a un dato o documento faltante; nunca llega como `null`. Es una etiqueta descriptiva, no un catálogo cerrado, y no corresponde uno a uno con los `item_type` de la verificación: úsala para mostrarla, no para ramificar lógica. Fecha y hora (ISO 8601) de la corrida que produjo los hallazgos. Es `null` en verificaciones antiguas, anteriores a que Trébol registrara este dato. Es también el valor que comparas para saber que una corrida bajo demanda ya terminó. `provisional` o `final`. Ver abajo. #### `null` no es lo mismo que una lista vacía * `"findings": null` — la revisión todavía no ha corrido para esa verificación. * `"findings": { "items": [], ... }` — la revisión corrió y no encontró nada. Si tu integración trata ambos casos igual, reporta "sin hallazgos" en verificaciones que nadie ha revisado todavía. #### Cuándo deja de ser `null` La Síntesis de Dictamen se habilita por cuenta. Si la tuya no la tiene habilitada, `findings` es `null` en todas tus verificaciones, siempre — no es un estado transitorio. Si esperas hallazgos y no llegan, confírmalo con tu contacto en Trébol antes de seguir consultando. Con la revisión habilitada, Trébol la corre por su cuenta: una corrida `provisional` cuando termina de procesar los documentos cargados, y una `final` al completarse la verificación. También puedes pedir una corrida tú mismo — ver [Pedir una corrida bajo demanda](#pedir-una-corrida-bajo-demanda) más abajo. Para saber que ya llegó la definitiva tienes dos caminos: * **Webhook (recomendado)**: suscríbete a [`verification.v2.findings.updated`](/docs/guia-devs/webhooks#verification-v2-findings-updated) y recibirás cada corrida, con su `source`, en cuanto se guarde. Si solo te interesa la definitiva, [`verification.v2.finished`](/docs/guia-devs/webhooks#verification-v2-finished) también sirve: Trébol escribe la corrida `final` antes de publicarlo. Ninguno de los dos necesita polling. * **Polling**: consulta la verificación por su ID y revisa `findings.source`. Cuando vale `final`, esos son los hallazgos definitivos de esa corrida. `findings.source` es la señal, no el `status` de la verificación: una corrida `final` solo se escribe al completarse, así que el `source` ya lo implica. Toda corrida que se guarde emite [`verification.v2.findings.updated`](/docs/guia-devs/webhooks#verification-v2-findings-updated) — las `provisional`, la `final` y las que pidas tú. Es opt-in: hay que suscribirse a ese evento. Sin la suscripción, la corrida `provisional` solo se ve consultando la verificación, porque `verification.v2.finished` se dispara al completarse la verificación y no una vez por corrida. Si después de finalizada se agregan documentos y la verificación se vuelve a procesar, una nueva corrida puede reemplazar los hallazgos.

Pedir una corrida bajo demanda

Si no quieres esperar a que un documento nuevo la dispare, puedes encolar una corrida con [`POST /verifications/{verification-id}/findings/run`](https://docs.gotrebol.com/api-reference/sintesis-de-dictamen/ejecutar-sintesis-de-dictamen-bajo-demanda). Sirve, sobre todo, porque varios hallazgos dependen de la vigencia de los documentos: las conclusiones pueden cambiar con el calendario aunque no hayas subido nada. ```bash theme={"dark"} curl -X POST "https://api.gotrebol.com/verifications/{verification-id}/findings/run" \ -H "x-api-key: TU_API_KEY" ``` Sustituye `{verification-id}` por el id que te devolvió `POST /verifications` y `TU_API_KEY` por tu API key. Si la corrida queda encolada, la respuesta es: ```json theme={"dark"} { "status": "queued" } ``` **Es asíncrona.** Responde `202 {"status": "queued"}` y la corrida termina unos segundos después; el `202` sólo dice que quedó encolada. Para saber que terminó, guarda el `findings.computed_at` que tenías antes de llamar y consulta la verificación cada 3-5 segundos hasta que ese valor cambie — o hasta que `findings` deje de ser `null`, si la revisión nunca había corrido. Dos minutos de espera son holgados; si se agotan, vuelve a consultar más tarde en vez de reintentar el `POST`, porque la corrida encolada sigue en curso. Un `202` implica que tu cuenta tiene la revisión habilitada: si no la tuviera, la respuesta sería `409 not_enabled`. La corrida que pidas se escribe como `final` si la verificación ya está completa y como `provisional` si todavía no lo está. Cuando no procede, responde `409` con un `error_code`: ```json theme={"dark"} { "error_code": "recently_run", "message": "Findings were recalculated moments ago. Try again in 240 seconds.", "retry_after_seconds": 240 } ``` * **`not_enabled`** — tu cuenta no tiene la revisión habilitada. Reintentar no cambia nada. * **`pending_documents`** — faltan documentos por subir o procesar. `pending_items` los nombra, pero son etiquetas para mostrar, no identificadores: para saber cuándo reintentar, consulta la verificación y espera a que sus items documentales estén en `item_status: "complete"`. * **`already_scheduled`** — ya hay una corrida en vuelo. No reintentes el `POST`: pasa directo a sondear, porque su resultado es el que esperas. Puede llegar también en tu **primer** `POST`, si una corrida automática ya estaba corriendo. * **`recently_run`** — corrió hace poco. Espera `retry_after_seconds` y vuelve a pedirla. `pending_items` sólo viene con `pending_documents`, y `retry_after_seconds` sólo con `recently_run`. Un segundo `POST` mientras hay una corrida en vuelo devuelve `409 already_scheduled`, nunca un `202` que duplique la corrida. Los códigos generales de la API (`401`, `404`, `500`) están en [Errores](/docs/guia-devs/errores), y la tabla completa del endpoint en [la referencia](https://docs.gotrebol.com/api-reference/sintesis-de-dictamen/ejecutar-sintesis-de-dictamen-bajo-demanda). Si estás suscrito a [`verification.v2.findings.updated`](/docs/guia-devs/webhooks#verification-v2-findings-updated), la corrida que pidas por este endpoint también lo emite al guardarse, y te llega sin sondear. Si no, lee el resultado consultando la verificación, como arriba. #### `provisional` y `final` `source` dice en qué momento Trébol calculó la revisión. * `provisional`: la calcula antes de completarse la verificación, con un modelo más rápido. Una corrida final puede reemplazarla, y sus hallazgos pueden cambiar de severidad o desaparecer. * `final`: la calcula al completarse la verificación. Si tu flujo toma una decisión a partir de los hallazgos, espera a `source: "final"`. Un `provisional` sirve para adelantar trabajo — avisarle al cliente qué le falta, por ejemplo — pero no es definitivo. #### Patrón recomendado ```js theme={"dark"} const res = await fetch(`https://api.gotrebol.com/verifications/${verificationId}`, { headers: { "x-api-key": apiKey }, }) // fetch no rechaza ante un status de error: hay que revisarlo a mano. if (!res.ok) throw new Error(`Trébol respondió ${res.status}`) const verification = await res.json() const findings = verification.findings if (findings === null) { // La revisión no ha corrido. Puede que tu cuenta no la tenga habilitada. return { estado: "sin_revisar" } } if (findings.source === "provisional") { // Útil para avisarle al cliente qué le falta, no para decidir. return { estado: "preliminar", hallazgos: findings.items } } // source === "final": los hallazgos ya no cambian. // Qué hacer con cada severidad lo decide tu proceso: Trébol no las trata // como bloqueantes. Aquí solo se agrupan para mostrarlas. return { estado: "revisado", hallazgos: findings.items, porSeveridad: { high: findings.items.filter((f) => f.severity === "high"), medium: findings.items.filter((f) => f.severity === "medium"), low: findings.items.filter((f) => f.severity === "low"), }, } ``` Para la estructura completa de la respuesta, consulta [Obtener una verificación por su ID](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-una-verificación-por-su-id) en el API Reference. *** ## 3. Leer por sección de la empresa Para consultas más granulares, puedes leer una **sección específica** de los datos de la empresa. Esto es útil cuando solo necesitas una parte de la información (por ejemplo, solo los accionistas o solo los documentos). Hay dos formas de consultar por sección: ### Por ID de verificación ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/v2/verifications/{verification_id}/{seccion}" \ -H "x-api-key: {api_key}" ``` ### Por etiqueta de empresa (tag) ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/v2/companies/{tag}/{seccion}" \ -H "x-api-key: {api_key}" ``` ### Secciones disponibles | Sección | Descripción | Aplica a | | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------- | | `details` | Información de la empresa: constitución, datos fiscales, domicilio, etc. | KYB México | | `shareholders` | Accionistas: nombres, participación, RFC. Incluye el [motivo cuando la lista viene vacía](/docs/guia-devs/uso-kyb/mexico/accionistas#motivo-sin-accionistas). | KYB México | | `people` | Personas clave: apoderados, representantes legales, poderes y roles. | KYB México | | `documents` | Documentos asociados a la verificación. | Todos los casos de uso | | `sources` | Fuentes de información (items) que alimentan la verificación y datos extraídos. | Todos los casos de uso | | `external-lookups` | Evidencia de auditoría de las consultas a fuentes públicas (SAT, RENAPO, INE, SIGER). Ver [Consultas públicas externas](/docs/guia-devs/monitorear/consultas-publicas-externas). | KYB México | Las secciones `documents` y `sources` están disponibles para **cualquier caso de uso** (KYB, Hipotecas, Nómina, etc.). Las secciones `details`, `shareholders` y `people` aplican específicamente al caso de uso **KYB México**. Puedes agregar `?with_citations=true` en los siguientes endpoints para obtener URLs firmadas a los artifacts de coordenadas: * **`GET /v2/verifications/{id}/{section}` y `/v2/companies/{tag}/{section}`**: para las secciones de `people` y `shareholders` devuelven `data.citations.url` (un artifact por sección). * **`GET /v2/verifications/{id}/{section}` y `/v2/companies/{tag}/{section}`**: para la seccion de `sources` cada item de tipo acta en `data.sources` recibe su propio campo `citations.url`. * **`GET /verifications/{id}`**: cada item de acta en `items[]` recibe `citations.url`. * **`GET /verification-items/{id}`**: el campo `citations.url` aparece en el objeto raíz si el item es de tipo acta. Ver [Coordenadas de citas](/docs/guia-devs/referencia/coordenadas-citas). Para la estructura completa de cada sección, consulta los endpoints en el API Reference: * [Obtener sección por ID de verificación](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-id-de-verificación) * [Obtener sección por etiqueta de empresa](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-etiqueta-de-empresa) *** ## 4. Estado de validación de documentos (widget) Cuando una verificación se crea **vía widget** con un `flow_id` que tiene un `record_validation_schema`, puedes consultar el estado de validación de cada documento requerido. Esto te permite saber qué documentos se han subido, cuáles están pendientes y cuáles han sido validados. ```bash theme={"dark"} curl -X GET "https://api.gotrebol.com/verifications/{verification_id}/record_validation" \ -H "x-api-key: {api_key}" ``` La respuesta muestra el estado de cada requerimiento definido en el `record_validation_schema` del flujo, incluyendo si el documento fue subido, clasificado correctamente y validado. Este endpoint aplica únicamente a verificaciones creadas a través del **widget de onboarding** que tienen un flujo con `record_validation_schema` configurado. Para más detalle sobre los estados del expediente, consulta [Estados del expediente](/docs/guia-devs/crear-verificaciones/via-widget/estados-expediente). Para la estructura completa de la respuesta, consulta [Obtener estado de validación de documentos](https://docs.gotrebol.com/api-reference/estado-de-validacion-de-documentos/obtener-estado-de-validacion-de-documentos-por-el-id-de-verificacion) en el API Reference. *** ## Siguientes pasos Ciclo de vida de una verificación: cuándo está lista para consultar. Recibe eventos automáticos cuando una verificación termina. Notificaciones por email, Slack, Teams o Google Workspace.