PostMessage Events

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"
    }
  ]
}

string

Folio del expediente asignado por KYB. Puede estar vacio si el expediente aun no ha sido enviado.

string (GUID)

Identificador unico del expediente dentro de KYB.

string

Identificador externo proporcionado por tu sistema al crear el expediente.

object

Resumen numerico del progreso del expediente.

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": [...]
}

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"
}

string

Folio definitivo asignado al expediente.

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.

Tipo	Nombre visible	Descripcion
`ArticleIncorporation`	Acta Constitutiva	Acta constitutiva de la empresa
`BankStatement`	Estado de Cuenta	Estado de cuenta bancario
`ConditionsLetter`	Carta Condiciones	Carta de condiciones
`PersonaFisica`	Personas Fisicas	Informacion de persona fisica
`LegalRepresentative`	Representantes Legales	Datos del representante legal
`ProofAddress`	Comprobante de Domicilio	Comprobante de domicilio
`TaxInformations`	Informacion Fiscal	Constancia de situacion fiscal
`Sucursal`	Sucursales	Informacion de sucursales
`Extra`	Adicional	Documentos adicionales
`Formulario`	Formulario	Formularios personalizados
`InformacionCrediticia`	Informacion Crediticia	Informacion crediticia
`TermsCondition`	Terminos y Condiciones	Aceptacion de terminos
`Facturacion`	Facturacion	Informacion de facturacion
`PoderesRepresentanteLegal`	Poderes de Representante Legal	Poderes notariales
`Accionistas`	Accionistas	Informacion de accionistas
`OrganosInternos`	Organos Internos	Organos internos de la empresa
`PuntosContacto`	Puntos de Contacto	Puntos de contacto
`Docflow`	Docflow	Documentos gestionados por Docflow

Status de seccion (`status`)

Cada seccion pasa por los siguientes estados durante el proceso de validacion:

Status	Descripcion
`Pendiente`	La seccion aun no ha sido cargada por el usuario
`EnRevision`	El documento fue cargado y esta siendo procesado o revisado
`RequiereAtencion`	El documento fue revisado y necesita correccion por parte del usuario
`Completado`	El documento fue cargado y validado exitosamente
`Aceptado`	El documento fue aceptado definitivamente por el analista
`Rechazado`	El 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:

Campo	Tipo	Descripcion
`percentage`	`number`	Porcentaje de completado (0-100)
`total`	`number`	Total de secciones en el expediente
`completed`	`number`	Secciones con status Completado o Aceptado
`pending`	`number`	Secciones con status Pendiente o EnRevision
`inReview`	`number`	Secciones en revision
`requiresAttention`	`number`	Secciones que requieren atencion del usuario
`rejected`	`number`	Secciones 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>

​Descripcion

​Configuracion

​Eventos disponibles

kyb_ready

kyb_section_updated

kyb_document_submitted

​kyb_ready

​kyb_section_updated

​kyb_document_submitted

​Tipos de seccion (type)

​Status de seccion (status)

​Objeto progress

​Ejemplo completo de integracion

Descripcion

Configuracion

Eventos disponibles

`kyb_ready`

`kyb_section_updated`

`kyb_document_submitted`

Tipos de seccion (`type`)

Status de seccion (`status`)

Objeto `progress`

Ejemplo completo de integracion