openapi: '3.1.0'
info:
  title: microservices.cz API
  version: '1.0.0'
  description: |
    API pro parsování faktur pomocí AI a export do účetních systémů.

    ## Autentizace
    Všechny requesty vyžadují Bearer token v hlavičce `Authorization`.
    API klíče spravujete v [admin panelu](https://microservices.cz/admin/account).

    ## Kreditový systém
    Každé API volání spotřebuje kredity. Aktuální stav zjistíte přes `/v1/account/balance`.
  contact:
    name: microservices.cz podpora
    url: https://microservices.cz
    email: podpora@microservices.cz

servers:
  - url: https://microservices.cz
    description: Produkce

security:
  - BearerAuth: []

paths:
  /v1/invoice/parse:
    post:
      operationId: parseInvoice
      summary: Parsování faktury
      description: |
        Extrahuje strukturovaná data z PDF, JPEG, PNG, WEBP nebo ISDOC souboru.
        Používá AI model (Haiku → Sonnet fallback, nebo Opus přes `model=full`).
      tags: [Faktury]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: Soubor faktury (PDF, JPEG, PNG, WEBP, ISDOC). Max 20 MB.
                model:
                  type: string
                  enum: [auto, full]
                  default: auto
                  description: '`auto` = Haiku + Sonnet fallback, `full` = Opus (nejlepší kvalita, +2.5 kreditů)'
                export:
                  type: string
                  enum: ['true', 'false']
                  default: 'false'
                  description: Automaticky exportovat do účetního systému (pokud je nakonfigurován)
      responses:
        '200':
          description: Faktura úspěšně parsována
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseSuccessResponse'
        '400':
          description: Chybný požadavek (chybí soubor, neplatný formát)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Parsování selhalo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/invoice/parse-batch:
    post:
      operationId: parseInvoiceBatch
      summary: Dávkové parsování faktur
      description: Parsuje více faktur najednou. Kredity se odečítají za každý soubor zvlášť.
      tags: [Faktury]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files]
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Pole souborů faktur (max 10 souborů)
      responses:
        '200':
          description: Výsledky parsování
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/invoice/export:
    post:
      operationId: exportInvoice
      summary: Export faktury do účetního systému
      description: |
        Odešle parsovaná data faktury do napojeného účetního systému (iDoklad nebo ABRA Flexi).
        Vyžaduje scope `invoice:export` a nakonfigurované přihlašovací údaje na API klíči.
      tags: [Faktury]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoice]
              properties:
                invoice:
                  type: object
                  description: Parsovaná data faktury (výstup z `/v1/invoice/parse`)
      responses:
        '200':
          description: Export úspěšný
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportSuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/invoice/parse-feedback:
    post:
      operationId: parseFeedback
      summary: Zpětná vazba na parsování
      description: Nahlásí kvalitu parsování pro zlepšení AI modelu.
      tags: [Faktury]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [request_id, rating]
              properties:
                request_id:
                  type: string
                  description: ID requestu z meta odpovědi parsování
                rating:
                  type: integer
                  minimum: 1
                  maximum: 5
                  description: Hodnocení kvality (1-5)
                comment:
                  type: string
                  description: Volitelný komentář
      responses:
        '200':
          description: Zpětná vazba přijata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/account/balance:
    get:
      operationId: getBalance
      summary: Stav kreditů
      description: Vrátí aktuální stav kreditového účtu (zůstatek, rezervováno, dostupné).
      tags: [Účet]
      responses:
        '200':
          description: Stav kreditů
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/BalanceData'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/account/usage:
    get:
      operationId: getUsage
      summary: Historie použití
      description: Vrátí historii API volání s filtry.
      tags: [Účet]
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: Datum od (YYYY-MM-DD)
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: Datum do (YYYY-MM-DD)
        - name: service
          in: query
          schema:
            type: string
          description: Filtr dle služby (např. invoice-parse)
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
          description: Počet záznamů
      responses:
        '200':
          description: Historie použití
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UsageLogEntry'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API klíč jako Bearer token

  schemas:
    Meta:
      type: object
      properties:
        request_id:
          type: string
          example: req_a1b2c3d4e5f6g7h8
        credits_used:
          type: number
          example: 2.0
        credits_remaining:
          type: number
          example: 148.0
        processing_ms:
          type: integer
          example: 1243

    BalanceData:
      type: object
      properties:
        balance:
          type: number
          description: Celkový zůstatek
          example: 150.0
        reserved:
          type: number
          description: Rezervováno (probíhající volání)
          example: 2.0
        available:
          type: number
          description: Dostupné kredity (balance - reserved)
          example: 148.0

    UsageLogEntry:
      type: object
      properties:
        request_id:
          type: string
        service:
          type: string
          example: invoice-parse
        credits_used:
          type: number
        status:
          type: string
          enum: [success, error]
        processing_ms:
          type: integer
        created_at:
          type: string
          format: date-time

    ParsedInvoice:
      type: object
      properties:
        invoice_number:
          type: string
          example: FV-2026-0042
        variable_symbol:
          type: string
        issue_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
        currency:
          type: string
          example: CZK
        total_without_vat:
          type: number
          example: 10000.00
        total_vat:
          type: number
          example: 2100.00
        total_with_vat:
          type: number
          example: 12100.00
        supplier:
          type: object
          properties:
            name:
              type: string
            ico:
              type: string
            dic:
              type: string
            address:
              type: string
        items:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              quantity:
                type: number
              unit_price:
                type: number
              vat_rate:
                type: integer
              total:
                type: number

    SuccessResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        data:
          type: object
        meta:
          $ref: '#/components/schemas/Meta'

    ParseSuccessResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/ParsedInvoice'
        meta:
          $ref: '#/components/schemas/Meta'

    BatchSuccessResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        data:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  filename:
                    type: string
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ParsedInvoice'
                  error:
                    type: string
                    nullable: true
        meta:
          $ref: '#/components/schemas/Meta'

    ExportSuccessResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        data:
          type: object
          properties:
            external_id:
              type: string
              description: ID dokladu v účetním systému
            document_number:
              type: string
              description: Číslo dokladu v účetním systému
            status:
              type: string
              enum: [success, failed]
        meta:
          $ref: '#/components/schemas/Meta'

    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: insufficient_credits
            message:
              type: string
              example: Nedostatek kreditů
            docs_url:
              type: string
              example: https://docs.microservices.cz/errors/insufficient_credits

  responses:
    Unauthorized:
      description: Neplatná nebo chybějící autentizace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            error:
              code: invalid_key
              message: Neplatný API klíč
              docs_url: https://docs.microservices.cz/errors/invalid_key

    Forbidden:
      description: Nedostatečná oprávnění
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            error:
              code: insufficient_scope
              message: API klíč nemá oprávnění pro tuto službu
              docs_url: https://docs.microservices.cz/errors/insufficient_scope

    InsufficientCredits:
      description: Nedostatek kreditů
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            error:
              code: insufficient_credits
              message: Nedostatek kreditů
              credits_required: 2.0
              credits_available: 0.5
              docs_url: https://docs.microservices.cz/errors/insufficient_credits

    RateLimited:
      description: Příliš mnoho požadavků
      headers:
        Retry-After:
          schema:
            type: integer
          description: Počet sekund do resetu
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            error:
              code: rate_limit_exceeded
              message: Příliš mnoho požadavků. Limit 10/min
              docs_url: https://docs.microservices.cz/errors/rate_limit_exceeded
