Errores en consultas públicas

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.

¿Qué hacer cuando una consulta falla?

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.

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:

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

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.

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

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

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.

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:

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

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:

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:

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

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

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

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:

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

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

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

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

Siguientes pasos

Consultas públicas — México

Documentación completa de SIGER, SAT y CURP.

Consultas públicas — Colombia

Documentación completa de RUES, DIAN y Cámara de Comercio.

Items de documentos — INE

Documentación del ítem person_id y validación del INE.

Webhooks

Eventos de webhook incluyendo errores de CURP.

Intro al API de Trébol

Guías por caso de uso

Errores en consultas públicas

Tabla resumen

México

RENAPO — Validación CURP

INE — Validación

SAT — Firmas y sellos

SIGER — Sistema Integral de Gestión Registral

Colombia

RUES — Registro Único Empresarial

DIAN — Consulta de NIT (`public_rut_co`)

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

Siguientes pasos

Consultas públicas — México

Consultas públicas — Colombia

Items de documentos — INE

Webhooks

​Tabla resumen

​México

​RENAPO — Validación CURP

​INE — Validación

​SAT — Firmas y sellos

​SIGER — Sistema Integral de Gestión Registral

​Colombia

​RUES — Registro Único Empresarial

​DIAN — Consulta de NIT (public_rut_co)

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

​Siguientes pasos

Consultas públicas — México

Consultas públicas — Colombia

Items de documentos — INE

Webhooks

Tabla resumen

México

RENAPO — Validación CURP

INE — Validación

SAT — Firmas y sellos

SIGER — Sistema Integral de Gestión Registral

Colombia

RUES — Registro Único Empresarial

DIAN — Consulta de NIT (`public_rut_co`)

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

Siguientes pasos