Guía de integración de @singula_systems/identity-js

Tu API key (sk_live_*) nunca llega al browser: el servidor crea la sesión y sólo el token de corta vida viaja al front-end. El widget lo acepta con o sin el prefijo vt_. Los permisos de cámara los otorga el origen de Singula, no el tuyo. Y el veredicto de registro vive del lado del servidor: onComplete es UX, no autorización.

Es la misma sesión: puedes mandar el link por WhatsApp a quien no está en tu web y abrir el widget a quien sí. Un <iframe> crudo con embed_url y sin la librería también carga, pero entonces el handshake init lo haces tú; sin él la página cierra con origin_unknown.

Cuando la tubería no pudo dar un veredicto no hay nada que afirmar sobre la persona, así que la sesión va a revisión humana en lugar de decir que fue rechazada.

Ninguna ruta de identidad acepta la API key como parámetro de la URL, el stream de eventos incluido: una llave en la URL se filtra en logs y referrers.

La lista gobierna el enmarcado. verification_url se abre como pestaña propia (correo, SMS, WhatsApp) y no tiene padre a quien autorizar. En las tres fallas de arriba la captura nunca empieza.

Si el cliente ya tenía una verificación pendiente se devuelve ESA con reused: true: no se cobra de nuevo y NO se le cambian las opciones. Para empezar de cero, cancela la anterior con POST …/customer/{customerId}/cancel (cancelar no consume saldo).

Con una INE, un pasaporte o una tarjeta de residente y un cliente con CURP, la sesión coteja la CURP, el nombre, la fecha de nacimiento y el sexo del documento contra RENAPO, sin cargo extra: reusa la validación de CURP que ya exista para esa CURP y, si no hay ninguna, corre una por dentro cuando la verificación se lanza, sin cobrarla (sale en tu actividad con bundled_with). Una validación de CURP que pidas tú —POST /app/curp/validate o un paso de CURP en un flujo— sí se cobra. La INE se consulta además en la Lista Nominal: llega después del veredicto, sobre el mismo request_id, con el webhook identity.listanominal.completed. Es la misma regla por la API, el panel, el SDK, los links y los flujos.

Un <script> de tercero es código que delegas a un CDN. Fija la versión exacta y deja que el navegador verifique los bytes con integrity (ver el panel): así un objeto mal servido falla cerrado en vez de ejecutarse. El hash vale para UN archivo, así que no sirve con un alias móvil ni entre versiones.

Las etapas y el veredicto son independientes: cinco etapas en passed no implican una decisión, y con el veredicto retenido la etapa decision no llega nunca. Guía tu UI por onComplete, y el veredicto léelo en tu servidor.

Nunca otorgues nada con base en un callback del browser: describe lo que la página frente a esa persona dice que pasó, y quien tiene el teclado puede llamar tu handler con lo que quiera. Usa requestId para preguntarle a TU backend, que tiene la API key.

El veredicto llega minutos después del envío, por un canal que puede morir (la pestaña se congela, la sesión se cancela). El SDK arma un respaldo al detectar el envío: si no llega nada en verdictTimeoutMs (35 min) dispara verdict_timeout una vez. retryStage() está reservado: hoy la página hospedada no lo atiende.

Con wrong_document la foto es de OTRA identificación: detected_document_type dice cuál. La página hospedada lo dice así —«Esta foto parece de tu tarjeta de residente» / «Aquí necesitamos el reverso de tu INE»— con «Tomar otra vez» y, sólo si la sesión también ofrece el documento detectado, «Usar mi tarjeta de residente»: cambia de documento y abre su captura desde su primer lado, conserva la prueba de vida (nunca se repite) y, al tomar su último lado, va directo al envío. En el primer lado del documento nuevo, «Regresar» deshace el cambio. Si la página no reconoce el documento, dice «Esta foto parece de otro documento» y sólo ofrece tomarla otra vez. Con tus propias pantallas, cambiar de documento es confirmar las fotos del nuevo y nombrarlo al enviar: desde MasterApi 1.130.0 submit acepta { "document_type": "resident_card" } (ine, passport o resident_card), que manda sobre la inferencia —sin él, la sesión verifica el documento de la ÚLTIMA foto del documento confirmada, y la confirmación lenta del documento que se dejó puede llegar después—. Tiene que ser uno que la sesión ofrece y con sus fotos; una foto de un documento que la sesión no ofrece contesta 400 document_type_not_offered.

Se revisan hasta tres fotos de cada lado (max_attempts). Con la tercera, retake_suggested llega en false aunque la foto siga mal: lanza la verificación, y una cuarta foto llega como unavailable. Nunca repitas la prueba de vida: sólo la foto que se pidió. El veredicto decide como siempre: un documento que no se pudo leer sale failed (revisión), un dígito verificador que falla sobre una foto de baja calidad sale partial (revisión) con el control retake_suggested, y lo que se rechaza hoy se sigue rechazando.

Confirmar otra vez la MISMA foto no cuenta como foto nueva ni la vuelve a revisar. La ruta se autentica con el token, como presign y confirm: 404 si no existe, 409 si la sesión ya se envió, 410 si venció; 300 consultas por minuto por sesión y 3000 por IP (desde MasterApi 1.130.0), y nunca devuelve llaves de S3. Las demás rutas de la captura tienen su propio tope por minuto: presign, confirm y la subida multipart, 600 por sesión y 3000 por IP; submit, 60 y 600. Pasado un tope contestan 429 con Retry-After, los segundos para reintentar. Ni la revisión ni las fotos repetidas se cobran: la verificación se cobra como siempre, una vez, con su veredicto. En sandbox contesta ok sin revisar nada, y la subida multipart obsoleta no tiene revisión previa.

Con @singula_systems/identity-js 0.7.0 o posterior, onRetake({ side, reason, attempt }) llega cada vez que la página pide otra foto: side es front o back (la página de datos del pasaporte es front), reason es uno de los nueve códigos de arriba y attempt es 1 en la primera repetición de ese lado y 2 en la segunda. Desde 0.8.0, con wrong_document llega además detectedDocumentType: ine, passport o resident_card (en minúsculas; en el mensaje, detected_document_type), y no viene si la página no reconoció el documento. Un SDK 0.7.0 recibe wrong_document como unreadable, y con 0.7.0 o anterior una captura con tarjeta de residente deja de mandar onStepChange (descarta el documento que no conoce): actualiza a 0.8.0. Viaja como el mensaje document_retake. Es sólo informativo —la página ya pide la foto sola— y una versión anterior del SDK lo ignora.

Aparte de la revisión previa, el resultado final puede traer el control retake_suggested, en false: un dígito verificador del MRZ falló sobre una foto de baja calidad y por eso la sesión quedó en partial (revisión) y no en rejected, o la zona de abajo del reverso de una INE no se pudo leer y la sesión quedó en partial y no en verified. Es informativo, no cuenta en el score y su details dice qué hacer: pedir otra foto. Ver la regla dura en Cómo se calcula el score.

El objeto verification crudo se conserva tal cual: quien ya leía de ahí no tiene que cambiar nada. 404 si ese requestId no es de tu organización.

network trae las IPs confiables de la sesión —la que vio nuestro servidor, nunca un X-Forwarded-For del cliente— con país, ASN y si son Tor, nube/hosting/VPN o iCloud Private Relay. Es una señal: no cobra y nunca sale en el webhook. La IP de quien sube las fotos también cuenta: si tu backend las sube desde una nube con POST /app/identity-verification/submit/:token, esa IP es de hosting y, en un expediente KYC, ip_not_hosting lo manda a revisión (nunca a rechazo). Súbelas desde el dispositivo de la persona —el link hospedado o el widget— o apaga kyc.checks.ip_not_hosting (y ip_country_vs_document si tu servidor está fuera de México) en la política de verificación. País y ASN salen de una base abierta de geolocalización de IP. Si los muestras en tus pantallas, incluye los créditos de datos de singula.mx/creditos.

Una categoría sin checks en esa verificación no cuenta como cero: su peso se reparte en proporción entre las que sí están, para que la falta de una señal no baje el score. El caso típico es RENAPO: en una INE sin registro de RENAPO (el cliente no tiene CURP, o RENAPO no la confirmó) los pesos quedan en 66.7 % críticos, 20 % consistencia interna y 13.3 % calidad (cada uno entre 0.75). El pasaporte y la tarjeta de residente se califican con la misma regla sobre sus propios checks: lo impreso y la CURP contra su MRZ cuentan en consistencia interna, y con un cliente con CURP traen también la categoría de RENAPO.

Si falla la prueba de vida, el cotejo facial o un dígito verificador de la MRZ, el veredicto es rejected (decision: declined) sin importar el score. Se revisa antes que las bandas: el score se calcula igual y viaja en la respuesta, pero no rescata un rechazo. Un score de 0.87 con la prueba de vida fallida sigue siendo un rechazo. En un pasaporte cuentan como críticos los dígitos verificadores de su número, de la fecha de nacimiento, del vencimiento y el compuesto; el del número personal opcional, no. Un pasaporte vencido o con una fecha de nacimiento imposible nunca sale verified: a lo más partial (decision: review), aunque el score pase de 0.85. Y uno cuya MRZ no se pudo leer sale failed. En la tarjeta de residente son críticos los dígitos verificadores del número de documento, de la fecha de nacimiento, del campo de vencimiento de su MRZ y el compuesto. Una tarjeta vencida, con una fecha de nacimiento imposible o que no expidió México nunca sale verified, y tampoco una temporal cuyo vencimiento impreso no se pudo leer (o no cae entre su expedición y cuatro años después), una cuyo MRZ no es el de una tarjeta del INM, ni una cuyo frente no trae el nombre del MRZ o cuya fecha de expedición impresa no es la del MRZ: el frente de otra persona; una permanente no vence. Sin MRZ legible, sale failed. Una excepción, en la INE, el pasaporte y la tarjeta de residente: un dígito verificador que falla sobre una foto de baja calidad —sin falla de rostro ni de prueba de vida— no rechaza: la sesión sale partial (decision: review) con el control retake_suggested, porque con esa foto el dígito pudo leerse mal. Con una foto buena sigue siendo un rechazo. Y una INE cuya zona de abajo del reverso (la MRZ) no se pudo leer nunca sale verified: a lo más partial (decision: review), también con retake_suggested.

Son evidencia de auditoría y hasta 30 firmas más, así que por defecto no se firman. Pídelos con include_frames=true cuando de verdad los vayas a revisar.

end { reason: "timeout" } es el corte de 15 minutos de ESE stream, con la sesión todavía abierta: reconecta o lee status/{requestId}. Sólo terminal cierra la historia. Una verificación la completa una persona: tarda lo que tarda.

X-Singula-Signature llega como t=<unix>,v1=<hmac>, donde el HMAC-SHA256 se calcula sobre `${t}.${rawBody}` con el secreto de tu webhook. Calcúlalo sobre el cuerpo CRUDO, antes de parsearlo. El evento también viaja en X-Singula-Event.

Con un webhook dado de alta en el dashboard recibes el sobre { id, type, created, data } firmado y con reintentos: lee body.data. Por la ruta de respaldo (sin webhook dado de alta) el mismo objeto llega plano y sin firma. Sandbox manda exactamente el mismo payload, así que lo que integres contra pruebas funciona en producción.

El gate es sólo para el browser. status y result con API key y el webhook identity.completed siguen entregando el veredicto completo, lo expongas o no. Escribe el manejo de withheld desde el primer día: es lo que emite una organización recién configurada.

Una página que se remonta después del envío no pinta «enlace usado»: falta el veredicto, así que sigue consultando el estado y muestra «recibimos tu verificación». La pantalla de enlace muerto es sólo para completed, cancelled y expired.

Los overrides viajan dos veces: como parámetros de la URL, para el primer pintado, y por el mensaje init una vez que el iframe está listo, que es el canal autoritativo. Una opción rechazada lanza sin dejar nada montado.

Tres capas, y cada una pisa sólo los campos que trae: la marca de tu ORGANIZACIÓN (Ajustes › Marca) es la base; un FLUJO puede traer la suya en settings.ui, congelada en la versión publicada; y theme, en la llamada, gana sobre las dos y vale sólo para esa sesión. Sin theme, la sesión se ve como el flujo —o como la organización, si el flujo no fijó apariencia—. El objeto se manda igual para una verificación de identidad y para un flujo: es el mismo Identity.open.

La captura es pública (el token es la auth), así que el ambiente no se decide ahí: se hereda de la llave con la que creaste la verificación. Desde el panel lo fija su modo: en «Sandbox» manda X-Singula-Env: sandbox y la verificación nace de prueba, gratis, como con sk_test_. Misma forma de respuesta que producción, para que lo que integres en pruebas no cambie al pasar a vivo.

La identidad, la INE, la CURP ante RENAPO y el correo verificado del sandbox son todos de la misma persona de ejemplo: MARIA LOPEZ GARCIA, CURP LOGM900101MDFPRR02, nacida el 1990-01-01. Las listas de sanciones y el judicial sí contestan con el nombre que de verdad se buscó —el de tu cliente—, y lo devuelven en queries. Eso es a propósito: un expediente KYC de pruebas que cruzara a dos personas distintas nunca podría aprobar.