Skip to main content

​
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.
ÍtemDescripción
aa_mxActas de asamblea.
fme_mxFolio mercantil electrónico del Registro Público de la Propiedad y de Comercio (RPPyC).
csf_mxConstancia de situación fiscal.
pw_mxPoder notarial.
ac_mxActa constitutiva.
em_mxEscritura de compraventa de inmuebles en México. (Beta)

​
Colombia

ÍtemDescripción
rut_coDocumento del RUT (Registro Único Tributario) proporcionado.
cc_coCertificado de representación legal (Cámara de Comercio).
em_coEscritura de compraventa de inmuebles en Colombia. (Beta)

​
Brasil

ÍtemDescripción
ac_brActo constitutivo de empresas en Brasil. (Beta)

​
España

ÍtemDescripción
em_esEscritura 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.
ÍtemDescripción
bank_statementEstado de cuenta bancario.
proof_addressComprobante de domicilio.
person_idDocumento de identidad de persona física/natural.
genericDocumento genérico. Usar preferentemente al crear una verificación para que Trebol clasifique.
unknownDocumento desconocido o no procesable por Trebol.
corrupted_fileDocumento dañado (no legible o corrupto).
property_deedEscritura de compraventa de inmuebles. (Beta)
lien_certificateCertificado de gravámenes sobre inmuebles. (Beta)
property_tax_receiptRecibo de pago de impuestos. (Beta)
payroll_receiptRecibo de pago pensión o nómina de una persona. (Beta)
camara_comercio_co_extractorCamara de comercio (Cámara de Comercio). (Beta)
trust_contract_fideicomiso_extractorContrato de fideicomiso. (Beta)
union_documents_extractorDocumentos de unión (pareja de hecho). (Beta)
designacion_responsable_cumplimiento_extractorDesignación de responsable de cumplimiento. (Beta)
registro_actividades_vulnerables_extractorRegistro de actividades vulnerables. (Beta)
irs_ein_assignment_letter_extractorLetra de asignación de EIN (Internal Revenue Service). (Beta)
certificate_of_incumbency_extractorCertificado de incumbencia. (Beta)
certificate_of_incorporation_extractorCertificado de constitución. (Beta)
fincen_msb_registration_extractorRegistro 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

ÍtemDescripciónEjemplo de Payload
sigerConsulta 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_signaturesConsulta 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_itemConsulta 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

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

​
Ítems de Widget

Estos ítems son parte del widget utilizado en el proceso de onboarding:
ÍtemDescripción
ubosFormulario de declaración de propietarios reales (beneficiarios finales).
formsFormularios de cuestionarios de onboarding.

​
Configuración de Ítems forms

Los ítems de tipo forms requieren una configuración específica: Propiedades requeridas:
  • schema_id (string): ID del esquema de formulario que debe corresponder a un esquema existente en la cuenta.
Ejemplo de configuración: 
{
  "type": "forms",
  "options": {
    "schema_id": "some-test-form-schema",
    "is_optional": true
  }
}
Importante: El schema_id es obligatorio para ítems de tipo forms. Debe corresponder a un esquema de formulario válido creado previamente en tu cuenta.

​
Ítems de Integraciones

Estos ítems corresponden a integraciones con otros sistemas o servicios:
ÍtemDescripción
aml_validationConsulta en listas de sanciones (OFAC, CNBV, etc).
signatory_validationValidación biométrica de firmantes.

​
Ítems en Beta

Los siguientes ítems están actualmente en fase beta y pueden estar sujetos a cambios:
ÍtemDescripción
financial_statements_anyEstados financieros de empresas en cualquier país.
ac_brActo constitutivo en Brasil.
em_mxEscritura de compraventa de inmuebles en México.
em_coEscritura de compraventa de inmuebles en Colombia.
em_esEscritura de compraventa de inmuebles en España.
payroll_proofComprobante de nómina en cualquier país.
ac_brActo 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:
  1. Creación del Ítem:
    • Enviar el documento utilizando el tipo generic.
  2. Procesamiento por Trebol:
    • Trebol analiza el documento y determina su tipo específico.
  3. 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": "..."
}

​
Detalle del Ítem: Firmas y Sellos SAT (public_sat_signatures)

Este ítem permite consultar las firmas electrónicas (FIEL) y sellos digitales registrados ante el SAT (Servicio de Administración Tributaria) de México para empresas y representantes legales.

​
Opciones de Creación

El ítem public_sat_signatures puede crearse con las siguientes opciones:
  • Para empresas: Especifica el RFC de la empresa a consultar. 
    {
  "type": "public_sat_signatures",
  "options": {
    "type": "business",
    "tax_id_number": "LNW150825653"
  }
}
  • Para representantes legales: Consulta automáticamente los RFCs de los representantes legales asociados a la verificación. 
    {
  "type": "public_sat_signatures",
  "options": {
    "type": "representatives"
  }
}
Importante: Los dos items deben siempre estar presentes en el payload de creación si se quiere obtener los datos de una empresa y sus representantes.

​
Estructura de la Respuesta

La respuesta del ítem contiene la siguiente estructura:
  • tax_ids: Array con los RFCs consultados.
  • data: Objeto donde cada clave es un RFC y contiene la información de certificados asociados.

​
Propiedades del Objeto de Datos por RFC

Cada entrada en data contiene:
  • status: Estado de la consulta ("success" o "fail").
  • legalName: Nombre legal de la empresa o persona.
  • taxIdNumber: RFC consultado.
  • businessType: Tipo de empresa (solo para empresas).
  • certificates: Array de certificados FIEL y sellos encontrados.
  • validationMessage: Mensaje descriptivo del resultado de la consulta.
  • screenshotUrl: URL de la captura de pantalla de la consulta en el portal del SAT.
  • scrapedAt: Fecha y hora en que se realizó la consulta.
  • validatedAt: Fecha y hora de validación de los datos.

​
Estructura de Certificados

Cada certificado en el array certificates contiene:
  • tipo: Tipo de certificado ("FIEL" o "SELLO").
  • estado: Estado del certificado ("Activo", "Revocado" o "Caduco").
  • fechaInicial: Fecha de inicio de vigencia del certificado.
  • fechaFinal: Fecha de fin de vigencia del certificado.
  • numeroSerie: Número de serie del certificado.
  • serieLink: URL al certificado en el portal del SAT.
  • cerFile: Archivo del certificado en formato base64 (solo para certificados activos con datos completos).
  • data: Objeto con información detallada del certificado (solo para certificados activos):
    • type: Tipo de certificado.
    • status: Estado.
    • startDate y endDate: Fechas de vigencia.
    • serialNumber: Número de serie.
    • certificate: Objeto con información del emisor y sujeto del certificado.
  • legalRepresentativeRFC: RFC del representante legal asociado (solo para sellos de empresas).
  • personEmail: Email de la persona (solo para certificados FIEL de personas físicas).

​
Ejemplo de Respuesta Exitosa

Este ejemplo muestra una verificación que incluye consultas tanto para una empresa como para representantes legales: 
{
  "id": 12345, //business sat item
  "item_order": 0,
  "item_status": "complete",
  "item_type": "public_sat_signatures",
  "item_internal_status": "screenshot_taken",
  "item_value": {
    "tax_ids": ["ABC123456789"],
    "data": {
      "ABC123456789": {
        "status": "success",
        "bucketId": "business-verification-stack-verificationsbucket-example",
        "fileName": "mx/sat/screenshots/12345/ABC123456789/example-file.jpg",
        "legalName": "EMPRESA EJEMPLO SA DE CV",
        "scrapedAt": "2025-01-15T10:30:00.000Z",
        "taxIdNumber": "ABC123456789",
        "validatedAt": "2025-01-15T10:30:00.000Z",
        "businessType": "SOCIEDAD ANONIMA DE CAPITAL VARIABLE",
        "certificates": [
          {
            "data": {
              "type": "FIEL",
              "status": "Activo",
              "endDate": "2027-12-31T23:59:59.000Z",
              "startDate": "2023-01-01T00:00:00.000Z",
              "certificate": {
                "issuer": {
                  "C": "MX",
                  "L": "CUAUHTEMOC",
                  "O": "SERVICIO DE ADMINISTRACION TRIBUTARIA",
                  "CN": "AC DEL SERVICIO DE ADMINISTRACION TRIBUTARIA",
                  "OU": "SAT-IES Authority",
                  "ST": "CDMX",
                  "street": "Av. Hidalgo 77, Col. Guerrero",
                  "postalCode": "06300",
                  "emailAddress": "[email protected]",
                  "unstructuredName": "responsable: ADMINISTRACION CENTRAL DE SERVICIOS TRIBUTARIOS AL CONTRIBUYENTE",
                  "x500UniqueIdentifier": "SAT970701NN3"
                },
                "subject": {
                  "O": "EMPRESA EJEMPLO SA DE CV",
                  "CN": "EMPRESA EJEMPLO SA DE CV",
                  "OU": "MATRIZ",
                  "name": "EMPRESA EJEMPLO SA DE CV",
                  "serialNumber": " / REP123456ABCD00",
                  "x500UniqueIdentifier": "ABC123456789 / REP123456EF1"
                }
              },
              "serialNumber": "3030303031303030303030373030333333303132"
            },
            "tipo": "SELLO",
            "estado": "Activo",
            "cerFile": "MIIF7DCCA9SgAwIBAgIUMDAwMDEwMDAwMDA3MDAzMzMwMTIwDQYJKoZIhvcNAQELBQAwggGV... [truncado]",
            "serieLink": "https://rdc.sat.gob.mx/rccf/000010/000007/00/33/30/00001000000700333012.cer",
            "fechaFinal": "2027-12-31T23:59:59.000Z",
            "numeroSerie": "00001000000700333012",
            "fechaInicial": "2023-01-01T00:00:00.000Z",
            "legalRepresentativeRFC": "REP123456EF1"
          },
          {
            "tipo": "FIEL",
            "estado": "Revocado",
            "serieLink": "https://rdc.sat.gob.mx/rccf/000010/000005/01/88/04/00001000000501880457.cer",
            "fechaFinal": "2023-02-28T18:09:20.000Z",
            "numeroSerie": "00001000000501880457",
            "fechaInicial": "2019-10-24T20:41:37.000Z"
          }
        ],
        "screenshotAt": "2025-01-15 10:30:15",
        "validationResult": null,
        "validationMessage": "Enterprise data has been successfully retrieved.",
        "screenshotUrl": "https://files.sandbox.gotrebol.com/mx/sat/screenshots/12345/ABC123456789/example-file.jpg?..."
      }
    }
  },
  "tag": null,
  "item_scope": "advanced",
  "tags": {}
},
{
    "id": 12346, //representatives sat item
    "item_order": 1,
    "item_status": "complete",
    "item_type": "public_sat_signatures",
    "item_internal_status": "screenshot_taken",
    "item_value": {
        "tax_ids": [
            "XYZ987654321"
        ],
        "data": {
            "XYZ987654321": {
                "status": "success",
                "bucketId": "business-verification-stack-verificationsbucket-example",
                "fileName": "mx/sat/screenshots/12346/XYZ987654321/example-file.jpg",
                "legalName": "JUAN PEREZ GARCIA",
                "scrapedAt": "2025-01-15T10:30:30.000Z",
                "taxIdNumber": "XYZ987654321",
                "validatedAt": "2025-01-15T10:30:30.000Z",
                "businessType": "",
                "certificates": [
                    {
                        "data": {
                            "type": "FIEL",
                            "status": "Activo",
                            "endDate": "2027-09-21T16:05:26.000Z",
                            "startDate": "2023-09-21T16:04:46.000Z",
                            "certificate": {
                                "issuer": {
                                    "C": "MX",
                                    "L": "CUAUHTEMOC",
                                    "O": "SERVICIO DE ADMINISTRACION TRIBUTARIA",
                                    "CN": "AC DEL SERVICIO DE ADMINISTRACION TRIBUTARIA",
                                    "OU": "SAT-IES Authority",
                                    "ST": "CDMX",
                                    "street": "Av. Hidalgo 77, Col. Guerrero",
                                    "postalCode": "06300",
                                    "emailAddress": "[email protected]",
                                    "unstructuredName": "responsable: ADMINISTRACION CENTRAL DE SERVICIOS TRIBUTARIOS AL CONTRIBUYENTE",
                                    "x500UniqueIdentifier": "SAT970701NN3"
                                },
                                "subject": {
                                    "C": "MX",
                                    "O": "JUAN PEREZ GARCIA",
                                    "CN": "JUAN PEREZ GARCIA",
                                    "name": "JUAN PEREZ GARCIA",
                                    "emailAddress": "[email protected]",
                                    "serialNumber": "XYZ987654321",
                                    "x500UniqueIdentifier": "XYZ987654321"
                                }
                            },
                            "serialNumber": "3030303031303030303030373032343330373934"
                        },
                        "tipo": "FIEL",
                        "estado": "Activo",
                        "cerFile": "MIIGSzCCBDOgAwIBAgIUMDAwMDEwMDAwMDA3MDI0MzA3OTQwDQYJKoZIhvcNAQELBQAwggGV... [truncado]",
                        "serieLink": "https://rdc.sat.gob.mx/rccf/000010/000007/02/43/07/00001000000702430794.cer",
                        "fechaFinal": "2027-09-21T16:05:26.000Z",
                        "numeroSerie": "00001000000702430794",
                        "personEmail": "[email protected]",
                        "fechaInicial": "2023-09-21T16:04:46.000Z"
                    },
                    {
                        "tipo": "FIEL",
                        "estado": "Revocado",
                        "serieLink": "https://rdc.sat.gob.mx/rccf/000010/000005/01/85/63/00001000000501856356.cer",
                        "fechaFinal": "2023-09-21T16:04:46.000Z",
                        "numeroSerie": "00001000000501856356",
                        "fechaInicial": "2019-10-23T17:27:19.000Z"
                    },
                    {
                        "tipo": "FIEL",
                        "estado": "Caduco",
                        "serieLink": "https://rdc.sat.gob.mx/rccf/000010/000004/00/46/61/00001000000400466137.cer",
                        "fechaFinal": "2019-09-25T17:34:23.000Z",
                        "numeroSerie": "00001000000400466137",
                        "fechaInicial": "2015-09-25T17:33:43.000Z"
                    }
                ],
                "screenshotAt": "2025-01-15 10:30:45",
                "validationResult": null,
                "validationMessage": "Enterprise data has been successfully retrieved.",
                "screenshotUrl": "https://files.sandbox.gotrebol.com/mx/sat/screenshots/12346/XYZ987654321/example-file.jpg?..."
            }
        }
    },
    "tag": null,
    "item_scope": "advanced",
    "tags": {}
}

​
Ejemplo de Respuesta con Error

Cuando el RFC no se encuentra o la consulta falla, la respuesta incluye un estado "fail" y un mensaje descriptivo: 
{
  "id": 12346, //business sat item
  "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 succesfull 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, //Representatives sat item
    "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"
    }
}
Importante: Si el RFC no se encuentra en el sistema del SAT, el campo status será "fail", el array certificates estará vacío, y el validationMessage indicará el motivo del fallo. En estos casos, el item sat de tipo representantes se completara con internal status "sat_scrap_failed". Verifica que el RFC sea correcto y esté registrado en el SAT.