openapi: 3.0.3
info:
  title: 'ServicesHub.dev API Reference'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'http://localhost'
tags:
  -
    name: Endpoints
    description: ''
components:
  securitySchemes:
    default:
      type: apiKey
      name: X-Api-Key
      in: header
      description: 'Retrieve your API key from the **SaaS Management > Applications** section in the Admin Dashboard.'
security:
  -
    default: []
paths:
  /api/user:
    get:
      summary: ''
      operationId: getApiUser
      description: ''
      parameters:
        -
          in: header
          name: X-Api-Key
          description: ''
          example: shub_...
          schema:
            type: string
      responses:
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Endpoints
  /api/v1/vision/extract:
    post:
      summary: 'Extract data from a document (OCR)'
      operationId: extractDataFromADocumentOCR
      description: 'Process an image or PDF to extract structured information using AI providers.'
      parameters:
        -
          in: header
          name: X-Api-Key
          description: ''
          example: 'Tu llave API (shub_...)'
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  ok: true
                  data:
                    amount: '1,500.00'
                    currency: MXN
                    date: '2026-03-26'
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      amount:
                        type: string
                        example: '1,500.00'
                      currency:
                        type: string
                        example: MXN
                      date:
                        type: string
                        example: '2026-03-26'
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  ok: false
                  error: 'Missing X-Api-Key header'
                properties:
                  ok:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Missing X-Api-Key header'
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  ok: false
                  error: 'Schema not found or unauthorized'
                properties:
                  ok:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Schema not found or unauthorized'
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 'El archivo a procesar (PDF, JPEG, PNG). Max 15MB.'
                dpi:
                  type: integer
                  description: 'La resolución para el procesamiento inicial. Min 72, Max 600. Default: 300.'
                  example: 300
                  nullable: true
                schema:
                  type: object
                  description: 'Un esquema JSON ad-hoc para la extracción (campo -> descripción).'
                  example:
                    amount: 'Total amount paid'
                  properties: {  }
                  nullable: true
                schema_id:
                  type: integer
                  description: 'El ID de un esquema guardado en el sistema Vision.'
                  example: 1
                  nullable: true
                return_raw:
                  type: boolean
                  description: 'Si es verdadero, devuelve todo el texto encontrado en el documento sin procesar.'
                  example: false
                  nullable: true
              required:
                - file