Skip to main content
Esta guía explica cómo crear verificaciones KYB para empresas colombianas usando Trébol. Incluye los items aplicables, variaciones de creación con ejemplos de payload copy-pasteables, y consideraciones específicas. Para entender el método de creación a usar (Aplicativo Web, widget, API sin flujo, API con flujo), consulta Cómo funciona Trébol. Esta guía asume creación vía API.

​
¿Qué puedes verificar?

KYB Colombia permite verificar:
  • Empresas colombianas (Sociedades por Acciones Simplificadas, S.A., Ltda., etc.)
  • Representantes legales de una empresa
  • Estructura accionaria y juntas directivas
Trébol automatiza la consulta de información ante fuentes oficiales (RUES, DIAN, Cámara de Comercio) y la extracción de información de RUT y certificados de representación legal.

​
Items aplicables

​
Documentos

Items que representan archivos que se cargan a Trébol.
ÍtemDescripción
rut_coRegistro Único Tributario (documento del cliente)
cc_co_opsCertificado de Cámara de Comercio (cuando el cliente lo sube)
Ver detalle completo y estructura de respuesta en Items de documentos — KYB Colombia.

​
Consultas públicas

Items que Trébol consulta automáticamente ante fuentes oficiales.
ÍtemDescripción
ruesConsulta de NIT en el Registro Único Empresarial (RUES)
public_address_cc_coConsulta de NIT para obtener dirección y contacto (Cámara de Comercio pública)
public_rut_coVerifica existencia, estado y facturación del NIT en la DIAN
cc_co_opsCertificado de representación legal (Cámara de Comercio - cuando Trébol lo consulta)
El item cc_co_ops puede funcionar como consulta pública (Trébol lo obtiene directamente de Cámara de Comercio) o como documento cargable (el cliente lo sube). Depende del flujo que decidas usar.
Ver detalle completo en Items de consultas públicas — KYB Colombia.

​
Items globales aplicables

Además de los CO-específicos, puedes usar items globales:
  • person_id (cédula de ciudadanía colombiana, pasaporte)
  • proof_address (comprobante de domicilio)
  • bank_statement (estado de cuenta)
  • generic (para clasificación automática)

​
Variaciones de creación

Cada variación incluye un ejemplo de payload completo copy-pasteable.

​
1. Consulta simple por NIT (sin documentos)

Verificación sin documentos. Solo con el NIT se consultan fuentes públicas. Cada item es independiente — incluye solo los que necesites:
  • rues: NIT en el Registro Único Empresarial.
  • public_rut_co: verifica en la DIAN que el NIT exista, esté activo y la empresa sea facturable.
  • public_address_cc_co: dirección y contacto desde Cámara de Comercio pública.
  • cc_co_ops: certificado de existencia y representación legal (Trébol lo obtiene de Cámara de Comercio — más completo que las consultas anteriores).
{
  "country": "co",
  "tag": "uuid-cliente-1234",
  "tax_id": "900123456-7",
  "items": [
    {
      "type": "rues",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "public_rut_co",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "public_address_cc_co",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "cc_co_ops",
      "options": {
        "nit": "900123456"
      }
    }
  ]
}

​
2. Con documentos: clasificación automática + extracción

Verificación que incluye documentos para que Trébol clasifique automáticamente y extraiga la información. Usa items de tipo generic. El campo client_item_type es opcional: si lo defines, ayudas al clasificador con un hint del tipo esperado; si lo omites, Trébol detecta el tipo por sí solo. 
{
  "country": "co",
  "tag": "uuid-cliente-5678",
  "tax_id": "900123456-7",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/rut.pdf",
        "client_item_type": "rut_co"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/certificado-cc.pdf"
      }
    }
  ]
}

​
3. Con tipo conocido: solo validación o solo extracción

Cuando ya sabes qué tipo de documento te entregan, puedes saltarte la clasificación. Hay dos sub-casos: 3.a — Solo validación (item doc_validation): Trébol verifica que el archivo coincida con el tipo declarado y cumpla las reglas que configures. No extrae información. El campo client_item_type es obligatorio porque define contra qué tipo se compara. 
{
  "country": "co",
  "tag": "uuid-cliente-validacion",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/rut.pdf",
        "client_item_type": "rut_co",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El RUT debe corresponder a ACME Colombia S.A.S.",
            "params": {
              "entity_name": "ACME Colombia S.A.S."
            }
          }
        ]
      }
    }
  ]
}
ruleset es opcional. Para el catálogo completo de reglas predefinidas (vr_trebol_*) y cómo armar reglas personalizadas, ver Reglas de validación. 3.b — Solo extracción (tipo directo, ej. rut_co): Trébol extrae la información asumiendo que el documento es del tipo declarado. No valida tipo ni reglas. 
{
  "country": "co",
  "tag": "uuid-cliente-extraccion",
  "items": [
    {
      "type": "rut_co",
      "options": {
        "file_url": "https://www.ejemplo.com/rut.pdf"
      }
    }
  ]
}
Si quieres validar y extraer, ver Combinar Validación + Extracción.

​
4. Combinación completa (consultas públicas + documentos con las 3 formas)

Caso de KYB realista que combina todo: consultas públicas y las 3 formas de procesar documentos. 
{
  "country": "co",
  "tag": "uuid-cliente-completo",
  "tax_id": "900123456-7",
  "friendly_name": "ACME Colombia S.A.S.",
  "items": [
    {
      "type": "rues",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "public_rut_co",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "public_address_cc_co",
      "options": {
        "nit": "900123456"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/cedula-rep-legal.pdf"
      }
    },
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/rut.pdf",
        "client_item_type": "rut_co",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El RUT debe corresponder a ACME Colombia S.A.S.",
            "params": {
              "entity_name": "ACME Colombia S.A.S."
            }
          }
        ]
      }
    },
    {
      "type": "cc_co_ops",
      "options": {
        "file_url": "https://www.ejemplo.com/certificado-cc.pdf"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  }
}
Qué pasa en la verificación:
  • RUES, DIAN (consulta de NIT) y Cámara de Comercio (dirección) entregan información pública del NIT.
  • La cédula del representante legal (generic) se clasifica automáticamente como person_id y se extrae su información.
  • El RUT (doc_validation) se valida que sea un RUT y que mencione a ACME Colombia S.A.S. No se extrae información.
  • El certificado de Cámara de Comercio (cc_co_ops) se extrae directamente como documento cargado, sin validar tipo ni reglas.

​
Ejemplo de flujo completo

Ejemplo de un flujo completo para onboarding de empresas colombianas. Incluye requerimientos obligatorios (RUT + Cámara de Comercio), un requerimiento opcional con conditional_render, consultas a fuentes externas (RUES, DIAN, Cámara), captura de beneficiarios finales con co_form y un formulario para capturar datos adicionales de la empresa.
El schema_id del item forms se obtiene primero creando el esquema con el endpoint de esquemas de formularios. Ver detalle en Items del flujo — forms.
{
  "friendly_name": "Onboarding Empresa CO - Estándar",
  "id_slug": "onboarding-co-estandar",
  "country": "co",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "doc_1": {
        "allowed_item_types": ["rut_co"],
        "ui_options": {
          "label": "RUT",
          "description": "Registro Único Tributario"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      },
      "doc_2": {
        "allowed_item_types": ["cc_co_ops"],
        "ui_options": {
          "label": "Certificado de Cámara de Comercio",
          "description": "Certificado de existencia y representación legal"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    },
    "optional_requirements": {
      "doc_3": {
        "ui_options": {
          "label": "Cédula del Representante Legal",
          "description": "Documento de identidad del representante legal de la empresa.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar la cédula del representante legal?"
        },
        "allowed_item_types": ["person_id"],
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    }
  },
  "flow_items": {
    "items": [
      {
        "type": "rues"
      },
      {
        "type": "public_rut_co"
      },
      {
        "type": "public_address_cc_co"
      },
      {
        "type": "ubos",
        "options": {
          "ubos_form_schema": "co_form",
          "ubos_threshold": 5,
          "is_optional": false
        }
      },
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-empresa-co",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "compliance@tuempresa.com"
    }
  }
}
Ver Crear el flujo para detalle de cada sección del flujo.

​
Consideraciones

cc_co_ops: documento vs consulta públicaEl mismo item puede usarse de dos formas:
  • Como consulta pública: Trébol obtiene el certificado directamente de Cámara de Comercio (pasando solo el NIT en options.nit).
  • Como documento cargable: el cliente sube el archivo (pasando file_url en options).
Usa el que convenga a tu flujo de onboarding.
Formato del NITEl NIT colombiano puede venir con o sin dígito de verificación. En el atributo tax_id a nivel de verificación, puedes incluirlo con dígito (ej: 900123456-7). En options.nit de items, usualmente se pasa sin dígito (ej: 900123456).

​
Siguientes pasos

Items de documentos

Detalle de estructura de respuesta para rut_co, cc_co_ops, etc.

Items de consultas públicas

Detalle de RUES, consulta de NIT en la DIAN, Cámara de Comercio.

Cómo funciona Trébol

Comparación de Aplicativo Web, widget, API sin/con flujo.

Estados de verificación

Ciclo de vida de una verificación.