Claix JSON a Excel API

openapi: 3.2.0
info:
  title: Claix JSON a Excel API
  description: 'Claix es una API de conversión de datos tabulares, JSON y documentos (PDF, Word, texto plano, imágenes, audio) pensada para integraciones server-to-server (backends, scripts, herramientas de automatización como n8n, Zapier o Make). Source Tracing opcional: citas por campo `{ value, source }` o `requires_human_revision` si falta evidencia. Expone seis endpoints principales de conversión:

    - **Excel/CSV → JSON**: recibe un archivo Excel o CSV y lo transforma en

    JSON según la estructura definida en un "schema" previamente creado. - **JSON → Excel**: recibe uno o varios documentos JSON y devuelve un

    archivo Excel (.xlsx) binario, según la estructura definida en un

    "schema" previamente creado. - **PDF → JSON**: recibe un archivo PDF (de texto o escaneado) y devuelve

    un objeto JSON con los datos extraídos del documento, según la

    estructura definida en un "schema" previamente creado. - **Documento → JSON**: recibe un archivo de documento (.docx, .txt, .md

    o .rtf) y devuelve un objeto JSON con los datos extraídos, según la

    estructura definida en un "schema" previamente creado. - **Imagen → JSON**: recibe una imagen (.jpeg, .jpg, .png, .webp, .heic

    o .heif) y devuelve un objeto JSON con los datos extraídos del

    contenido visible, según la estructura definida en un "schema"

    previamente creado. - **Txt / HTML / XML → JSON**: recibe el campo `content` (texto plano,

    HTML o XML ya procesado, sin archivo) y devuelve un objeto JSON con los

    datos extraídos, según un schema de tipo txt-json. Máximo 300.000

    caracteres. Tarifa fija €0,10 por llamada exitosa tras el free tier. - **Excel/CSV → Markdown**, **PDF → Markdown**, **Documento → Markdown**,

    **Imagen → Markdown**, **Txt/HTML/XML → Markdown** y **Audio → Markdown**:

    misma autenticación, mismos formatos y mismos límites que el endpoint JSON

    equivalente. No piden schema_id. save=true inserta el Markdown en la base

    conectada y la respuesta incluye row_id. PDF con texto, Excel, documentos y

    texto se convierten en local. PDF escaneado, imagen y audio llaman al

    mismo modelo con BYOK. - **Audio → JSON**: recibe un archivo de audio (.mp3, .wav, .m4a o .ogg)

    y un schema_id, y devuelve un único objeto JSON con los datos extraídos

    de lo hablado. Tamaño máximo 12 MB y duración máxima 10 minutos. Si el

    audio no es inteligible, responde 422. Además, expone endpoints para consultar y gestionar los schemas de la cuenta:

    - **Listar schemas**: dado un API key, devuelve todos los schemas de esa

    cuenta con su información completa (id, nombre, tipo y definición). - **Obtener schema**: dado un `schema_id` en la URL, devuelve ese schema

    con su definición completa. - **Crear schema**: crea un schema con `name`, `type`, `schema_definition`

    y, opcionalmente, Modo Agente (`is_agent_mode`, `agent_definition`,

    `resumen_agent`) y verificación de fuente. - **Actualizar schema**: sustituye la configuración completa de un schema

    existente (`schema_id` en la URL; mismo body que crear). - **Borrar schema**: elimina un schema de la cuenta por `schema_id`. **Ventana de Contexto** — Tras una extracción con `window_context` activo, el `document_id` devuelto permite consultar el contenido bruto, preguntar al markdown persistido o eliminar el documento:

    - **GET https://claix.dev/get-document/{document_id}**: devuelve el

    contenido bruto y metadatos del documento (`content`, `file_name`,

    `schema_id`, `processed_at`). Llamada gratuita. - **POST https://claix.dev/document-context/{document_id}**: body

    `{ "questions": [{ "question": "...", "format": "string"|"int"|"boolean"|"timestamp"|"array" }] }`

    (máximo 5 preguntas, 400 caracteres cada una). Respuesta

    `{ user_ask, ia_response, log_id }`. Cada respuesta respeta el `format`

    pedido (o `null`). Si la verificación de fuente está activada en consulta

    a documentos, cada ítem de `ia_response` es `{ value, source }`. - **DELETE https://claix.dev/delete-document/{document_id}**: elimina el

    documento persistido por `document_id`. Sin body ni query params. Respuesta `{ document_id }`.'
  version: 1.12.0
servers:
- url: https://claix.dev/api
  description: Producción (dominio público Claix)
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: JSON a Excel
  description: Conversión de datos JSON a archivos Excel binarios
paths:
  /json-excel:
    post:
      operationId: jsonToExcel
      tags:
      - JSON a Excel
      summary: Convierte uno o varios documentos JSON a un archivo Excel
      description: Recibe datos JSON (como archivo, texto plano o cuerpo JSON puro) y un schema_id, y devuelve un archivo .xlsx binario con las columnas en el orden y nombres definidos por el schema. Admite multipart/form-data (uno o varios campos con JSON) o application/json puro (array, objeto único, o sobre con schema_id + data/records).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/JsonExcelMultipartRequest'
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/JsonExcelArrayRequest'
              - $ref: '#/components/schemas/JsonExcelSingleObjectRequest'
              - $ref: '#/components/schemas/JsonExcelEnvelopeRequest'
      parameters:
      - name: schema_id
        in: query
        required: false
        description: 'UUID del schema a utilizar. Alternativa a incluirlo en el cuerpo JSON (solo aplica cuando se usa application/json puro sin sobre).

          '
        schema:
          type: string
          format: uuid
          example: 1f9e6103-9221-4c22-8a3a-8592d8b0eb38
      responses:
        '200':
          description: Archivo Excel generado correctamente (respuesta binaria)
          headers:
            Content-Disposition:
              description: Nombre de archivo sugerido basado en el nombre del schema
              schema:
                type: string
                example: attachment; filename="Leads de Ventas.xlsx"
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: Petición inválida (datos JSON o schema_id incorrectos/faltantes)
          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'
        '422':
          description: No se encontró correspondencia entre claves y schema
          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 interpretar los datos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    JsonExcelArrayRequest:
      type: array
      description: Forma B.1 -- array directo de registros.
      items:
        type: object
        additionalProperties: true
      example:
      - nombre: Laura Fernández
        email: laura@nebulatech.com
      - nombre: Miguel Gómez
        email: m.gomez@construred.es
    LogId:
      type:
      - string
      - 'null'
      format: uuid
      description: 'Identificador del registro en usage_logs de esta llamada. Presente en respuestas de éxito de extracción, modo agente, document-context y space-context, y en la mayoría de errores una vez autenticada la petición. Puede omitirse si el insert del log falla.

        '
      example: 7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34
    JsonExcelMultipartRequest:
      type: object
      required:
      - schema_id
      properties:
        schema_id:
          type: string
          format: uuid
          description: 'Identificador del schema (previamente creado) de tipo "JSON a Excel".

            '
          example: 1f9e6103-9221-4c22-8a3a-8592d8b0eb38
        files:
          type: array
          description: 'Uno o varios archivos o campos de texto con contenido JSON (objeto único o array de objetos). Se puede repetir este campo o usar nombres de campo distintos; todos los que contengan JSON válido son tenidos en cuenta.

            '
          items:
            type: string
            format: binary
    JsonExcelSingleObjectRequest:
      type: object
      description: Forma B.2 -- un único objeto de registro.
      additionalProperties: true
      example:
        nombre: Laura Fernández
        email: laura@nebulatech.com
    JsonExcelEnvelopeRequest:
      type: object
      description: 'Forma B.3 -- "sobre" con el schema_id incluido y los datos dentro de "data" (o, de forma equivalente, "records").

        '
      required:
      - schema_id
      - data
      properties:
        schema_id:
          type: string
          format: uuid
          example: 1f9e6103-9221-4c22-8a3a-8592d8b0eb38
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          example:
          - nombre: Laura Fernández
            email: laura@nebulatech.com
          - nombre: Miguel Gómez
            email: m.gomez@construred.es
        records:
          type: array
          description: Alternativa equivalente a "data".
          items:
            type: object
            additionalProperties: true
    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.
        log_id:
          $ref: '#/components/schemas/LogId'
  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.
x-provenance:
  method: harvested
  publisher: Claix
  source: https://www.claix.dev/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)