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_refpropio (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.
| Credencial | Cómo viaja | Quién la usa |
|---|---|---|
| API key | Cabecera x-api-key | Solo su servidor. Nunca en el navegador, en una app móvil ni en un repositorio. |
| Token del reto | Authorization: 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 navegador | Authorization: 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.
- Su servidor registra la evidencia de la autorización del titular (
POST /v1/consent). - Su servidor crea la sesión (
POST /v1/sessions) y redirige a la persona asession_url. - 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.
- PredictoFace decide en el servidor, firma el recibo y el token en KMS y devuelve a la persona a su
return_url. - 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ámetro | Qué es |
|---|---|
pf_session | El session_id. |
pf_token | JWS compacto ES256, firmado en KMS. Vence a los 5 minutos y se acepta una sola vez. |
state | El valor que usted mandó al crear la sesión. Compárelo con el que guardó. |
pf_error | Solo 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:
algesES256y la firma es válida (r‖s de 64 bytes, RFC 7518).isses la URL de su pila yaudes su id de cliente.expno pasó (admita hasta 60 s de diferencia de reloj).subes igual apf_sessionystatees el que usted guardó.- El
jtino 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:
- Calcule el JSON canónico (RFC 8785) del objeto
receipty su SHA-256. Debe ser igual asignature.signed_sha256. - Busque la llave por
signature.kiden/.well-known/predictoface-keys(trae JWK, SPKI y PEM, y las llaves anteriores mientras haya recibos firmados con ellas). - Verifique
signature.value: ECDSA P-256 con SHA-256, firma en DER (ES256-DER), sobre ese SHA-256. - 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/compareconimage_1eimage_2en base64 (JPEG o PNG, hasta 2 MB) y sudeclared_type(selfie,live_photo,cedula_digital,cedula_amarilla,documentoauto). Devuelve la similitud, el puntaje calibrado, la tasa de impostores aceptados,meets_thresholdy el recibo. - Prueba de vida con el componente web: su servidor crea el reto (
POST /v1/liveness/challenge), su página muestrapredictoface-liveness.jscon elsession_tokendel 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 elreference_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
| Ruta | Autenticación | Qué hace |
|---|---|---|
POST /v1/sessions | API key | Crear una sesión alojada |
GET /v1/sessions | API key | Últimas sesiones de la pila |
GET /v1/sessions/{session_id} | API key | Estado y resultado de una sesión |
POST /v1/sessions/{session_id}/result | API key | Canjear el token de resultado (un solo uso) |
Autorizaciones
| Ruta | Autenticación | Qué hace |
|---|---|---|
POST /v1/consent | API key | Registrar la evidencia de autorización del titular |
POST /v1/consent/{consent_id}/revoke | API key | Revocar una autorización |
Comparación
| Ruta | Autenticación | Qué hace |
|---|---|---|
POST /v1/compare | API key | Comparar dos rostros |
Prueba de vida
| Ruta | Autenticación | Qué hace |
|---|---|---|
POST /v1/liveness/challenge | API key | Crear un reto de prueba de vida de un solo uso (10 minutos) |
POST /v1/liveness/segment | Token del reto | Subir y analizar un tramo de video (lo llama el navegador) |
POST /v1/liveness/decision | API key | Decidir la prueba de vida en el servidor (un solo uso) |
Recibos
| Ruta | Autenticación | Qué hace |
|---|---|---|
GET /v1/receipts/{receipt_id} | API key | Recibo firmado |
Titulares
| Ruta | Autenticación | Qué hace |
|---|---|---|
DELETE /v1/subjects/{subject_ref} | API key | Suprimir todo lo que la API guarda de un titular |
POST /v1/subjects/{subject_ref}/legend | API key | Registrar o quitar una leyenda (Ley 1581, art. 18) |
Llaves públicas
| Ruta | Autenticación | Qué hace |
|---|---|---|
GET /.well-known/jwks.json | Pública | JWKS (RFC 7517) para verificar el token del flujo alojado |
GET /.well-known/predictoface-keys | Pública | Llaves 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.
| Ruta | Autenticación | Qué hace |
|---|---|---|
POST /v1/hosted/open | Pública | Cambiar el token del enlace por un token de navegador (un solo uso) |
POST /v1/hosted/resume | Token de navegador | Retomar la sesión tras recargar la página |
POST /v1/hosted/warm | Token de navegador | Cargar los modelos mientras la persona lee el aviso |
POST /v1/hosted/accept | Token de navegador | Registrar que la persona aceptó el aviso mostrado antes de la cámara |
POST /v1/hosted/challenge | Token de navegador | Crear el reto de prueba de vida de la sesión (máximo 3 por sesión) |
POST /v1/hosted/finish | Token de navegador | Terminar 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.
| code | HTTP | Significado |
|---|---|---|
invalid_base64 | 400 | Una imagen o un video no es base64 válido. |
invalid_events | 400 | Los eventos del tramo no son un objeto JSON de hasta 64 KB. |
invalid_field | 400 | Un campo no tiene el tipo esperado. |
invalid_json | 400 | El cuerpo no es JSON o no es un objeto. |
missing_field | 400 | Falta un campo obligatorio; el mensaje dice cuál. |
invalid_api_key | 401 | Falta la API key o no es de esta pila. |
invalid_session | 401 | El token del enlace, del reto o del navegador no es válido. |
invalid_token | 401 | El token de resultado no tiene firma válida o no es de esta sesión. |
consent_purpose_missing | 403 | La autorización no incluye la finalidad de la operación. |
consent_required | 403 | No hay una autorización registrada de ese titular con ese consent_id. |
consent_revoked | 403 | El titular revocó la autorización. |
cross_site_request | 403 | Llamada a la página alojada desde otro sitio. |
reference_mismatch | 403 | El reference_token no es el del frente fijado en este reto. |
challenge_not_found | 404 | No hay un reto vigente con ese id. |
consent_not_found | 404 | No hay una autorización vigente con ese id para ese titular. |
not_found | 404 | La ruta no existe. |
receipt_not_found | 404 | No hay un recibo vigente con ese id. |
session_not_found | 404 | No hay una sesión vigente con ese id (venció la retención o se suprimió). |
already_decided | 409 | El reto ya tiene decisión (un solo uso). |
capability_not_requested | 409 | La sesión no incluye esa capacidad. |
challenge_closed | 409 | El reto ya tiene decisión; no admite más tramos. |
challenge_missing | 409 | Se pidió cerrar sin haber hecho la prueba de vida. |
consent_already_revoked | 409 | La autorización ya estaba revocada. |
finishing_in_progress | 409 | El 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_accepted | 409 | La persona no ha aceptado el aviso (409) o el aviso aceptado no es el mostrado (422). |
reference_missing | 409 | Primero debe aprobarse el tramo «frente». |
segment_rejected | 409 | El reto venció, terminó o llegó al máximo de tramos. |
session_already_opened | 409 | El enlace de la sesión ya se abrió: cree una sesión nueva. |
session_closed | 409 | La sesión ya terminó. |
token_already_redeemed | 409 | El token ya se canjeó: use GET /v1/receipts/{id}. |
challenge_expired | 410 | El reto venció (600 s). |
reference_destroyed | 410 | La referencia del reto ya se destruyó al decidir. |
session_expired | 410 | La sesión venció. En la página alojada, el error trae la return_url con pf_error. |
token_expired | 410 | El token venció (300 s). El error trae receipt_id para leer el recibo. |
invalid_size | 413 | La imagen o el tramo es demasiado grande (413) o demasiado pequeño (400). |
payload_too_large | 413 | El cuerpo o un campo supera el tamaño máximo. |
attestations_incomplete | 422 | Falta una declaración obligatoria; missing dice cuál y por qué norma. |
client_reference_invalid | 422 | client_reference no cumple el formato o parece un número de documento. |
document_no_face | 422 | No hay un rostro en la foto del documento; la sesión sigue abierta para repetirla. |
document_required | 422 | Falta la foto del documento. |
granted_at_in_future | 422 | La autorización no puede tener fecha futura: debe ser previa. |
invalid_capabilities | 422 | capabilities debe ser liveness, document_match o ambas. |
invalid_channel | 422 | authorization.channel no es uno de los admitidos. |
invalid_declared_type | 422 | declared_type no es uno de los admitidos. |
invalid_evidence_sha256 | 422 | authorization.evidence_sha256 debe ser un SHA-256 hexadecimal. |
invalid_expires_in | 422 | expires_in debe estar entre 120 y 3600 segundos. |
invalid_granted_at | 422 | authorization.granted_at debe ser ISO 8601 con zona horaria. |
invalid_image | 422 | La imagen no es un JPEG o PNG legible de 64 a 8000 px. |
invalid_legend | 422 | legend no es una de las admitidas. |
invalid_limit | 422 | limit debe estar entre 1 y 100. |
invalid_outcome | 422 | outcome debe ser completed, alternative o cancelled. |
invalid_purposes | 422 | authorization.purposes admite comparacion_facial y prueba_de_vida. |
invalid_return_url | 422 | return_url no es https o lleva usuario, contraseña, fragmento o caracteres no válidos. |
invalid_state | 422 | state admite de 1 a 256 caracteres ASCII visibles. |
invalid_text_sha256 | 422 | authorization.text_sha256 debe ser un SHA-256 hexadecimal en minúsculas. |
no_face_detected | 422 | No se encontró un rostro en una de las imágenes; el error dice en cuál. |
return_url_not_allowed | 422 | return_url no está en la lista blanca de la pila. |
selfie_required | 422 | Falta la foto del rostro (sesión solo con document_match). |
step_not_in_challenge | 422 | Ese paso no es parte del reto. |
subject_ref_not_pseudonymous | 422 | subject_ref parece un número de documento, un correo o un nombre. |
blocked_by_sic | 423 | La SIC ordenó bloquear la información de este titular. |
challenge_limit | 429 | La sesión llegó a 3 retos de prueba de vida. |
rate_limited | 429 | Demasiados intentos para este titular en la última hora. |
internal_error | 500 | Error no previsto: la respuesta no trae detalles y el id de la solicitud queda en los registros. |
analysis_unavailable | 503 | No se pudo analizar un tramo: repítalo. No es una falla de la persona. |
hosted_flow_not_configured | 503 | La pila no tiene configurado el flujo alojado. |
timestamp_unavailable | 503 | La 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ímite | Valor | Si se supera |
|---|---|---|
| Tasa con API key | 10 por segundo, ráfagas de 20 | 429 de API Gateway |
| Cuota diaria con API key | 20.000 peticiones | 429 de API Gateway |
| Por dirección IP (cortafuegos) | 600 peticiones cada 5 minutos | 403 del WAF |
| Retos de prueba de vida por titular | 8 por hora | 429 rate_limited |
| Comparaciones por titular | 30 por hora | 429 rate_limited |
| Retos por sesión alojada | 3 | 429 challenge_limit |
| Tramos por reto | 24 | 409 segment_rejected |
| Imagen | 2 MB, de 64 a 8000 px | 413 o 422 invalid_image |
| Tramo de video | de 5 KB a 4 MB | 400 o 413 invalid_size |
| Cuerpo de la petición | 6 MB | 413 payload_too_large |
| Tiempo de respuesta máximo | 29 s | 504 de API Gateway |
| Elemento | Vigencia |
|---|---|
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 vida | 600 s; su registro se borra una hora después |
| Recibos, autorizaciones y sesiones | La 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_urldebe 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: DENYy 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ó.
| Dato | ¿Se guarda? | Dónde y cuánto |
|---|---|---|
| Imágenes de comparación y del documento | No Se decodifican en memoria y se descartan al responder. | — |
| Videos de los retos | No Se leen en memoria; no hay archivo temporal. | — |
| Vector facial y foto de referencia | No Viajan sellados (AES-256-GCM) en el navegador mientras dura el reto; la llave se destruye al decidir. | — |
| Vectores de los tramos y del documento | No Solo queda la similitud, un número. | — |
| Autorización registrada | Sí Seudónimo, huellas, versión, canal y fechas. | Tabla de la pila, retención del cliente |
| Sesiones alojadas | Sí Estado, capacidades, return_url, huella del aviso aceptado, resultado e ids de recibos. Sin biometría. | Tabla de la pila, retención del cliente |
| Recibos | Sí Huellas, puntajes y versiones. | Tabla de la pila, retención del cliente |
| Registro del reto | Sí Valores del reto, huellas y resultados de los tramos, llave cifrada del reto. | Una hora después del reto |
| Contadores de límite | Sí | 2 horas |
| Constancia de supresión | Sí Sin el seudónimo. | Retención del cliente |
| Registros técnicos | Sí 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 susubject_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}/legendregistra «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).