openapi: 3.0.3
info:
  title: MICROWARE Pohoda REST API
  version: 1.0.0
  description: |
    Moderní, bezpečné a rychlé REST API rozhraní pro účetní systém Stormware POHODA.
    Zajišťuje obousměrnou synchronizaci faktur, skladových karet, příjemek, výdejek a adresáře partnerů.
    Plná podpora idempotence (prevence duplicitních dokladů) a asynchronního zpracování při údržbě účetnictví.
servers:
  - url: https://api.vasadomena.cz/v1
    description: Produkční nebo lokální instance na serveru klienta

paths:
  /invoices:
    get:
      summary: Seznam vydaných faktur
      description: Vrátí stránkovaný seznam vydaných faktur s možností filtrace podle data vystavení a partnera.
      parameters:
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date
          example: '2026-10-01'
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
          example: '2026-10-31'
        - name: partnerIco
          in: query
          schema:
            type: string
          example: '25971468'
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Úspěšně načtený seznam faktur
    post:
      summary: Vytvoření vydané faktury
      description: Vytvoří novou vydanou fakturu v Pohodě. Vyžaduje hlavičku Idempotency-Key proti duplicitám.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
          example: '8f3a91bc-23d4-4e11-9a72-4d518e9fbcde'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - numberSeriesId
                - date
                - partner
                - items
              properties:
                numberSeriesId:
                  type: integer
                  example: 2601
                date:
                  type: string
                  format: date
                  example: '2026-10-28'
                partner:
                  type: object
                  properties:
                    ico:
                      type: string
                      example: '25971468'
                    company:
                      type: string
                      example: 'Ukázkový Klient s.r.o.'
                text:
                  type: string
                  example: 'Objednávka z e-shopu č. 2026102801'
                items:
                  type: array
                  items:
                    type: object
                    required:
                      - text
                      - quantity
                      - unitPrice
                    properties:
                      text:
                        type: string
                        example: 'Průmyslový senzor AX-100'
                      quantity:
                        type: number
                        example: 2
                      unitPrice:
                        type: number
                        example: 1500.0
                      rateVAT:
                        type: string
                        enum: [none, low, high]
                        example: 'high'
      responses:
        '201':
          description: Faktura byla úspěšně vystavena v Pohodě
        '202':
          description: Pohoda provádí údržbu – požadavek zařazen do outbox fronty a bude zapsán automaticky
        '409':
          description: Duplicitní Idempotency-Key (faktura již byla vystavena dříve)

  /stock/items:
    get:
      summary: Skladové karty a stavy zásob
      description: Rychlé čtení skladových karet, aktuálních stavů zásob, rezervací a ceníků.
      parameters:
        - name: query
          in: query
          description: Vyhledávání dle kódu nebo názvu zboží
          schema:
            type: string
        - name: store
          in: query
          description: Kód skladu
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Seznam skladových karet se stavy zásob

  /partners:
    get:
      summary: Adresář partnerů
      description: Vyhledání zákazníků a dodavatelů podle IČO, názvu nebo e-mailu.
    post:
      summary: Založení nebo aktualizace partnera
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: Partner úspěšně založen / aktualizován

  /health:
    get:
      summary: Stav služby a spojení s Pohodou
      responses:
        '200':
          description: Informace o stavu mServeru, databáze a hloubce outbox fronty