Saltar al contenido
PredictoFace API 1.0
Índice

Documentación de la API

PredictoFace verifica la identidad de una persona con su rostro: prueba de vida decidida en el servidor, comparación con su documento y un recibo con firma electrónica por cada operación. Esta guía explica cómo integrarla desde el servidor de su empresa.

Introducción

La forma recomendada de integrar es el flujo alojado: su servidor crea una sesión, la persona hace la verificación en la página de PredictoFace desde el celular o el computador y vuelve a su sitio con un token firmado. Su sitio no maneja la cámara, las imágenes ni los videos.

Responsable y encargado
Su empresa es la responsable del tratamiento: decide para qué y con qué autorización. Novvai Systems S.A.S. es la encargada: procesa el rostro por cuenta suya, según el contrato de transmisión de datos.
Una pila por cliente
Cada cliente tiene su propia infraestructura en AWS: llaves de firma y de datos, tabla, API key, cortafuegos y alarmas. Nada se comparte con otros clientes y los recibos de cada uno se firman con su propia llave.
Titular seudónimo
Usted identifica a la persona con un subject_ref propio (8 a 128 caracteres; letras, números, . _ : -). No puede ser un número de documento, un correo ni un nombre: la API lo rechaza.
Recibo firmado
Cada operación produce un recibo en JSON canónico (RFC 8785) firmado con ECDSA P-256 en AWS KMS. Cualquiera puede verificarlo con la llave pública, sin acceso a la API.

URL base de la pila de demostración: https://attest.novvai.systems. Su pila de producción tendrá su propio dominio, su API key y su id de cliente (el aud del token).

Autenticación

Hay tres credenciales y cada una sirve para una sola cosa.

Credenciales de la API
CredencialCómo viajaQuién la usa
API keyCabecera x-api-keySolo su servidor. Nunca en el navegador, en una app móvil ni en un repositorio.
Token del retoAuthorization: Bearer <session_token>El navegador, para subir los tramos de video de un reto. Vale para ese reto y vence a los 10 minutos.
Token de navegadorAuthorization: Bearer …Solo la página alojada de PredictoFace. Usted no lo ve ni lo necesita.

La API key la exige API Gateway (con el plan de uso de la pila) y la función la vuelve a comprobar contra su huella SHA-256, guardada en AWS Systems Manager; la llave en sí no se guarda en ningún lado del lado de Novvai. Para rotarla, Novvai agrega la huella de la llave nueva, usted cambia a la nueva y después se retira la vieja: durante el cambio valen las dos.

Flujo alojado con redirección

Así se ve una verificación completa. Las flechas continuas son peticiones y las punteadas, respuestas.

Diagrama de secuencia del flujo alojado El servidor del cliente registra la autorización y crea la sesión; la persona abre el enlace, acepta el aviso y hace los retos; la API firma en KMS el recibo y el token; la persona vuelve al cliente, que valida el token o lo canjea por los recibos. Servidor del cliente Navegador de la persona PredictoFace API AWS KMS POST /v1/consent (evidencia de autorización) consent_id + recibo firmado POST /v1/sessions (return_url, capacidades, state) session_url (un solo uso, vence) redirige a session_url POST /v1/hosted/open aviso y autorización retos: challenge + segment × N ok / repetir POST /v1/hosted/finish Sign (recibo y token) firma ECDSA P-256 redirect_url return_url?pf_session&pf_token&state valida con JWKS o POST /v1/sessions/{id}/result recibos firmados (sin biometría)
Ninguna imagen ni video pasa por el servidor del cliente ni queda guardado. El token y los recibos no llevan biometría.
  1. Su servidor registra la evidencia de la autorización del titular (POST /v1/consent).
  2. Su servidor crea la sesión (POST /v1/sessions) y redirige a la persona a session_url.
  3. La persona lee el aviso, autoriza, hace los retos y, si se pidió, toma la foto de su documento. En el celular acerca y aleja el teléfono; en el computador se acerca y se aleja de la cámara.
  4. PredictoFace decide en el servidor, firma el recibo y el token en KMS y devuelve a la persona a su return_url.
  5. Su servidor valida el token (o lo canjea) y guarda los recibos.

1. Registrar la autorización

La API no recoge la autorización: usted la obtiene con su propio texto y canal, y registra la prueba (huellas, versión, canal y fecha). Sin una autorización registrada, vigente y con la finalidad correcta, la API no crea la sesión. La página alojada además muestra un aviso y pide una aceptación expresa antes de encender la cámara; la huella de ese aviso queda en el recibo de la sesión.

curl -s https://attest.novvai.systems/v1/consent \
  -H "x-api-key: $PREDICTOFACE_API_KEY" -H "content-type: application/json" \
  -d '{
    "subject_ref": "cli-7f3a9c21-ab",
    "authorization": {
      "text_sha256": "<SHA-256 del texto que aceptó el titular>",
      "version": "aut-biometria-v3",
      "channel": "web",
      "purposes": ["prueba_de_vida", "comparacion_facial"],
      "granted_at": "2026-11-15T14:00:00Z",
      "privacy_notice_version": "aviso-v7"
    },
    "attestations": {
      "explicit_authorization": true,
      "prior_and_informed": true,
      "informed_optional_sensitive": true,
      "informed_sensitive_data_and_purpose": true,
      "alternative_without_biometrics_offered": true
    }
  }'

Respuesta 201: consent_id y el recibo consent_registration. Las cinco declaraciones son obligatorias; si falta una, la respuesta 422 attestations_incomplete dice cuál y por qué norma.

2. Crear la sesión

Pida las capacidades que necesite: liveness (prueba de vida), document_match (comparación con el documento) o ambas. Con las dos, el documento se compara contra la misma referencia que fijó la prueba de vida. Genere un state al azar, guárdelo en la sesión de su usuario y compruébelo al volver.

curl

curl -s https://attest.novvai.systems/v1/sessions \
  -H "x-api-key: $PREDICTOFACE_API_KEY" -H "content-type: application/json" \
  -d '{
    "subject_ref": "cli-7f3a9c21-ab",
    "consent_id": "2f1c7a0e-9b7d-4d0e-9f5e-2a7c1d3b8e44",
    "capabilities": ["liveness", "document_match"],
    "return_url": "https://cliente.example/verificacion/retorno",
    "state": "9b1d4c2e7f",
    "client_reference": "SOL-2026-0001"
  }'

Node

import { randomUUID } from "node:crypto";

const BASE = "https://attest.novvai.systems";

export async function crearSesion(consentId, usuario) {
  const state = randomUUID();               // guárdelo en la sesión del usuario (anti-CSRF)
  usuario.pfState = state;
  const r = await fetch(`${BASE}/v1/sessions`, {
    method: "POST",
    headers: { "x-api-key": process.env.PREDICTOFACE_API_KEY, "content-type": "application/json" },
    body: JSON.stringify({
      subject_ref: usuario.seudonimo,          // nunca la cédula ni el correo
      consent_id: consentId,
      capabilities: ["liveness", "document_match"],
      return_url: "https://cliente.example/verificacion/retorno",
      state,
      client_reference: usuario.solicitud,
    }),
  });
  const cuerpo = await r.json();
  if (!r.ok) throw new Error(cuerpo.error.code);
  return cuerpo.session_url;                  // res.redirect(303, session_url)
}

Python

import json, os, secrets, urllib.request

BASE = "https://attest.novvai.systems"

def crear_sesion(consent_id: str, usuario: dict) -> str:
    usuario["pf_state"] = state = secrets.token_urlsafe(16)   # guárdelo en la sesión del usuario
    cuerpo = {"subject_ref": usuario["seudonimo"], "consent_id": consent_id,
              "capabilities": ["liveness", "document_match"],
              "return_url": "https://cliente.example/verificacion/retorno",
              "state": state, "client_reference": usuario["solicitud"]}
    pet = urllib.request.Request(f"{BASE}/v1/sessions", data=json.dumps(cuerpo).encode(), method="POST",
                                 headers={"x-api-key": os.environ["PREDICTOFACE_API_KEY"],
                                          "content-type": "application/json"})
    with urllib.request.urlopen(pet, timeout=15) as r:
        return json.load(r)["session_url"]    # redirija a la persona con un 303

La respuesta 201 trae session_id, session_url y expires_at. El enlace es de un solo uso: su token viaja en el fragmento (#…), que el navegador no envía a ningún servidor ni en el Referer, y la página lo cambia una sola vez por una credencial propia. No guarde session_url en registros ni la mande por canales inseguros.

Lista blanca de return_url

Cada pila tiene su lista de URL de retorno. La de la petición debe coincidir exactamente en esquema (https), host, puerto y ruta; se permite agregar una consulta (?…), pero no un fragmento, un usuario ni otra ruta. Así nadie puede usar PredictoFace para redirigir a un sitio ajeno. Pida a Novvai que agregue sus URL.

3. Recibir el retorno

Al terminar, la persona vuelve a su return_url con estos parámetros:

Parámetros de la URL de retorno
ParámetroQué es
pf_sessionEl session_id.
pf_tokenJWS compacto ES256, firmado en KMS. Vence a los 5 minutos y se acepta una sola vez.
stateEl valor que usted mandó al crear la sesión. Compárelo con el que guardó.
pf_errorSolo si no hubo token: session_expired (el enlace venció) o session_already_opened (el enlace ya se había usado). Cree una sesión nueva.

El resultado (result.status) es uno de estos:

  • approved: pasó todo lo pedido (prueba de vida aprobada y, si se pidió, el documento supera el umbral de la pila).
  • rejected: algo no pasó. Es apoyo a la decisión: un resultado negativo no prueba suplantación. Ofrezca revisión humana y la alternativa sin biometría.
  • alternative_requested: la persona eligió verificar su identidad de otra forma. Usted debe ofrecérsela.
  • cancelled: la persona canceló.

4. Validar el token

Valide el token en su servidor con la llave pública de /.well-known/jwks.json (elija la llave por kid; la de tokens tiene pf_purpose: "token"). Compruebe, en este orden:

  1. alg es ES256 y la firma es válida (r‖s de 64 bytes, RFC 7518).
  2. iss es la URL de su pila y aud es su id de cliente.
  3. exp no pasó (admita hasta 60 s de diferencia de reloj).
  4. sub es igual a pf_session y state es el que usted guardó.
  5. El jti no se ha usado antes: guárdelo y rechace uno repetido.

Node

import { createPublicKey, verify } from "node:crypto";

const ISS = "https://attest.novvai.systems";
const AUD = "novvai-demo";                     // su id de cliente
let jwks;                                      // puede guardarlo en caché 5 minutos

export async function validarToken(token, pfSession, stateGuardado) {
  jwks ??= await (await fetch(`${ISS}/.well-known/jwks.json`)).json();
  const [h, p, s] = token.split(".");
  const cab = JSON.parse(Buffer.from(h, "base64url"));
  const jwk = jwks.keys.find((k) => k.kid === cab.kid && k.pf_purpose === "token");
  if (cab.alg !== "ES256" || !jwk) throw new Error("llave desconocida");
  const { kty, crv, x, y } = jwk;
  const llave = createPublicKey({ key: { kty, crv, x, y }, format: "jwk" });
  const firmaOk = verify("sha256", Buffer.from(`${h}.${p}`), { key: llave, dsaEncoding: "ieee-p1363" },
                         Buffer.from(s, "base64url"));
  if (!firmaOk) throw new Error("firma inválida");
  const c = JSON.parse(Buffer.from(p, "base64url"));
  const ahora = Date.now() / 1000;
  if (c.iss !== ISS || c.aud !== AUD || ahora > c.exp + 60) throw new Error("token vencido o ajeno");
  if (c.sub !== pfSession || c.state !== stateGuardado) throw new Error("token de otra sesión");
  await marcarJtiUsado(c.jti);                 // en su base de datos; falla si el jti ya existía
  return c;                                    // c.result.status, c.receipt_id, c.operation_receipt_id
}

Python

import base64, json, time, urllib.request
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature

ISS, AUD = "https://attest.novvai.systems", "novvai-demo"

def b64u(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

def validar_token(token: str, pf_session: str, state_guardado: str) -> dict:
    with urllib.request.urlopen(f"{ISS}/.well-known/jwks.json", timeout=10) as r:
        jwks = json.load(r)
    h, p, s = token.split(".")
    cab = json.loads(b64u(h))
    jwk = next(k for k in jwks["keys"] if k["kid"] == cab["kid"] and k["pf_purpose"] == "token")
    assert cab["alg"] == "ES256"
    llave = ec.EllipticCurvePublicNumbers(int.from_bytes(b64u(jwk["x"]), "big"),
                                          int.from_bytes(b64u(jwk["y"]), "big"), ec.SECP256R1()).public_key()
    firma = b64u(s)
    llave.verify(encode_dss_signature(int.from_bytes(firma[:32], "big"), int.from_bytes(firma[32:], "big")),
                 f"{h}.{p}".encode(), ec.ECDSA(hashes.SHA256()))       # lanza InvalidSignature
    c = json.loads(b64u(p))
    if c["iss"] != ISS or c["aud"] != AUD or time.time() > c["exp"] + 60:
        raise ValueError("token vencido o ajeno")
    if c["sub"] != pf_session or c["state"] != state_guardado:
        raise ValueError("token de otra sesión")
    marcar_jti_usado(c["jti"])                 # en su base de datos; falla si el jti ya existía
    return c

Verificador

python verificador/verificar_token.py "$PF_TOKEN" \
  --jwks https://attest.novvai.systems/.well-known/jwks.json \
  --aud novvai-demo --iss https://attest.novvai.systems --session "$PF_SESSION"

La carga del token tiene iss, aud, sub, iat, exp, jti, state, client_reference, result, receipt_id (recibo de la sesión) y operation_receipt_id (recibo de la prueba de vida o de la comparación). result trae el estado, si la prueba de vida se aprobó y qué pasos fallaron, y para el documento meets_threshold, calibrated_score (0 a 100; 80 equivale a una tasa de impostores aceptados de 1 en 10.000) y false_match_rate. Nunca trae imágenes, vectores faciales ni el subject_ref.

5. Canjear el token y guardar los recibos

Si prefiere no verificar firmas, o necesita los recibos completos, canjee el token. El canje es de un solo uso: un segundo canje responde 409 token_already_redeemed. Si el token ya venció, los recibos siguen disponibles con GET /v1/receipts/{receipt_id}.

curl

curl -s "https://attest.novvai.systems/v1/sessions/$PF_SESSION/result" \
  -H "x-api-key: $PREDICTOFACE_API_KEY" -H "content-type: application/json" \
  -d "{\"token\": \"$PF_TOKEN\"}"

Node

const r = await fetch(`${BASE}/v1/sessions/${pfSession}/result`, {
  method: "POST",
  headers: { "x-api-key": process.env.PREDICTOFACE_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({ token: pfToken }),
});
const { session, token_claims, receipts } = await r.json();
// receipts.session (hosted_session) y receipts.operation (liveness o compare): guárdelos tal cual

Python

pet = urllib.request.Request(f"{BASE}/v1/sessions/{pf_session}/result", method="POST",
                             data=json.dumps({"token": pf_token}).encode(),
                             headers={"x-api-key": os.environ["PREDICTOFACE_API_KEY"],
                                      "content-type": "application/json"})
with urllib.request.urlopen(pet, timeout=15) as r:
    canje = json.load(r)
recibos = canje["receipts"]     # guárdelos tal cual: son la prueba firmada de la verificación

Guarde los recibos sin modificarlos: cualquier cambio, incluso de espacios, cambia el JSON canónico. El recibo de la sesión (hosted_session) registra la huella del aviso que aceptó la persona, la hora, el desenlace y el id del recibo de la operación.

Webhook

Opcionalmente, la pila avisa a una URL suya cuando termina una sesión: POST con {"type": "session.finished", "id", "created", "data": {"session_id", "status", "client_reference", "receipt_id", "operation_receipt_id"}}. Se envía una vez y no hay reintentos: es un aviso. La fuente de verdad es el canje o GET /v1/sessions/{id}.

La cabecera PredictoFace-Signature: t=<época>,v1=<hex> lleva v1 = HMAC-SHA256(secreto, t + "." + cuerpo), calculado sobre el cuerpo crudo, antes de interpretarlo como JSON. Rechace firmas con más de 5 minutos de diferencia. Novvai le entrega el secreto por un canal seguro.

Node

import { createHmac, timingSafeEqual } from "node:crypto";

export function webhookValido(cabecera, cuerpoCrudo, secreto) {
  const partes = Object.fromEntries(cabecera.split(",").map((x) => x.split("=", 2)));
  const t = Number(partes.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = createHmac("sha256", secreto).update(`${t}.`).update(cuerpoCrudo).digest();
  const recibido = Buffer.from(partes.v1 ?? "", "hex");
  return recibido.length === esperado.length && timingSafeEqual(recibido, esperado);
}

Python

import hashlib, hmac, time

def webhook_valido(cabecera: str, cuerpo_crudo: bytes, secreto: bytes) -> bool:
    partes = dict(p.split("=", 1) for p in cabecera.split(","))
    t = int(partes.get("t", "0"))
    if abs(time.time() - t) > 300:
        return False
    esperado = hmac.new(secreto, f"{t}.".encode() + cuerpo_crudo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes.get("v1", ""))

Verificar un recibo

Un recibo es {"receipt": {…}, "signature": {…}, "timestamp": …}. Para verificarlo:

  1. Calcule el JSON canónico (RFC 8785) del objeto receipt y su SHA-256. Debe ser igual a signature.signed_sha256.
  2. Busque la llave por signature.kid en /.well-known/predictoface-keys (trae JWK, SPKI y PEM, y las llaves anteriores mientras haya recibos firmados con ellas).
  3. Verifique signature.value: ECDSA P-256 con SHA-256, firma en DER (ES256-DER), sobre ese SHA-256.
  4. Si hay timestamp, es un sello RFC 3161 sobre el SHA-256 de la firma: prueba que el recibo firmado existía a esa hora.

El verificador independiente verificador/verificar_recibo.py hace todo eso con Python y cryptography, sin acceso a la API. Con --archivo comprueba además que la huella de una imagen o un video que usted conserve aparece en el recibo.

python verificador/verificar_recibo.py recibo.json \
  --url https://attest.novvai.systems/.well-known/predictoface-keys
python verificador/verificar_recibo.py recibo.json --llaves llaves.json --archivo cedula.jpg

El recibo es un mensaje de datos firmado con una llave que solo controla Novvai (en un módulo KMS del que no se puede exportar), atado a su contenido por el JSON canónico: cualquier cambio invalida la firma. Esa es la base de su valor probatorio como firma electrónica (Ley 527 de 1999 y Decreto 2364 de 2012); el sello de tiempo de una entidad acreditada se puede activar por pila.

Integración directa (alternativa)

Si ya tiene su propia captura, puede llamar las operaciones sin el flujo alojado:

  • Comparación: POST /v1/compare con image_1 e image_2 en base64 (JPEG o PNG, hasta 2 MB) y su declared_type (selfie, live_photo, cedula_digital, cedula_amarilla, document o auto). Devuelve la similitud, el puntaje calibrado, la tasa de impostores aceptados, meets_threshold y el recibo.
  • Prueba de vida con el componente web: su servidor crea el reto (POST /v1/liveness/challenge), su página muestra predictoface-liveness.js con el session_token del reto (los tramos van directo a PredictoFace, por CORS solo desde sus orígenes) y su servidor pide la decisión (POST /v1/liveness/decision) con el reference_token.
import base64, json, os, urllib.request

def b64(ruta):
    return base64.b64encode(open(ruta, "rb").read()).decode()

cuerpo = {"subject_ref": "cli-7f3a9c21-ab", "consent_id": consent_id, "client_reference": "SOL-2026-0001",
          "image_1": {"data_b64": b64("selfie.jpg"), "declared_type": "selfie"},
          "image_2": {"data_b64": b64("cedula.jpg"), "declared_type": "cedula_digital"}}
pet = urllib.request.Request("https://attest.novvai.systems/v1/compare", method="POST",
                             data=json.dumps(cuerpo).encode(),
                             headers={"x-api-key": os.environ["PREDICTOFACE_API_KEY"], "content-type": "application/json"})
r = json.load(urllib.request.urlopen(pet, timeout=29))
print(r["meets_threshold"], r["calibrated_score"], r["false_match_rate_text"])

En la integración directa usted es quien debe mostrar el aviso, ofrecer la alternativa sin biometría y no guardar las imágenes. Por eso recomendamos el flujo alojado.

Referencia de rutas

La especificación completa, con esquemas y ejemplos, está en OpenAPI 3.1 (YAML) y JSON; fuera de las que aparecen aquí, la API no responde ninguna otra.

Flujo alojado

RutaAutenticaciónQué hace
POST /v1/sessionsAPI keyCrear una sesión alojada
GET /v1/sessionsAPI keyÚltimas sesiones de la pila
GET /v1/sessions/{session_id}API keyEstado y resultado de una sesión
POST /v1/sessions/{session_id}/resultAPI keyCanjear el token de resultado (un solo uso)

Autorizaciones

RutaAutenticaciónQué hace
POST /v1/consentAPI keyRegistrar la evidencia de autorización del titular
POST /v1/consent/{consent_id}/revokeAPI keyRevocar una autorización

Comparación

RutaAutenticaciónQué hace
POST /v1/compareAPI keyComparar dos rostros

Prueba de vida

RutaAutenticaciónQué hace
POST /v1/liveness/challengeAPI keyCrear un reto de prueba de vida de un solo uso (10 minutos)
POST /v1/liveness/segmentToken del retoSubir y analizar un tramo de video (lo llama el navegador)
POST /v1/liveness/decisionAPI keyDecidir la prueba de vida en el servidor (un solo uso)

Recibos

RutaAutenticaciónQué hace
GET /v1/receipts/{receipt_id}API keyRecibo firmado

Titulares

RutaAutenticaciónQué hace
DELETE /v1/subjects/{subject_ref}API keySuprimir todo lo que la API guarda de un titular
POST /v1/subjects/{subject_ref}/legendAPI keyRegistrar o quitar una leyenda (Ley 1581, art. 18)

Llaves públicas

RutaAutenticaciónQué hace
GET /.well-known/jwks.jsonPúblicaJWKS (RFC 7517) para verificar el token del flujo alojado
GET /.well-known/predictoface-keysPúblicaLlaves públicas de los recibos (JWK, SPKI y PEM)

Página alojada

Las usa la página de PredictoFace desde el mismo origen. Su integración no las necesita.

RutaAutenticaciónQué hace
POST /v1/hosted/openPúblicaCambiar el token del enlace por un token de navegador (un solo uso)
POST /v1/hosted/resumeToken de navegadorRetomar la sesión tras recargar la página
POST /v1/hosted/warmToken de navegadorCargar los modelos mientras la persona lee el aviso
POST /v1/hosted/acceptToken de navegadorRegistrar que la persona aceptó el aviso mostrado antes de la cámara
POST /v1/hosted/challengeToken de navegadorCrear el reto de prueba de vida de la sesión (máximo 3 por sesión)
POST /v1/hosted/finishToken de navegadorTerminar la sesión y obtener la URL de retorno con el token firmado

Códigos de error

Todos los errores tienen la forma {"error": {"code": "…", "message": "…"}}. Programe contra code, que es estable; message está en español, puede cambiar y nunca lleva datos personales.

Códigos de error de la API
codeHTTPSignificado
invalid_base64400Una imagen o un video no es base64 válido.
invalid_events400Los eventos del tramo no son un objeto JSON de hasta 64 KB.
invalid_field400Un campo no tiene el tipo esperado.
invalid_json400El cuerpo no es JSON o no es un objeto.
missing_field400Falta un campo obligatorio; el mensaje dice cuál.
invalid_api_key401Falta la API key o no es de esta pila.
invalid_session401El token del enlace, del reto o del navegador no es válido.
invalid_token401El token de resultado no tiene firma válida o no es de esta sesión.
consent_purpose_missing403La autorización no incluye la finalidad de la operación.
consent_required403No hay una autorización registrada de ese titular con ese consent_id.
consent_revoked403El titular revocó la autorización.
cross_site_request403Llamada a la página alojada desde otro sitio.
reference_mismatch403El reference_token no es el del frente fijado en este reto.
challenge_not_found404No hay un reto vigente con ese id.
consent_not_found404No hay una autorización vigente con ese id para ese titular.
not_found404La ruta no existe.
receipt_not_found404No hay un recibo vigente con ese id.
session_not_found404No hay una sesión vigente con ese id (venció la retención o se suprimió).
already_decided409El reto ya tiene decisión (un solo uso).
capability_not_requested409La sesión no incluye esa capacidad.
challenge_closed409El reto ya tiene decisión; no admite más tramos.
challenge_missing409Se pidió cerrar sin haber hecho la prueba de vida.
consent_already_revoked409La autorización ya estaba revocada.
finishing_in_progress409El cierre de la sesión sigue en curso (p. ej. tras un 504). Reintente en unos segundos: la respuesta será el mismo retorno.
notice_not_accepted409La persona no ha aceptado el aviso (409) o el aviso aceptado no es el mostrado (422).
reference_missing409Primero debe aprobarse el tramo «frente».
segment_rejected409El reto venció, terminó o llegó al máximo de tramos.
session_already_opened409El enlace de la sesión ya se abrió: cree una sesión nueva.
session_closed409La sesión ya terminó.
token_already_redeemed409El token ya se canjeó: use GET /v1/receipts/{id}.
challenge_expired410El reto venció (600 s).
reference_destroyed410La referencia del reto ya se destruyó al decidir.
session_expired410La sesión venció. En la página alojada, el error trae la return_url con pf_error.
token_expired410El token venció (300 s). El error trae receipt_id para leer el recibo.
invalid_size413La imagen o el tramo es demasiado grande (413) o demasiado pequeño (400).
payload_too_large413El cuerpo o un campo supera el tamaño máximo.
attestations_incomplete422Falta una declaración obligatoria; missing dice cuál y por qué norma.
client_reference_invalid422client_reference no cumple el formato o parece un número de documento.
document_no_face422No hay un rostro en la foto del documento; la sesión sigue abierta para repetirla.
document_required422Falta la foto del documento.
granted_at_in_future422La autorización no puede tener fecha futura: debe ser previa.
invalid_capabilities422capabilities debe ser liveness, document_match o ambas.
invalid_channel422authorization.channel no es uno de los admitidos.
invalid_declared_type422declared_type no es uno de los admitidos.
invalid_evidence_sha256422authorization.evidence_sha256 debe ser un SHA-256 hexadecimal.
invalid_expires_in422expires_in debe estar entre 120 y 3600 segundos.
invalid_granted_at422authorization.granted_at debe ser ISO 8601 con zona horaria.
invalid_image422La imagen no es un JPEG o PNG legible de 64 a 8000 px.
invalid_legend422legend no es una de las admitidas.
invalid_limit422limit debe estar entre 1 y 100.
invalid_outcome422outcome debe ser completed, alternative o cancelled.
invalid_purposes422authorization.purposes admite comparacion_facial y prueba_de_vida.
invalid_return_url422return_url no es https o lleva usuario, contraseña, fragmento o caracteres no válidos.
invalid_state422state admite de 1 a 256 caracteres ASCII visibles.
invalid_text_sha256422authorization.text_sha256 debe ser un SHA-256 hexadecimal en minúsculas.
no_face_detected422No se encontró un rostro en una de las imágenes; el error dice en cuál.
return_url_not_allowed422return_url no está en la lista blanca de la pila.
selfie_required422Falta la foto del rostro (sesión solo con document_match).
step_not_in_challenge422Ese paso no es parte del reto.
subject_ref_not_pseudonymous422subject_ref parece un número de documento, un correo o un nombre.
blocked_by_sic423La SIC ordenó bloquear la información de este titular.
challenge_limit429La sesión llegó a 3 retos de prueba de vida.
rate_limited429Demasiados intentos para este titular en la última hora.
internal_error500Error no previsto: la respuesta no trae detalles y el id de la solicitud queda en los registros.
analysis_unavailable503No se pudo analizar un tramo: repítalo. No es una falla de la persona.
hosted_flow_not_configured503La pila no tiene configurado el flujo alojado.
timestamp_unavailable503La autoridad de sellado de tiempo no respondió y la pila lo exige.

Límites y vigencias

Son los valores por defecto de una pila; el contrato puede fijar otros.

Límites por pila
LímiteValorSi se supera
Tasa con API key10 por segundo, ráfagas de 20429 de API Gateway
Cuota diaria con API key20.000 peticiones429 de API Gateway
Por dirección IP (cortafuegos)600 peticiones cada 5 minutos403 del WAF
Retos de prueba de vida por titular8 por hora429 rate_limited
Comparaciones por titular30 por hora429 rate_limited
Retos por sesión alojada3429 challenge_limit
Tramos por reto24409 segment_rejected
Imagen2 MB, de 64 a 8000 px413 o 422 invalid_image
Tramo de videode 5 KB a 4 MB400 o 413 invalid_size
Cuerpo de la petición6 MB413 payload_too_large
Tiempo de respuesta máximo29 s504 de API Gateway
Vigencias
ElementoVigencia
Sesión alojada (session_url)20 minutos por defecto; de 120 a 3600 s con expires_in. El cierre se acepta hasta 3 minutos después, para quien estaba en el último reto.
Token de resultado (pf_token)300 s, un solo uso
Reto de prueba de vida600 s; su registro se borra una hora después
Recibos, autorizaciones y sesionesLa retención que fije el cliente en su pila (por defecto 5 años)

Seguridad

  • Transporte. Solo HTTPS con TLS 1.2 o superior, por el dominio propio de la pila; el punto de acceso genérico de API Gateway está apagado. HSTS en todas las respuestas.
  • Llaves. AWS KMS: una llave de firma de recibos y otra de tokens (ECDSA P-256, no exportables), y una llave de datos con rotación para la tabla, los registros y la llave propia de cada reto.
  • Cortafuegos. AWS WAF con límite por IP y la lista de reputación de IP de AWS, además del plan de uso por API key.
  • Sin redirección abierta. return_url debe estar en la lista blanca exacta de la pila.
  • Un solo uso. El enlace, el cierre de la sesión, la decisión de la prueba de vida y el canje del token son escrituras condicionales: no se pueden repetir. Los tokens son de 256 bits y solo se guarda su SHA-256.
  • Página alojada. Política de seguridad de contenido estricta (solo recursos propios, Trusted Types, sin marcos de terceros), cabeceras Permissions-Policy (solo cámara), X-Frame-Options: DENY y rechazo de peticiones de otros sitios con Fetch Metadata. No usa cookies ni almacenamiento persistente.
  • Registros. Sin cuerpos, sin la ruta concreta (que lleva identificadores), sin IP y sin identificadores de titulares: solo el nombre de la ruta, el código, la latencia y el id de la solicitud. Cifrados con KMS y con 90 días de retención.
  • Secretos. Ninguno en el código: la huella de la API key, la pimienta del seudónimo y el secreto del webhook están en AWS Systems Manager (SecureString).
  • Imagen de la función. Dependencias con versión fija, modelos verificados por SHA-256 al arrancar y escaneo de vulnerabilidades al subir la imagen.
  • Alarmas. Errores, limitaciones, latencia, respuestas 4XX y 5XX, DynamoDB y bloqueos del cortafuegos.

Protección de datos

La imagen del rostro es un dato sensible (Ley 1581 de 2012, art. 5). PredictoFace la trata solo en memoria y para la finalidad que usted pidió.

Qué se guarda y qué no
Dato¿Se guarda?Dónde y cuánto
Imágenes de comparación y del documentoNo Se decodifican en memoria y se descartan al responder.—
Videos de los retosNo Se leen en memoria; no hay archivo temporal.—
Vector facial y foto de referenciaNo Viajan sellados (AES-256-GCM) en el navegador mientras dura el reto; la llave se destruye al decidir.—
Vectores de los tramos y del documentoNo Solo queda la similitud, un número.—
Autorización registradaSí Seudónimo, huellas, versión, canal y fechas.Tabla de la pila, retención del cliente
Sesiones alojadasSí Estado, capacidades, return_url, huella del aviso aceptado, resultado e ids de recibos. Sin biometría.Tabla de la pila, retención del cliente
RecibosSí Huellas, puntajes y versiones.Tabla de la pila, retención del cliente
Registro del retoSí Valores del reto, huellas y resultados de los tramos, llave cifrada del reto.Una hora después del reto
Contadores de límiteSí2 horas
Constancia de supresiónSí Sin el seudónimo.Retención del cliente
Registros técnicosSí Nombre de la ruta, código, latencia e id de la solicitud.CloudWatch, 90 días
  • Seudónimo. La API guarda HMAC-SHA256(pimienta, "<cliente>:<subject_ref>"), no su subject_ref. La pimienta es propia de cada pila.
  • Supresión. DELETE /v1/subjects/{subject_ref} borra las autorizaciones, los recibos, los retos, las sesiones, los contadores y las leyendas de ese titular, y devuelve una constancia firmada.
  • Leyendas. POST /v1/subjects/{subject_ref}/legend registra «reclamo en trámite», «información en discusión judicial» o el bloqueo ordenado por la SIC (con el bloqueo, los recibos de ese titular dejan de entregarse).
  • Sin otros usos. No se estima edad ni sexo, nada se usa para entrenar modelos y cada recibo lo declara en data_handling.
  • Infraestructura. Amazon Web Services, como subencargado, en la región de la pila (por defecto us-east-1).