> ## 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. # Errores en consultas públicas > Cómo detectar si una consulta pública falló según la fuente externa: RENAPO, INE, SAT, SIGER, RUES, DIAN y Cámara de Comercio. Trébol realiza consultas a fuentes públicas externas (RENAPO, INE, SAT, SIGER, RUES, DIAN, Cámaras de Comercio) como parte del proceso de verificación. Estas fuentes pueden fallar por distintos motivos: datos incorrectos, servicio no disponible o errores inesperados. Esta página consolida **cómo detectar si una consulta pública falló** para cada fuente, dónde encontrar el indicador de error y qué valores esperar. **Cómo funcionan los errores en consultas públicas:** * **HTTP 200 OK siempre.** La API responde 200 incluso cuando la consulta a la fuente externa falla. El indicador de error vive dentro del `item_value` del ítem (o en el payload del webhook para RENAPO) — no en el status code HTTP. * **Errores finales.** Trébol reintenta automáticamente antes de reportar; los valores de esta página solo aparecen cuando se agotan los reintentos internos. * **Sincronía.** **RENAPO (CURP)** opera de forma **asíncrona** — resultado vía webhook. Las demás fuentes (INE, SAT, SIGER, RUES, DIAN, Cámara de Comercio) devuelven el resultado en el `item_value` al procesar la verificación. * Si el error fue causado por **datos de entrada incorrectos** (ej. RFC mal escrito, NIT inexistente), corrige el dato y crea una nueva verificación. * Si el error refleja un **problema técnico del servicio externo**, contacta a soporte. Los términos `item_value` e `item_internal_status` que aparecen en la tabla son campos del response de cada ítem (datos estructurados y estado interno de procesamiento, respectivamente). Para la estructura completa de respuesta, consulta [Respuestas por tipo de ítem](/docs/guia-devs/referencia/respuestas-por-tipo-de-item). ## Tabla resumen | Fuente externa | Ítem | País | Cómo detectar el fallo | | ---------------------- | -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **RENAPO** | `person_id`, `ac_mx`, `aa_mx`, `pw_mx` | México | Webhook `verification_people.curp_search_completed` → campo `people_error` | | **INE** | `person_id` (tipo `ine_mx`) | México | `item_value.ine_validation_result` con valor `failed`, `error`, `missing_parameters`, `maximum_retries_reached` o `missing_validation_parameters` | | **SAT** | `public_sat_signatures` | México | `item_value.data.{rfc}.status` = `"fail"` | | **SIGER** | `siger` | México | `item_internal_status` = `"siger_error"` | | **RUES** | `rues` | Colombia | `item_value.status` = `"NIT NO EXISTE"` | | **DIAN** | `public_rut_co` | Colombia | `item_value.status` = `"EXCEPTION"` / `"invalid"` **o** `item_value.rut_validation_result` = `"failed"` | | **Cámara de Comercio** | `public_address_cc_co` | Colombia | `item_value.legal_name` vacío (`""` o ausente) | *** ## México

RENAPO — Validación CURP

La búsqueda de CURP contra RENAPO se dispara automáticamente al procesar items `person_id` o al extraer accionistas de documentos tipo acta (`ac_mx`, `aa_mx`, `pw_mx`), y se ejecuta de forma asíncrona. Para saber si falló, revisa el payload del webhook `verification_people.curp_search_completed`. Cuando la búsqueda falla, el campo `people_error` está presente en el payload. **Campo indicador:** `people_error` (string, opcional) — solo presente cuando ocurre un error. **Valores posibles de `people_error`:** | Valor | Significado | | -------------------------- | --------------------------------------------------------------- | | `curp_scrapper_error` | Error al extraer información del CURP desde el servicio externo | | `curp_format_error` | El formato del CURP proporcionado no es válido | | `curp_service_unavailable` | El servicio de búsqueda de CURP no está disponible | **Ejemplo de payload con error:** ```json theme={"dark"} { "event_name": "verification_people.curp_search_completed", "data": { "verification_id": "c0361bc7-9318-4b09-8186-4ee451cc569f", "item_id": 32640, "people_error": "curp_format_error", "people_error_message": "CURP is required and must be a string", "people_id": 3908, "account_name": "trebol", "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03", "verification_tag": "personidgeneric-uuid" } } ``` Si el webhook llega **sin** el campo `people_error`, la consulta CURP fue exitosa. Consulta la documentación completa del webhook en [Webhooks → verification\_people.curp\_search\_completed](/docs/guia-devs/webhooks#verification_people-curp_search_completed). ***

INE — Validación

Para items de tipo `person_id` con `id_type: "ine_mx"`, Trébol realiza una validación del INE. El resultado se encuentra dentro de `item_value` en las claves `ine_validation_result` e `ine_validation_message`. **Campos indicadores:** * `ine_validation_result` (string) — resultado de la validación. * `ine_validation_message` (string) — mensaje descriptivo del resultado. **Valores de `ine_validation_result` que indican error (requieren acción del desarrollador):** | Valor | Significado | | ------------------------------- | ---------------------------------------------------------------- | | `failed` | La validación falló (puede ser temporal o por datos incorrectos) | | `error` | Excepción durante el proceso de validación | | `missing_parameters` | Faltan parámetros específicos para la validación | | `maximum_retries_reached` | Se superó el máximo de reintentos | | `missing_validation_parameters` | No puede ser validado por configuración (no es INE) | **Valores de `ine_validation_result` informativos (no requieren acción):** | Valor | Significado | | ------------ | ---------------------------------------------------------------------------- | | `valid_id` | Validación exitosa — el INE es válido | | `invalid_id` | El INE fue verificado pero resultó inválido — puede requerir revisión manual | **Valores de `ine_validation_message`:** | Valor | Significado | | ---------------------------------------------------------- | ------------------------------ | | `ID successfully validated` | Validación exitosa | | `A problem occured trying to validate the INE information` | Ocurrió un problema al validar | La validación del INE solo se ejecuta cuando el `id_type` es `ine_mx`. Para otros tipos de identificación (`passport`, `residence_mx`, `cc`), estos campos son `null`. Para la estructura completa de respuesta, consulta [Items de documentos — KYB Todos los países → Validación del INE](/docs/guia-devs/uso-kyb/todos-paises/items-documentos#person_id--identificación-oficial-persona). ***

SAT — Firmas y sellos

El ítem `public_sat_signatures` consulta los certificados FIEL y sellos digitales ante el SAT. Cuando la consulta no devuelve certificados hay que distinguir **dos casos distintos**. El campo `status` dentro de `item_value.data.{rfc}` indica si la consulta falló, y `validationResult.reason` indica **por qué**. **Valores de `status`:** | Valor | Significado | | ----------- | ------------------------------------------------------------------------------------------ | | `success` | La consulta encontró certificados para el RFC | | `fail` | La consulta no devolvió certificados (revisa `validationResult.reason` para saber por qué) | | `exception` | Error inesperado durante la consulta — reintenta más tarde | **Valores de `validationResult.reason`** (presente cuando `status` es `fail`): | Valor | Significado | Acción | | --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `rfc_not_found` | El SAT no tiene información para el RFC consultado (la consulta corrió correctamente) | Verifica que el RFC sea correcto y esté registrado en el SAT | | `scraper_error` | Falla técnica al consultar el portal del SAT (respuesta inesperada, bloqueo o cambio en la página) | Reintenta más tarde | **Valores de `validationMessage`:** | `validationResult.reason` | `validationMessage` | | ------------------------- | --------------------------------------------------------------------------------------------- | | `rfc_not_found` | `No se encontró información del RFC en la página del SAT. Verifique que el RFC sea correcto.` | | `scraper_error` | `SAT returned an unexpected response while validating the RFC.` | `status` sigue tomando los mismos valores de siempre (`success`, `fail`, `exception`); `validationResult.reason` es un campo **adicional** que refina el motivo del fallo. Si hoy ramificas solo por `status`, tu integración sigue funcionando sin cambios. **Ejemplo de respuesta cuando el RFC no se encuentra en el SAT (`rfc_not_found`):** Este ejemplo muestra ambos ítems SAT (business y representatives): ```json theme={"dark"} { "id": 12346, "item_order": 0, "item_status": "complete", "item_type": "public_sat_signatures", "item_internal_status": "screenshot_taken", "item_value": { "tax_ids": ["INVALID123456"], "data": { "INVALID123456": { "status": "fail", "bucketId": "business-verification-stack-verificationsbucket-example", "fileName": "mx/sat/screenshots/12346/INVALID123456/example-file.jpg", "legalName": "", "scrapedAt": "2025-01-15T10:35:00.000Z", "taxIdNumber": "INVALID123456", "validatedAt": "2025-01-15T10:35:00.000Z", "businessType": "", "certificates": [], "screenshotAt": "2025-01-15 10:35:15", "validationResult": { "success": false, "reason": "rfc_not_found" }, "validationMessage": "No se encontró información del RFC en la página del SAT. Verifique que el RFC sea correcto.", "screenshotUrl": "https://files.sandbox.gotrebol.com/mx/sat/screenshots/12346/INVALID123456/example-file.jpg?..." } } }, "tag": null, "item_scope": "advanced", "tags": { "uploaded-from": "api-creation" } }, { "id": 12347, "item_order": 1, "item_status": "complete", "item_type": "public_sat_signatures", "item_internal_status": "sat_not_found", "item_value": {}, "tag": null, "item_scope": "advanced", "tags": { "uploaded-from": "api-creation" } } ``` Cuando el ítem SAT de tipo `business` **no encuentra** el RFC (`status: "fail"` con `validationResult.reason: "rfc_not_found"`), el ítem de tipo `representatives` asociado se completa con `item_internal_status: "sat_not_found"` y `item_value` vacío, como se muestra en el segundo objeto del ejemplo. Si en cambio hubo una **falla técnica** (`reason: "scraper_error"` o `status: "exception"`), el ítem `representatives` se completa con `item_internal_status: "sat_scrap_failed"`. Distingue los dos casos por `validationResult.reason`: `rfc_not_found` significa que el RFC no está registrado en el SAT — verifica que sea correcto. `scraper_error` (o `status: "exception"`) indica una falla técnica del portal del SAT — reintenta más tarde. No trates una falla técnica como un RFC inválido. Para la documentación completa del ítem SAT, consulta [Items de consultas públicas — KYB México → public\_sat\_signatures](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas#public-sat-signatures). ***

SIGER — Sistema Integral de Gestión Registral

Cuando la consulta al portal SIGER falla por problemas técnicos o comportamientos inesperados de la página, el ítem refleja el error en su estado interno. **Campo indicador:** * `item_internal_status` = `"siger_error"` — la consulta no pudo completarse. Cuando `item_internal_status` es `"siger_error"`, el `item_value` puede estar vacío o incompleto. El error `siger_error` indica problemas técnicos con el portal SIGER (mal funcionamiento de la página o comportamientos inesperados), no datos incorrectos ingresados por el usuario. Para la documentación completa del ítem SIGER, consulta [Items de consultas públicas — KYB México → siger](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas#siger). *** ## Colombia

RUES — Registro Único Empresarial

Cuando el NIT consultado no existe en RUES, la respuesta lo indica dentro del `item_value`. **Campo indicador:** * `item_value.status` = `"NIT NO EXISTE"` — el NIT no fue encontrado en el RUES. **Ejemplo de respuesta con error:** ```json theme={"dark"} { "item_type": "rues", "item_value": { "status": "NIT NO EXISTE" } } ``` Este error indica que la página de RUES no encontró registros para el NIT proporcionado. Verifica que el NIT sea correcto e incluya el dígito de verificación. Para la documentación completa del ítem RUES, consulta [Items de consultas públicas — KYB Colombia → rues](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#rues). ***

DIAN — Consulta de NIT (`public_rut_co`)

Cuando la consulta del NIT en la DIAN falla, el resultado se refleja en `item_value`. No uses el código HTTP ni `item_internal_status` como único indicador de éxito: el scrape puede terminar en `"scrap_completed"` tanto si la consulta fue exitosa como si falló. **Campos indicadores:** * `item_value.status` — estado tributario devuelto por la DIAN en consultas exitosas (texto del campo `estado`, por ejemplo `"ACTIVO"`); en fallos puede ser `"EXCEPTION"`, `"invalid"` o cadena vacía. * `item_value.rut_validation_result` — resultado de la validación: `"success"` o `"failed"`. * `item_value.message` — detalle operativo del proceso (mensaje de éxito, error de DIAN, NIT inválido, etc.). **Cómo detectar que la consulta falló:** Considera la consulta **fallida** si se cumple **cualquiera** de estas condiciones: ```text theme={"dark"} item_value.status === "EXCEPTION" OR item_value.status === "invalid" OR item_value.rut_validation_result === "failed" ``` **Escenarios de fallo:** | Condición | `status` | `rut_validation_result` | Significado | | ----------------------------------------------------------------------------- | ------------- | ----------------------- | -------------------------------------------------- | | Error técnico (red, captcha, excepción al scrapear, etc.) | `"EXCEPTION"` | suele no enviarse | Reintentos internos agotados; revisa `message` | | NIT inválido antes de consultar DIAN (vacío o menos de 4 caracteres) | `"invalid"` | `"failed"` | Dato de entrada incorrecto | | DIAN no devolvió registro válido (NIT inexistente o mal formado en la fuente) | `""` (vacío) | `"failed"` | Sin datos de contribuyente en la respuesta de DIAN | **Consulta exitosa:** * `item_value.rut_validation_result` = `"success"`. * `item_value.status` = texto del estado en DIAN (por ejemplo `"ACTIVO"`); la capitalización puede variar según la fuente. * `item_value.message` en la implementación actual suele ser `"Process finished successfully."` (texto operativo; para lógica de negocio prioriza `status` y `rut_validation_result`). **Ejemplo — error técnico:** ```json theme={"dark"} { "item_type": "public_rut_co", "item_internal_status": "scrap_completed", "item_value": { "status": "EXCEPTION", "message": "An error occurred trying to parse the public source of DIAN for existence of NIT: ..." } } ``` **Ejemplo — NIT no encontrado en DIAN:** ```json theme={"dark"} { "item_type": "public_rut_co", "item_internal_status": "scrap_completed", "item_value": { "status": "", "rut_validation_result": "failed", "message": "Ocurrió un error en la consulta a DIAN o bien el nit no existe y/o está mal formado." } } ``` **Ejemplo — NIT inválido (entrada):** ```json theme={"dark"} { "item_type": "public_rut_co", "item_internal_status": "scrap_completed", "item_value": { "status": "invalid", "rut_validation_result": "failed", "message": "Provided NIT is invalid." } } ``` `item_internal_status` = `"scrap_completed"` solo indica que el proceso de consulta terminó, **no** que la DIAN devolvió un RUT válido. Integradores que solo validan `status === "EXCEPTION"` van a tratar los otros dos escenarios como exitosos por error. Para la documentación completa del ítem de consulta de NIT en la DIAN, consulta [Items de consultas públicas — KYB Colombia → public\_rut\_co](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#public-rut-co). ***

Cámara de Comercio — Dirección pública (`public_address_cc_co`)

Trébol consulta datos de contacto y dirección en cámaras de comercio públicas. El flujo intenta, en orden: **Medellín**, luego **Cali**, y por último **Bucaramanga** (esta última también puede completar el correo si Cali no lo trae). Este ítem **no** expone `item_value.status`, `item_value.message` ni un campo equivalente a `rut_validation_result`. La detección de fallo se hace por **contenido** de `item_value` y, de forma auxiliar, por `item_internal_status`. **Campos en `item_value`:** * `legal_name` * `organization_type` * `legal_email` * `phone` * `business_address` (`address`, `city`, `state`, `country`) * `tax_id_number` * `request_id` (si se envió en la creación de la verificación) **Cómo detectar que la consulta falló:** No hay código de error dedicado. Considera la consulta **fallida** si, una vez procesado el ítem, el nombre legal está vacío: ```text theme={"dark"} !item_value.legal_name OR item_value.legal_name === "" ``` Para validaciones más estrictas, también puedes considerar fallida la consulta si la dirección comercial está vacía: ```text theme={"dark"} !item_value.business_address?.address || item_value.business_address?.address === "" ``` `business_address` es siempre un **objeto** (`address`, `city`, `state`, `country`) cuando viene en la respuesta; nunca es un string. Si la consulta no obtuvo dirección, la clave suele **omitirse** (no aparece en `item_value`). **Consulta exitosa:** * `item_value.legal_name` poblado. * `item_value.business_address` con dirección y, habitualmente, `city` / `state`. * Pueden faltar `legal_email` o `phone` según la cámara que respondió; eso no implica fallo total si hay razón social y dirección. **Escenarios (implementación actual):** | Situación | Qué se guarda en `item_value` | `item_internal_status` | | -------------------------------------------- | ----------------------------------------------------- | ---------------------- | | NIT inválido (vacío o menos de 4 caracteres) | Campos de texto vacíos (`""`); sin `business_address` | `"scrap_completed"` | | NIT no encontrado en ninguna cámara | Campos de texto vacíos; sin `business_address` | `"scrap_completed"` | | Error técnico durante el scrape | Campos de texto vacíos; sin `business_address` | `"scrap_completed"` | | Éxito en alguna cámara | Datos de la empresa y `business_address` (objeto) | `"scrap_completed"` | **Ejemplo — consulta exitosa:** ```json theme={"dark"} { "item_type": "public_address_cc_co", "item_internal_status": "scrap_completed", "item_value": { "legal_name": "EMPRESA EJEMPLO COLOMBIA S.A.S.", "organization_type": "Sociedad por Acciones Simplificada", "legal_email": "legal@empresa-ejemplo.com.co", "phone": "+57 1 2345678", "business_address": { "address": "Calle 123 # 45-67, Oficina 901", "city": "Bogotá", "state": "Cundinamarca", "country": "Colombia" }, "tax_id_number": "900123456", "request_id": "CC-2024-001234" } } ``` **Ejemplo — consulta fallida (sin registro en ninguna fuente):** ```json theme={"dark"} { "item_type": "public_address_cc_co", "item_internal_status": "scrap_completed", "item_value": { "legal_name": "", "organization_type": "", "legal_email": "", "phone": "", "tax_id_number": "", "request_id": "" } } ``` En fallo sin datos de cámara, `business_address` **no** se incluye en `item_value` (no es `""` ni un objeto con strings vacíos). `item_internal_status` = `"scrap_completed"` indica que el job de consulta **terminó**, no que se obtuvo dirección o razón social. No uses solo este campo para decidir éxito. Si el error fue por **NIT incorrecto**, corrige el dato y crea una nueva verificación. Si `legal_name` viene vacío pero el NIT es correcto y el problema persiste, puede tratarse de indisponibilidad de las cámaras — contacta a soporte. Para la documentación completa del ítem, consulta [Items de consultas públicas — KYB Colombia → public\_address\_cc\_co](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#public-address-cc-co). *** ## Siguientes pasos Documentación completa de SIGER, SAT y CURP. Documentación completa de RUES, DIAN y Cámara de Comercio. Documentación del ítem `person_id` y validación del INE. Eventos de webhook incluyendo errores de CURP.