{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "PredictoFace API",
    "version": "1.0.0",
    "summary": "Verificación de identidad con el rostro, prueba de vida decidida en el servidor y recibos firmados.",
    "description": "API comercial de Novvai Systems S.A.S. Novvai actúa como **encargado** del tratamiento; el cliente es el\n**responsable**. Cada cliente tiene su propia pila de AWS (llaves KMS, tabla, API key, WAF y alarmas).\n\n- Ninguna comparación ni prueba de vida corre sin una autorización registrada del mismo titular\n  (`POST /v1/consent`) con la finalidad que corresponde.\n- Las imágenes y los videos se procesan en memoria y no se guardan. No se guardan vectores faciales,\n  no se estima edad ni sexo y nada se usa para entrenar.\n- Cada operación deja un recibo firmado (ECDSA P-256 en AWS KMS sobre JSON canónico RFC 8785).\n- El flujo alojado (`/v1/sessions`) termina con un token JWS ES256 de un solo uso que nunca lleva biometría.\n\nTodos los errores tienen la forma `{\"error\": {\"code\": \"...\", \"message\": \"...\"}}`. Un error no previsto\nresponde 500 con `internal_error`, sin detalles.\n\nGuía completa: https://attest.novvai.systems/docs/\n",
    "contact": {
      "name": "Novvai Systems S.A.S.",
      "url": "https://attest.novvai.systems/docs/"
    },
    "license": {
      "name": "Propietaria (uso según contrato con Novvai Systems)",
      "identifier": "LicenseRef-Novvai-Propietaria"
    }
  },
  "servers": [
    {
      "url": "https://attest.novvai.systems",
      "description": "Pila de demostración (cliente novvai-demo)"
    }
  ],
  "tags": [
    {
      "name": "Flujo alojado",
      "description": "El servidor del cliente crea una sesión; la persona hace la verificación en la página de PredictoFace y vuelve con un token firmado."
    },
    {
      "name": "Página alojada",
      "description": "Rutas que usa la página alojada de PredictoFace (mismo origen). El cliente no las llama."
    },
    {
      "name": "Autorizaciones"
    },
    {
      "name": "Comparación"
    },
    {
      "name": "Prueba de vida",
      "description": "Integración directa con el componente web, como alternativa al flujo alojado."
    },
    {
      "name": "Recibos"
    },
    {
      "name": "Titulares"
    },
    {
      "name": "Llaves públicas"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/v1/sessions": {
      "post": {
        "tags": [
          "Flujo alojado"
        ],
        "operationId": "crearSesion",
        "summary": "Crear una sesión alojada",
        "description": "Devuelve `session_url`, un enlace de un solo uso que vence. El token de apertura viaja en el fragmento\n(`#…`), que el navegador no envía al servidor ni en el `Referer`. `return_url` debe coincidir **exactamente**\n(esquema, host, puerto y ruta) con una URL de la lista blanca de la pila; la consulta (`?…`) se permite.\nLa autorización registrada (`consent_id`) debe incluir la finalidad de cada capacidad:\n`liveness` → `prueba_de_vida`, `document_match` → `comparacion_facial`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionCreateRequest"
              },
              "examples": {
                "ambas": {
                  "summary": "Prueba de vida y comparación con la cédula",
                  "value": {
                    "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",
                    "expires_in": 1200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sesión creada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionCreateResponse"
                },
                "example": {
                  "session_id": "0193a0c2-5e1b-7c3d-9a2f-4b6e8d0c1a23",
                  "status": "created",
                  "session_url": "https://attest.novvai.systems/s/0193a0c2-5e1b-7c3d-9a2f-4b6e8d0c1a23#Zm9v...",
                  "expires_at": "2026-11-15T23:40:00.000Z",
                  "capabilities": [
                    "liveness",
                    "document_match"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "429": {
            "$ref": "#/components/responses/Limite"
          },
          "503": {
            "$ref": "#/components/responses/NoDisponible"
          }
        }
      },
      "get": {
        "tags": [
          "Flujo alojado"
        ],
        "operationId": "listarSesiones",
        "summary": "Últimas sesiones de la pila",
        "description": "Las más recientes primero (los `session_id` son UUID v7). Sin datos personales ni biometría.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de sesiones.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sessions"
                  ],
                  "properties": {
                    "sessions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SessionSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/v1/sessions/{session_id}": {
      "get": {
        "tags": [
          "Flujo alojado"
        ],
        "operationId": "consultarSesion",
        "summary": "Estado y resultado de una sesión",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          }
        ],
        "responses": {
          "200": {
            "description": "Resumen de la sesión.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionSummary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          }
        }
      }
    },
    "/v1/sessions/{session_id}/result": {
      "post": {
        "tags": [
          "Flujo alojado"
        ],
        "operationId": "canjearToken",
        "summary": "Canjear el token de resultado (un solo uso)",
        "description": "Verifica la firma del token, que su `sub` y su `jti` correspondan a la sesión y que no haya vencido\n(`exp`, 300 s). Lo marca como canjeado con una escritura condicional y devuelve los recibos firmados\ncompletos: el de la sesión (`hosted_session`) y el de la operación (`liveness` o `compare`), si la hubo.\nSi el token ya venció, los recibos siguen disponibles en `GET /v1/receipts/{receipt_id}`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "JWS compacto recibido en `pf_token`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token canjeado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RedeemResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalido"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "423": {
            "$ref": "#/components/responses/Bloqueado"
          }
        }
      }
    },
    "/v1/hosted/open": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "abrirSesion",
        "summary": "Cambiar el token del enlace por un token de navegador (un solo uso)",
        "security": [],
        "description": "Exige `Sec-Fetch-Site` igual a `same-origin` o `none` cuando el navegador lo envía.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_id",
                  "open_token"
                ],
                "properties": {
                  "session_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "open_token": {
                    "type": "string",
                    "description": "Fragmento de `session_url`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sesión abierta. `browser_token` solo se devuelve aquí.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostedSession"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/OtroSitio"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          }
        }
      }
    },
    "/v1/hosted/resume": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "reanudarSesion",
        "summary": "Retomar la sesión tras recargar la página",
        "security": [
          {
            "browserToken": []
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/SoloSesion"
        },
        "responses": {
          "200": {
            "description": "Estado público de la sesión (sin `browser_token`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostedSession"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/OtroSitio"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          }
        }
      }
    },
    "/v1/hosted/warm": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "calentarSesion",
        "summary": "Cargar los modelos mientras la persona lee el aviso",
        "description": "La página lo llama sin esperar la respuesta al abrir la sesión. Si el contenedor estaba frío puede tardar hasta un minuto (o devolver 504 de API Gateway); no cambia el estado de la sesión ni guarda nada.",
        "security": [
          {
            "browserToken": []
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/SoloSesion"
        },
        "responses": {
          "200": {
            "description": "Modelos cargados en este contenedor.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/OtroSitio"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          }
        }
      }
    },
    "/v1/hosted/accept": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "aceptarAviso",
        "summary": "Registrar que la persona aceptó el aviso mostrado antes de la cámara",
        "description": "`notice_sha256` debe ser el SHA-256 (JSON canónico) del aviso que entregó el servidor; queda en el recibo de la sesión.",
        "security": [
          {
            "browserToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_id",
                  "accepted",
                  "notice_sha256"
                ],
                "properties": {
                  "session_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "accepted": {
                    "const": true
                  },
                  "notice_sha256": {
                    "$ref": "#/components/schemas/Sha256"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Aviso aceptado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "notice_accepted": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/OtroSitio"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/v1/hosted/challenge": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "crearRetoAlojado",
        "summary": "Crear el reto de prueba de vida de la sesión (máximo 3 por sesión)",
        "security": [
          {
            "browserToken": []
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/SoloSesion"
        },
        "responses": {
          "201": {
            "description": "Reto creado. Los tramos se suben a `POST /v1/liveness/segment` con su `session_token`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ChallengeResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "challenges_left": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "429": {
            "$ref": "#/components/responses/Limite"
          }
        }
      }
    },
    "/v1/hosted/finish": {
      "post": {
        "tags": [
          "Página alojada"
        ],
        "operationId": "terminarSesion",
        "summary": "Terminar la sesión y obtener la URL de retorno con el token firmado",
        "description": "`completed` ejecuta la decisión de la prueba de vida (y la comparación con el documento contra la misma\nreferencia) o, si solo se pidió `document_match`, la comparación selfie contra documento.\n`alternative` y `cancelled` también vuelven con token firmado y sin operación biométrica.\nSi el documento no tiene un rostro (422 `document_no_face`) la sesión sigue abierta para repetir la foto.\n",
        "security": [
          {
            "browserToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HostedFinishRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sesión terminada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "redirect_url"
                  ],
                  "properties": {
                    "status": {
                      "$ref": "#/components/schemas/SessionResultStatus"
                    },
                    "redirect_url": {
                      "type": "string",
                      "format": "uri",
                      "description": "`return_url` con `pf_session`, `pf_token` y `state`."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "413": {
            "$ref": "#/components/responses/MuyGrande"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "429": {
            "$ref": "#/components/responses/Limite"
          },
          "503": {
            "$ref": "#/components/responses/NoDisponible"
          }
        }
      }
    },
    "/v1/consent": {
      "post": {
        "tags": [
          "Autorizaciones"
        ],
        "operationId": "registrarAutorizacion",
        "summary": "Registrar la evidencia de autorización del titular",
        "description": "La API no recoge la autorización: guarda la **prueba** que aporta el cliente (huellas, versión, canal y\nfechas) y la vincula al titular seudónimo. Las cinco declaraciones (`attestations`) son obligatorias.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Autorización registrada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "consent_id",
                    "receipt"
                  ],
                  "properties": {
                    "consent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/SignedReceipt"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PeticionMala"
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/v1/consent/{consent_id}/revoke": {
      "post": {
        "tags": [
          "Autorizaciones"
        ],
        "operationId": "revocarAutorizacion",
        "summary": "Revocar una autorización",
        "parameters": [
          {
            "name": "consent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "subject_ref"
                ],
                "properties": {
                  "subject_ref": {
                    "$ref": "#/components/schemas/SubjectRef"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Autorización revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "consent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "revoked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/SignedReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/v1/compare": {
      "post": {
        "tags": [
          "Comparación"
        ],
        "operationId": "comparar",
        "summary": "Comparar dos rostros",
        "description": "No devuelve edad ni sexo. `meets_threshold` compara la tasa de impostores aceptados (FMR) con el punto\nde operación de la pila (1e-3 selfie contra documento, 1e-4 en vivo contra en vivo). Es apoyo a la\ndecisión: un resultado negativo no prueba suplantación.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompareRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado y recibo firmado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PeticionMala"
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "413": {
            "$ref": "#/components/responses/MuyGrande"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "429": {
            "$ref": "#/components/responses/Limite"
          }
        }
      }
    },
    "/v1/liveness/challenge": {
      "post": {
        "tags": [
          "Prueba de vida"
        ],
        "operationId": "crearReto",
        "summary": "Crear un reto de prueba de vida de un solo uso (10 minutos)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "subject_ref",
                  "consent_id"
                ],
                "properties": {
                  "subject_ref": {
                    "$ref": "#/components/schemas/SubjectRef"
                  },
                  "consent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "client_reference": {
                    "$ref": "#/components/schemas/ClientReference"
                  },
                  "return_reference_image": {
                    "type": "boolean",
                    "default": false,
                    "description": "Si es verdadero, la decisión devuelve la foto de referencia (del tramo «frente» fijado)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reto creado. Entregue al navegador solo `challenge_id`, `session_token`, `steps` y `values`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChallengeResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "429": {
            "$ref": "#/components/responses/Limite"
          }
        }
      }
    },
    "/v1/liveness/segment": {
      "post": {
        "tags": [
          "Prueba de vida"
        ],
        "operationId": "subirTramo",
        "summary": "Subir y analizar un tramo de video (lo llama el navegador)",
        "description": "Responde solo `ok` y un mensaje, nunca el puntaje. El primer «frente» bueno fija la referencia y devuelve\n`reference_token` (sellado con AES-256-GCM; la API no lo guarda). CORS solo desde los orígenes de la pila.\n",
        "security": [
          {
            "challengeToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SegmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tramo analizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PeticionMala"
          },
          "401": {
            "$ref": "#/components/responses/SesionInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "413": {
            "$ref": "#/components/responses/MuyGrande"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "503": {
            "$ref": "#/components/responses/NoDisponible"
          }
        }
      },
      "options": {
        "tags": [
          "Prueba de vida"
        ],
        "operationId": "preflightTramo",
        "summary": "Preflight CORS",
        "security": [],
        "responses": {
          "204": {
            "description": "Sin contenido."
          }
        }
      }
    },
    "/v1/liveness/decision": {
      "post": {
        "tags": [
          "Prueba de vida"
        ],
        "operationId": "decidir",
        "summary": "Decidir la prueba de vida en el servidor (un solo uso)",
        "description": "Con `document_image`, compara la cédula contra la **misma** referencia del reto. Destruye la llave del reto (borrado criptográfico).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge_id"
                ],
                "properties": {
                  "challenge_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "reference_token": {
                    "type": "string"
                  },
                  "document_image": {
                    "$ref": "#/components/schemas/ImageInput"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decisión y recibo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecisionResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "403": {
            "$ref": "#/components/responses/SinAutorizacion"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "409": {
            "$ref": "#/components/responses/Conflicto"
          },
          "410": {
            "$ref": "#/components/responses/Vencido"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          },
          "503": {
            "$ref": "#/components/responses/NoDisponible"
          }
        }
      }
    },
    "/v1/receipts/{receipt_id}": {
      "get": {
        "tags": [
          "Recibos"
        ],
        "operationId": "leerRecibo",
        "summary": "Recibo firmado",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recibo, con la leyenda del titular si la hay.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedReceipt"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "404": {
            "$ref": "#/components/responses/NoEncontrado"
          },
          "423": {
            "$ref": "#/components/responses/Bloqueado"
          }
        }
      }
    },
    "/v1/subjects/{subject_ref}": {
      "delete": {
        "tags": [
          "Titulares"
        ],
        "operationId": "suprimirTitular",
        "summary": "Suprimir todo lo que la API guarda de un titular",
        "description": "Autorizaciones, recibos, retos, sesiones, contadores y leyendas. Devuelve la constancia firmada, que se guarda sin el seudónimo.",
        "parameters": [
          {
            "$ref": "#/components/parameters/SubjectRefPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Supresión hecha.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "integer"
                      },
                      "example": {
                        "consents": 1,
                        "receipts": 3,
                        "liveness_challenges": 1,
                        "hosted_sessions": 1,
                        "rate_counters": 2
                      }
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/SignedReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/v1/subjects/{subject_ref}/legend": {
      "post": {
        "tags": [
          "Titulares"
        ],
        "operationId": "leyendaTitular",
        "summary": "Registrar o quitar una leyenda (Ley 1581, art. 18)",
        "description": "Con `bloqueo_sic`, la API deja de entregar los recibos de ese titular (423).",
        "parameters": [
          {
            "$ref": "#/components/parameters/SubjectRefPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "legend"
                ],
                "properties": {
                  "legend": {
                    "type": "string",
                    "enum": [
                      "reclamo_en_tramite",
                      "informacion_en_discusion_judicial",
                      "bloqueo_sic",
                      "ninguna"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Leyenda registrada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "legend": {
                      "type": "string"
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/SignedReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyInvalida"
          },
          "422": {
            "$ref": "#/components/responses/Validacion"
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "tags": [
          "Llaves públicas"
        ],
        "operationId": "jwks",
        "summary": "JWKS (RFC 7517) para verificar el token del flujo alojado",
        "security": [],
        "description": "Incluye la llave del token (`pf_purpose: token`) y la de recibos (`pf_purpose: receipt`).\nElija la llave por `kid`. Se puede guardar en caché 5 minutos.\n",
        "responses": {
          "200": {
            "description": "Llaves públicas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Jwks"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/predictoface-keys": {
      "get": {
        "tags": [
          "Llaves públicas"
        ],
        "operationId": "llavesRecibos",
        "summary": "Llaves públicas de los recibos (JWK, SPKI y PEM)",
        "security": [],
        "responses": {
          "200": {
            "description": "Llaves vigentes y anteriores mientras sus recibos sigan vigentes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictoFaceKeys"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "sessionFinished": {
      "post": {
        "summary": "Aviso de sesión terminada (opcional)",
        "description": "Se envía una vez, sin reintentos, a la URL configurada en la pila. Es un aviso: la fuente de verdad es el\ncanje del token o `GET /v1/sessions/{id}`. Cabecera `PredictoFace-Signature: t=<época>,v1=<hex>` con\n`v1 = HMAC-SHA256(secreto, t + \".\" + cuerpo)`. Rechace firmas con más de 5 minutos de diferencia.\n",
        "parameters": [
          {
            "name": "PredictoFace-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1794799494,v1=5f0c...e1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Recibido."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key de la pila. Solo desde el servidor del cliente; nunca en el navegador ni en una app."
      },
      "challengeToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "`session_token` del reto (256 bits; la API solo guarda su SHA-256)."
      },
      "browserToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token de navegador de la página alojada (lo entrega `POST /v1/hosted/open`)."
      }
    },
    "parameters": {
      "SessionId": {
        "name": "session_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "description": "UUID v7"
        }
      },
      "SubjectRefPath": {
        "name": "subject_ref",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/SubjectRef"
        }
      }
    },
    "requestBodies": {
      "SoloSesion": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "session_id"
              ],
              "properties": {
                "session_id": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "PeticionMala": {
        "description": "JSON inválido, campo faltante o base64 inválido (`invalid_json`, `missing_field`, `invalid_field`, `invalid_base64`, `invalid_events`, `invalid_size`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ApiKeyInvalida": {
        "description": "`invalid_api_key`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "SesionInvalida": {
        "description": "`invalid_session`: token de reto, de enlace o de navegador inválido.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TokenInvalido": {
        "description": "`invalid_token`: firma inválida o el token no es de esta sesión.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "SinAutorizacion": {
        "description": "`consent_required`, `consent_revoked`, `consent_purpose_missing` o `reference_mismatch`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "OtroSitio": {
        "description": "`cross_site_request`: la página alojada solo acepta llamadas del mismo origen.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NoEncontrado": {
        "description": "`not_found`, `session_not_found`, `receipt_not_found`, `consent_not_found` o `challenge_not_found`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflicto": {
        "description": "Estado incompatible: `session_already_opened`, `session_closed`, `finishing_in_progress`, `notice_not_accepted`, `capability_not_requested`, `challenge_missing`, `token_already_redeemed`, `already_decided`, `challenge_closed`, `reference_missing`, `segment_rejected`, `consent_already_revoked`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Vencido": {
        "description": "`session_expired`, `token_expired`, `challenge_expired` o `reference_destroyed`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MuyGrande": {
        "description": "`payload_too_large` o `invalid_size`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Validacion": {
        "description": "Datos válidos como JSON pero no aceptables: `subject_ref_not_pseudonymous`, `client_reference_invalid`, `invalid_capabilities`, `invalid_return_url`, `return_url_not_allowed`, `invalid_state`, `invalid_expires_in`, `invalid_limit`, `invalid_outcome`, `notice_not_accepted`, `document_required`, `document_no_face`, `selfie_required`, `no_face_detected`, `invalid_image`, `invalid_declared_type`, `step_not_in_challenge`, `invalid_text_sha256`, `invalid_channel`, `invalid_purposes`, `invalid_granted_at`, `granted_at_in_future`, `invalid_evidence_sha256`, `attestations_incomplete`, `invalid_legend`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Bloqueado": {
        "description": "`blocked_by_sic`: la SIC ordenó bloquear la información de este titular.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Limite": {
        "description": "`rate_limited` (por titular y hora) o `challenge_limit` (3 retos por sesión).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NoDisponible": {
        "description": "`analysis_unavailable`, `timestamp_unavailable` o `hosted_flow_not_configured`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "return_url_not_allowed"
              },
              "message": {
                "type": "string",
                "description": "En español y sin datos personales."
              },
              "return_url": {
                "type": "string",
                "format": "uri",
                "description": "Solo en `session_expired` y `session_already_opened` de la página alojada; lleva `pf_error`."
              },
              "receipt_id": {
                "type": "string",
                "format": "uuid"
              },
              "missing": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "images": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": true
          }
        }
      },
      "Sha256": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$"
      },
      "SubjectRef": {
        "type": "string",
        "pattern": "^[A-Za-z0-9._:\\-]{8,128}$",
        "description": "Seudónimo del titular que elige el cliente. No puede ser solo dígitos (número de documento) ni llevar `@` (correo).",
        "example": "cli-7f3a9c21-ab"
      },
      "ClientReference": {
        "type": [
          "string",
          "null"
        ],
        "pattern": "^[A-Za-z0-9._:\\-]{1,128}$",
        "description": "Referencia propia del cliente (no un número de documento). Va en los recibos.",
        "example": "SOL-2026-0001"
      },
      "Capability": {
        "type": "string",
        "enum": [
          "liveness",
          "document_match"
        ]
      },
      "SessionStatus": {
        "type": "string",
        "enum": [
          "created",
          "opened",
          "finishing",
          "finished",
          "redeemed",
          "expired"
        ]
      },
      "SessionResultStatus": {
        "type": "string",
        "enum": [
          "approved",
          "rejected",
          "alternative_requested",
          "cancelled"
        ]
      },
      "SessionCreateRequest": {
        "type": "object",
        "required": [
          "subject_ref",
          "consent_id",
          "capabilities",
          "return_url"
        ],
        "properties": {
          "subject_ref": {
            "$ref": "#/components/schemas/SubjectRef"
          },
          "consent_id": {
            "type": "string",
            "format": "uuid",
            "description": "De `POST /v1/consent`."
          },
          "capabilities": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "return_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "state": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,256}$",
            "description": "Valor opaco del cliente (anti-CSRF). Vuelve en la URL de retorno y en el token."
          },
          "client_reference": {
            "$ref": "#/components/schemas/ClientReference"
          },
          "expires_in": {
            "type": "integer",
            "minimum": 120,
            "maximum": 3600,
            "default": 1200
          }
        }
      },
      "SessionCreateResponse": {
        "type": "object",
        "required": [
          "session_id",
          "status",
          "session_url",
          "expires_at",
          "capabilities"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "const": "created"
          },
          "session_url": {
            "type": "string",
            "format": "uri",
            "description": "Un solo uso. No la guarde en registros."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          }
        }
      },
      "SessionResult": {
        "type": "object",
        "required": [
          "status",
          "liveness",
          "document_match"
        ],
        "description": "Resultado sin biometría.",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/SessionResultStatus"
          },
          "liveness": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "approved": {
                "type": "boolean"
              },
              "failed_steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "pending_steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "document_match": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "meets_threshold": {
                "type": "boolean"
              },
              "calibrated_score": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0,
                "maximum": 100
              },
              "false_match_rate": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "task": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "selfie_vs_document",
                  "live_vs_live",
                  null
                ]
              },
              "compared_against": {
                "type": "string",
                "enum": [
                  "liveness_reference",
                  "selfie"
                ]
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "`no_face_detected` o `not_compared_liveness_failed`."
              }
            }
          }
        }
      },
      "SessionSummary": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/SessionStatus"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "client_reference": {
            "$ref": "#/components/schemas/ClientReference"
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "redeemed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "completed",
              "alternative",
              "cancelled",
              null
            ]
          },
          "result": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SessionResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "receipt_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "operation_receipt_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "webhook": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "delivered": {
                "type": "boolean"
              },
              "status": {
                "type": "integer"
              },
              "error": {
                "type": "string"
              },
              "event_id": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        }
      },
      "TokenClaims": {
        "type": "object",
        "description": "Carga del JWS (cabecera `{\"alg\":\"ES256\",\"typ\":\"JWT\",\"kid\":\"pf-…\"}`).",
        "required": [
          "iss",
          "aud",
          "sub",
          "iat",
          "exp",
          "jti",
          "result",
          "receipt_id"
        ],
        "properties": {
          "iss": {
            "type": "string",
            "format": "uri",
            "example": "https://attest.novvai.systems"
          },
          "aud": {
            "type": "string",
            "description": "Id del cliente (tenant)",
            "p. ej. `novvai-demo`.": null
          },
          "sub": {
            "type": "string",
            "format": "uuid",
            "description": "`session_id` (= `pf_session`)."
          },
          "iat": {
            "type": "integer"
          },
          "exp": {
            "type": "integer",
            "description": "`iat` + 300."
          },
          "jti": {
            "type": "string",
            "format": "uuid",
            "description": "Guárdelo para aceptar el token una sola vez."
          },
          "client_reference": {
            "$ref": "#/components/schemas/ClientReference"
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "result": {
            "$ref": "#/components/schemas/SessionResult"
          },
          "receipt_id": {
            "type": "string",
            "format": "uuid",
            "description": "Recibo `hosted_session`."
          },
          "operation_receipt_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Recibo `liveness` o `compare`."
          }
        }
      },
      "RedeemResponse": {
        "type": "object",
        "required": [
          "session",
          "token_claims",
          "receipts"
        ],
        "properties": {
          "session": {
            "$ref": "#/components/schemas/SessionSummary"
          },
          "token_claims": {
            "$ref": "#/components/schemas/TokenClaims"
          },
          "receipts": {
            "type": "object",
            "required": [
              "session"
            ],
            "properties": {
              "session": {
                "$ref": "#/components/schemas/SignedReceipt"
              },
              "operation": {
                "$ref": "#/components/schemas/SignedReceipt"
              }
            }
          }
        }
      },
      "Notice": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "example": "aviso-sesion-2026-11-15"
          },
          "title": {
            "type": "string"
          },
          "paragraphs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "checkbox": {
            "type": "string"
          },
          "controller": {
            "type": "string",
            "description": "Responsable (el cliente)."
          },
          "processor": {
            "type": "string",
            "example": "Novvai Systems S.A.S."
          },
          "privacy_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "sha256": {
            "$ref": "#/components/schemas/Sha256"
          }
        }
      },
      "HostedSession": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "client_name": {
            "type": "string"
          },
          "notice": {
            "$ref": "#/components/schemas/Notice"
          },
          "notice_accepted": {
            "type": "boolean"
          },
          "challenges_left": {
            "type": "integer"
          },
          "return_origin": {
            "type": "string",
            "format": "uri"
          },
          "browser_token": {
            "type": "string",
            "description": "Solo en `open`."
          }
        }
      },
      "HostedFinishRequest": {
        "type": "object",
        "required": [
          "session_id",
          "outcome"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "completed",
              "alternative",
              "cancelled"
            ]
          },
          "reference_token": {
            "type": "string",
            "description": "El que devolvió el tramo «frente»."
          },
          "document_image": {
            "type": "object",
            "properties": {
              "data_b64": {
                "type": "string",
                "contentEncoding": "base64",
                "description": "JPEG o PNG",
                "hasta 2 MB.": null
              }
            }
          },
          "selfie_image": {
            "type": "object",
            "description": "Solo si la sesión pide únicamente `document_match`.",
            "properties": {
              "data_b64": {
                "type": "string",
                "contentEncoding": "base64"
              }
            }
          }
        }
      },
      "ConsentRequest": {
        "type": "object",
        "required": [
          "subject_ref",
          "authorization",
          "attestations"
        ],
        "properties": {
          "subject_ref": {
            "$ref": "#/components/schemas/SubjectRef"
          },
          "authorization": {
            "type": "object",
            "required": [
              "text_sha256",
              "version",
              "channel",
              "purposes",
              "granted_at"
            ],
            "properties": {
              "text_sha256": {
                "$ref": "#/components/schemas/Sha256"
              },
              "version": {
                "type": "string",
                "example": "aut-biometria-v3"
              },
              "channel": {
                "type": "string",
                "enum": [
                  "web",
                  "app",
                  "presencial",
                  "telefonico",
                  "otro"
                ]
              },
              "purposes": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "string",
                  "enum": [
                    "comparacion_facial",
                    "prueba_de_vida"
                  ]
                }
              },
              "granted_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 con zona; no futura."
              },
              "evidence_sha256": {
                "$ref": "#/components/schemas/Sha256"
              },
              "privacy_notice_version": {
                "type": "string"
              }
            }
          },
          "attestations": {
            "type": "object",
            "required": [
              "explicit_authorization",
              "prior_and_informed",
              "informed_optional_sensitive",
              "informed_sensitive_data_and_purpose",
              "alternative_without_biometrics_offered"
            ],
            "properties": {
              "explicit_authorization": {
                "const": true
              },
              "prior_and_informed": {
                "const": true
              },
              "informed_optional_sensitive": {
                "const": true
              },
              "informed_sensitive_data_and_purpose": {
                "const": true
              },
              "alternative_without_biometrics_offered": {
                "const": true
              }
            }
          }
        }
      },
      "ImageInput": {
        "type": "object",
        "required": [
          "data_b64"
        ],
        "properties": {
          "data_b64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "JPEG o PNG legible",
            "64–8000 px": null,
            "hasta 2 MB.": null
          },
          "declared_type": {
            "type": "string",
            "enum": [
              "auto",
              "selfie",
              "live_photo",
              "cedula_digital",
              "cedula_amarilla",
              "document"
            ],
            "default": "auto"
          }
        }
      },
      "CompareRequest": {
        "type": "object",
        "required": [
          "subject_ref",
          "consent_id",
          "image_1",
          "image_2"
        ],
        "properties": {
          "subject_ref": {
            "$ref": "#/components/schemas/SubjectRef"
          },
          "consent_id": {
            "type": "string",
            "format": "uuid"
          },
          "client_reference": {
            "$ref": "#/components/schemas/ClientReference"
          },
          "image_1": {
            "$ref": "#/components/schemas/ImageInput"
          },
          "image_2": {
            "$ref": "#/components/schemas/ImageInput"
          }
        }
      },
      "CompareResponse": {
        "type": "object",
        "properties": {
          "task": {
            "type": "string",
            "enum": [
              "selfie_vs_document",
              "live_vs_live"
            ]
          },
          "similarity": {
            "type": "number"
          },
          "calibrated_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "80 = FMR 1e-4. No es una probabilidad."
          },
          "false_match_rate": {
            "type": "number"
          },
          "false_match_rate_text": {
            "type": "string",
            "example": "1 de cada 250.000"
          },
          "fmr_target": {
            "type": "number"
          },
          "meets_threshold": {
            "type": "boolean"
          },
          "decision_note": {
            "type": "string"
          },
          "image_type": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "model": {
            "type": "string",
            "example": "predictoface-v2.1"
          },
          "model_version": {
            "type": "string",
            "example": "v2.1"
          },
          "inputs": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "receipt": {
            "$ref": "#/components/schemas/SignedReceipt"
          }
        }
      },
      "ChallengeResponse": {
        "type": "object",
        "properties": {
          "challenge_id": {
            "type": "string",
            "format": "uuid"
          },
          "session_token": {
            "type": "string",
            "description": "Bearer de `POST /v1/liveness/segment`."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "steps": {
            "type": "array",
            "description": "Siempre empieza por `frente`. Los demás los configura la pila (`RetosLiveness`); por defecto un gesto al azar y `acercar` (con guía en vivo en la página alojada). Sonrisa y sorpresa exigen un cambio frente al rostro en reposo del `frente`.",
            "items": {
              "type": "string",
              "enum": [
                "frente",
                "sonrisa",
                "sorpresa",
                "boca",
                "acercar",
                "punto"
              ]
            },
            "example": [
              "frente",
              "sonrisa",
              "acercar"
            ]
          },
          "values": {
            "type": "object",
            "properties": {
              "punto": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "minItems": 2,
                  "maxItems": 2
                }
              },
              "boca_veces": {
                "type": "integer",
                "minimum": 3,
                "maximum": 4
              },
              "luz": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "d": {
                      "type": "number"
                    },
                    "nivel": {
                      "type": "integer",
                      "enum": [
                        0,
                        1
                      ]
                    }
                  }
                }
              }
            }
          },
          "limits": {
            "type": "object",
            "properties": {
              "max_segment_bytes": {
                "type": "integer",
                "example": 4000000
              },
              "max_segments": {
                "type": "integer",
                "example": 24
              },
              "valid_seconds": {
                "type": "integer",
                "example": 600
              }
            }
          }
        }
      },
      "SegmentRequest": {
        "type": "object",
        "required": [
          "challenge_id",
          "step",
          "video_b64"
        ],
        "properties": {
          "challenge_id": {
            "type": "string",
            "format": "uuid"
          },
          "step": {
            "type": "string",
            "enum": [
              "frente",
              "sonrisa",
              "sorpresa",
              "boca",
              "acercar",
              "punto"
            ]
          },
          "events": {
            "type": "object",
            "description": "Marcas de tiempo del reto (hasta 64 KB)."
          },
          "mime": {
            "type": "string",
            "example": "video/webm"
          },
          "video_b64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "5 KB a 4 MB."
          },
          "reference_token": {
            "type": "string",
            "description": "Obligatorio después del «frente»."
          }
        }
      },
      "SegmentResponse": {
        "type": "object",
        "required": [
          "n",
          "step",
          "ok"
        ],
        "properties": {
          "n": {
            "type": "integer"
          },
          "step": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "next_values": {
            "type": "object"
          },
          "reference_token": {
            "type": "string"
          }
        }
      },
      "DecisionResponse": {
        "type": "object",
        "properties": {
          "challenge_id": {
            "type": "string",
            "format": "uuid"
          },
          "approved": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "aprobado",
              "rechazado"
            ]
          },
          "pending_steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "failed_steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "document_compare": {
            "type": [
              "object",
              "null"
            ]
          },
          "reference_image_b64": {
            "type": "string",
            "contentEncoding": "base64"
          },
          "receipt": {
            "$ref": "#/components/schemas/SignedReceipt"
          }
        }
      },
      "SignedReceipt": {
        "type": "object",
        "required": [
          "receipt",
          "signature"
        ],
        "properties": {
          "receipt": {
            "type": "object",
            "required": [
              "receipt_id",
              "receipt_type",
              "issued_at",
              "api_version",
              "issuer",
              "tenant_id",
              "data_handling"
            ],
            "properties": {
              "receipt_id": {
                "type": "string",
                "format": "uuid"
              },
              "receipt_type": {
                "type": "string",
                "enum": [
                  "compare",
                  "liveness",
                  "consent_registration",
                  "consent_revocation",
                  "subject_legend",
                  "subject_deletion",
                  "hosted_session"
                ]
              },
              "issued_at": {
                "type": "string",
                "format": "date-time"
              },
              "api_version": {
                "type": "string"
              },
              "issuer": {
                "type": "object"
              },
              "tenant_id": {
                "type": "string"
              },
              "subject_hash": {
                "type": "string",
                "description": "HMAC-SHA256(pimienta, \"<cliente>:<subject_ref>\")."
              },
              "data_handling": {
                "type": "object",
                "properties": {
                  "images_stored": {
                    "const": false
                  },
                  "videos_stored": {
                    "const": false
                  },
                  "biometric_templates_stored": {
                    "const": false
                  },
                  "age_or_sex_estimated": {
                    "const": false
                  },
                  "used_for_training": {
                    "const": false
                  }
                }
              }
            },
            "additionalProperties": true
          },
          "signature": {
            "type": "object",
            "properties": {
              "alg": {
                "const": "ES256-DER"
              },
              "kid": {
                "type": "string"
              },
              "value": {
                "type": "string",
                "contentEncoding": "base64",
                "description": "Firma DER sobre SHA-256 del JCS de `receipt`."
              },
              "signed_sha256": {
                "$ref": "#/components/schemas/Sha256"
              },
              "canonicalization": {
                "const": "RFC 8785"
              }
            }
          },
          "timestamp": {
            "type": [
              "object",
              "null"
            ],
            "description": "Sello RFC 3161 opcional sobre el SHA-256 de la firma."
          },
          "timestamp_error": {
            "type": "string"
          },
          "legend": {
            "type": "object"
          }
        }
      },
      "Jwk": {
        "type": "object",
        "required": [
          "kty",
          "crv",
          "x",
          "y",
          "kid"
        ],
        "properties": {
          "kty": {
            "const": "EC"
          },
          "crv": {
            "const": "P-256"
          },
          "x": {
            "type": "string"
          },
          "y": {
            "type": "string"
          },
          "kid": {
            "type": "string",
            "example": "pf-3a9c0d1e2f4b5a6c"
          },
          "alg": {
            "const": "ES256"
          },
          "use": {
            "const": "sig"
          },
          "pf_purpose": {
            "type": "string",
            "enum": [
              "token",
              "receipt"
            ]
          }
        }
      },
      "Jwks": {
        "type": "object",
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Jwk"
            }
          }
        }
      },
      "PredictoFaceKeys": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string"
          },
          "stack": {
            "type": "string"
          },
          "api_version": {
            "type": "string"
          },
          "canonicalization": {
            "type": "string"
          },
          "signature_alg": {
            "type": "string"
          },
          "keys": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Jwk"
                },
                {
                  "type": "object",
                  "properties": {
                    "spki_der_b64": {
                      "type": "string"
                    },
                    "pem": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "properties": {
          "type": {
            "const": "session.finished"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "properties": {
              "session_id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "$ref": "#/components/schemas/SessionResultStatus"
              },
              "client_reference": {
                "$ref": "#/components/schemas/ClientReference"
              },
              "receipt_id": {
                "type": "string",
                "format": "uuid"
              },
              "operation_receipt_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      }
    }
  }
}
