Respuestas por tipo de ítem

Este documento describe la estructura de respuesta del API para cada item_type. Úsalo para validar contratos y mapear las respuestas.

Ver listado de tipos: Tipos de Ítems
Cómo leer las respuestas: Leer información vía API
Estados y flujos: Estados de verificación

Estructura base de un ítem en las respuestas

A nivel superior, todos los ítems comparten la misma estructura.

{
  "id": 123,
  "item_order": 1,
  "item_status": "pending|needs-review|complete|error",
  "item_type": "<item_code>",
  "item_internal_status": "...",
  "item_error": "string (ver detalle abajo)",
  "item_value": {
    /* según el item_type */
  },
  "item_options": {
    "upload_url": "https://...",
    "item_type_guide": "...",
    "item_label": "...",
    "is_optional": false
  },
  "original_file_url": "https://..."
}

Nota: item_type es el código del ítem (por ejemplo, ac_mx, csf_mx, siger, ubos). El campo item_value usa snake_case y su estructura depende del item_type.

Extracciones personalizadas: si tu cuenta tiene una extracción personalizada activa para el tipo, item_value incluye además una llave cp_<prompt_id> por cada extracción con resultado. Ese prefijo solo aplica a tipos de documento estándar: los tipos de ítem personalizados (cit_*) exponen sus resultados en item_value.pipeline. item_error: Campo opcional que indica errores públicos relacionados con el procesamiento del ítem. Su valor depende del item_type. Códigos más comunes:

Documentales: password_protected_pdf (PDF con contraseña), get_input_file_info_failed (falló obtener el archivo de entrada).
doc_splitter: unsupported_file_type, unknown_custom_item_type, misconfigured_custom_item_type, no_splits_returned, pdf_slice_failed, pdf_slice_upload_failed, doc_splitter_request_failed. Detalle en la guía del divisor de documentos.
doc_validation: invalid_document_type, ruleset_validation_failed.

Trata este campo como un string opaco: pueden llegar otros códigos específicos por item_type (por ejemplo prevalidation_failed en csf_mx). El listado completo vive en el schema PublicVerificationItem.item_error del OpenAPI.

Índice rápido

Widgets: ubos, forms
Integraciones: aml_validation, signatory_validation
Otros: document, doc_classification, unknown, generic, error, cit_*

Para items de documentos y consultas públicas específicos de un caso de uso (KYB México, KYB Colombia, KYB Estados Unidos, KYB Todos los países, Hipotecas, Nómina), consulta la guía correspondiente en Guías por caso de uso en la barra lateral.

Widgets

`ubos` — Beneficiarios finales

{
  "item_type": "ubos",
  "item_value": {
    "ubos": {
      "data": [
        {
          "currency": "MXN",
          "id_number": "12345678",
          "id_type": "INE",
          "name": "Ana María López Rodríguez",
          "email": "ana.lopez@email.com",
          "type": "Accionista",
          "share_percentage": 25,
          "documents": [
            { "key": "documento-identidad.pdf", "bucket": "trebol-documents" }
          ],
          "upload_urls": [
            {
              "index": 0,
              "url": "https://s3.amazonaws.com/trebol-documents/documento-identidad.pdf"
            }
          ],
          "external_identities": {
            "curp": {
              "success": true,
              "message": "CURP validado exitosamente",
              "applicant_data": {
                "curp": "LORA800101MDFXXX01",
                "names": "Ana María",
                "gender": "M",
                "birth_date": "1980-01-01",
                "birth_entity": "Distrito Federal",
                "nationality": "Mexicana",
                "first_surname": "López",
                "second_surname": "Rodríguez",
                "evidentiary_document": "Acta de nacimiento"
              },
              "evidentiary_document_data": {
                "act_number": "123456",
                "registry_date": "1980-01-15",
                "register_entity": "Distrito Federal",
                "register_municipality": "Cuauhtémoc"
              },
              "curp_file": "https://curp.gob.mx/curp/consultaCurp.jsp"
            }
          },
          "shareholders": [
            /* estructura anidada de UBO */
          ],
          "aux": {}
        }
      ]
    }
  }
}

`forms` — Formularios de onboarding

{
  "item_type": "forms",
  "item_value": {
    "account_id": "acc_123456789",
    "form_schema": {},
    "ui_schema": {},
    "form_values": {},
    "aux": {}
  }
}

Integraciones

`aml_validation`

{
  "item_type": "aml_validation",
  "item_value": {
    "validation_provider": "compliance_check",
    "validation_data": [
      /* AMLItemValidationData[] */
    ]
  }
}

`signatory_validation`

{
  "item_type": "signatory_validation",
  "item_value": {
    "id_number": "1234567890123456",
    "id_type": "INE",
    "email": "firmante@empresa.com",
    "name": "Roberto Carlos Méndez Silva",
    "nationality": "Mexicana",
    "confirmation_date": "2024-01-01T00:00:00Z",
    "confirmation_ip_address": "192.168.1.100",
    "confirmation_check_boxes": {
      "data": [{ "text": "Acepto los términos y condiciones", "checked": true }]
    },
    "validation_date": "2024-01-01T00:00:00Z",
    "validation_result": "valid",
    "validation_name": "Roberto Carlos Méndez Silva",
    "validation_data": {
      "ocr": {
        "name": {
          "full_name": "Roberto Carlos Méndez Silva",
          "paternal_last_name": "Méndez",
          "maternal_last_name": "Silva"
        },
        "document_number": "1234567890123456"
      },
      "scores": { "overall": { "status": "passed", "value": 95 } }
    },
    "name_comparison_result": true
  }
}

Otros

`document` — Extractor de documentos (genérico)

Este ítem agrupa distintos extractores de documentos bajo un mismo item_type. La forma de la respuesta es:

{
  "item_type": "document",
  "item_value": {
    "type": "<document_type>",
    "payload": {
      /* estructura depende de <document_type> */
    }
  }
}

“type”: uno de los tipos soportados.
“payload”: objeto JSON con los datos extraídos. La estructura varía por tipo y corresponde a los esquemas JSON del AI Prompter.

Tipos soportados (type):

property_deed
lien_certificate
property_tax_receipt
property_appraisal
payroll_receipt
camara_comercio_co_extractor
trust_contract_fideicomiso_extractor
union_documents_extractor
designacion_responsable_cumplimiento_extractor
registro_actividades_vulnerables_extractor
irs_ein_assignment_letter_extractor
certificate_of_incumbency_extractor
certificate_of_incorporation_extractor
fincen_msb_registration_extractor
financial_statements_any

Notas:

La estructura exacta de payload depende del type y se define en los esquemas del AI Prompter.
La respuesta pública expone payload ya “normalizado” como JSON plano según el esquema correspondiente.

Dónde encontrar la estructura de cada `type`

La estructura detallada de respuesta de cada type vive en la guía del caso de uso correspondiente:

trust_contract_fideicomiso_extractor, union_documents_extractor, financial_statements_any: KYB Todos los países
camara_comercio_co_extractor: KYB Colombia — Items de documentos
designacion_responsable_cumplimiento_extractor, registro_actividades_vulnerables_extractor: KYB México — Items de documentos
property_deed, lien_certificate, property_tax_receipt, property_appraisal: Hipotecas — Items
payroll_receipt: Nómina — Items
certificate_of_incorporation_extractor, certificate_of_incumbency_extractor, irs_ein_assignment_letter_extractor, fincen_msb_registration_extractor: KYB Estados Unidos — Items de documentos

Tipos de ítem personalizados (`cit_*`)

Los ítems de un tipo de ítem personalizado llevan como item_type el name del tipo, siempre con prefijo cit_. Su item_value no tiene campos por tipo de documento: expone el resultado de cada proceso configurado en el tipo.

{
  "item_type": "cit_contrato_arrendamiento",
  "item_value": {
    "current_stage": "extraction",
    "pipeline": {
      "validation": [
        {
          "process_reference": "validar_firmas",
          "executed": true,
          "execution_result": true,
          "value": {
            "identifier": "activeVersionId_87",
            "validation_result": true,
            "explanation": "El contrato está firmado por ambas partes."
          }
        }
      ],
      "extraction": [
        {
          "process_reference": "extraer_datos_contrato",
          "executed": true,
          "execution_result": "success",
          "value": {
            "landlord_name": "María López García",
            "monthly_rent": 15000
          }
        }
      ]
    }
  }
}

pipeline.extraction[].value: el JSON extraído, con las claves del json_schema de tu proceso. Es null si el proceso no corrió o falló.
pipeline.validation[].execution_result: true o false según se haya cumplido la regla.
Estos ítems no llevan llaves cp_<prompt_id>. Detalle del contrato en Dónde salen los resultados.