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 el RFC consultado no arroja resultados, la respuesta indica fallo dentro de item_value.data.{rfc}. Campos indicadores dentro de item_value.data.{rfc}:

status = "fail" — la consulta no encontró resultados para ese RFC.
validationMessage = "No successful response has been returned, please check RFC." — detalle del fallo.

Ejemplo de respuesta con error: Este ejemplo muestra ambos ítems SAT (business y representatives) cuando el RFC no arroja resultados:

{
  "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": null,
        "validatedAt": "2025-01-15T10:35:00.000Z",
        "businessType": "",
        "certificates": [],
        "screenshotAt": "2025-01-15 10:35:15",
        "validationResult": null,
        "validationMessage": "No successful response has been returned, please check RFC.",
        "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_scrap_failed",
  "item_value": {},
  "tag": null,
  "item_scope": "advanced",
  "tags": {
    "uploaded-from": "api-creation"
  }
}

Cuando el ítem SAT de tipo business falla, el ítem de tipo representatives asociado se completa con item_internal_status: "sat_scrap_failed" y item_value vacío, como se muestra en el segundo objeto del ejemplo.

Si el status es "fail", verifica que el RFC sea correcto y esté registrado en el SAT.

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

Intro al API de Trébol

Guías por caso de uso

Documentation Index

​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