Skip to main content

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.

Esta guía explica cómo crear verificaciones KYB para empresas en Estados Unidos 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 Estados Unidos permite verificar:
  • Corporaciones e entidades legales registradas en los distintos estados de EEUU
  • Estructura corporativa (directores, accionistas, incorporators)
  • Identificación fiscal federal (EIN - Employer Identification Number)
  • Registro federal de servicios monetarios (MSB en FinCEN)
Trébol automatiza la extracción de información de los documentos oficiales de constitución y registro.

​
Items aplicables

​
Documentos

Items que representan archivos que se cargan a Trébol.
ÍtemDescripción
certificate_of_incorporation_extractorCertificado de constitución (Beta)
certificate_of_incumbency_extractorCertificado de incumbencia (Beta)
irs_ein_assignment_letter_extractorCarta de asignación de EIN del IRS (Beta)
fincen_msb_registration_extractorRegistro de MSB (Money Services Business) en FinCEN (Beta)
Ver detalle completo y estructura de respuesta en Items de documentos — KYB EEUU.

​
Items globales aplicables

Además de los EEUU-específicos, puedes usar items globales:
  • person_id (pasaporte, otros)
  • 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.
Estados Unidos no es un valor soportado de country. Los valores soportados son mx y co; cualquier otro se procesa como not_specified (modo genérico, sin validaciones de formato locales). Por eso todos los ejemplos de KYB EEUU usan "country": "not_specified".

​
1. 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": "not_specified",
  "tag": "uuid-cliente-us-1234",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/certificate-of-incorporation.pdf",
        "client_item_type": "certificate_of_incorporation_extractor"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/irs-ein-letter.pdf"
      }
    }
  ]
}

​
2. 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: 2.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": "not_specified",
  "tag": "uuid-cliente-validacion",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/certificate-of-incorporation.pdf",
        "client_item_type": "certificate_of_incorporation_extractor",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El certificado debe mencionar a ACME Corp.",
            "params": {
              "entity_name": "ACME Corp."
            }
          }
        ]
      }
    }
  ]
}
ruleset es opcional. Para el catálogo completo de reglas predefinidas (vr_trebol_*) y cómo armar reglas personalizadas, ver Reglas de validación. 2.b — Solo extracción (tipo directo, ej. irs_ein_assignment_letter_extractor): Trébol extrae la información asumiendo que el documento es del tipo declarado. No valida tipo ni reglas. 
{
  "country": "not_specified",
  "tag": "uuid-cliente-extraccion",
  "items": [
    {
      "type": "irs_ein_assignment_letter_extractor",
      "options": {
        "file_url": "https://www.ejemplo.com/irs-ein-letter.pdf"
      }
    }
  ]
}
Si quieres validar y extraer, ver Combinar Validación + Extracción.

​
3. Combinación completa (las 3 formas en una verificación)

Caso de KYB realista que combina las 3 formas de procesar documentos. 
{
  "country": "not_specified",
  "tag": "uuid-cliente-completo",
  "friendly_name": "ACME Corp.",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/certificate-of-incumbency.pdf"
      }
    },
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/certificate-of-incorporation.pdf",
        "client_item_type": "certificate_of_incorporation_extractor",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El certificado debe mencionar a ACME Corp.",
            "params": {
              "entity_name": "ACME Corp."
            }
          }
        ]
      }
    },
    {
      "type": "irs_ein_assignment_letter_extractor",
      "options": {
        "file_url": "https://www.ejemplo.com/irs-ein-letter.pdf"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  }
}
Qué pasa en la verificación:
  • El certificate of incumbency (generic) se clasifica automáticamente y se extrae su información.
  • El certificate of incorporation (doc_validation) se valida que sea del tipo esperado y que mencione a ACME Corp. No se extrae información.
  • La IRS EIN letter (tipo directo) se extrae directamente, sin validar tipo ni reglas.

​
Ejemplo de flujo completo

Ejemplo de un flujo completo para onboarding de empresas en Estados Unidos. Incluye certificate of incorporation y EIN letter como obligatorios, certificate of incumbency como opcional con conditional_render, y captura de beneficiarios finales.
EEUU no está soportado como valor de country específico, por lo que se usa not_specified (modo genérico). Los items EEUU se mantienen disponibles independiente del country.
ubos_form_schema para flujos not_specified: hoy solo existen mx_form y co_form. Para un flujo de EEUU debes escoger explícitamente uno de los dos según cuál se adapte mejor a tus prospectos. En este ejemplo usamos mx_form.
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 US Corp - Estándar",
  "id_slug": "onboarding-us-estandar",
  "country": "not_specified",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "doc_1": {
        "allowed_item_types": ["certificate_of_incorporation_extractor"],
        "ui_options": {
          "label": "Certificate of Incorporation",
          "description": "Certificado oficial de constitución de la empresa"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      },
      "doc_2": {
        "allowed_item_types": ["irs_ein_assignment_letter_extractor"],
        "ui_options": {
          "label": "IRS EIN Assignment Letter",
          "description": "Carta de asignación del EIN emitida por el IRS"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    },
    "optional_requirements": {
      "doc_3": {
        "allowed_item_types": ["certificate_of_incumbency_extractor"],
        "ui_options": {
          "label": "Certificate of Incumbency",
          "description": "Documento que certifica los cargos vigentes de directores y oficiales.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar el Certificate of Incumbency?"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    }
  },
  "flow_items": {
    "items": [
      {
        "type": "ubos",
        "options": {
          "ubos_form_schema": "mx_form",
          "ubos_threshold": 25,
          "is_optional": false
        }
      },
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-empresa-us",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "compliance@tuempresa.com"
    }
  }
}
Ver Crear el flujo para detalle de cada sección del flujo.

​
Consideraciones

Fase BetaLos items específicos de EEUU están actualmente en fase Beta. La estructura de respuesta puede tener ajustes. Contáctanos en help@gotrebol.com si encuentras casos no cubiertos.

​
Siguientes pasos

Items de documentos

Detalle de estructura de respuesta para certificate_of_incorporation, EIN, FinCEN, etc.

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.