openapi: 3.0.0
info:
  version: 1.7.0
  title: INE-Service Rest API
  description: |
    API REST de la solución biométrica para la autenticación facial de INE.

    La autenticación JWT opcional se puede habilitar al arrancar desde `config.json` o
    las variables de entorno `FACEPHI_INE_REST_AUTH_*`.

    `GET /api/v1/health` y `GET /api/v1/version` permanecen públicos.
    `POST /api/v1/facial/authentication` requiere un JWT válido cuando la autenticación está habilitada.

    Este servicio no expone endpoints `GET/POST /config` en tiempo de ejecución.

servers:
 - url: http://127.0.0.1:6982/

tags:
  - name: Authentication
    description: Operación protegida de autenticación facial.
  - name: Management
    description: Endpoints públicos de estado y versión del servicio.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  schemas:

    IdTransaction:
      type: string
      description: Identificador único asociado a la transacción que se está procesando.
      example: idTx

    PhotoBuffer:
      type: string
      example: /9j/4AAQSkZJRgABAQEAtAC0AAD...
      description: Imagen de la foto codificada en base64 RFC4648.

    ErrorCodes:
      type: number
      description: Códigos de error de la operación.
      example: 0
      enum:
        - OK              = 0
        - MALFORMED_JSON  = 400
        - PHOTOA_EMPTY    = 401
        - PHOTOB_EMPTY    = 402
        - NO_PHOTOS       = 403
        - POSE_INVALID    = 404
        - PHOTOA_INVALID  = 405
        - PHOTOB_INVALID  = 406

    PhotoTypes:
      type: number
      description: Tipos de imagen de foto soportados.
      example: 0
      enum:
        - INE               = 0
        - JPEG              = 1
        - TEMPLATE_RAW      = 2
        - BEST_IMAGE_TOKEN  = 3

    Score:
      type: integer
      minimum: 0
      maximum: 1
      description: Puntuación resultante de la comparación.
      example: 1

    Similarity:
      type: number
      minimum: 0
      maximum: 100
      description: Similitud resultante de la comparación.
      example: 99.00

    ServiceTime:
      type: integer
      description: Tiempo total en milisegundos desde que llega la solicitud hasta que se envía la respuesta.
      example: 492

    TimeStamp:
      type: string
      description: Un valor de fecha/hora en formato "%Y-%m-%dT%H:%M:%SZ".
      example: "2026-07-02T10:42:05Z"

    Photo:
      type: object
      properties:
        tipo:
          $ref: '#/components/schemas/PhotoTypes'
        data:
          $ref: '#/components/schemas/PhotoBuffer'

    AuthenticationResponse:
      type: object
      description: Resultado de la comparación de fotos
      properties:
        codigo:
          $ref: '#/components/schemas/ErrorCodes'
        score:
          $ref: '#/components/schemas/Score'
        resultado:
          $ref: '#/components/schemas/Similarity'
        tiempoServicio:
          $ref: '#/components/schemas/ServiceTime'

    AuthenticationBody:
      type: object
      description: Cuerpo de la solicitud de autenticación
      properties:
        idTransaccion:
          $ref: '#/components/schemas/IdTransaction'
        fotoA:
          $ref: '#/components/schemas/Photo'
        fotoB:
          $ref: '#/components/schemas/Photo'

      required:
        - idTransaccion
        - fotoA
        - fotoB

    BadRequestResult:
      type: object
      description: Resultado cuando llegan parámetros incorrectos en la solicitud.
      properties:
        status:
          type: number
          example: 400
        error:
          type: string
          example: "BadRequest"
        message:
          type: string
          example: "Malformed Base64 input"
        timeStamp:
          $ref: '#/components/schemas/TimeStamp'

    UnauthorizedResult:
      type: object
      description: Resultado cuando la solicitud no proporciona un JWT válido.
      properties:
        status:
          type: number
          example: 401
        error:
          type: string
          example: "Unauthorized"
        message:
          type: string
          example: "Missing authentication token"
        timeStamp:
          $ref: '#/components/schemas/TimeStamp'

    ExceptionResult:
      type: object
      description: Se ha producido un error en la llamada al backend del SDK.
      properties:
        status:
          type: number
          example: 500
        error:
          type: string
          example: "SDK Exception"
        exception:
          type: string
          example: "Bad format"
        timeStamp:
          $ref: '#/components/schemas/TimeStamp'

    HealthStatus:
      type: string
      description: Resultado del servicio de salud (si el SDK está activo o no).
      example: "Healthy"
      enum:
        - Healthy
        - Unhealthy

    HealthResult:
      type: object
      description: El resultado de una comprobación de salud.
      properties:
        message:
          $ref: '#/components/schemas/HealthStatus'

    VersionResult:
      type: object
      description: El resultado de una comprobación de versión.
      properties:
        message:
          type: string
          example: "1.7.0 Copyright @ 2026 FacePhi. All rights reserved."
        sdk:
          type: object
          description: Información del SDK devuelta por el servicio.
          properties:
            version:
              type: string
              example: "SelphIDVerifier 6.20.0"
            modules:
              type: string
              example: "Face & Extractors"

paths:

  /api/v1/facial/authentication:
    post:
      description: Este endpoint se utiliza para autenticar dos imágenes de fotos.

      tags:
        - Authentication

      security:
        - BearerAuth: []
        - ApiKeyAuth: []

      requestBody:
        description: Json con la foto de entrada codificada en formato base64 RFC4648
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationBody'

      responses:
        '200':
          description: El resultado de la autenticación.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'

        '400':
          description: Llegan parámetros incorrectos en la solicitud.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResult'

        '401':
          description: Falta el token de autenticación JWT o no es válido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResult'

        '500':
          description: Se ha producido un error en la llamada al backend del SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResult'

  /api/v1/health:
    get:
      description: Endpoint público. Comprueba si el servicio está activo.

      tags:
        - Management

      responses:
        '200':
          description: Un mensaje con el estado de salud.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResult'
        '400':
          description: Llegan parámetros incorrectos en la solicitud.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResult'
        '500':
          description: Se ha producido un error en la llamada al backend del SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResult'

  /api/v1/version:
    get:
      description: Endpoint público. Comprueba la versión del servicio INE.

      tags:
        - Management

      responses:
        '200':
          description: Un mensaje con la versión.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResult'
        '400':
          description: Llegan parámetros incorrectos en la solicitud.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResult'
        '500':
          description: Se ha producido un error en la llamada al backend del SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResult'
