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

{
  "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
  "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verification_url": "https://app.singula.mx/verify/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "embed_url": "https://app.singula.mx/embed/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-09-14T18:45:00.000Z",
  "redirect_url": "https://acme.com/kyc/listo",
  "external_id": "ord_123",
  "metadata": { "plan": "pro" },
  "document_types": ["ine"],
  "language": "es"
}

{
  "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
  "session_status": "completed",
  "decision": "approved",
  "score": 0.95,
  "verdict": "verified",
  "result": {
    "status": "verified",
    "document_type": "INE",
    "overall_confidence": 0.95,
    "extracted_data": {
      "nombre": "JUAN",
      "apellido_paterno": "PEREZ",
      "apellido_materno": "LOPEZ",
      "curp": "PELJ900101HDFRPN07",
      "fecha_nacimiento": "1990-01-01",
      "vigencia": "2030"
    },
    "checks": [
      { "check_name": "curp_validation", "passed": true, "confidence": 1.0 },
      { "check_name": "mrz_check_digits", "passed": true, "confidence": 1.0 }
    ],
    "face_result": {
      "match_score": 0.82, "match_decision": true,
      "liveness_score": 0.91, "liveness_decision": true
    }
  },
  "external_id": "ord_123",
  "metadata": { "plan": "pro" },
  "submitted_at": "2026-09-11T12:00:00.000Z",
  "completed_at": "2026-09-11T12:03:00.000Z",
  "verification": { "…": "documento crudo de la sesión (token, status, s3_keys, device_info, opens…)" }
}

{
  "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
  "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verification_url": "https://app.singula.mx/verify/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "embed_url": "https://app.singula.mx/embed/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-09-14T18:45:00.000Z",
  "redirect_url": "https://acme.com/kyc/listo",
  "external_id": "ord_123",
  "metadata": { "plan": "pro" },
  "document_types": ["ine"],
  "language": "es"
}

// onStage fires once per stage transition (iframe → parent):
{ "stage": "received",   "status": "passed" }
{ "stage": "liveness",   "status": "running" }
{ "stage": "liveness",   "status": "passed",  "score": 0.91 }
{ "stage": "face_match", "status": "passed",  "score": 0.82 }
{ "stage": "document",   "status": "passed" }
{ "stage": "decision",   "status": "passed" }

// With the verdict withheld (the DEFAULT) the 'decision' stage never
// arrives — the page cannot report 'passed' for a verdict it does not know.

{
  "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
  "session_status": "completed",
  "decision": "approved",
  "score": 0.95,
  "verdict": "verified",
  "result": {
    "status": "verified",
    "document_type": "INE",
    "overall_confidence": 0.95,
    "extracted_data": {
      "nombre": "JUAN",
      "apellido_paterno": "PEREZ",
      "apellido_materno": "LOPEZ",
      "curp": "PELJ900101HDFRPN07",
      "fecha_nacimiento": "1990-01-01",
      "vigencia": "2030"
    },
    "checks": [
      { "check_name": "curp_validation", "passed": true, "confidence": 1.0 },
      { "check_name": "mrz_check_digits", "passed": true, "confidence": 1.0 }
    ],
    "face_result": {
      "match_score": 0.82, "match_decision": true,
      "liveness_score": 0.91, "liveness_decision": true
    }
  },
  "external_id": "ord_123",
  "metadata": { "plan": "pro" },
  "submitted_at": "2026-09-11T12:00:00.000Z",
  "completed_at": "2026-09-11T12:03:00.000Z",
  "verification": { "…": "documento crudo de la sesión (token, status, s3_keys, device_info, opens…)" }
}

{
  "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
  "session_status": "submitted",
  "decision": null,
  "score": null,
  "verdict": null,
  "result": null,
  "files": {
    "ine_front": "https://s3…/ine_front.jpg?X-Amz-Signature=REDACTED",
    "ine_back":  "https://s3…/ine_back.jpg?X-Amz-Signature=REDACTED",
    "selfie":    "https://s3…/selfie.jpg?X-Amz-Signature=REDACTED"
  },
  "files_expires_at": "2026-09-11T12:10:00.000Z"
}

event: session
data: {"request_id":"6622f8a1c1d2e3f4a5b6c7d8","session_status":"submitted","decision":null,
       "score":null,"verdict":null,"external_id":"ord_123","metadata":{"plan":"pro"},
       "submitted_at":"2026-09-11T12:00:00.000Z","completed_at":null}

event: keepalive
data: {"at":"2026-09-11T12:00:15.000Z"}

event: session
data: {"request_id":"6622f8a1c1d2e3f4a5b6c7d8","session_status":"completed",
       "decision":"approved","score":0.95,"verdict":"verified",
       "completed_at":"2026-09-11T12:03:00.000Z"}

event: end
data: {"reason":"terminal"}

// Singula → tu endpoint. El mismo sobre firmado de todas las herramientas:
// POST https://your-server.com/webhooks/singula
// X-Singula-Signature: t=1757596980,v1=<hmac-sha256("<t>.<raw body>", secret)>
// X-Singula-Event: identity.completed
// X-Singula-Delivery-Id: <id de la entrega>

{
  "id": "6b1f…",                    // id de la entrega
  "type": "identity.completed",
  "created": 1757596980,             // unix, en segundos
  "data": {
    "event": "identity.completed",
    "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
    "customer_id": "cus_9f2a7c410b8e",
    "tool_type": "identityVerification",
    "status": "success",
    "session_status": "completed",
    "decision": "approved",          // approved | review | declined | null
    "verdict": "verified",           // verified | partial | rejected | failed
    "score": 0.95,                   // 0..1
    "document_type": "INE",
    "external_id": "ord_123",
    "metadata": { "plan": "pro" },
    "completed_at": "2026-09-11T12:03:00.000Z"
  }
}

// Ajustes › Marca › Resultado de la verificación → Apagado (el DEFAULT)

// 1. What the browser gets (GET /app/embed/status/:token, token-auth):
{
  "data": {
    "request_id": "6622f8a1c1d2e3f4a5b6c7d8",
    "session_status": "completed",
    "decision": null,
    "score": null,
    "verdict_withheld": true,
    "redirect_url": "https://acme.com/kyc/listo",
    "started_on_desktop": false
  }
}

// 2. What the widget emits:
onComplete({ decision: 'withheld', requestId: '6622f8a1c1d2e3f4a5b6c7d8' })  // no score

// 3. Where the verdict of record lives (API key / webhook):
GET /app/identity-verification/status/6622f8a1c1d2e3f4a5b6c7d8  → decision: "approved"

// Escritorio → celular, sin que el token viaje en la barra del navegador.

// 1. QR: la «URL desktop» de tu organización con el relevo anexado
https://acme.com/kyc/continua-en-tu-celular?token=a1b2c3d4-e5f6-7890-abcd-ef1234567890&request_id=6622f8a1c1d2e3f4a5b6c7d8
// (o usa {token} / {request_id} en la URL para colocarlos donde quieras)

// 2. Mientras el QR está en pantalla, la página consulta el estado público
GET /app/embed/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890   // cada 3 s los primeros 5 min, luego cada 10 s

// 3. Al terminar en el celular, con redirect_url configurado:
https://acme.com/kyc/listo?request_id=6622f8a1c1d2e3f4a5b6c7d8&status=submitted
// NO viaja el token: con request_id tu servidor ya lee el resultado con su
// API key. Si hubo salto de dispositivo (started_on_desktop: true) la
// pantalla dice «regresa a tu computadora» y no redirige.

{
  "session_status": "completed",
  "decision": "approved",
  "verdict": "verified",
  "score": 0.95,
  "result": {
    "status": "verified",
    "document_type": "INE",
    "extracted_data": { "nombre": "JUAN", "apellido_paterno": "PEREZ",
                        "curp": "PELJ900101HDFRPN07" }
  }
}

// onError — fatal errors only. The flow cannot continue.
{
  "code": "origin_not_configured",
  "message": "This organization has no allowed origins configured."
}

// In modal mode a fatal error also closes the widget with onClose('error').
// In inline mode the widget stays mounted so your page renders its fallback.