#!TODO change process image field
openapi: 3.0.0
info:
  version: 2.18.2
  title: OCR Service Rest API
  description: |
    API REST para el procesamiento OCR.

    Se puede habilitar de forma opcional la autenticación JWT al arrancar desde `config.json` o mediante las variables de entorno `FACEPHI_OCR_REST_AUTH_*`.
    Cuando está habilitada, `GET /api/v1/version` y `GET /api/v1/health` siguen siendo públicos, mientras que el resto de endpoints requieren un JWT válido.

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

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Nombre de la cabecera de la clave de API por defecto. Puede sobrescribirse en el arranque con `auth_api_key_header_name`.

  schemas:

    type:
        type: string
        description: Es necesario especificar el tipo de documento que se desea procesar, ya que nuestro servicio puede gestionar diferentes tipos de documentos.
        example: "id_card"
        enum:
            - id_card
            - passport
            - driver_license
            - foreign_card
            - invoice
            - pdf

    model:
        type: string
        example: "ARG"
        description:  Este parámetro especifica el ID del documento que se va a procesar.

    image:
        type: string
        example: "/9j/4AAQSkZJRgABAQEAtAC0AAD..."
        description: Este parámetro especifica la imagen a procesar codificada en base64 RFC4648.

    isCropped:
        type: boolean
        default: false
        deprecated: true
        description: Si la `image` ya está recortada y alineada, el servicio puede evitar realizar estas operaciones. Solo aplica a documentos `invoice`.

    forceDetection:
        type: boolean
        default: false
        deprecated: true
        description: Si el documento `invoice` no tiene la relación de aspecto correcta, el servicio puede realizar una operación para corregirla y mejorar la detección del documento. Solo aplica a documentos `invoice`.

    files:
        type: array
        example: ["iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC.b64"]
        description: Array de imágenes en formato de buffer en bruto codificadas en base64 RFC4648.
        items:
            type: string

    retrieveImages:
        type: boolean
        default: false
        description: El servicio devolverá la imagen recortada en base64 en el resultado final.

    DictionaryResult:
        type: object
        description: Campos detectados en una imagen. Serán diferentes en función de la imagen.
        properties:
            DateOfBirth:
                type: string
                description: Fecha de nacimiento.
                example: "1900-01-01"
            DateOfExpiry:
                type: string
                description: Fecha de caducidad.
                example: "1900-01-01"
            DateOfIssue:
                type: string
                description: Fecha de expedición.
                example: "1901-01-01"
            DocumentCaptured:
                type: string
                description: Tipo de documento capturado.
                example: "ARG/v1"
            DocumentNumber:
                type: string
                description: Número de documento.
                example: "12345678A"
            FirstName:
                type: string
                description: Nombre.
                example: "Alicia"
            Nationality:
                type: string
                description: Nacionalidad.
                example: "ESP"

    ProcessResult:
        type: object
        description: Resultado del procesamiento de una imagen.
        properties:
            dictionary:
                $ref: '#/components/schemas/DictionaryResult'
            type:
                $ref: '#/components/schemas/type'
            model:
                $ref: '#/components/schemas/model'
            version:
                type: string
                description: Versión del documento detectado.
                example: "2020"
            side:
                type: string
                description: Lado del documento detectado.
                example: "front"
            croppedImage:
                type: string
                description: Imagen recortada codificada en base64 RFC4648.
                example: "/9j/4AAQSkZJRgABAQEAtAC0AAD..."

    ProcessResultUniversal:
        type: object
        description: Resultado en formato de respuesta universal de un procesamiento de imagen (soporte multialfabeto).
        required:
            - version
            - type
            - model
            - ocr
            - viz
            - checks
        properties:
            version:
                type: integer
                description: Versión del esquema JSON UR de OCR.
                example: 1
            type:
                type: string
                description: Tipo de documento.
                example: "id_card"
            model:
                type: string
                description: Modelo del documento.
                example: "ARG"
            ocr:
                type: object
                description: Diccionario de campos OCR procesados por widgets (claves sin estructura Side/Source/FieldName).
                additionalProperties:
                    $ref: '#/components/schemas/UROCRField'
            images:
                type: array
                description: Array que contiene las imágenes extraídas del documento.
                items:
                    $ref: '#/components/schemas/URImage'
            viz:
                type: array
                description: Datos extraídos mediante la fuente ML/VIZ.
                items:
                    $ref: '#/components/schemas/URViz'
            mrz:
                type: array
                description: Datos extraídos de la MRZ (Machine Readable Zone).
                items:
                    $ref: '#/components/schemas/URMRZ'
            encoded:
                type: array
                description: Datos extraídos de QR, código de barras o PDF417.
                items:
                    $ref: '#/components/schemas/UREncoded'
            nfc:
                type: array
                description: Datos extraídos mediante NFC.
                items:
                    $ref: '#/components/schemas/URNFC'
            checks:
                $ref: '#/components/schemas/URChecks'

    UROCRField:
        type: object
        description: Campo OCR con información de valor, confianza y origen.
        required:
            - value
        properties:
            value:
                type: string
                description: El valor extraído.
                example: "12345678A"
            confidence:
                type: number
                description: Puntuación de confianza de la extracción.
                example: 0.95
                minimum: 0
                maximum: 1
            source:
                $ref: '#/components/schemas/UROCRSource'

    UROCRSource:
        type: object
        description: Información de origen de un campo OCR.
        required:
            - type
            - index
        properties:
            type:
                $ref: '#/components/schemas/URSourceType'
            index:
                type: integer
                description: Índice del elemento de origen.
                example: 0

    URSourceType:
        type: string
        description: Tipo de origen de los datos extraídos.
        enum:
            - viz
            - encoded
            - nfc
            - mrz

    URImage:
        type: object
        description: Imagen extraída del documento.
        required:
            - type
            - source
        properties:
            type:
                $ref: '#/components/schemas/URImageType'
            side:
                type: integer
                description: Lado del documento (0=Anverso, 1=Reverso).
                example: 0
            source:
                $ref: '#/components/schemas/URSourceType'
            content:
                $ref: '#/components/schemas/URImageContent'
            region:
                $ref: '#/components/schemas/URRegion'

    URImageType:
        type: string
        description: Tipo de imagen extraída.
        enum:
            - portrait
            - ghost
            - signature
            - fullFrame
            - document
            - fingerprint

    URImageContent:
        type: object
        description: Contenido de una imagen en formato base64.
        required:
            - data
            - length
        properties:
            data:
                type: string
                description: Datos de la imagen codificados en base64 RFC4648.
                example: "/9j/4AAQSkZJRgABAQEAtAC0AAD..."
            length:
                type: integer
                description: Longitud de los datos de la imagen.
                example: 12345
            mime_type:
                type: string
                description: Tipo MIME de la imagen.
                example: "image/jpeg"

    URViz:
        type: object
        description: Datos extraídos mediante la fuente ML/VIZ.
        required:
            - field
            - value
            - side
        properties:
            field:
                type: string
                description: Nombre del campo.
                example: "DocumentNumber"
            value:
                type: string
                description: Valor extraído.
                example: "12345678A"
            side:
                type: integer
                description: Lado del documento (0=Anverso, 1=Reverso).
                example: 0
            confidence:
                type: number
                description: Puntuación de confianza.
                example: 0.95
                minimum: 0
                maximum: 1
            alphabet:
                type: string
                description: Alfabeto utilizado en el campo.
                example: "latin"
            region:
                $ref: '#/components/schemas/URRegion'

    URMRZ:
        type: object
        description: Datos de la MRZ (Machine Readable Zone).
        required:
            - side
            - raw
            - fields
        properties:
            side:
                type: integer
                description: Lado del documento (0=Anverso, 1=Reverso).
                example: 1
            confidence:
                type: number
                description: Puntuación de confianza.
                example: 0.98
                minimum: 0
                maximum: 1
            raw:
                type: string
                description: Texto MRZ en bruto (equivalente al campo MrzText).
                example: "P<ESPGARCIA<<MARIA<<<<<<<<<<<<<<<<<<<<<<<"
            fields:
                type: object
                description: Diccionario de campos MRZ analizados.
                additionalProperties:
                    type: string
                example:
                    DocumentNumber: "AAA000000"
                    DateOfBirth: "1990-01-01"
            region:
                $ref: '#/components/schemas/URRegion'

    UREncoded:
        type: object
        description: Datos extraídos de formatos codificados (QR, código de barras, PDF417).
        required:
            - fields
            - type
            - side
            - raw
            - rawBinary
        properties:
            fields:
                type: object
                description: Diccionario de campos analizados a partir de los datos codificados.
                additionalProperties:
                    type: string
            type:
                $ref: '#/components/schemas/UREncodedType'
            side:
                type: integer
                description: Lado del documento (0=Anverso, 1=Reverso).
                example: 1
            raw:
                type: string
                description: Cadena decodificada en bruto (QrData, BarcodeData o PdfData).
                example: "RAW_ENCODED_DATA"
            rawBinary:
                type: string
                description: Datos binarios originales extraídos de la imagen codificada, en base64.
                example: "AQIDBAUGBwgJ"
            region:
                $ref: '#/components/schemas/URRegion'

    UREncodedType:
        type: string
        description: Tipo de dato codificado.
        enum:
            - qr
            - barcode
            - pdf

    URNFC:
        type: object
        description: Datos extraídos mediante el componente NFC.
        required:
            - field
            - value
        properties:
            field:
                type: string
                description: Nombre del campo NFC.
                example: "DocumentNumber"
            value:
                type: string
                description: Valor extraído mediante NFC.
                example: "12345678A"
            alphabet:
                type: string
                description: Alfabeto utilizado en el campo.
                example: "latin"

    URChecks:
        type: object
        description: Comprobaciones de validación realizadas sobre los datos OCR.
        properties:
            field_inconsistency:
                type: array
                description: Lista de inconsistencias de campo encontradas.
                items:
                    $ref: '#/components/schemas/FieldInconsistency'

    FieldInconsistency:
        type: object
        description: Inconsistencia detectada entre los valores de un campo.
        required:
            - field
            - distance
        properties:
            field:
                type: string
                description: Nombre del campo con inconsistencia.
                example: "DocumentNumber"
            values:
                type: array
                description: Diferentes valores encontrados para el mismo campo.
                items:
                    type: string
                example: ["12345678A", "12345678B"]
            distance:
                type: integer
                description: Métrica de distancia de la inconsistencia.
                example: 1

    URRegion:
        type: object
        description: Coordenadas de la región que definen la ubicación de los datos extraídos en la imagen.
        required:
            - top_left
            - top_right
            - bottom_left
            - bottom_right
        properties:
            top_left:
                $ref: '#/components/schemas/URCoordinates'
            top_right:
                $ref: '#/components/schemas/URCoordinates'
            bottom_left:
                $ref: '#/components/schemas/URCoordinates'
            bottom_right:
                $ref: '#/components/schemas/URCoordinates'

    URCoordinates:
        type: object
        description: Coordenadas X,Y en la imagen.
        required:
            - x
            - y
        properties:
            x:
                type: number
                description: Coordenada X.
                example: 100.5
            y:
                type: number
                description: Coordenada Y.
                example: 200.3

    ProcessBody:
        type: object
        description: Cuerpo para el procesamiento OCR
        properties:
            type:
                $ref: '#/components/schemas/type'
            model:
                $ref: '#/components/schemas/model'
            files:
                $ref: '#/components/schemas/files'
            isCropped:
                $ref: '#/components/schemas/isCropped'
            forceDetection:
                $ref: '#/components/schemas/forceDetection'
            retrieveImages:
                $ref: '#/components/schemas/retrieveImages'

    RawBody:
        type: object
        description: Cuerpo para el procesamiento OCR en modo raw
        properties:
            type:
                $ref: '#/components/schemas/type'
            image:
                $ref: '#/components/schemas/image'

    RawResultVertice:
        type: object
        description: Coordenadas x, y en sentido horario.
        properties:
            x:
                type: number
            y:
                type: number

    RawResultVertices:
        type: array
        description: Coordenadas x, y en sentido horario.
        items:
            $ref: '#/components/schemas/RawResultVertice'

    RawResult:
        type: object
        description: Resultado del procesamiento de una imagen.
        properties:
            description:
                type: string
                description: Palabra encontrada.
                example: "12345678A"
            vertices:
                type: array
                description: Cuatro coordenadas x, y en sentido horario.
                items:
                    $ref: '#/components/schemas/RawResultVertices'
            confidence:
                type: number
                description: Confianza de la palabra.
                example: 0.871

    TimeStamp:
        type: string
        description: Un valor de fecha/hora en formato "%Y-%m-%dT%H:%M:%SZ".
        example: "2022-01-14T10:42:05.521922Z"

    BadRequestResult:
        type: object
        description: Resultado cuando llegan parámetros incorrectos en la petición.
        properties:
            status:
                type: number
                example: 400
            error:
                type: string
                example: "BadRequest"
            message:
                type: string
                example: "Invalid number of files. Expected 2 max, got 3."
            timeStamp:
                $ref: '#/components/schemas/TimeStamp'

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

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

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

    VersionResult:
        type: object
        description: El resultado de una comprobación de versión.
        properties:
            message:
                type: string
                example: "X.X.X Copyright @ 2025 FacePhi. All rights reserved."

    ConfigResult:
      type: object
      description: Objeto JSON con los parámetros de configuración del servicio. Los ajustes de autenticación JWT se omiten intencionadamente.
      example: {
        "port": 6982,
        "number_of_threads": 1,
        "connection_timeout": 0,
        "keep_alive_request_number": 0,
        "client_max_body_size": 100,
        "logger_path": "",
        "logger_level": "off",
        "logger_rotation": "daily",
        "logger_max_files": 7
      }

    ConfigBody:
      type: object
      description: Cuerpo para la petición de configuración. Este endpoint no acepta ajustes de autenticación JWT.
      properties:
        config_json_string:
          type: string
          description: Cadena JSON con los parámetros de configuración del servicio que se pueden actualizar en tiempo de ejecución.
          example: "{\"fake_param\":\"fake\",\"number_of_threads\":\"2\"}"
      required:
        - config_json_string

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

paths:
  /api/v1/process:
    post:
      description: Procesa el alfabeto latino mediante OCR
      tags:
        - OCR processing

      requestBody:
        description: JSON con la entrada OCR
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessBody'

      responses:
        '200':
          description: El resultado del procesamiento OCR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessResult'

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

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

  /api/v1/process_multi:
    post:
      description: Procesa múltiples alfabetos mediante OCR
      tags:
        - OCR processing

      requestBody:
        description: JSON con la entrada OCR
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessBody'

      responses:
        '200':
          description: El resultado del procesamiento OCR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessResultUniversal'

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

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

  /api/v1/raw:
    post:
      description: Procesa OCR en modo raw
      tags:
        - OCR processing

      requestBody:
        description: JSON con la entrada OCR
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RawBody'

      responses:
        '200':
          description: El resultado del procesamiento OCR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RawResult'

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

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

  /api/v1/health:
    get:
      description: Comprueba si el servicio está activo.
      security: []
      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 petición.
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/BadRequestResult'
        '500':
          description:  Se ha producido un error en la llamada al backend de OCR-SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResult'

  /api/v1/version:
    get:
      description: Comprueba la versión del servicio OCR.
      security: []
      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 petición.
            content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/BadRequestResult'
        '500':
            description:  Se ha producido un error en la llamada al backend de OCR-SDK.
            content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/ExceptionResult'

  /api/v1/config:
    get:
      description: Obtiene la configuración del servicio. Los ajustes de autenticación JWT se ocultan intencionadamente en esta respuesta.
      tags:
        - Management
      responses:
        '200':
          description: Objeto JSON con la configuración del servicio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResult'
        '400':
          description: Llegan parámetros incorrectos en la petición.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResult'
        '500':
          description:  Se ha producido un error en la llamada al backend de Voice-SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResult'
    post:
      description: Actualiza la configuración del servicio. Solo se pueden actualizar algunos parámetros en tiempo de ejecución.
                   Los parámetros relacionados con la red (puerto, timeouts, tamaño del cuerpo...) o con el logger (ruta, nivel...) no se pueden actualizar en tiempo de ejecución.
                   Los ajustes de autenticación JWT son exclusivos del arranque y este endpoint los rechaza.
      tags:
        - Management
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigBody'
        required: true
      responses:
        '200':
          description: Mensaje con el resultado de la operación.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Configuration updated successfully"

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

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