Leer una verificación

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 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.

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 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`

curl -X GET "https://api.gotrebol.com/verifications/{verification_id}" \
     -H "x-api-key: {api_key}"

Por etiqueta (`tag`)

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.

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.

{
  "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"
  }
}

object | null

El bloque completo de la revisión. Es null mientras la revisión no haya corrido para esa verificación.

Show campos del bloque

array

Los hallazgos de la corrida. Lista vacía si la revisión no encontró nada.

Show campos de cada hallazgo

string

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.

string

Descripción del hallazgo en lenguaje natural, pensada para mostrarse a un analista.

string

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.

string | null

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ó.

string

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 más abajo. Para saber que ya llegó la definitiva tienes dos caminos:

Webhook (recomendado): suscríbete a 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 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 — 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. 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.

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:

{ "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:

{
  "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, y la tabla completa del endpoint en la referencia.

Si estás suscrito a 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

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 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

curl -X GET "https://api.gotrebol.com/v2/verifications/{verification_id}/{seccion}" \
     -H "x-api-key: {api_key}"

Por etiqueta de empresa (tag)

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.	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.	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.

Para la estructura completa de cada sección, consulta los endpoints en el API Reference:

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.

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.

Para la estructura completa de la respuesta, consulta Obtener estado de validación de documentos en el API Reference.

Siguientes pasos

Estados de verificación

Ciclo de vida de una verificación: cuándo está lista para consultar.

Webhooks

Recibe eventos automáticos cuando una verificación termina.

Notificaciones

Notificaciones por email, Slack, Teams o Google Workspace.

Intro al API de Trébol

Guías por caso de uso

Leer una verificación

1. Listar verificaciones

Parámetros de consulta

2. Obtener una verificación por ID

Por `verification_id`

Por etiqueta (`tag`)

Síntesis de Dictamen

`null` no es lo mismo que una lista vacía

Cuándo deja de ser `null`

Pedir una corrida bajo demanda

`provisional` y `final`

Patrón recomendado

3. Leer por sección de la empresa

Por ID de verificación

Por etiqueta de empresa (tag)

Secciones disponibles

4. Estado de validación de documentos (widget)

Siguientes pasos

Estados de verificación

Webhooks

Notificaciones

​1. Listar verificaciones

​Parámetros de consulta

​2. Obtener una verificación por ID

​Por verification_id

​Por etiqueta (tag)

​Síntesis de Dictamen

​null no es lo mismo que una lista vacía

​Cuándo deja de ser null

​Pedir una corrida bajo demanda

​provisional y final

​Patrón recomendado

​3. Leer por sección de la empresa

​Por ID de verificación

​Por etiqueta de empresa (tag)

​Secciones disponibles

​4. Estado de validación de documentos (widget)

​Siguientes pasos

Estados de verificación

Webhooks

Notificaciones

1. Listar verificaciones

Parámetros de consulta

2. Obtener una verificación por ID

Por `verification_id`

Por etiqueta (`tag`)

Síntesis de Dictamen

`null` no es lo mismo que una lista vacía

Cuándo deja de ser `null`

Pedir una corrida bajo demanda

`provisional` y `final`

Patrón recomendado

3. Leer por sección de la empresa

Por ID de verificación

Por etiqueta de empresa (tag)

Secciones disponibles

4. Estado de validación de documentos (widget)

Siguientes pasos