Skip to main content

​
Descripcion

Cuando integras KYB mediante iframe, tu aplicacion puede escuchar eventos postMessage para:
  • Saber cuando el iframe esta listo
  • Recibir actualizaciones de status de cada seccion en tiempo real
  • Detectar cuando el usuario final envia su expediente
Todos los eventos se envian desde el iframe hacia la ventana padre usando window.parent.postMessage().

​
Configuracion

Agrega un listener en tu pagina que contiene el iframe: 
window.addEventListener('message', (event) => {
  // Filtrar solo eventos de KYB
  if (!event.data?.type?.startsWith('kyb_')) return;

  switch (event.data.type) {
    case 'kyb_ready':
      // El iframe cargo correctamente
      break;
    case 'kyb_section_updated':
      // Una seccion cambio de status
      break;
    case 'kyb_document_submitted':
      // El expediente fue enviado
      break;
  }
});
Los eventos solo se envian cuando el iframe se carga con el parametro ?isiframe=true en la URL del guest. Ejemplo: https://app.nufi.mx/guest/{accessToken}?isiframe=true

​
Eventos disponibles

kyb_ready

Se dispara cuando el iframe termino de cargar y esta listo para interactuar.

kyb_section_updated

Se dispara cuando una seccion cambia de status (por ejemplo, un analista aprobo un documento).

kyb_document_submitted

Se dispara cuando el usuario final envia el expediente completo.

​
kyb_ready

Se envia una sola vez al terminar la carga inicial del iframe. Contiene el estado completo de todas las secciones. 
{
  "type": "kyb_ready",
  "folio": "NF-2026-001234",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "EXT-999",
  "progress": {
    "percentage": 25,
    "total": 4,
    "completed": 1,
    "pending": 2,
    "inReview": 0,
    "requiresAttention": 1,
    "rejected": 0
  },
  "allSections": [
    {
      "name": "Acta Constitutiva",
      "type": "ArticleIncorporation",
      "status": "Completado",
      "comments": ""
    },
    {
      "name": "Estado de Cuenta",
      "type": "BankStatement",
      "status": "RequiereAtencion",
      "comments": "El estado de cuenta tiene una antiguedad mayor a 3 meses"
    }
  ]
}
​
folio
string
Folio del expediente asignado por KYB. Puede estar vacio si el expediente aun no ha sido enviado.
​
id
string (GUID)
Identificador unico del expediente dentro de KYB.
​
externalId
string
Identificador externo proporcionado por tu sistema al crear el expediente.
​
progress
object
Resumen numerico del progreso del expediente.
​
allSections
array
Lista completa de todas las secciones del expediente con su status actual.

​
kyb_section_updated

Se envia cada vez que una seccion cambia de status. Incluye un array changes que indica exactamente que seccion cambio y de que status a cual. 
{
  "type": "kyb_section_updated",
  "folio": "NF-2026-001234",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "EXT-999",
  "changes": [
    {
      "name": "Estado de Cuenta",
      "type": "BankStatement",
      "previousStatus": "Pendiente",
      "newStatus": "RequiereAtencion",
      "comments": "El estado de cuenta tiene una antiguedad mayor a 3 meses"
    }
  ],
  "progress": {
    "percentage": 25,
    "total": 4,
    "completed": 1,
    "pending": 1,
    "inReview": 0,
    "requiresAttention": 2,
    "rejected": 0
  },
  "allSections": [...]
}
​
changes
array
Lista de secciones que cambiaron de status en esta actualizacion. Cada elemento contiene:
  • name: Nombre legible de la seccion
  • type: Tipo tecnico de la seccion (ver tabla de tipos)
  • previousStatus: Status anterior
  • newStatus: Status nuevo
  • comments: Comentarios del analista (si aplica)
El array changes puede contener multiples secciones si varias cambiaron al mismo tiempo. Si changes esta vacio, significa que la notificacion no produjo cambios visibles en los status.

​
kyb_document_submitted

Se envia cuando el usuario final hace clic en “Enviar” y el expediente se entrega exitosamente. Este es el evento mas importante para tu flujo: indica que puedes proseguir con los siguientes pasos de tu lado. 
{
  "type": "kyb_document_submitted",
  "folio": "NF-2026-001234",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "EXT-999",
  "submittedAt": "2026-04-14T15:30:00.0000000Z"
}
​
folio
string
Folio definitivo asignado al expediente.
​
submittedAt
string (ISO 8601)
Fecha y hora UTC en que se envio el expediente.

​
Tipos de seccion (type)

Cada seccion tiene un type que indica el tipo de documento o informacion que contiene.
TipoNombre visibleDescripcion
ArticleIncorporationActa ConstitutivaActa constitutiva de la empresa
BankStatementEstado de CuentaEstado de cuenta bancario
ConditionsLetterCarta CondicionesCarta de condiciones
PersonaFisicaPersonas FisicasInformacion de persona fisica
LegalRepresentativeRepresentantes LegalesDatos del representante legal
ProofAddressComprobante de DomicilioComprobante de domicilio
TaxInformationsInformacion FiscalConstancia de situacion fiscal
SucursalSucursalesInformacion de sucursales
ExtraAdicionalDocumentos adicionales
FormularioFormularioFormularios personalizados
InformacionCrediticiaInformacion CrediticiaInformacion crediticia
TermsConditionTerminos y CondicionesAceptacion de terminos
FacturacionFacturacionInformacion de facturacion
PoderesRepresentanteLegalPoderes de Representante LegalPoderes notariales
AccionistasAccionistasInformacion de accionistas
OrganosInternosOrganos InternosOrganos internos de la empresa
PuntosContactoPuntos de ContactoPuntos de contacto
DocflowDocflowDocumentos gestionados por Docflow

​
Status de seccion (status)

Cada seccion pasa por los siguientes estados durante el proceso de validacion:
StatusDescripcion
PendienteLa seccion aun no ha sido cargada por el usuario
EnRevisionEl documento fue cargado y esta siendo procesado o revisado
RequiereAtencionEl documento fue revisado y necesita correccion por parte del usuario
CompletadoEl documento fue cargado y validado exitosamente
AceptadoEl documento fue aceptado definitivamente por el analista
RechazadoEl documento fue rechazado
Los status Completado y Aceptado se consideran “terminados” para el calculo de progreso. Los status Pendiente y EnRevision se consideran “pendientes”.

​
Objeto progress

El objeto progress aparece en los eventos kyb_ready y kyb_section_updated. Resume el avance general del expediente:
CampoTipoDescripcion
percentagenumberPorcentaje de completado (0-100)
totalnumberTotal de secciones en el expediente
completednumberSecciones con status Completado o Aceptado
pendingnumberSecciones con status Pendiente o EnRevision
inReviewnumberSecciones en revision
requiresAttentionnumberSecciones que requieren atencion del usuario
rejectednumberSecciones rechazadas

​
Ejemplo completo de integracion

<iframe
  id="kyb-iframe"
  src="https://app.nufi.mx/guest/ACCESS_TOKEN?isiframe=true"
  style="width: 100%; height: 800px; border: none;">
</iframe>

<script>
  window.addEventListener('message', (event) => {
    if (!event.data?.type?.startsWith('kyb_')) return;

    const { type, folio, id, externalId, progress, changes, allSections, submittedAt } = event.data;

    switch (type) {
      case 'kyb_ready':
        console.log('KYB iframe listo');
        console.log(`Progreso inicial: ${progress.percentage}%`);

        // Renderizar estado inicial de secciones
        allSections.forEach(section => {
          updateSectionUI(section.name, section.status);
        });
        break;

      case 'kyb_section_updated':
        console.log('Seccion actualizada');

        // Actualizar solo las secciones que cambiaron
        changes.forEach(change => {
          console.log(`${change.name}: ${change.previousStatus} -> ${change.newStatus}`);
          updateSectionUI(change.name, change.newStatus);

          if (change.comments) {
            showComment(change.name, change.comments);
          }
        });

        // Actualizar barra de progreso
        updateProgressBar(progress.percentage);
        break;

      case 'kyb_document_submitted':
        console.log(`Expediente enviado. Folio: ${folio}`);
        console.log(`External ID: ${externalId}`);
        console.log(`Enviado: ${submittedAt}`);

        // Habilitar siguiente paso en tu flujo
        enableNextStep(folio, externalId);
        break;
    }
  });
</script>