Documentación de la API de Revisión de Documentos y Consultas de Onboarding

Trébol permite la creación y verificación de documentos y consultas para el proceso de onboarding de empresas y validación de documentos. A continuación se listan los tipos de documentos soportados, organizados por país y tipo, así como los ítems disponibles para consultas, widgets, integraciones y funcionalidades en beta. Importante:
Para la mayoría de los documentos, se recomienda crear los ítems utilizando el tipo generic. La plataforma Trebol clasificará automáticamente el documento al tipo específico correspondiente (por ejemplo, ac_mx o csf_mx). Adicionalmente, es posible especificar un tipo esperado mediante la opción client_item_type para mejorar la experiencia del cliente. Los ítems de tipo consulta no cambian su valor después de ser creados.

Tipos de Documentos por País

México

Estos ítems son soportados por Trébol para el proceso de onboarding de empresas y validación de documentos. En el proceso de onboarding, se recomienda crear cada item con el tipo generic para que Trébol clasifique el documento al tipo específico correspondiente.

Ítem	Descripción
`aa_mx`	Actas de asamblea.
`fme_mx`	Folio mercantil electrónico del Registro Público de la Propiedad y de Comercio (RPPyC).
`csf_mx`	Constancia de situación fiscal.
`pw_mx`	Poder notarial.
`ac_mx`	Acta constitutiva.
`em_mx`	Escritura de compraventa de inmuebles en México. (Beta)

Colombia

Ítem	Descripción
`rut_co`	Documento del RUT (Registro Único Tributario) proporcionado.
`cc_co`	Certificado de representación legal (Cámara de Comercio).
`em_co`	Escritura de compraventa de inmuebles en Colombia. (Beta)

Brasil

Ítem	Descripción
`ac_br`	Acto constitutivo de empresas en Brasil. (Beta)

España

Ítem	Descripción
`em_es`	Escritura de compraventa de inmuebles en España.

Soportados en todos los países

Estos ítems no están asociados a un país en específico y pueden utilizarse en múltiples contextos.

Ítem	Descripción
`bank_statement`	Estado de cuenta bancario.
`proof_address`	Comprobante de domicilio.
`person_id`	Documento de identidad de persona física/natural.
`generic`	Documento genérico. Usar preferentemente al crear una verificación para que Trebol clasifique.
`unknown`	Documento desconocido o no procesable por Trebol.
`corrupted_file`	Documento dañado (no legible o corrupto).
`property_deed`	Escritura de compraventa de inmuebles. (Beta)
`lien_certificate`	Certificado de gravámenes sobre inmuebles. (Beta)
`property_tax_receipt`	Recibo de pago de impuestos. (Beta)
`payroll_receipt`	Recibo de pago pensión o nómina de una persona. (Beta)
`camara_comercio_co_extractor`	Camara de comercio (Cámara de Comercio). (Beta)
`trust_contract_fideicomiso_extractor`	Contrato de fideicomiso. (Beta)
`union_documents_extractor`	Documentos de unión (pareja de hecho). (Beta)
`designacion_responsable_cumplimiento_extractor`	Designación de responsable de cumplimiento. (Beta)
`registro_actividades_vulnerables_extractor`	Registro de actividades vulnerables. (Beta)
`irs_ein_assignment_letter_extractor`	Letra de asignación de EIN (Internal Revenue Service). (Beta)
`certificate_of_incumbency_extractor`	Certificado de incumbencia. (Beta)
`certificate_of_incorporation_extractor`	Certificado de constitución. (Beta)
`fincen_msb_registration_extractor`	Registro de MSB (Money Services Business) en FinCEN. (Beta)

Ítems de Tipo Consulta

Los siguientes ítems están orientados a la consulta de información ante entidades o fuentes externas. Su valor no cambia una vez creados.

México

Ítem	Descripción	Ejemplo de Payload
`siger`	Consulta del SIGER (Sistema Integral de Gestión Registral).	`Agregado automaticamente en el request a menos que se especifique lo contrario con {"skip_siger":true} en los verification options.`
`public_sat_signatures`	Consulta de firmas y sellos (FIEL) ante el SAT.	`[{"type": "public_sat_signatures", "options": {"type": "business", "tax_id_number": "LT*********3"}}, {"type": "public_sat_signatures", "options": {"type": "representatives"}}]`
`curp_item`	Consulta de los datos asociados al CURP.	`{"type": "curp_item", "options": {"curp": "DAH************L06"}}`

Ejemplo Completo de Payload para CURP

{
  "country": "mx",
  "items": [
    {
      "type": "curp_item",
      "options": {
        "curp": "DAH**************6"
      }
    }
  ],
  "metadata": {
    "reason": "Curp item example."
  },
  "tag": "custom-identity-tag",
  "options": {
    "skip_siger": true
  }
}

Colombia

Í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`	Consulta del NIT en la DIAN (RUT público).
`cc_co_ops`	Certificado de representación legal (Cámara de Comercio - variación “ops”).

Estos ítems son parte del widget utilizado en el proceso de onboarding:

Ítem	Descripción
`ubos`	Formulario de declaración de propietarios reales (beneficiarios finales).
`forms`	Formularios de cuestionarios de onboarding.

Ítems de Integraciones

Estos ítems corresponden a integraciones con otros sistemas o servicios:

Ítem	Descripción
`aml_validation`	Consulta en listas de sanciones (OFAC, CNBV, etc).
`signatory_validation`	Validación biométrica de firmantes.

Ítems en Beta

Los siguientes ítems están actualmente en fase beta y pueden estar sujetos a cambios:

Ítem	Descripción
`financial_statements_any`	Estados financieros de empresas en cualquier país.
`ac_br`	Acto constitutivo en Brasil.
`em_mx`	Escritura de compraventa de inmuebles en México.
`em_co`	Escritura de compraventa de inmuebles en Colombia.
`em_es`	Escritura de compraventa de inmuebles en España.
`payroll_proof`	Comprobante de nómina en cualquier país.
`ac_br`	Acto constitutivo de empresas en Brasil.

Workflow de Clasificación de Documentos

Para la mayoría de los documentos, se recomienda crear los ítems utilizando el tipo generic. A continuación, Trebol clasificará automáticamente el documento al tipo específico correspondiente, como ac_mx para actas constitutivas en México o csf_mx para constancias de situación fiscal en México. Este flujo simplifica la integración y asegura una clasificación precisa sin intervención manual. Pasos del Workflow:

Creación del Ítem:
- Enviar el documento utilizando el tipo generic.
Procesamiento por Trebol:
- Trebol analiza el documento y determina su tipo específico.
Actualización del Ítem:
- El ítem inicialmente creado como generic se actualiza automáticamente al tipo correspondiente, como ac_mx, csf_mx, etc.
- Si Trebol no puede clasificar el documento, el ítem se actualiza a unknown o corrupted_file según corresponda.

Para los ítems de tipo consulta, su valor permanece constante y no se modifican después de la creación.

Ejemplos de Manejo de Errores

Ejemplo: Documento Genérico que Termina siendo `unknown` o `corrupted_file`

Imaginemos que una empresa está realizando el onboarding y sube un documento, este documento es de tipo generic. Una vez enviado, Trebol procesa el documento para determinar su tipo específico.

Caso 1: Documento Termina siendo unknown Después del procesamiento, Trebol no reconoce el tipo de documento proporcionado. En este caso, el ítem creado como generic se actualiza automáticamente a unknown. Manejo del Error:
- La aplicación debe verificar el estado del ítem y detectar que su tipo es unknown.
- Se puede notificar al usuario que el documento subido no fue reconocido.
- Se puede solicitar al usuario que proporcione un nuevo documento o que intente con otro tipo de archivo compatible.
Caso 2: Documento Termina siendo corrupted_file Si Trebol detecta que el archivo subido está dañado o no es legible, el ítem creado como generic se actualiza automáticamente a corrupted_file. Manejo del Error:
- La aplicación debe identificar que el ítem tiene el tipo corrupted_file.
- Informar al usuario que el archivo cargado está dañado o corrupto.
- Solicitar al usuario que vuelva a subir el documento en un formato legible y sin errores.

Detalle del Ítem: Recibo de Nómina (`payroll_receipt`)

Este ítem representa un recibo de pago de nómina o pensión. A continuación se detalla la estructura de datos extraída y un ejemplo. Descripción del Esquema: El objeto principal PaymentReceipt contiene la siguiente información estructurada:

informacion_emisor: Detalles de la entidad que emite el pago (nombre, ID fiscal).
informacion_empleado: Detalles del empleado (nombre, ID, tipo de ID).
informacion_pago: Detalles del periodo de pago (fecha emisión, periodo, inicio, fin, periodicidad, moneda).
ingresos: Detalle de ingresos recurrentes y no recurrentes, y el total.
creditos: Lista de créditos con entidad y monto de cuota.
embargos: Lista de embargos con tipo y monto.
descuentos: Descuentos de ley (salud, pensión, retención en la fuente) y otros descuentos detallados.
ingreso_neto_reportado: Ingreso neto explícitamente mencionado en el documento (si existe).
ingreso_neto_calculado: Ingreso neto calculado a partir de los ingresos y descuentos extraídos.

Ejemplo de Respuesta:

{
  "id": 99999,
  "item_order": 0,
  "item_status": "complete",
  "item_type": "document",
  "item_internal_status": "finish_extraction",
  "item_value": {
    "type": "payroll_receipt",
    "payload": {
      "metadata": {
        "file_type": "application/pdf",
        "error_count": 0,
        "processed_at": "YYYY-MM-DDTHH:MM:SS.ffffff",
        "success_count": 1,
        "total_pages_processed": 1
      },
      "receipts": [
        {
          "creditos": {
            "detalle_creditos": [
              { "valor": 1000.0, "entidad": "ENTIDAD_A" },
              { "valor": 200.0, "entidad": "ENTIDAD_B" }
            ]
          },
          "embargos": {
            "detalle_embargos": [{ "valor": 500.0, "tipo_embargo": "otro" }]
          },
          "ingresos": {
            "total_ingresos": 5000.0,
            "detalle_recurrentes": [
              { "valor": 4000.0, "concepto": "SUELDO BASICO" }
            ],
            "detalle_no_recurrentes": [
              { "valor": 150.0, "concepto": "BONO_A" },
              { "valor": 100.0, "concepto": "BONO_B" },
              { "valor": 400.0, "concepto": "PRIMA_X" },
              { "valor": 200.0, "concepto": "PRIMA_Y" },
              { "valor": 150.0, "concepto": "PRIMA_Z" }
            ]
          },
          "descuentos": {
            "salud": 150.0,
            "pension": 40.0,
            "otros_descuentos": [
              { "valor": 10.0, "concepto": "OTRO_DESCUENTO" }
            ],
            "retencion_fuente": 0
          },
          "informacion_pago": {
            "moneda": "COP",
            "periodo": "YYYY-MM",
            "periodo_fin": "YYYY-MM-DD",
            "periodicidad": "mensual",
            "fecha_emision": "YYYY-MM-DD",
            "periodo_inicio": "YYYY-MM-DD"
          },
          "receipt_metadata": {
            "end_page": 0,
            "start_page": 0,
            "receipt_metadata": 1,
            "extraction_status": "success"
          },
          "informacion_emisor": {
            "id_emisor": "NIT_EMISOR_EJEMPLO",
            "nombre_emisor": "EMPRESA_EJEMPLO"
          },
          "informacion_empleado": {
            "tipo_id": "otro",
            "id_empleado": "ID_EMPLEADO_EJEMPLO",
            "nombre_empleado": "NOMBRE APELLIDO"
          },
          "ingreso_neto_calculado": 3000.0,
          "ingreso_neto_reportado": 2000.0
        }
      ],
      "num_receipts": 1,
      "internalStatus": "comprehend_completed"
    }
  },
  "validation_result": null,
  "user_event_name": null,
  "user_event_reason": null,
  "tag": null,
  "item_scope": "advanced",
  "original_file_url": "..."
}

Intro al API de Trébol

Tipos de Documentos y Consultas

Documentación de la API de Revisión de Documentos y Consultas de Onboarding

Tipos de Documentos por País

México

Colombia

Brasil

España

Soportados en todos los países

Ítems de Tipo Consulta

México

Ejemplo Completo de Payload para CURP

Colombia

Ítems de Widget

Ítems de Integraciones

Ítems en Beta

Workflow de Clasificación de Documentos

Ejemplos de Manejo de Errores

Ejemplo: Documento Genérico que Termina siendo `unknown` o `corrupted_file`

Detalle del Ítem: Recibo de Nómina (`payroll_receipt`)

Intro al API de Trébol

​Documentación de la API de Revisión de Documentos y Consultas de Onboarding

​Tipos de Documentos por País

​México

​Colombia

​Brasil

​España

​Soportados en todos los países

​Ítems de Tipo Consulta

​México

​Ejemplo Completo de Payload para CURP

​Colombia

​Ítems de Widget

​Ítems de Integraciones

​Ítems en Beta

​Workflow de Clasificación de Documentos

​Ejemplos de Manejo de Errores

​Ejemplo: Documento Genérico que Termina siendo unknown o corrupted_file

​Detalle del Ítem: Recibo de Nómina (payroll_receipt)

Documentación de la API de Revisión de Documentos y Consultas de Onboarding

Tipos de Documentos por País

México

Colombia

Brasil

España

Soportados en todos los países

Ítems de Tipo Consulta

México

Ejemplo Completo de Payload para CURP

Colombia

Ítems de Widget

Ítems de Integraciones

Ítems en Beta

Workflow de Clasificación de Documentos

Ejemplos de Manejo de Errores

Ejemplo: Documento Genérico que Termina siendo `unknown` o `corrupted_file`

Detalle del Ítem: Recibo de Nómina (`payroll_receipt`)