Saltar al contenido principal
ShieldID

Inicio rápido

La guía de inicio rápido de verificación de identidad.

De la clave de sandbox al primer webhook firmado, en orden. Cada paso incluye un ejemplo funcional: cópielo, reemplace su propia clave y sus URL, y ejecútelo.

Solicitar una clave de sandboxReferencia completa de la API

Paso a paso

Siete pasos, una tarde.

  1. Obtenga una clave de sandbox

    Las claves de sandbox (prefijo vk_sand_) se emiten por solicitud mientras se desarrolla el registro de autoservicio. Solicítela mediante el formulario de contacto: la mayoría de las solicitudes se resuelven el mismo día hábil. Las sesiones de sandbox nunca se facturan, así que no hay motivo para esperar.

  2. Cree su primera sesión

    Una sola llamada. Envíe un return_url (donde llega el solicitante al terminar) y un webhook_url (a donde se envía el resultado firmado). Recibirá un session_id y un verification_url.

    bash
    curl -X POST https://api.shieldid.ca/v1/sessions \
  -H "X-Api-Key: vk_sand_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.example/verified",
    "webhook_url": "https://yourapp.example/hooks/shieldid",
    "expected_name": "Jordan Smith",
    "locale": "en",
    "metadata": { "application_id": "app_9182" }
  }'

  3. Entregue el enlace al solicitante

    Abra verification_url y verá la página alojada. En un navegador de escritorio muestra un código QR: al escanearlo, el mismo enlace se abre en un teléfono, que es donde ocurren la foto del documento, el desafío de prueba de vida y la selfie. Pruébelo ahora mismo en su propio teléfono.

  4. Configure un punto de conexión de webhook

    Dirija webhook_url a una ruta que acepte un POST, lea el cuerpo crudo de la solicitud (lo necesita sin procesar para comprobar la firma) y devuelva un estado 2xx. En cualquier otro caso, ShieldID reintenta la entrega hasta tres veces.

    javascript
    import express from "express";
const app = express();

app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  // Verify the signature before you trust this body — see the next step.
  console.log("Received a webhook:", req.body.toString());
  res.status(200).send("ok");
});

app.listen(3000);

  5. Verifique la firma

    No actúe sobre el cuerpo de un webhook hasta comprobar que realmente proviene de ShieldID. Calcule un HMAC-SHA256 sobre el cuerpo crudo con su secreto de webhook y compárelo con el encabezado X-Bio-Signature.

    javascript
    import crypto from "node:crypto";

function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader || "";
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
  if (!ok) return res.status(401).send("invalid signature");

  const result = JSON.parse(req.body);
  // result.session_id, result.status, result.checks, …
  res.status(200).send("ok");
});

  6. Lea el resultado

    La carga útil del webhook ya contiene todo lo que necesita. Si prefiere obtener el resultado por su cuenta (por ejemplo, después de una redirección), llame directamente al punto de conexión de resultados.

    bash
    curl https://api.shieldid.ca/v1/sessions/ses_9f2c1a/result \
  -H "X-Api-Key: vk_sand_your_key"

# → { "session_id": "ses_9f2c1a", "status": "VERIFIED", "checks": { "document": "PASS", … }, … }

  7. Maneje FAILED y un reintento

    Una sesión que llega a FAILED incluye un failure_reason. Muestre al solicitante algo útil. Próximamente: reintentar una sesión FAILED para restablecerla a PENDING. Hoy, trate FAILED como estado final y cree una nueva sesión si el solicitante desea intentarlo de nuevo.

Antes de activar el cambio

Pase a producción.

La estructura de la solicitud nunca cambia entre sandbox y producción: solo cambia la clave. Confirme estos puntos antes de enviar a un solicitante real por una sesión vk_live_.

  • Cambie vk_sand_ por una clave vk_live_. Nada más de la solicitud cambia.
  • Dirija webhook_url a un punto de conexión real y siempre disponible que verifique la firma, no a un servicio de captura de solicitudes ni a una laptop.
  • Maneje en su aplicación los tres estados finales: VERIFIED, FAILED y EXPIRED, no solo el camino ideal.
  • Confirme que su return_url lea los parámetros de consulta session_id y status que ShieldID agrega en la redirección.
  • Consulte los precios vigentes con GET /v1/pricing/{country} o en la página de precios, para que los cargos de producción no sean una sorpresa.
  • Mantenga las claves de sandbox fuera de todo lo que un solicitante real pueda alcanzar: una sesión de sandbox es gratuita porque no es real.

Preguntas

Preguntas frecuentes de la guía de inicio rápido.

Comience ahora

Ejecute el primer paso ahora mismo.

Solicite una clave de sandbox, pegue el primer comando cURL en una terminal y ya llevará ventaja sobre la mayoría de las integraciones.

Solicitar una clave de sandboxReferencia completa de la API