openapi: 3.2.0
info:
  title: Claix Imagen a JSON API
  description: Claix es una API de conversión de datos tabulares, JSON y documentos (PDF, Word, texto plano, imágenes) pensada para integraciones server-to-server (backends, scripts, herramientas de automatización como n8n, Zapier o Make).
  version: 1.8.2
servers:
- url: https://claix.dev/api
  description: Producción (dominio público Claix)
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Imagen a JSON
  description: Extracción de datos estructurados a partir de imágenes (.jpeg, .jpg, .png, .webp, .heic, .heif)
paths:
  /img-json:
    post:
      operationId: imgToJson
      tags:
      - Imagen a JSON
      summary: Extrae datos estructurados de una imagen según un schema
      description: 'Recibe una imagen (.jpeg, .jpg, .png, .webp, .heic o .heif) y un schema_id, y devuelve un único objeto JSON con los datos extraídos del contenido visible, con las claves exactamente iguales a las propiedades definidas en el schema. El análisis lo realiza un modelo multimodal de IA. Antes de extraer datos, el modelo evalúa si la imagen es legible (nitidez, enfoque, iluminación); si no lo es, responde con 422. Igual que en pdf-json, la imagen se trata como una única fuente de datos: la respuesta siempre contiene exactamente un registro en "data". El tamaño máximo de archivo admitido es 15 MB.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImgJsonRequest'
      responses:
        '200':
          description: Imagen analizada y datos extraídos correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImgJsonSuccessResponse'
        '400':
          description: 'Petición inválida (archivo faltante, formato no soportado, imagen vacía, corrupta, firma binaria incoherente, o schema_id incorrecto/faltante/de tipo equivocado)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No autorizado (API key inválida, inactiva o cuenta suspendida)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: El schema_id no existe o no pertenece a la cuenta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Método HTTP no permitido (solo se admite POST)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: La imagen supera el tamaño máximo admitido (15 MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: 'Imagen ilegible (borrosa, desenfocada, mal iluminada) o sin datos extraíbles según el schema indicado

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Fallo del servicio de IA encargado de analizar la imagen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Descripción legible del problema.
          example: No se envió el campo schema_id.
        detalle:
          type: string
          description: Información técnica adicional (solo presente en algunos casos).
          example: Missing required field 'schema_id' in multipart/form-data body.
    ImgJsonSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        schema_utilizado:
          type: string
          description: Nombre del schema aplicado.
          example: Facturas de Proveedores
        total_registros:
          type: integer
          description: 'Siempre 1 en este endpoint: la imagen completa se trata como una única fuente de datos, no como una tabla de múltiples filas.

            '
          example: 1
        data:
          type: array
          description: 'Contiene exactamente un objeto con los datos extraídos de la imagen, según las propiedades definidas en el schema. Los datos no encontrados se devuelven como null.

            '
          items:
            type: object
            additionalProperties: true
          example:
          - numero_factura: F-2026-00456
            fecha_emision: '2026-03-14'
            proveedor: Suministros Industriales del Ebro S.L.
            importe_total: 1284.5
            moneda: EUR
    ImgJsonRequest:
      type: object
      required:
      - file
      - schema_id
      properties:
        file:
          type: string
          format: binary
          description: 'Imagen a analizar. Formatos admitidos: .jpeg, .jpg, .png, .webp, .heic y .heif. Tamaño máximo admitido: 15 MB.

            '
        schema_id:
          type: string
          format: uuid
          description: 'Identificador del schema (previamente creado) de tipo "Imagen a JSON".

            '
          example: 3c7a9f21-4b8e-4d1a-9c6f-2e0d8a5b7c4f
        space_id:
          type: string
          format: uuid
          description: 'Opcional. Espacio de conocimiento al que se asocia el documento guardado. Debe pertenecer al mismo usuario dueño de la API key. Solo tiene efecto cuando el schema tiene la ventana de contexto activada, que es cuando el documento se guarda.

            '
          example: 5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key secreta de servidor. Tiene prioridad sobre Authorization si se envían ambos headers.

        '
    BearerAuth:
      type: http
      scheme: bearer
      description: Forma alternativa de enviar la API key como Bearer token.