Overview — KYB Colombia

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.

Ítem	Descripción
`rut_co`	Registro Único Tributario (documento del cliente)
`cc_co_ops`	Certificado 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.

Ítem	Descripción
`rues`	Consulta de NIT en el Registro Único Empresarial (RUES)
`public_address_cc_co`	Consulta de NIT para obtener dirección y contacto (Cámara de Comercio pública)
`public_rut_co`	Verifica existencia, estado y facturación del NIT en la DIAN
`cc_co_ops`	Certificado 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.

Intro al API de Trébol

Guías por caso de uso

Overview — KYB Colombia

¿Qué puedes verificar?

Items aplicables

Documentos

Consultas públicas

Items globales aplicables

Variaciones de creación

1. Consulta simple por NIT (sin documentos)

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

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

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

Ejemplo de flujo completo

Consideraciones

Siguientes pasos

Items de documentos

Items de consultas públicas

Cómo funciona Trébol

Estados de verificación

​¿Qué puedes verificar?

​Items aplicables

​Documentos

​Consultas públicas

​Items globales aplicables

​Variaciones de creación

​1. Consulta simple por NIT (sin documentos)

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

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

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

​Ejemplo de flujo completo

​Consideraciones

​Siguientes pasos

Items de documentos

Items de consultas públicas

Cómo funciona Trébol

Estados de verificación

¿Qué puedes verificar?

Items aplicables

Documentos

Consultas públicas

Items globales aplicables

Variaciones de creación

1. Consulta simple por NIT (sin documentos)

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

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

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

Ejemplo de flujo completo

Consideraciones

Siguientes pasos