> ## 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.
# Consultas públicas externas
> Lee la evidencia de las consultas a fuentes gubernamentales (SAT, RENAPO, INE, SIGER) y descarga el reporte PDF de auditoría.
Durante una verificación, Trébol consulta varias fuentes públicas y gubernamentales (SAT, RENAPO, INE, SIGER). La sección de **consultas públicas externas** te entrega una vista de auditoría de esas consultas. Para cada una verás qué dependencia consultó Trébol, sobre quién, en qué fecha, con qué resultado y con qué evidencia técnica.
Esta página explica cómo **leer la evidencia** de las consultas externas. Para saber cómo **solicitar** cada consulta (opciones y cuerpos de la solicitud), revisa [Items de consultas públicas — KYB México](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas).
Tienes dos formas de consumir esta información, según tu caso de uso:
Un arreglo JSON con un registro por consulta, ideal para procesar de forma programática.
Un documento descargable, estandarizado y con marca de tiempo, ideal para soportes de cumplimiento.
Las dos formas viven en endpoints distintos. La sección estructurada usa el endpoint **v2** (`/v2/verifications/...`). El reporte PDF viaja dentro del endpoint de la verificación (`/verifications/{id}`, **sin** `/v2/`). No es un error de tipeo.
Los ejemplos usan la URL base de producción `https://api.gotrebol.com`. Ver [Conéctate al API](/docs/guia-devs/conectarse).
***
## Qué consultas se incluyen
Cada consulta externa proviene de un item de la verificación. Trébol la dispara automáticamente al procesar ese item; no necesitas activarla aparte. Hoy Trébol cubre las siguientes fuentes para **México**:
| Fuente (`source`) | `lookup_type` | Dependencia | Item que la origina |
| ----------------- | ------------------------ | --------------------------------------------- | ------------------------------------------------------------- |
| `sat` | `signature_certificates` | Servicio de Administración Tributaria (SAT) | `public_sat_signatures` |
| `sat` | `csf_qr_validation` | Servicio de Administración Tributaria (SAT) | `csf_mx` (solo cuando se valida el QR) |
| `renapo` | `curp` | Registro Nacional de Población (RENAPO) | `curp_item`, o personas con CURP detectadas desde `person_id` |
| `ine` | `lista_nominal` | Instituto Nacional Electoral (INE) | `person_id` con `idType: "ine_mx"` (validación INE) |
| `siger` | `commercial_registry` | Sistema Integral de Gestión Registral (SIGER) | `siger` |
Por ahora las consultas externas cubren los flujos de **México**. Las verificaciones de otros países (por ejemplo Colombia) aún no generan registros; en esos casos la sección llega vacía y Trébol no genera el reporte PDF.
***
## Opción 1: sección estructurada `external-lookups`
Devuelve un arreglo plano de registros, uno por cada consulta externa realizada, sin paginación: trae todas las consultas de la verificación en una sola respuesta. El esquema es estable: agregar nuevas fuentes no cambia su forma, solo suma registros.
Es la misma operación parametrizada `GET /v2/verifications/{id}/{entity}` con `entity = external-lookups` (igual que `sources` o `people`); su contrato vive en [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). Léela en cualquier momento, incluso con la verificación en curso; para el documento de cierre firmado, usa el [reporte PDF](#opcion-2-reporte-pdf-de-auditoria) de la Opción 2.
El endpoint responde `200` en cualquier estado de la verificación. Si todavía no hay consultas externas, `data` llega como arreglo vacío (`[]`). Mientras una consulta sigue en curso, su registro puede traer `status: "pending"`: vuelve a consultar más tarde. Para una evidencia completa, lee la sección cuando la verificación esté `finished`; Trébol te avisa de ese momento con [webhooks](/docs/guia-devs/webhooks), o puedes revisar los [estados de verificación](/docs/guia-devs/monitorear/estados-verificacion).
Una verificación inexistente o de otra cuenta devuelve `404`; sin `x-api-key` válida, `401`.
### Por ID de verificación
```bash curl theme={"dark"}
curl -X GET "https://api.gotrebol.com/v2/verifications/{verification_id}/external-lookups" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={"dark"}
const res = await fetch(
`https://api.gotrebol.com/v2/verifications/${verificationId}/external-lookups`,
{ headers: { "x-api-key": "YOUR_API_KEY" } },
);
const { data: lookups } = await res.json();
```
```python Python theme={"dark"}
import requests
res = requests.get(
f"https://api.gotrebol.com/v2/verifications/{verification_id}/external-lookups",
headers={"x-api-key": "YOUR_API_KEY"},
)
lookups = res.json()["data"]
```
### Por etiqueta de empresa (`tag`)
```bash curl theme={"dark"}
curl -X GET "https://api.gotrebol.com/v2/companies/{etiqueta}/external-lookups" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={"dark"}
const res = await fetch(
`https://api.gotrebol.com/v2/companies/${etiqueta}/external-lookups`,
{ headers: { "x-api-key": "YOUR_API_KEY" } },
);
const { data: lookups } = await res.json();
```
```python Python theme={"dark"}
import requests
res = requests.get(
f"https://api.gotrebol.com/v2/companies/{etiqueta}/external-lookups",
headers={"x-api-key": "YOUR_API_KEY"},
)
lookups = res.json()["data"]
```
### Estructura de la respuesta
La respuesta es un envelope con tres campos: `success` (siempre `true` en respuestas `200`), `data` (el arreglo de registros) y `meta` (la sección consultada y los datos básicos de la verificación: `id`, `tag`, `status`).
Cada elemento de `data` describe una consulta:
Fuente consultada: `sat`, `renapo`, `ine` o `siger`.
Tipo de consulta: `signature_certificates`, `csf_qr_validation`, `curp`, `lista_nominal` o `commercial_registry`.
Nombre completo de la dependencia consultada (por ejemplo, `Servicio de Administración Tributaria (SAT)`).
Sujeto de la consulta: `business` (empresa) o `person` (persona).
Nombre del sujeto consultado. Puede ser `null` si la fuente no lo devuelve.
Identificador enviado a la dependencia: RFC, CURP, clave de elector o folio mercantil (FME), según la fuente.
Fecha y hora (ISO 8601) de la consulta. Puede ser `null` cuando la fuente todavía no expone una fecha confiable (por ejemplo, algunas consultas de RENAPO).
Resultado de la consulta:
* `success`: la consulta se completó y devolvió datos.
* `not_found`: la dependencia respondió, pero no encontró coincidencias. Es un resultado definitivo, no un error.
* `failed`: la consulta falló por un error de la fuente o del proceso; conviene reintentar. Para diagnosticar, revisa los [errores en consultas públicas](/docs/guia-devs/referencia/errores-consultas-publicas).
* `pending`: la consulta sigue en curso; vuelve a consultar más tarde.
* `unknown`: no se pudo determinar el estado.
Revisa siempre `status` antes de leer `data`: solo en `success` puedes asumir el payload completo.
Artefactos de soporte de la consulta. Cada elemento incluye:
Tipo de evidencia: `screenshot` (captura de pantalla), `pdf` (documento descargable), `external_link` (enlace a la dependencia para reproducir la consulta) o `trebol_report` (reporte estandarizado de Trébol).
URL del artefacto. Para `screenshot` y `pdf` es una URL firmada de **corta duración** (\~1 hora) que se regenera en cada llamada: descárgala dentro de esa ventana o vuelve a consultar la sección. Para `external_link` es la URL pública de la dependencia (no caduca).
Descripción legible del artefacto.
Fecha (ISO 8601) de generación del artefacto, si se conoce.
Fecha (ISO 8601) en que expira la URL firmada. Es `null` para enlaces externos o estáticos.
Datos extraídos de la consulta, específicos de cada fuente y siempre en `snake_case`. Cuando `status` no es `success`, `data` puede venir parcial o con campos en `null`.
Es una vista **normalizada** para auditoría: sus nombres difieren del `item_value` crudo del item (por ejemplo, aquí el certificado SAT usa `serial_number` y `start_date`, no `numeroSerie` ni `fechaInicial`). Para el significado de cada dato según la fuente, revisa [Items de consultas públicas — KYB México](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas).
La evidencia disponible depende de la fuente:
* **SAT (firmas):** captura de pantalla (`screenshot`).
* **SAT (QR de la constancia):** enlace al validador del SAT (`external_link`).
* **RENAPO:** certificado de CURP (`pdf`).
* **INE:** sin evidencia adicional; los datos viven en `data` y `evidence` llega vacío.
Trébol reserva el tipo `trebol_report` para el reporte estandarizado; aún no aparece en esta sección.
### Ejemplo de respuesta
```json theme={"dark"}
{
"success": true,
"data": [
{
"source": "sat",
"lookup_type": "signature_certificates",
"agency_name": "Servicio de Administración Tributaria (SAT)",
"subject_type": "business",
"subject_name": "EMPRESA EJEMPLO SA DE CV",
"subject_identifier": "ABC123456789",
"queried_at": "2026-06-16T18:25:00.000Z",
"status": "success",
"evidence": [
{
"type": "screenshot",
"url": "https://files.gotrebol.com/.../sat-screenshot.jpg?...firma...",
"label": "SAT certificate lookup screenshot",
"generated_at": "2026-06-16T18:25:00.000Z",
"expires_at": "2026-06-16T19:25:00.000Z"
}
],
"data": {
"tax_id": "ABC123456789",
"legal_name": "EMPRESA EJEMPLO SA DE CV",
"business_type": "SOCIEDAD ANONIMA DE CAPITAL VARIABLE",
"certificates": [
{
"serial_number": "00001000000700333012",
"status": "Activo",
"type": "SELLO",
"start_date": "2023-01-01T00:00:00.000Z",
"end_date": "2027-12-31T23:59:59.000Z",
"legal_representative_rfc": "REP123456EF1",
"person_email": null
}
]
}
},
{
"source": "sat",
"lookup_type": "csf_qr_validation",
"agency_name": "Servicio de Administración Tributaria (SAT)",
"subject_type": "business",
"subject_name": "EMPRESA EJEMPLO SA DE CV",
"subject_identifier": "ABC123456789",
"queried_at": "2026-06-16T18:22:00.000Z",
"status": "success",
"evidence": [
{
"type": "external_link",
"url": "https://siat.sat.gob.mx/app/qr/faces/pages/mobile/validadorqr.jsf?D1=10&D2=1&D3=...",
"label": "SAT CSF QR validator",
"generated_at": null,
"expires_at": null
}
],
"data": {
"validation_result": "VALID",
"validation_status": "completed",
"validation_message": "Constancia válida y vigente.",
"constancia_type": "moral"
}
},
{
"source": "renapo",
"lookup_type": "curp",
"agency_name": "Registro Nacional de Población (RENAPO)",
"subject_type": "person",
"subject_name": "Juan Carlos Pérez García",
"subject_identifier": "PERE800101HDFXXX01",
"queried_at": null,
"status": "success",
"evidence": [
{
"type": "pdf",
"url": "https://files.gotrebol.com/.../renapo-curp.pdf?...firma...",
"label": "RENAPO CURP certificate",
"generated_at": null,
"expires_at": "2026-06-16T19:25:00.000Z"
}
],
"data": {
"curp": "PERE800101HDFXXX01",
"curp_status": "alta_normal",
"names": "Juan Carlos",
"first_surname": "Pérez",
"second_surname": "García",
"gender": "H",
"birth_date": "1980-01-01",
"nationality": "Mexicana",
"birth_entity": "Hidalgo",
"evidentiary_document": "Acta de nacimiento",
"evidentiary_document_data": {
"registry_date": "1980-02-01",
"act_number": "123456",
"register_entity": "Hidalgo",
"register_municipality": "Pachuca"
}
}
},
{
"source": "ine",
"lookup_type": "lista_nominal",
"agency_name": "Instituto Nacional Electoral (INE)",
"subject_type": "person",
"subject_name": "Juan Carlos Pérez García",
"subject_identifier": "PEREJC80010112H300",
"queried_at": "2026-06-16T18:20:00.000Z",
"status": "success",
"evidence": [],
"data": {
"validation_message": "Credencial válida y vigente en lista nominal."
}
},
{
"source": "siger",
"lookup_type": "commercial_registry",
"agency_name": "Sistema Integral de Gestión Registral (SIGER)",
"subject_type": "business",
"subject_name": "EMPRESA EJEMPLO SA DE CV",
"subject_identifier": "N-2024038395",
"queried_at": "2026-06-16T18:15:00.000Z",
"status": "success",
"evidence": [],
"data": {
"legal_name": "EMPRESA EJEMPLO SA DE CV",
"fme_number": "N-2024038395",
"fme_status": "Activo",
"federal_entity": "Ciudad de México",
"city": "Cuauhtémoc",
"office": "Oficina Central",
"tax_id_number": "ABC123456789",
"business_type": "Sociedad Anónima",
"registration_date": "2024-01-02",
"acts": [
{
"pre_coded_form": "Constitución de Sociedad Anónima",
"act": "Acta constitutiva",
"registration_date": "2024-01-02",
"document_number": "DOC-2024-001234",
"mode": "Electrónico"
}
]
}
}
],
"meta": {
"section": "external-lookups",
"verification": {
"id": "c8dc41fc-c477-404e-aff7-b9074f86d6d1",
"tag": "mi-etiqueta",
"status": "finished"
}
}
}
```
Cuando la verificación todavía no tiene consultas externas, `data` llega vacío:
```json theme={"dark"}
{
"success": true,
"data": [],
"meta": {
"section": "external-lookups",
"verification": {
"id": "c8dc41fc-c477-404e-aff7-b9074f86d6d1",
"tag": "mi-etiqueta",
"status": "pending"
}
}
}
```
***
Opción 2: reporte PDF de auditoría
Cuando una verificación finaliza, Trébol genera un **reporte PDF estandarizado** que agrupa todas las consultas externas. El reporte incluye una tarjeta por fuente con la dependencia, el sujeto, el estado, la fecha de consulta y los datos extraídos. Cada tarjeta adjunta su evidencia: capturas, certificados de RENAPO y enlaces de validación. El documento lleva el sello de Trébol con el ID de verificación y la fecha de generación.
Trébol expone este reporte como un campo opcional en `GET /verifications/{id}`:
Presente solo cuando existe un reporte para la verificación.
URL firmada para descargar el PDF. Trébol la sirve con `Content-Disposition: attachment`, así que abrirla descarga el archivo directamente.
Fecha y hora (ISO 8601) en que se generó el reporte.
```bash curl theme={"dark"}
curl -X GET "https://api.gotrebol.com/verifications/{verification_id}" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={"dark"}
import fs from "node:fs/promises";
const res = await fetch(
`https://api.gotrebol.com/verifications/${verificationId}`,
{ headers: { "x-api-key": "YOUR_API_KEY" } },
);
const verification = await res.json();
if (verification.lookups_report) {
// Descarga dentro de la ventana de validez de la URL (~1 h).
const pdf = await fetch(verification.lookups_report.url);
if (pdf.ok) {
await fs.writeFile("reporte-consultas.pdf", Buffer.from(await pdf.arrayBuffer()));
} else {
// URL caducada: vuelve a consultar la verificación para obtener una URL fresca.
}
}
```
```python Python theme={"dark"}
import requests
res = requests.get(
f"https://api.gotrebol.com/verifications/{verification_id}",
headers={"x-api-key": "YOUR_API_KEY"},
)
verification = res.json()
report = verification.get("lookups_report")
if report:
# Descarga dentro de la ventana de validez de la URL (~1 h).
pdf = requests.get(report["url"])
if pdf.ok:
with open("reporte-consultas.pdf", "wb") as f:
f.write(pdf.content)
# Si pdf.ok es False, la URL caducó: vuelve a consultar la verificación.
```
Respuesta (fragmento):
```json theme={"dark"}
{
"id": "c8dc41fc-c477-404e-aff7-b9074f86d6d1",
"status": "finished",
"lookups_report": {
"url": "https://files.gotrebol.com/.../lookups-report.pdf?...firma...",
"generated_at": "2026-06-16T18:30:00.000Z"
}
}
```
La `url` del reporte es una URL firmada de **corta duración** (\~1 hora de tiempo de vida, o TTL) y Trébol la regenera en cada llamada. No la guardes a largo plazo: si una página queda abierta más tiempo que ese TTL, vuelve a consultar la verificación antes de descargar.
El campo `lookups_report` **no aparece** cuando no hay reporte: verificaciones antiguas, verificaciones sin consultas externas o flujos de países que el generador aún no cubre. Trébol regenera el reporte cada vez que finaliza la verificación, por lo que siempre obtienes la última versión.
Trébol genera el reporte de forma asíncrona, así que puede tardar unos momentos en aparecer tras finalizar. Si la verificación está `finished` y el campo aún no está, vuelve a consultar en unos segundos.
***
## Siguientes pasos
Cómo solicitar cada consulta (SAT, SIGER, CURP) y el detalle de sus datos.
Las distintas formas de consultar los resultados de una verificación.
Cómo detectar y reaccionar a fallos en las consultas externas.