openapi: 3.1.0
info:
  title: efakt portal API
  version: 1.0.0
  summary: REST API portálu pro správu e-faktur (SK eFaktúra / Peppol).
  description: |
    Verze `/api/v1`. Zdroj pravdy kontraktu je tento soubor; zod schémata v `src/schemas` jsou s ním
    udržována v paritě testem (`test/openapi-parity.test.ts`).

    ## Autentizace
    * **Uživatelé (web UI)** – cookie session `efakt_session` (HttpOnly, Secure, SameSite=Lax) po
      `POST /auth/login` (+ `POST /auth/totp`). Změny stavu (POST/PUT/PATCH/DELETE) při cookie autentizaci
      vyžadují hlavičku `X-CSRF-Token` s hodnotou cookie `efakt_csrf` (double-submit). Viz ADR 001.
    * **Účetní software** – API klíč tenanta: `Authorization: Bearer efk_<...>` **nebo** `X-API-Key: efk_<...>`.
      Klíč je vázán na jednoho tenanta a má scopes. CSRF se u API klíčů nevyžaduje.

    ## Obecné konvence
    * Chyby: `application/problem+json` (RFC 9457) s vlastním polem `code` (katalog `ErrorCode`).
    * Čas: ISO 8601 UTC (`2026-10-04T12:00:00Z`). Datum faktury: `YYYY-MM-DD` (den v Europe/Bratislava).
    * Částky: **desetinný řetězec** (`"1234.50"`), nikdy JSON number.
    * Stránkování: cursor. Dotaz `?limit=&cursor=`, odpověď `{ "items": [...], "next_cursor": "..." | null }`.
      Cursor je neprůhledný, platný pro stejné filtry a řazení.
    * Rate limit: hlavičky `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (sekundy do resetu),
      při překročení `429` + `Retry-After` (sekundy).
    * Každá odpověď nese `X-Request-Id` (korelační ID, vrací se i v poli `request_id` chyby).
    * Data se nikdy nemažou. Endpointy `DELETE` na konfiguraci (webhook, spojení, členství) provádějí
      **deaktivaci** (soft), záznam zůstává a je auditován.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: http://localhost:18080/api/v1
    description: Lokální backend (Podman)
  - url: http://localhost:18082
    description: Prism mock server (`npm run mock` v packages/contracts)
tags:
  - name: Auth
    description: Přihlášení, TOTP, session
  - name: Tenants
    description: Tenanti uživatele a aktivní tenant
  - name: Invoices
    description: Faktury - seznam, detail, XML, odesílání, import
  - name: Exports
    description: Hromadné exporty (ZIP/CSV)
  - name: Participants
    description: Dotaz na účastníka Peppolu
  - name: Connections
    description: Spojení s poštářem (zákaznický pohled) a příjem webhooků poštáře
  - name: ApiKeys
    description: API klíče tenanta
  - name: Webhooks
    description: Webhooky portálu směrem k účetnímu SW
  - name: Admin
    description: Administrace (role admin)
  - name: ERP
    description: ERP API (Caris a kompatibilní účetní programy) a správa ERP integrací
  - name: Verteco
    description: Verteco – partnerský (reseller / sprostredkovateľ) režim, FS verifikační a partnerské webhooky
  - name: Backups
    description: Zálohy na externí úložiště – proxy k enginu efakt-backup (jen role admin) a notifikační webhook enginu
  - name: Validation
    description: Předodesílací validace e-faktury (dry-run, stav vrstev, nastavení, vyloučení příjemci)
  - name: Forwarding
    description: Přeposílání faktur e-mailem (pravidla, příjemci s double opt-in, doručení, sdílené odkazy s heslem, oprávnění) a veřejné stránky sdílené kopie
  - name: Sandbox
    description: Veřejný vývojářský sandbox - samoobslužná registrace (double opt-in), kvóty, správa
  - name: System
    description: Provozní endpointy

security:
  - cookieAuth: []
  - bearerApiKey: []
  - apiKeyHeader: []

paths:
  /health:
    get:
      tags: [System]
      operationId: getHealth
      summary: Liveness API (bez autentizace)
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [status, version]
                properties:
                  status: { type: string, enum: [ok] }
                  version: { type: string }

  # ------------------------------------------------------------------ AUTH
  /auth/login:
    post:
      tags: [Auth]
      operationId: login
      summary: Přihlášení e-mailem a heslem (1. krok)
      description: |
        Při úspěchu a vypnutém TOTP vrátí `authenticated` a nastaví cookie. Má-li uživatel TOTP, vrátí
        `totp_required` + krátkodobý `challenge_token` (5 min) a cookie **nenastaví**. Pokud role vyžaduje TOTP a
        uživatel ho nemá aktivní, vrátí `totp_enrollment_required` (a omezenou session jen pro `/auth/totp/*`).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginRequest' }
      responses:
        '200':
          description: Výsledek prvního kroku
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LoginResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/totp:
    post:
      tags: [Auth]
      operationId: loginTotp
      summary: Přihlášení – 2. krok (kód TOTP nebo záložní kód)
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TotpRequest' }
      responses:
        '200':
          description: Přihlášen, nastavena cookie `efakt_session` a `efakt_csrf`.
          headers:
            Set-Cookie: { $ref: '#/components/headers/SetCookie' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LoginResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/totp/enroll:
    post:
      tags: [Auth]
      operationId: totpEnroll
      summary: Zahájení zápisu TOTP (vrátí otpauth URI a tajemství)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: Tajemství se zobrazuje jen jednou. Aktivace až po `/auth/totp/confirm`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TotpEnrollment' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/totp/confirm:
    post:
      tags: [Auth]
      operationId: totpConfirm
      summary: Potvrzení zápisu TOTP prvním kódem; vrátí záložní kódy (jednou)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: { type: string, pattern: '^[0-9]{6}$' }
      responses:
        '200':
          description: TOTP aktivní
          content:
            application/json:
              schema:
                type: object
                required: [backup_codes]
                properties:
                  backup_codes:
                    type: array
                    items: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/password-reset/request:
    post:
      tags: [Auth]
      operationId: requestPasswordReset
      summary: Žádost o reset hesla e-mailem (veřejné)
      description: |
        Vždy `202` (neprozrazuje, zda účet existuje ani zda je SMTP nastaveno). Pokud účet existuje, není zablokovaný a SMTP je nastaveno,
        odešle se e-mail s jednorázovým odkazem (platnost 1 hodina). Bez SMTP se nic neodešle (správce může heslo nastavit v administraci).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PasswordResetRequest' }
      responses:
        '202': { description: 'Přijato (vždy)' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/password-reset/confirm:
    post:
      tags: [Auth]
      operationId: confirmPasswordReset
      summary: Nastavení hesla jednorázovým odkazem (pozvánka i reset; veřejné)
      description: |
        Token je jednorázový a časově omezený (pozvánka 72 h, reset 1 h). Po úspěchu se zruší všechny session uživatele a ostatní odkazy; TOTP zůstává beze změny.
        Neplatný/prošlý/použitý token: `400 INVALID_TOKEN`; slabé heslo `422 WEAK_PASSWORD`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PasswordResetConfirm' }
      responses:
        '204': { description: Heslo nastaveno }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/logout:
    post:
      tags: [Auth]
      operationId: logout
      summary: Odhlášení (zneplatní session)
      security: [{ cookieAuth: [] }]
      responses:
        '204': { description: Odhlášen }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /auth/me:
    get:
      tags: [Auth]
      operationId: getMe
      summary: Přihlášený uživatel, aktivní tenant a členství
      description: |
        Funguje i v omezené session po `totp_enrollment_required` (`session_kind: enrollment`): vrací identitu a `csrf_token`,
        `permissions` i `tenants` jsou pak prázdná pole (aplikační endpointy vrací 403 do dokončení zápisu TOTP).
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Me' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /me/tenants:
    get:
      tags: [Tenants]
      operationId: listMyTenants
      summary: Tenanti, které uživatel smí spravovat (admin vidí všechny aktivní)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/TenantSummary' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /me/active-tenant:
    put:
      tags: [Tenants]
      operationId: switchActiveTenant
      summary: Přepnutí aktivního tenanta v session
      description: Všechny tenant-scoped endpointy (`/invoices`, `/connections`, `/api-keys`, `/webhooks`, ...) pracují s aktivním tenantem session. Pro API klíč je tenant dán klíčem a tento endpoint není dostupný.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SwitchTenantRequest' }
      responses:
        '200':
          description: Přepnuto
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Me' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /tenant:
    get:
      tags: [Tenants]
      operationId: getCurrentTenant
      summary: Aktivní tenant (včetně nastavení; funguje i s API klíčem)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tenant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ INVOICES
  /invoices:
    get:
      tags: [Invoices]
      operationId: listInvoices
      summary: Seznam faktur aktivního tenanta
      description: Výchozí řazení `-issue_date` (sestupně), tie-break `id`. Scope API klíče `invoices:read`.
      parameters:
        - { name: direction, in: query, schema: { $ref: '#/components/schemas/Direction' } }
        - name: status
          in: query
          description: Jeden nebo více stavů (čárkou oddělené nebo opakovaný parametr).
          style: form
          explode: false
          schema:
            type: array
            items: { $ref: '#/components/schemas/InvoiceStatus' }
        - { name: validation_status, in: query, schema: { $ref: '#/components/schemas/ValidationStatus' } }
        - { name: erp_delivered, in: query, description: 'Převzato do ERP (ACK aspoň jednou integrací): `true` = převzato, `false` = nepřevzato (jen příchozí faktury mají smysl).', schema: { type: boolean } }
        - { name: doc_type, in: query, description: "Kód typu dokladu (380, 381, ...)", schema: { $ref: '#/components/schemas/DocumentTypeCode' } }
        - { name: source, in: query, schema: { $ref: '#/components/schemas/InvoiceSource' } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
        - { name: partner, in: query, description: 'Protistrana: DIČ, IČO, Peppol ID nebo část názvu (podřetězec, case-insensitive). U inbound hledá v dodavateli, u outbound v odběrateli, bez `direction` v obou.', schema: { type: string, maxLength: 200 } }
        - { name: number, in: query, description: "Číslo faktury (přesná shoda; pro částečnou použij `search`)", schema: { type: string, maxLength: 200 } }
        - { name: issue_date_from, in: query, schema: { type: string, format: date } }
        - { name: issue_date_to, in: query, schema: { type: string, format: date } }
        - { name: currency, in: query, schema: { type: string, pattern: '^[A-Z]{3}$' } }
        - { name: amount_min, in: query, description: Minimum `total_gross`, schema: { $ref: '#/components/schemas/Money' } }
        - { name: amount_max, in: query, description: Maximum `total_gross`, schema: { $ref: '#/components/schemas/Money' } }
        - { name: search, in: query, description: "Fulltext/trigram nad číslem faktury a názvy stran", schema: { type: string, maxLength: 200 } }
        - name: sort
          in: query
          schema:
            type: string
            enum: [-issue_date, issue_date, -received_at, received_at, -total_gross, total_gross]
            default: -issue_date
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: Stránka faktur
          headers:
            RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
            RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
            RateLimit-Reset: { $ref: '#/components/headers/RateLimitReset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoicePage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Invoices]
      operationId: submitInvoice
      summary: Odeslání faktury přes poštáře tenanta (vždy asynchronní)
      description: |
        Scope `invoices:send`, role (cookie) `tenant_user`/`admin`.

        Postup (viz docs/CONTRACTS.md): autentizace -> `Idempotency-Key` -> rychlé kontroly (well-formed XML,
        Invoice/CreditNote, typ dokladu, **dodavatel = tenant**) -> validace XSD+Schematron -> kontrola
        `IssueDate` (= dnešní den v Europe/Bratislava; dle `TenantSettings.issue_date_policy` chyba nebo varování)
        -> uložení se stavem `queued` -> `202 Accepted` + `Location`.

        Těla: `application/xml` (UBL 2.1, bajty se ukládají beze změny) nebo `application/json` (obálka
        `InvoiceSubmitEnvelope` s base64 XML). Pro `application/xml` se volby předávají query parametrem
        `connection_id` a hlavičkou `X-External-Reference`.

        **Idempotence:** stejný `Idempotency-Key` + stejné tělo (SHA-256 těla) => vrátí se původní odpověď
        (`202` se stejným `id`, hlavička `Idempotent-Replayed: true`), žádné druhé odeslání. Stejný klíč a jiné tělo =>
        `409 IDEMPOTENCY_CONFLICT`. Souběžné zpracování téhož klíče => `409 IDEMPOTENCY_IN_PROGRESS` (+ `Retry-After`).
        Klíče se drží min. 7 dní. Nezávisle na klíči brání duplicitě přirozený klíč
        (tenant, direction, seller, doc_type, number, issue_date) => `409 DUPLICATE_INVOICE` s `existing_invoice_id`.

        Příjemce neregistrovaný v Peppolu **neblokuje** odeslání; do `warnings` přibude `RECIPIENT_NOT_REGISTERED`
        (u poštářů s dry-runem `receiverReachable`). Pokud dojde k nedoručení, výsledný stav je `delivery_failed` s důvodem
        `RECIPIENT_NOT_REGISTERED` (povinnost odeslat je splněna odesláním; fakturu NEvystavujte znovu).

        **Opětovné odeslání (M-01):** existuje-li faktura se stejným klíčem (číslo, datum, typ, prodavatel) ve stavu `failed_permanent`
        (kromě důvodu `OUTCOME_UNKNOWN`) nebo `rejected_by_provider`, další `POST` s NOVÝM `Idempotency-Key` ji nahradí novým pokusem
        (`202`, nová faktura; stará se označí `superseded` a nese `superseded_by_invoice_id`). Jinak `409 DUPLICATE_INVOICE`.
        Po `failed_permanent/rejected_by_provider` může poštář po pozdním webhooku stav opravit na `delivered`/`delivery_failed`.

        **Dodavatel = tenant:** shoduje se `EndpointID` (0245:DIČ), DIČ i první `cbc:CompanyID` v `AccountingSupplierParty`
        (podle něj určuje odesílatele ePodatelna24), jinak `422 SELLER_MISMATCH`. Samofakturace 389/261: odesílatelem je odběratel
        (`AccountingCustomerParty` = tenant) a tenant musí mít `allow_self_billing` (jinak `422 SELF_BILLING_NOT_ENABLED`).
        Typ 384 se nepřijímá (`422 UNSUPPORTED_DOCUMENT_TYPE`, použijte 381 + 380). XML > 4 000 000 B => `413 PAYLOAD_TOO_LARGE`
        u poštáře s tímto limitem (ePodatelna24).
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKey' }
        - name: connection_id
          in: query
          description: Odeslat přes konkrétní odchozí spojení (jinak výchozí odchozí poštář tenanta).
          schema: { type: string, format: uuid }
        - name: X-External-Reference
          in: header
          description: Libovolný odkaz účetního SW (max 200 znaků), vrací se v `external_reference`.
          schema: { type: string, maxLength: 200 }
        - { $ref: '#/components/parameters/TestQuery' }
        - { $ref: '#/components/parameters/TestModeHeader' }
        - { $ref: '#/components/parameters/SimulateQuery' }
        - { $ref: '#/components/parameters/SimulateWebhooksQuery' }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string, description: "UBL 2.1 Invoice nebo CreditNote (Peppol BIS Billing 3.0)" }
          application/json:
            schema: { $ref: '#/components/schemas/InvoiceSubmitEnvelope' }
      responses:
        '200':
          description: |
            Jen v testovacím režimu (`test=true`): provedlo se vše kromě odeslání, nic se neuložilo do `invoices` ani do fronty. Viz `TestSubmitResponse`.
            Pověření `test_only` a tenant `sandbox`: viz `GET /erp/me`. `403 TEST_ONLY_CREDENTIAL` při ostrém pokusu s pověřením `test_only`; `400 INVALID_TEST_FLAG` při neplatné hodnotě.
          headers:
            X-Test-Mode: { $ref: '#/components/headers/XTestMode' }
            X-Would-Have-Sent: { $ref: '#/components/headers/XWouldHaveSent' }
            Idempotent-Replayed: { description: '`true` při přehrání původní testovací odpovědi', schema: { type: string, enum: ['true'] } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TestSubmitResponse' }
        '202':
          description: Přijato do fronty
          headers:
            Location: { description: 'URL stavu `/api/v1/invoices/{id}`', schema: { type: string } }
            Idempotent-Replayed: { description: '`true` při přehrání původní odpovědi', schema: { type: string, enum: ['true'] } }
            RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
            RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
            RateLimit-Reset: { $ref: '#/components/headers/RateLimitReset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /test-runs/{testRunId}:
    get:
      tags: [Invoices]
      operationId: getTestRun
      summary: Výsledek testovacího odeslání (platí 24 hodin)
      description: |
        Vrací výsledek testu (`test_<uuid>`) vytvořený `POST /invoices` / `POST /erp/invoices` s `test=true`, včetně deterministických `simulated_events[]`.
        Výsledek se NIKDY nepočítá za doklad ani do statistik. Po 24 hodinách je nedostupný: `410 TEST_RUN_EXPIRED` (řádek se fyzicky nemaže, jen se nezobrazuje).
        Dostupné cookie session, API klíčem (scope `invoices:read`) i ERP údaji; cizí tenant = `404`.
      security: [{ cookieAuth: [] }, { bearerApiKey: [] }, { erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: testRunId, in: path, required: true, schema: { type: string, pattern: '^test_[0-9a-f-]{36}$' } }
      responses:
        '200':
          description: Testovací běh
          headers:
            X-Test-Mode: { $ref: '#/components/headers/XTestMode' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TestRun' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '410':
          description: 'Test je starší než 24 hodin (TEST_RUN_EXPIRED)'
          content:
            application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/test-runs/{testRunId}:
    get:
      tags: [ERP]
      operationId: erpGetTestRun
      summary: Výsledek testovacího odeslání pro ERP (platí 24 hodin; scope `send` nebo `status`)
      description: Totéž co `GET /test-runs/{id}`, ale s ERP údaji (ty se přijímají jen na `/erp/*`).
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: testRunId, in: path, required: true, schema: { type: string, pattern: '^test_[0-9a-f-]{36}$' } }
      responses:
        '200':
          description: Testovací běh
          headers:
            X-Test-Mode: { $ref: '#/components/headers/XTestMode' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TestRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '410':
          description: 'Test je starší než 24 hodin (TEST_RUN_EXPIRED)'
          content:
            application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/summary:
    get:
      tags: [Invoices]
      operationId: getInvoiceSummary
      summary: Souhrn počtů faktur (pro přehled)
      description: |
        Počty faktur aktivního tenanta podle směru a stavu, nad stejnými filtry jako `GET /invoices` (bez `sort`/`limit`/`cursor`).
        Stavy bez faktur jsou v `by_status` uvedeny s nulou. Scope API klíče `invoices:read`.
      parameters:
        - { name: direction, in: query, schema: { $ref: '#/components/schemas/Direction' } }
        - name: status
          in: query
          style: form
          explode: false
          schema:
            type: array
            items: { $ref: '#/components/schemas/InvoiceStatus' }
        - { name: validation_status, in: query, schema: { $ref: '#/components/schemas/ValidationStatus' } }
        - { name: erp_delivered, in: query, description: 'Převzato do ERP (ACK aspoň jednou integrací): `true` = převzato, `false` = nepřevzato (jen příchozí faktury mají smysl).', schema: { type: boolean } }
        - { name: source, in: query, schema: { $ref: '#/components/schemas/InvoiceSource' } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
        - { name: issue_date_from, in: query, schema: { type: string, format: date } }
        - { name: issue_date_to, in: query, schema: { type: string, format: date } }
        - { name: currency, in: query, schema: { type: string, pattern: '^[A-Z]{3}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceSummary' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/import:
    post:
      tags: [Invoices]
      operationId: importInvoice
      summary: Ruční import XML (zdroj `manual_import`)
      description: |
        Uloží UBL XML bez odeslání. `direction=inbound` (výchozí): buyer musí odpovídat tenantovi, nevalidní doklad se
        přesto uloží (`received_invalid`). `direction=outbound` (historie): seller musí odpovídat tenantovi, nic se neodesílá.
        Duplicita (přirozený klíč) => `409 DUPLICATE_INVOICE`. Role `tenant_user`/`admin`.
      parameters:
        - { name: direction, in: query, schema: { $ref: '#/components/schemas/Direction' } }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string }
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, contentEncoding: base64, contentMediaType: application/xml }
      responses:
        '201':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceDetail' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/validate:
    post:
      tags: [Validation]
      operationId: validateInvoice
      summary: Dry-run předodesílací validace (NIC se neukládá ani neodesílá)
      description: |
        Projde stejný engine jako `POST /invoices` (formát XSD+Schematron, SK národní pravidla, IČO/DIČ/IČ DPH, registry, příjemce v Peppolu,
        povinnost/zákaz e-faktury, časová pravidla, SK TDD dry-run a dry-run poštáře) a vrátí `ValidationReport`. `Idempotency-Key` se nepoužívá.
        Zablokovaná faktura (`verdict=blocked`) se vrací jako **200** (dotaz proběhl); `POST /invoices` ve stejné situaci vrací `422 VALIDATION_FAILED`
        (nebo `OBLIGATION_FORBIDDEN`). Tělo: `application/xml` nebo JSON `{ xml_base64, connection_id?, options? }`. Role `tenant_user`/`admin`, scope `invoices:send`.
        Výpadek validátoru formátu = `503 VALIDATOR_UNAVAILABLE` (fail-closed); výpadek ostatních vrstev jen nález a stav vrstvy (fail-open).
      parameters:
        - name: connection_id
          in: query
          description: Odchozí spojení, jehož poštář se použije pro lookup příjemce a dry-run (jinak výchozí odchozí poštář tenanta).
          schema: { type: string, format: uuid }
        - name: Accept-Language
          in: header
          description: 'Jazyk `message` v nálezech (`sk`, `cs`, `en`); výchozí `en`. Všechny jazyky jsou i v `messages`.'
          schema: { type: string }
        - name: X-Check-Routing
          in: header
          description: '`1`/`true` = výslovně ověřit příjemce v Peppolu (vrstva `routing`); jinak se spouští jen při `routing_default=always`. Lze i query `check_routing=true` nebo `options.check_routing`.'
          schema: { type: string, enum: ['1', 'true'] }
        - name: check_routing
          in: query
          description: 'Totéž co hlavička `X-Check-Routing`.'
          schema: { type: boolean }
        - name: X-Confidential-Supply
          in: header
          description: '`true` = plnění je utajované (e-fakturu nelze vystavit); `false` = uživatel potvrdil, že není. U JSON těla viz `options.confidential_supply`.'
          schema: { type: string, enum: ['true', 'false'] }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string }
          application/json:
            schema: { $ref: '#/components/schemas/ValidateInvoiceRequest' }
      responses:
        '200':
          description: 'Report validace. `verdict=blocked` (i doklad, kterému chybí povinná pole, např. `REQUIRED_FIELD_MISSING`) se vrací jako 200 s nálezy; 422 zůstává pro nevalidní XML/kódování, cizího odesílatele aj. (stejné kódy jako odeslání).'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationReport' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/invoices/validate:
    post:
      tags: [ERP, Validation]
      operationId: erpValidateInvoice
      summary: Dry-run předodesílací validace pro ERP (scope `send`; NIC se neukládá ani neodesílá)
      description: |
        Totéž co `POST /invoices/validate` pro integraci ERP. `Idempotency-Key` se nevyžaduje. Rate limit 20 dry-runů/min na integraci (dry-run poštáře
        sdílí limit adaptéru). Tělo `application/xml` (spojení z `?connection_id`, příznaky z hlaviček `X-Confidential-Supply`) nebo JSON.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
        - { name: Accept-Language, in: header, schema: { type: string } }
        - { name: X-Confidential-Supply, in: header, schema: { type: string, enum: ['true', 'false'] } }
        - { name: X-Check-Routing, in: header, schema: { type: string, enum: ['1', 'true'] } }
        - { name: check_routing, in: query, schema: { type: boolean } }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string }
          application/json:
            schema: { $ref: '#/components/schemas/ValidateInvoiceRequest' }
      responses:
        '200':
          description: 'Report validace. `verdict=blocked` (i doklad, kterému chybí povinná pole, např. `REQUIRED_FIELD_MISSING`) se vrací jako 200 s nálezy; 422 zůstává pro nevalidní XML/kódování, cizího odesílatele aj. (stejné kódy jako odeslání).'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationReport' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /validation/routing:
    get:
      tags: [Validation]
      operationId: getValidationRouting
      summary: Ověření příjemce v Peppolu (tlačítko „Ověřit příjemce v Peppol“)
      description: |
        Výslovná žádost: zjistí, zda je DIČ příjemce (`0245:<DIČ>`) registrováno v Peppolu – přímo v SMP (je-li v nastavení `registries` zapnuto `routing_smp`),
        jinak přes `lookupParticipant` výchozího odchozího poštáře tenanta. Výpadek nebo vypnutý zdroj = `registered=null` + `reason` (fail-open, vždy 200).
        Neexistence v Peppolu je jen informace – odeslání platí za splněnou povinnost. Scope `participants:read`.
      parameters:
        - { name: dic, in: query, required: true, schema: { type: string, pattern: '^[0-9]{10}$' } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationRouting' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/validation/routing:
    get:
      tags: [ERP, Validation]
      operationId: erpValidationRouting
      summary: Ověření příjemce v Peppolu pro ERP integraci (stejný výsledek jako `GET /validation/routing`)
      description: |
        Výslovná žádost (SMP / poštář výchozího odchozího spojení). Výpadek nebo vypnutý zdroj = `registered=null` + `reason` (fail-open, vždy 200).
        Autentizace ERP (Bearer `erp_…` / Basic), scope `send`. Limit 60 dotazů/min na integraci.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: dic, in: query, required: true, schema: { type: string, pattern: '^[0-9]{10}$' } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationRouting' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/validation-runs:
    get:
      tags: [Invoices, Validation]
      operationId: listInvoiceValidationRuns
      summary: Uložené běhy předodesílací validace faktury (nejnovější první)
      description: |
        Záznamy `validation_runs` (append-only) k faktuře: verdikt, vrstvy, verze artefaktů a nálezy každého běhu. Vznikají při přijetí/odeslání faktury;
        dry-run se neukládá. XML se neukládá, jen jeho `xml_sha256`. Scope `invoices:read`; cizí tenant = `404`.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationRunList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/revalidate:
    post:
      tags: [Invoices, Validation]
      operationId: revalidateInvoice
      summary: Opakovaná kontrola PŘÍCHOZÍ faktury (nový běh `inbound_recheck`)
      description: |
        Nad uloženým XML (beze změny, nikdy se nepřepisuje) znovu spustí vrstvy vhodné pro PŘÍCHOZÍ doklad: formát (XSD + Schematron), slovenská národní pravidla,
        kontrolu IČO/DIČ/IČ DPH a registry dodavatele, shodu odběratele s tenantem, typ dokladu, časová pravidla a duplicitu/rozpor. Vrstvy jen pro odesílání
        (příjemce v Peppolu, povinnost/zákaz vystavit, TDD dry-run, dry-run poštáře) se přeskočí. Zapíše nový append-only záznam `validation_runs` (`mode=inbound_recheck`);
        `validation_status` faktury se změní jen když se změní verdikt (a zapíše se událost). Příchozí doklad se nikdy nezahazuje: jen formát může být chybou, ostatní nálezy jsou
        nejvýše varování. Výpadek validátoru formátu = `503 VALIDATOR_UNAVAILABLE` (fail-closed), výpadek ostatních vrstev jen nález a stav vrstvy (fail-open).
        Odchozí faktura = `409 CONFLICT`, faktura bez XML = `409 XML_NOT_AVAILABLE`, cizí tenant = `404`. Rate limit 30/min na tenanta. Scope `invoices:read`, role `tenant_user`/`admin`.
        Testovací režim (`?test=true` / hlavička `X-Test-Mode`, jinak jako u odeslání): kontrola proběhne a vrátí výsledek, ale NIC se neuloží (žádný běh, změna stavu, událost ani idempotentní záznam; `run.id` je nulové UUID) a odpověď nese `X-Test-Mode: true`.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - name: Idempotency-Key
          in: header
          required: false
          description: Volitelný. Stejný klíč + stejná faktura vrátí původní výsledek (`Idempotent-Replayed - true`) bez nového běhu; 1-200 znaků `[A-Za-z0-9._:-]`.
          schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[A-Za-z0-9._:-]+$' }
        - name: Accept-Language
          in: header
          description: 'Jazyk `message` v nálezech (`sk`, `cs`, `en`); všechny jazyky jsou i v `messages`.'
          schema: { type: string }
      responses:
        '200':
          description: Nový běh uložen
          headers:
            Idempotent-Replayed: { description: 'true = výsledek z dřívějšího volání se stejným Idempotency-Key', schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceRevalidation' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/revalidate:
    post:
      tags: [Invoices, Validation]
      operationId: revalidateInvoices
      summary: Hromadná opakovaná kontrola příchozích faktur (asynchronní úloha)
      description: |
        Založí úlohu `revalidate_invoices`, která po aktualizaci validátoru nebo pravidel znovu zkontroluje příchozí faktury podle filtru (období vystavení, `validation_status`,
        `direction` = jen `inbound`, `limit` 1-5000, výchozí 1000; sandbox tenant nejvýše 100). Každá faktura dostane nový běh jako u `POST /invoices/{invoiceId}/revalidate`.
        Stav úlohy: `GET /invoices/revalidate/jobs/{jobId}`. Na tenanta běží jedna úloha najednou (`409 CONFLICT`). Výpadek validátoru úlohu pozastaví a zopakuje (průběh se zachová).
        Volitelný `Idempotency-Key`: stejný klíč + stejné tělo = stejná úloha, jiné tělo = `409 IDEMPOTENCY_CONFLICT`. Rate limit 6/min. Scope `invoices:read`, role `tenant_user`/`admin`.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: Volitelný. Stejný klíč + stejná faktura vrátí původní výsledek (`Idempotent-Replayed - true`) bez nového běhu; 1-200 znaků `[A-Za-z0-9._:-]`.
          schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[A-Za-z0-9._:-]+$' }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RevalidateInvoicesRequest' }
      responses:
        '202':
          description: Úloha založena (nebo existující při opakování se stejným Idempotency-Key)
          headers:
            Location: { schema: { type: string } }
            Idempotent-Replayed: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RevalidationJob' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/revalidate/jobs:
    get:
      tags: [Invoices, Validation]
      operationId: listRevalidationJobs
      summary: Úlohy hromadné opakované kontroly (nejnovější první)
      description: Scope `invoices:read`; jen úlohy vlastního tenanta.
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RevalidationJobPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/revalidate/jobs/{jobId}:
    get:
      tags: [Invoices, Validation]
      operationId: getRevalidationJob
      summary: Stav úlohy hromadné opakované kontroly
      description: Počty (`processed`/`changed`/`unchanged`/`failed`), seznam změn stavu a selhání (nejvýše 500). Cizí tenant = `404`.
      parameters:
        - { name: jobId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RevalidationJob' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /validation/layers:
    get:
      tags: [Validation]
      operationId: getValidationLayers
      summary: Stav vrstev předodesílací validace a jejich verzí
      description: |
        Zdraví a verze validátoru (XSD/Schematron/SK/TDD), čerstvost registrů (V-REG), podpora dry-runu u poštářů tenanta (cena, výchozí režim)
        a účinné nastavení tenanta. Čtení pro všechny role tenanta.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationLayers' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /validation/excluded-recipients:
    get:
      tags: [Validation]
      operationId: listExcludedRecipients
      summary: Vlastní seznam příjemců „nikdy e-faktura“ (SIS/VS/utajované plnění)
      description: Seznam spravuje tenant (žádný oficiální seznam neexistuje). Zásah při odeslání = blokující nález `OBL-EXCLUDED-RECIPIENT` (nelze vypnout).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ExcludedRecipientList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Validation]
      operationId: createExcludedRecipient
      summary: Přidání příjemce do seznamu „nikdy e-faktura“
      description: Aspoň jedno z `dic` / `ico`. Změna se audituje (`validation.excluded_recipient.added`). Role `tenant_user`/`admin`, cookie session.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExcludedRecipientCreate' }
      responses:
        '201':
          description: Přidáno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ExcludedRecipient' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /validation/excluded-recipients/{id}:
    delete:
      tags: [Validation]
      operationId: removeExcludedRecipient
      summary: Odebrání ze seznamu „nikdy e-faktura“ (soft; záznam zůstává v historii)
      description: Jen role `admin` (odebrání zmírňuje ochranu). Audituje se (`validation.excluded_recipient.removed`).
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '204': { description: Odebráno }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/validation/settings:
    get:
      tags: [Admin, Validation]
      operationId: adminGetValidationSettings
      summary: Nastavení předodesílací validace (systém, nebo tenant s `tenant_id`)
      description: |
        Bez `tenant_id`: systémové výchozí hodnoty (`system_settings` klíč `presend_validation`). S `tenant_id`: řídké přepsání tenanta + účinné hodnoty.
        Přísnost (`strictness`), vrstvy (`layers`), politika fail-open (`fail_open`), `require_provider_dryrun`, `provider_error_policy`, `severity`, `registry_max_age_days`.
        Zákonné bloky (`OBL-FORBIDDEN`, `OBL-EXCLUDED-RECIPIENT`) a `PTY-ENDPOINT-SCHEME` nelze vypnout ani přepsat. Jen role admin.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PresendSettingsDoc' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Admin, Validation]
      operationId: adminPutValidationSettings
      summary: Uložení nastavení předodesílací validace
      description: |
        Nahradí uložené hodnoty (systém nebo tenant). Pokus o přepsání závažnosti zákonného bloku / `PTY-ENDPOINT-SCHEME` = `422 INVALID_SETTING`.
        `expected_version` (optimistický zámek) při neshodě `409 CONFLICT`. Audit `settings.presend.updated`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PresendSettingsUpdate' }
      responses:
        '200':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PresendSettingsDoc' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/export:
    post:
      tags: [Exports]
      operationId: createInvoiceExport
      summary: Hromadný export (ZIP původních XML nebo CSV seznamu) – asynchronní job
      description: Vyber buď `invoice_ids`, nebo `filter` (stejné parametry jako `GET /invoices`). Výsledek se stahuje přes `GET /exports/{id}/download`, až je `status=ready`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExportRequest' }
      responses:
        '202':
          description: Job založen
          headers:
            Location: { description: 'URL `/api/v1/exports/{id}`', schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ExportJob' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /exports:
    get:
      tags: [Exports]
      operationId: listExports
      summary: Seznam exportních jobů aktivního tenanta (nejnovější první)
      description: Po `expires_at` se maže jen odvozený soubor; záznam jobu zůstává (stav `expired`). Scope API klíče `invoices:read`.
      parameters:
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/ExportStatus' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ExportPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /exports/{exportId}:
    get:
      tags: [Exports]
      operationId: getExport
      summary: Stav exportního jobu
      parameters:
        - { name: exportId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ExportJob' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /exports/{exportId}/download:
    get:
      tags: [Exports]
      operationId: downloadExport
      summary: Stažení hotového exportu (ZIP nebo CSV)
      parameters:
        - { name: exportId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Soubor. ZIP obsahuje `<issue_date>_<invoice_number>_<id>.xml` s přesnými bajty a `manifest.csv` (id, číslo, sha256).
          headers:
            Content-Disposition: { schema: { type: string } }
          content:
            application/zip:
              schema: { type: string, format: binary }
            text/csv:
              schema: { type: string, format: binary }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}:
    get:
      tags: [Invoices]
      operationId: getInvoice
      summary: Detail faktury (stav doručení, validace, události)
      description: Faktura jiného tenanta => vždy `404` (nikdy 403).
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceDetail' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/xml:
    get:
      tags: [Invoices]
      operationId: getInvoiceXml
      summary: Původní XML (bajt po bajtu)
      description: |
        Vrací přesně uložené bajty (bez překódování). `ETag: "<sha256 hex>"` (SHA-256 těla), `Content-Type: application/xml`.
        Podporuje `If-None-Match` (304). Každý přístup se auditují.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: If-None-Match, in: header, schema: { type: string } }
      responses:
        '200':
          description: XML
          headers:
            ETag: { description: 'Uvozovkami obalený SHA-256 hex těla', schema: { type: string } }
            Content-Disposition: { description: 'attachment; filename="<invoice_number>.xml"', schema: { type: string } }
          content:
            application/xml:
              schema: { type: string, format: binary }
        '304': { description: Nezměněno }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/source-xml:
    get:
      tags: [Invoices]
      operationId: getInvoiceSourceXml
      summary: Původní XML přesně tak, jak ho poslalo ERP (před převodem do UTF-8)
      description: |
        Vrací **originální bajty** (např. windows-1250) s původním `Content-Type: application/xml; charset=<kódování>` a
        `ETag: "<SHA-256 originálu>"`. Existuje-li převod (kódování ≠ UTF-8 nebo odstraněný BOM), je to zdrojový dokument z
        `invoice_source_documents` (nemazatelný); jinak je originál shodný s `GET /invoices/{id}/xml` a vrací se uložené XML.
        Závazná pro archivaci a doručení je UTF-8 verze (`/xml`); originál je důkazní. Stejné role jako `/xml` (včetně `tenant_viewer`),
        každý přístup se audituje. Podporuje `If-None-Match` (304). Faktura bez XML = `409 XML_NOT_AVAILABLE`.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: If-None-Match, in: header, schema: { type: string } }
      responses:
        '200':
          description: Originální bajty
          headers:
            ETag: { description: 'Uvozovkami obalený SHA-256 originálu', schema: { type: string } }
            Content-Disposition: { description: 'attachment; filename="<invoice_number>.source.xml"', schema: { type: string } }
            X-Source-Encoding: { description: Kódování originálu, schema: { type: string } }
            X-Result-SHA256: { description: 'SHA-256 UTF-8 verze (= ETag `/xml`)', schema: { type: string } }
          content:
            application/xml:
              schema: { type: string, format: binary }
        '304': { description: Nezměněno }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/html:
    get:
      tags: [Invoices]
      operationId: getInvoiceHtml
      summary: Čitelná HTML vizualizace (nezávazná pomůcka, vhodná pro tisk/PDF)
      description: |
        Samostatný HTML dokument (`Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:`, bez skriptů).
        Vkládat do `<iframe sandbox>`. S `?print=1` (otevření v nové záložce) přidá jediný konstantní skript `window.print()` připnutý
        v CSP hashem (`script-src 'sha256-…'`) a stránka má tiskové CSS (A4); obsah faktury je vždy escapovaný.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: print, in: query, description: 'Otevřít tiskový dialog prohlížeče (jen pro samostatnou záložku)', schema: { type: boolean } }
      responses:
        '200':
          description: HTML
          content:
            text/html:
              schema: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/duplicates/{duplicateId}/xml:
    get:
      tags: [Invoices]
      operationId: getInvoiceDuplicateXml
      summary: XML odlišného duplicitního dokladu (bajt po bajtu)
      description: |
        Příchozí doklad se stejným klíčem (prodavatel, typ, číslo, datum) a JINÝM obsahem se nezahazuje ani nepřepisuje původní:
        uloží se samostatně (viz `InvoiceDetail.conflicting_duplicates`). Vrací přesné uložené bajty, `ETag` = SHA-256. Přístup se auditují.
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: duplicateId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: XML
          headers:
            ETag: { description: 'Uvozovkami obalený SHA-256 hex těla', schema: { type: string } }
          content:
            application/xml:
              schema: { type: string, format: binary }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/attachments/{attachmentId}:
    get:
      tags: [Invoices]
      operationId: getInvoiceAttachment
      summary: Stažení přílohy (BT-125 / příloha od poštáře)
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: attachmentId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Binární obsah s původním `Content-Type`
          headers:
            Content-Disposition: { schema: { type: string } }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ PARTICIPANTS
  /participants/{peppolId}:
    get:
      tags: [Participants]
      operationId: lookupParticipant
      summary: Je partner registrován v Peppolu?
      description: Volá `lookupParticipant` adaptéru výchozího odchozího spojení (nebo `connection_id`). Poštář bez podpory => `501 LOOKUP_NOT_SUPPORTED`. Scope `participants:read`.
      parameters:
        - { name: peppolId, in: path, required: true, description: 'Např. `0245:2020123457` (URL-enkódovat dvojtečku)', schema: { type: string, pattern: '^[0-9]{4}:.+$' } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Participant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '501': { $ref: '#/components/responses/NotImplemented' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ VALIDATION / REGISTRY (V-REG)
  /validation/party:
    get:
      tags: [Participants]
      operationId: validateParty
      summary: Ověření subjektu (formát IČO/DIČ/IČ DPH + lokální kopie registrů FS + volitelně Peppol SMP)
      description: |
        Kombinuje formát (`@efakt/ids`) a lokální denní kopii veřejných registrů Finanční správy SR (CC0): plátce DPH (`ds_dphs`), vymazaný (`ds_dphv`),
        důvod ke zrušení (`ds_dphz`) a přidělené DIČ (`ds_dsrdp`). DIČ se nikdy neodvozuje z IČ DPH. Výsledek je INFORMATIVNÍ (nenalezení je varování, ne chyba):
        nově registrovaný plátce se v seznamu objeví se zpožděním. Osobní údaje: u fyzických osob (OSVČ) se vrací jen stav, nikdy jméno ani adresa;
        `include=name` vrací název jen právnické osoby. `include=peppol` volá centrální slovenský SMP (fail-open: nedostupnost = `registered: null`).
        Scope `participants:read` (API klíč) nebo přihlášený uživatel; ERP integrace `GET /erp/validation/party` (scope `send`). Limit 60 dotazů/min na klíč/uživatele.
        Alespoň jeden z `ico`, `dic`, `icdph`.
      parameters:
        - { name: ico, in: query, schema: { type: string, maxLength: 64 } }
        - { name: dic, in: query, schema: { type: string, maxLength: 64 } }
        - { name: icdph, in: query, schema: { type: string, maxLength: 64 } }
        - { name: country, in: query, description: 'Jen `SK` (výchozí); jiné země zatím nejsou podporovány.', schema: { type: string, enum: [SK] } }
        - { name: include, in: query, description: 'Čárkou oddělený seznam: `registry` (výchozí), `peppol`, `name`.', schema: { type: string, maxLength: 64 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartyValidation' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/validation/party:
    get:
      tags: [ERP]
      operationId: erpValidateParty
      summary: Ověření subjektu pro ERP integraci (stejný výsledek jako `GET /validation/party`)
      description: Autentizace ERP (Bearer `erp_…` / Basic), scope `send`. Limit 60 dotazů/min na integraci.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: ico, in: query, schema: { type: string, maxLength: 64 } }
        - { name: dic, in: query, schema: { type: string, maxLength: 64 } }
        - { name: icdph, in: query, schema: { type: string, maxLength: 64 } }
        - { name: country, in: query, schema: { type: string, enum: [SK] } }
        - { name: include, in: query, schema: { type: string, maxLength: 64 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartyValidation' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/registries/status:
    get:
      tags: [Admin]
      operationId: adminRegistriesStatus
      summary: Stav importu registrů FS (aktivní snímky, stáří, poslední běhy)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RegistryStatus' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/registries/import:
    post:
      tags: [Admin]
      operationId: adminRegistriesImport
      summary: Ruční spuštění importu registrů FS (zařadí úlohu workeru)
      description: Úloha se provede asynchronně v workeru (jedna aktivní úloha najednou). Selhání importu nikdy nesmaže předchozí snapshot. `force` ignoruje 304 / shodu SHA-256; `accept_row_delta` přijme i velkou změnu počtu řádků.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RegistryImportRequest' }
      responses:
        '202':
          description: Zařazeno (nebo už čeká/běží)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RegistryImportAccepted' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ CONNECTIONS (tenant view)
  /connections:
    get:
      tags: [Connections]
      operationId: listConnections
      summary: Stav spojení s poštářem v čitelné podobě (bez credentials)
      description: Zákaznický pohled. Tenant sám spojení nezakládá (konfiguruje admin – viz `/admin/connections`). Scope `connections:read`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Connection' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  # ------------------------------------------------------------------ PROVIDERS (moduly poštářů, ADR 009)
  /providers:
    get:
      tags: [Connections]
      operationId: listProviders
      summary: Dostupné moduly poštářů (deskriptory bez tajemství)
      description: |
        Seznam registrovaných modulů poštářů: název, popis, odkaz na dokumentaci, prostředí, capabilities, režim příjmu a schéma
        credentials a nastavení spojení s UI nápovědou (`fields`, `json_schema`). Z toho admin UI generuje formulář pro přidání spojení.
        Nikdy neobsahuje tajemství. Přístupné každému přihlášenému uživateli.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /connections/{connectionId}/test:
    post:
      tags: [Connections]
      operationId: testConnection
      summary: Test spojení (volá adaptér testConnection)
      description: Vždy vrací 200 s `ok=true|false` (selhání poštáře není chyba API). Role `tenant_user`/`admin`.
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '200':
          description: Výsledek testu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConnectionTestResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ API KEYS
  /api-keys:
    get:
      tags: [ApiKeys]
      operationId: listApiKeys
      summary: API klíče aktivního tenanta (bez hodnot klíčů)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/ApiKey' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [ApiKeys]
      operationId: createApiKey
      summary: Vytvoření API klíče (hodnota se zobrazí jen jednou)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ApiKeyCreate' }
      responses:
        '201':
          description: Vytvořeno; pole `key` je jediný výskyt hodnoty (v DB jen Argon2id hash + prefix).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiKeyCreated' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /api-keys/{apiKeyId}:
    delete:
      tags: [ApiKeys]
      operationId: revokeApiKey
      summary: Zneplatnění klíče (soft – nastaví `revoked_at`)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: apiKeyId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Klíč zneplatněn (idempotentní)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiKey' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ WEBHOOKS
  /webhooks:
    get:
      tags: [Webhooks]
      operationId: listWebhooks
      summary: Registrované webhooky tenanta
      description: Scope `webhooks:manage`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/WebhookEndpoint' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Webhooks]
      operationId: createWebhook
      summary: Registrace webhooku
      description: |
        `url` musí být `https` (výjimka: `http://localhost`/`127.0.0.1` v prostředí `development`) a projít SSRF kontrolou
        (žádné privátní/link-local adresy). Odpověď obsahuje `secret` (`whsec_...`) **jen jednou**.
        Podpisové schéma viz `components.schemas.WebhookEnvelope` a docs/CONTRACTS.md.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookCreate' }
      responses:
        '201':
          description: Vytvořeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookCreated' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /webhooks/{webhookId}:
    get:
      tags: [Webhooks]
      operationId: getWebhook
      summary: Detail webhooku
      parameters:
        - { $ref: '#/components/parameters/WebhookId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookEndpoint' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Webhooks]
      operationId: deleteWebhook
      summary: Deaktivace webhooku (soft; historie doručení zůstává)
      parameters:
        - { $ref: '#/components/parameters/WebhookId' }
      responses:
        '204': { description: "Deaktivováno (idempotentní)" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /webhooks/{webhookId}/deliveries:
    get:
      tags: [Webhooks]
      operationId: listWebhookDeliveries
      summary: Historie doručení webhooku
      parameters:
        - { $ref: '#/components/parameters/WebhookId' }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/WebhookDeliveryStatus' } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookDeliveryPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /webhooks/{webhookId}/ping:
    post:
      tags: [Webhooks]
      operationId: pingWebhook
      summary: Odešle testovací událost `ping` (jednorázově, bez retry)
      parameters:
        - { $ref: '#/components/parameters/WebhookId' }
      responses:
        '200':
          description: Výsledek pokusu o doručení
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookDelivery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ ADMIN
  /admin/tenants:
    get:
      tags: [Admin]
      operationId: adminListTenants
      summary: Seznam tenantů
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/TenantStatus' } }
        - { name: search, in: query, schema: { type: string } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenantPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Admin]
      operationId: adminCreateTenant
      summary: Založení tenanta
      description: '`peppol_id` se odvozuje jako `0245:<DIČ>`. DIČ je unikátní (`409 DIC_ALREADY_EXISTS`).'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenantCreate' }
      responses:
        '201':
          description: Vytvořeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tenant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/tenants/{tenantId}:
    get:
      tags: [Admin]
      operationId: adminGetTenant
      summary: Detail tenanta
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tenant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    patch:
      tags: [Admin]
      operationId: adminUpdateTenant
      summary: Úprava tenanta (včetně deaktivace `status=suspended`). DELETE neexistuje – data se nemažou.
      description: DIČ po založení nelze měnit (`422`).
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenantUpdate' }
      responses:
        '200':
          description: Upraveno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tenant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/tenants/{tenantId}/memberships:
    get:
      tags: [Admin]
      operationId: adminListMemberships
      summary: Členství v tenantu
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Membership' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/tenants/{tenantId}/memberships/{userId}:
    put:
      tags: [Admin]
      operationId: adminUpsertMembership
      summary: Přidání/změna role uživatele v tenantu
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
        - { $ref: '#/components/parameters/UserId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MembershipUpsert' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Membership' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Admin]
      operationId: adminRevokeMembership
      summary: Odebrání členství (soft – `revoked_at`)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
        - { $ref: '#/components/parameters/UserId' }
      responses:
        '204': { description: "Odebráno (idempotentní)" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/users:
    get:
      tags: [Admin]
      operationId: adminListUsers
      summary: Seznam uživatelů
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: search, in: query, schema: { type: string } }
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Admin]
      operationId: adminCreateUser
      summary: Založení uživatele
      description: |
        Pokud `password` chybí, backend vygeneruje počáteční heslo a vrátí ho jedinou odpovědí v `initial_password` (ADR 005 bod 3;
        pozvánka e-mailem zatím není). Slabé heslo = `422 WEAK_PASSWORD`, duplicitní e-mail = `409 EMAIL_ALREADY_EXISTS`.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserCreate' }
      responses:
        '201':
          description: Vytvořeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserCreated' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/users/{userId}:
    get:
      tags: [Admin]
      operationId: adminGetUser
      summary: Detail uživatele (včetně členství)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/UserId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    patch:
      tags: [Admin]
      operationId: adminUpdateUser
      summary: Úprava uživatele (jméno, role, `disabled`, reset TOTP). DELETE neexistuje.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/UserId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserUpdate' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections:
    get:
      tags: [Admin]
      operationId: adminListConnections
      summary: Spojení s poštáři (všechny tenanty; bez credentials)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { name: provider_type, in: query, schema: { $ref: '#/components/schemas/ProviderType' } }
        - { name: health, in: query, schema: { $ref: '#/components/schemas/ConnectionHealth' } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminConnectionPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Admin]
      operationId: adminCreateConnection
      summary: Založení spojení
      description: |
        `credentials` je write-only a validuje se podle `provider_type` (viz `CredentialsInput`). Šifruje se AES-256-GCM,
        v odpovědích se nikdy nevrací (jen `credentials_configured`). `base_url` prochází allowlistem domén poštářů (SSRF),
        jinak `422 SSRF_BASE_URL_NOT_ALLOWED`. Max. jedno **aktivní** spojení s `inbound` na tenanta
        (`409 INBOUND_CONNECTION_EXISTS`). První poll po založení stahuje historii `initial_sync_days` zpět (výchozí 31).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConnectionCreate' }
      responses:
        '201':
          description: Vytvořeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminConnection' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '404': { $ref: '#/components/responses/NotFound' }   # tenant_id neexistuje
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}:
    get:
      tags: [Admin]
      operationId: adminGetConnection
      summary: Detail spojení
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminConnection' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    patch:
      tags: [Admin]
      operationId: adminUpdateConnection
      summary: Úprava spojení (credentials se nahrazují celé, ne merge)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConnectionUpdate' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminConnection' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Admin]
      operationId: adminDeactivateConnection
      summary: Deaktivace spojení (soft; `enabled=false`, historie a faktury zůstávají)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '204': { description: "Deaktivováno (idempotentní)" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}/test:
    post:
      tags: [Admin]
      operationId: adminTestConnection
      summary: Test spojení
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '200':
          description: Výsledek testu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConnectionTestResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}/poll:
    post:
      tags: [Admin]
      operationId: adminTriggerPoll
      summary: Ruční spuštění pollingu (zařadí job `poll_connection`)
      description: Respektuje pravidlo „jeden běh na spojení“ – pokud už běží, vrátí `409 CONFLICT` s `job_id` běžícího jobu v `detail`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '202':
          description: Job zařazen
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}/manual-import:
    post:
      tags: [Admin]
      operationId: adminManualImport
      summary: Ruční import XML do tenanta spojení (push-only poštář, zmeškaný webhook nebo `received_without_xml`)
      description: |
        Admin nahraje UBL XML stažené z portálu poskytovatele; uloží se jako příchozí doklad tenanta spojení se zdrojem `manual_import`
        a `connection_id` spojení. Kontrola příjemce platí (doklad jiné firmy => `409 BUYER_MISMATCH`-like `422 BUYER_MISMATCH`).
        Duplicita se stejným obsahem => `409 DUPLICATE_INVOICE`; stejný klíč a jiný obsah se uloží jako odlišný duplikát (viz detail faktury).
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string }
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, contentEncoding: base64, contentMediaType: application/xml }
      responses:
        '201':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceDetail' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/quarantine:
    get:
      tags: [Admin]
      operationId: adminListQuarantine
      summary: Karanténa dokladů (jiný příjemce než tenant spojení; poison dokumenty)
      description: Viditelné jen adminovi. Tenant doklady v karanténě nikdy nevidí.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [retrying, quarantined, assigned, dismissed] } }
        - { name: kind, in: query, schema: { type: string, enum: [party_mismatch, poison_document] } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuarantinedDocumentPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/quarantine/{quarantineId}/xml:
    get:
      tags: [Admin]
      operationId: adminGetQuarantineXml
      summary: Původní XML dokladu v karanténě (bajt po bajtu; audit)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: quarantineId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: XML
          content:
            application/xml:
              schema: { type: string, format: binary }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-events:
    get:
      tags: [Admin]
      operationId: adminListProviderEvents
      summary: Uložené události webhooků poštáře (čekající a dead-letter)
      description: Surové tělo webhooku se ukládá před zpracováním; zde je vidět `pending` (čeká na validátor/job) a `dead` (vyčerpané pokusy).
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [pending, processed, xml_missing, pending_match, dead, ignored, quarantined] } }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderEventPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-events/{eventId}/retry:
    post:
      tags: [Admin]
      operationId: adminRetryProviderEvent
      summary: Znovu zpracovat uloženou událost poštáře (dead -> pending, nový job)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: eventId, in: path, required: true, schema: { type: string } }
      responses:
        '202':
          description: Zařazeno znovu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderEvent' }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}/reset-cursor:
    post:
      tags: [Admin]
      operationId: adminResetCursor
      summary: Reset kurzoru pollingu (opětovné stažení od `since`)
      description: Stažené dokumenty se **nepřepisují** (idempotence), reset jen znovu projde historii. Audit povinný.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ResetCursorRequest' }
      responses:
        '200':
          description: Kurzor resetován
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminConnection' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/connections/{connectionId}/provider-webhook:
    post:
      tags: [Admin]
      operationId: adminRotateProviderWebhook
      summary: Vygeneruje/rotuje tajný segment cesty pro příjem webhooků poštáře
      description: Starý segment přestane platit okamžitě. Výsledek se zadá poštáři jako URL webhooku (veřejný host + `path`). Jen pro spojení, jejichž adaptér má `webhook_push` (jinak `422 PROVIDER_OPERATION_NOT_SUPPORTED`).
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ConnectionId' }
      responses:
        '200':
          description: Nový segment (zobrazí se jen jednou)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderWebhookInfo' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /provider-webhooks/{connectionId}/{pathSecret}:
    post:
      tags: [Connections]
      operationId: receiveProviderWebhook
      summary: Veřejný příjem webhooku od poštáře (push ingest)
      description: |
        **Bez uživatelské autentizace.** Důvěra = (1) tajný segment cesty per spojení, (2) HMAC podpis poštáře ověřený
        adaptérem (`PostmanAdapter.handleWebhook`). Neznámé spojení / špatný `pathSecret` / spojení bez `webhook_push` =>
        vždy `404` (žádný oracle). Špatný podpis => `401 WEBHOOK_SIGNATURE_INVALID`.

        Tělo se čte **jako raw bajty** (jakýkoli Content-Type; podpis je nad surovým tělem) a limit těla musí být
        >= 8 MB (ePodatelna24 posílá až 4 MB UBL v JSON stringu). Odpovědět do 10 s.

        Zpracování (jedna DB transakce): `handleWebhook` -> pro každou normalizovanou událost INSERT
        `provider_webhook_events(connection_id, dedupe_key)` ON CONFLICT DO NOTHING (dedupe, např. `X-EP24-Delivery`) ->
        uložení faktury (stejná idempotence jako poll) nebo aplikace stavu doručení (stavový automat) -> audit.
        Duplicitní doručení vrací `200 duplicate`. Neočekávaný typ události => `200 ignored`.
        Opakovatelná chyba po ověření podpisu (DB, validátor) => `503` (poštář bude opakovat); trvalá chyba
        zpracování => `200` + uložení do dead-letter (nikdy neztratit fakturu).
      security: []
      parameters:
        - { name: connectionId, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: pathSecret, in: path, required: true, schema: { type: string, minLength: 32, maxLength: 128 } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
          application/xml:
            schema: { type: string }
      responses:
        '200':
          description: Přijato (`accepted`, `duplicate` nebo `ignored`)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderWebhookAck' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
  /admin/providers/verteco/partner:
    get:
      tags: [Verteco]
      operationId: adminGetVertecoPartner
      summary: "Verteco: stav partnerského účtu (bez tajemství)"
      description: |
        Jen admin. Odpověď nese pouze příznaky `*_set` (token, FS klíč, klíč registračního endpointu, podpisový secret), nikdy hodnoty.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: Stav partnerského účtu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoPartner' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
    put:
      tags: [Verteco]
      operationId: adminPutVertecoPartner
      summary: "Verteco: nastavit partnerský účet (write-only tajemství)"
      description: |
        Merge: vynechané pole se nemění, `null` smaže volitelnou hodnotu. Tajemství se ukládají šifrovaně (AES-256-GCM, AAD) a **nikdy se nevrací**. `generate_webhook_urls` vydá nový tajný segment URL FS verifikačního webhooku, `register_notification_webhook` nový segment partnerského webhooku a zaregistruje ho na Vertecu (`issued_webhook_urls`, zobrazí se jen jednou). Změna `billing_model` volá `PUT /resellers/me/billing` na Vertecu (platí od 1. dne následujícího měsíce) a je auditována. Chyba Verteca (neplatný token `PROVIDER_AUTH_FAILED`, nedostupnost `PROVIDER_UNAVAILABLE`) se vrací jako `502` s důvodem v `detail`; lokální hodnoty se přesto uloží a stav účtu se označí `error`.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoPartnerUpdate' }
      responses:
        '200':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoPartnerSaved' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/companies:
    get:
      tags: [Verteco]
      operationId: adminListVertecoCompanies
      summary: "Verteco: klientské firmy pod partnerským účtem"
      description: |
        Jen admin. `sync=true` nejprve načte stavy z `GET /resellers/me/clients` (SMP stav, aktivace) a zapíše je.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: sync, in: query, schema: { type: boolean, default: false } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: Seznam firem
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompanyPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
    post:
      tags: [Verteco]
      operationId: adminCreateVertecoCompany
      summary: "Verteco: založit firmu klienta (tenant -> POST /companies)"
      description: |
        Údaje (IČO, DIČ, název, adresa) se berou z tenanta, IBAN je povinný. Chybějící nebo neplatná pole (IČO, adresa, IBAN) se vrátí jako `400 BAD_REQUEST` s `errors[]` (pointer na pole). `404` neznámý tenant, `409 CONFLICT`, pokud tenant už firmu má. Firma vzniká ve stavu `pending_verification`: přijímá a odesílá až po výběru naší značky klientem na Portálu FS (`vpds_url`).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoCompanyCreate' }
      responses:
        '201':
          description: Firma založena
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/companies/{tenantId}/pause:
    post:
      tags: [Verteco]
      operationId: adminPauseVertecoCompany
      summary: "Verteco: pozastavit odesílání klienta"
      description: |
        Destruktivní pro klienta: `confirm_dic` musí být DIČ klienta. Volá `POST /resellers/me/clients/{companyId}/pause-sending`; příjem běží dál, odesílání se pozastaví (fronta zůstane, nic se neztratí).
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoConfirmRequest' }
      responses:
        '200':
          description: Provedeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/companies/{tenantId}/resume:
    post:
      tags: [Verteco]
      operationId: adminResumeVertecoCompany
      summary: "Verteco: obnovit odesílání klienta"
      description: |
        Volá `POST …/resume-sending`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      responses:
        '200':
          description: Provedeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '404': { $ref: '#/components/responses/NotFound' }
  /admin/providers/verteco/companies/{tenantId}/release:
    post:
      tags: [Verteco]
      operationId: adminReleaseVertecoCompany
      summary: "Verteco: uvolnit klienta z partnerského účtu (nevratné)"
      description: |
        Destruktivní: `confirm_dic` musí být DIČ klienta. Firma přechází pod přímou správu Verteca; z partnerské strany nevratné.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoConfirmRequest' }
      responses:
        '200':
          description: Provedeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/companies/{tenantId}/receiving-provider:
    post:
      tags: [Verteco]
      operationId: adminVertecoReceivingProvider
      summary: "Verteco: klient přijímá záměrně u jiného poštáře"
      description: |
        `elsewhere=true` zastaví připomínky `smp_registered_elsewhere` a automatickou registraci (klient jen odesílá přes nás). `PUT /resellers/me/clients/{companyId}/receiving-provider`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoReceivingProviderRequest' }
      responses:
        '200':
          description: Provedeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/companies/{tenantId}/smp-migrate:
    post:
      tags: [Verteco]
      operationId: adminVertecoSmpMigrate
      summary: "Verteco: migrace záznamu SMP s kódem od předchozího poštáře"
      description: |
        Volá se až po zadání migračního kódu a výslovném potvrzení (`confirm=true`). Kód je jednorázový; neopakuje se automaticky. `POST /companies/{id}/smp-migrate`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/TenantId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VertecoSmpMigrateRequest' }
      responses:
        '200':
          description: Provedeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoCompany' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/providers/verteco/usage:
    get:
      tags: [Verteco]
      operationId: adminVertecoUsage
      summary: "Verteco: spotřeba po firmách za měsíc (podklad pro přeúčtování)"
      description: |
        Stáhne `GET /companies/usage?month=` z Verteca, uloží snapshot a vrátí řádky po firmách; `format=csv` vrátí CSV export. Částky jsou jen ODHAD podle modelu účtování.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: month, in: query, schema: { type: string, pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$' } }
        - { name: format, in: query, schema: { type: string, enum: [json, csv], default: json } }
        - { name: refresh, in: query, schema: { type: boolean, default: true } }
      responses:
        '200':
          description: Spotřeba
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoUsageReport' }
            text/csv:
              schema: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '502': { $ref: '#/components/responses/BadGateway' }
  /admin/providers/verteco/events:
    get:
      tags: [Verteco]
      operationId: adminListVertecoEvents
      summary: "Verteco: uložené události (FS verifikační a partnerské webhooky)"
      description: |
        Syrové tělo se ukládá před zpracováním; zde jsou vidět čekající, zpracované, ignorované a selhané (`dead`, nepřeposlané/nezpracované) události. Tělo se nevrací.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [pending, processed, ignored, dead] } }
        - { name: source, in: query, schema: { type: string, enum: [fs_webhook, partner_webhook] } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: Stránka událostí
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoPartnerEventPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/providers/verteco/events/{eventId}/retry:
    post:
      tags: [Verteco]
      operationId: adminRetryVertecoEvent
      summary: "Verteco: znovu zpracovat/přeposlat selhanou událost (dead -> pending)"
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: eventId, in: path, required: true, schema: { type: string, pattern: '^[0-9]{1,18}$' } }
      responses:
        '202':
          description: Zařazeno znovu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoPartnerEvent' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
  /tenant/verteco:
    get:
      tags: [Verteco]
      operationId: getTenantVerteco
      summary: "Verteco: stav klienta a odkaz pro výběr naší značky na Portálu FS"
      description: |
        Tenant vidí jen svůj stav (čekám na aktivaci / aktivní / pozastaveno / SMP jinde), nikdy cizí firmy ani události. `vpds_url` je odkaz pro výběr naší značky na Portálu FS.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: Stav
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoTenantStatus' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /provider-webhooks/verteco-reseller/{secret}:
    post:
      tags: [Verteco]
      operationId: receiveVertecoFsWebhook
      summary: Veřejný FS verifikační webhook zprostředkovatele (přeposlání Vertecu)
      description: |
        **Bez uživatelské autentizace.** Finanční správa volá tento endpoint při výběru naší značky klientem. Důvěra = (1) tajný segment cesty,
        (2) hlavička `x-pds-secret` == hex(SHA-512(surové tělo + FS klíč)), porovnání v konstantním čase.
        Odpovědi (tvar určuje Verteco): `200 {"status":"received"}`, `403 {"status":"forbidden"}` (chybí/špatná hlavička; nic se neuloží ani nepřepošle),
        `413 {"status":"too_large"}` (tělo > 64 KB se zahodí), `429` (rate limit), neznámý segment `404`.
        Platné tělo se **nejdřív uloží** (syrové bajty) a teprve pak se asynchronně (opakování s backoffem) přepošle **nezměněné bajt po bajtu** i s původní hlavičkou
        `x-pds-secret` na `https://peppol.verteco.digital/peppol/webhook/reseller/{klíč}`. Obsah těla se nikdy nelogguje.
      security: []
      parameters:
        - { name: secret, in: path, required: true, schema: { type: string, minLength: 32, maxLength: 128 } }
        - { name: x-pds-secret, in: header, required: false, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Přijato
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoFsWebhookAck' }
        '403':
          description: Chybí hlavička nebo se podpis nerovná SHA-512(tělo + FS klíč)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoFsWebhookAck' }
        '413':
          description: Tělo je větší než 64 KB
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VertecoFsWebhookAck' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /provider-webhooks/verteco-partner/{secret}:
    post:
      tags: [Verteco]
      operationId: receiveVertecoPartnerWebhook
      summary: Veřejný partnerský notifikační webhook Verteca (události všech klientských firem)
      description: |
        **Bez uživatelské autentizace.** Důvěra = (1) tajný segment cesty, (2) podpis `X-Verteco-Signature: sha256=HMAC-SHA256(secret, tělo)` **nebo**
        Standard Webhooks (`webhook-id`/`webhook-timestamp`/`webhook-signature`, tolerance času 300 s), konstantní čas. Špatný podpis => `401 WEBHOOK_SIGNATURE_INVALID`.
        Syrové tělo se uloží PŘED zpracováním (dedupe podle `eventId`), `200 duplicate` při opakovaném doručení. Zpracování (mapování na tenanta,
        `company.activated`, `company.smp_registered_elsewhere`, `invoice.*`…) běží v workeru; cizí/neznámá firma se tiše ignoruje (nikdy neprozradí tenanty).
      security: []
      parameters:
        - { name: secret, in: path, required: true, schema: { type: string, minLength: 32, maxLength: 128 } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Přijato (`accepted`, `duplicate` nebo `ignored`)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderWebhookAck' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/polling:
    get:
      tags: [Admin]
      operationId: adminPollingOverview
      summary: Přehled pollingu všech spojení
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items, generated_at]
                properties:
                  generated_at: { type: string, format: date-time }
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/PollingOverviewItem' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/jobs:
    get:
      tags: [Admin]
      operationId: adminListJobs
      summary: Fronta úloh a dead-letter (`status=dead`)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/JobStatus' } }
        - { name: type, in: query, schema: { $ref: '#/components/schemas/JobType' } }
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/JobPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/jobs/{jobId}/retry:
    post:
      tags: [Admin]
      operationId: adminRetryJob
      summary: Opakování jobu ve stavu `dead`/`failed` (vznikne nový pokus, původní záznam zůstane)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: jobId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: Zařazeno znovu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/webhook-deliveries:
    get:
      tags: [Admin]
      operationId: adminListWebhookDeliveries
      summary: Doručení webhooků napříč tenanty (dead-letter = `status=dead`)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/WebhookDeliveryStatus' } }
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookDeliveryPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/webhook-deliveries/{deliveryId}/retry:
    post:
      tags: [Admin]
      operationId: adminRetryWebhookDelivery
      summary: Opakované doručení (stejné `event_id`, nový pokus)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: deliveryId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: Zařazeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookDelivery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/audit-log:
    get:
      tags: [Admin]
      operationId: adminListAuditLog
      summary: Audit log (kdo, co, kdy)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { name: actor_user_id, in: query, schema: { type: string, format: uuid } }
        - { name: action, in: query, description: 'Přesná akce nebo prefix končící `*` (např. `invoice.*`)', schema: { type: string } }
        - { name: entity_type, in: query, schema: { type: string } }
        - { name: entity_id, in: query, schema: { type: string } }
        - { name: from, in: query, schema: { type: string, format: date-time } }
        - { name: to, in: query, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK (nejnovější první)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AuditLogPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/settings:
    get:
      tags: [Admin]
      operationId: adminListSettings
      summary: Nastavení systému (BEZ tajemství; tajná pole jen jako `secrets_set`)
      description: Každá položka nese schéma formuláře (`fields`), aktuální netajné hodnoty, stav a zdroj (`db` | `env` | `default`). Jen role admin.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SystemSettingList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/settings/{key}:
    put:
      tags: [Admin]
      operationId: adminPutSetting
      summary: Uložení nastavení jednoho klíče (nahradí netajné hodnoty; tajná pole write-only)
      description: |
        `values` = celé netajné hodnoty klíče (validace zod schématem klíče, `422 INVALID_SETTING` s `errors`). `secrets`: pole vyplněné = nastaví/nahradí,
        nepřítomné = beze změny; `clear_secrets` = smaže. Tajemství se šifrují master klíčem (AES-256-GCM, AAD) a API je nikdy nevrací.
        `expected_version` (optimistický zámek) při neshodě `409 CONFLICT`. Změna se audituje a ukládá do append-only historie.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: key, in: path, required: true, schema: { $ref: '#/components/schemas/SettingKey' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SystemSettingUpdate' }
      responses:
        '200':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SystemSetting' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/settings/smtp/test:
    post:
      tags: [Admin]
      operationId: adminTestSmtp
      summary: Zkušební e-mail na zadanou adresu (přes uložené/účinné SMTP nastavení)
      description: Vždy `200` s výsledkem (`ok` true/false, srozumitelná chyba bez tajemství). Bez nastaveného SMTP `409 SMTP_NOT_CONFIGURED`. Přísnější rate limit (5/min).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SmtpTestRequest' }
      responses:
        '200':
          description: Výsledek testu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SettingsTestResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/settings/ai_refresher/test:
    post:
      tags: [Admin]
      operationId: adminTestAiRefresher
      summary: Test spojení s Ollamou (`GET {ollama_base_url}/api/tags`) pro uložené nastavení
      description: 'Vždy `200` s výsledkem (`ok`, `code`, seznam modelů v `info`, `model_available`). Ollama nedostupná = `ok: false`, ne chyba aplikace. Přísnější rate limit (5/min).'
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: Výsledek testu
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SettingsTestResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/notifications:
    get:
      tags: [Admin]
      operationId: adminListNotifications
      summary: Fronta e-mailových upozornění (outbox) s filtry
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/NotificationStatus' } }
        - { name: scope, in: query, schema: { $ref: '#/components/schemas/NotificationScope' } }
        - { name: type, in: query, schema: { type: string, maxLength: 64 } }
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: OK (nejnovější první)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/NotificationPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/notifications/{notificationId}/retry:
    post:
      tags: [Admin]
      operationId: adminRetryNotification
      summary: Ruční odeslání/opakování upozornění ve stavu `failed` nebo `suppressed`
      description: Příjemci se znovu určí (tenantová = aktuální `contact_email`, platformní = aktuální správci). Bez SMTP `409 SMTP_NOT_CONFIGURED`; jiný stav než failed/suppressed `409 CONFLICT`.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: notificationId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: Zařazeno k odeslání
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notification' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/notifications/flush-suppressed:
    post:
      tags: [Admin]
      operationId: adminFlushSuppressedNotifications
      summary: Odeslat všechna potlačená (`suppressed`) upozornění z posledních 30 dní po nastavení SMTP
      description: Bez SMTP `409 SMTP_NOT_CONFIGURED`. Starší a bez příjemce se přeskočí (`skipped`).
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: Výsledek
          content:
            application/json:
              schema: { $ref: '#/components/schemas/NotificationFlushResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/validation-summary:
    get:
      tags: [Admin]
      operationId: adminValidationSummary
      summary: Souhrn validačních chyb napříč tenanty (agregace po pravidlech)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: from, in: query, schema: { type: string, format: date-time } }
        - { name: to, in: query, schema: { type: string, format: date-time } }
        - { name: tenant_id, in: query, schema: { type: string, format: uuid } }
        - { name: direction, in: query, schema: { $ref: '#/components/schemas/Direction' } }
        - { name: severity, in: query, schema: { $ref: '#/components/schemas/FindingSeverity' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [items, generated_at]
                properties:
                  generated_at: { type: string, format: date-time }
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/ValidationSummaryItem' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ ERP API (ADR 015)
  /erp/auth/token:
    post:
      tags: [ERP]
      operationId: erpAuthToken
      summary: Výměna jména a hesla technického účtu za krátkodobý Bearer token
      description: |
        Veřejný endpoint (bez `Authorization`; alternativně lze údaje poslat jako HTTP Basic). Rate limit **před** drahým ověřením hesla
        (per IP a per uživatelské jméno), po opakovaných chybách zámek účtu (`429 ACCOUNT_LOCKED` + `Retry-After`). Token má platnost `expires_in` sekund
        a stejné scopes jako integrace; zrušení hesla nebo integrace ho zneplatní okamžitě.
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpTokenRequest' }
      responses:
        '200':
          description: 'Token vydán'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpTokenResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/me:
    get:
      tags: [ERP]
      operationId: erpMe
      summary: Kdo jsem – tenant, integrace, scopes, dostupná spojení s poštáři a limity
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpMe' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/invoices:
    post:
      tags: [ERP]
      operationId: erpSubmitInvoice
      summary: Odeslání jedné faktury přes poštáře (scope `send`, vždy asynchronní)
      description: |
        `Content-Type: application/xml` (UBL 2.1 Peppol BIS 3.0, bajty beze změny; volitelně `X-Client-Reference`, `?connection_id=`)
        **nebo** `application/json` obálka `{ xml_base64, connection_id?, tag?, client_reference? }`. Povinný `Idempotency-Key`
        (klíče jsou nezávislé per integrace). Platí všechna pravidla `POST /invoices` (seller = tenant, datum vystavení = den odeslání v Europe/Bratislava,
        retry po `failed_permanent` novým klíčem, `RECIPIENT_NOT_REGISTERED` = `delivery_failed`). Poštář: `connection_id` z požadavku, jinak
        výchozí poštář integrace, jinak výchozí odchozí poštář tenanta. Chyby 422 s `findings` jako u `POST /invoices`.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKey' }
        - { name: connection_id, in: query, schema: { type: string, format: uuid } }
        - { name: X-Client-Reference, in: header, schema: { type: string, maxLength: 200 } }
        - { $ref: '#/components/parameters/TestQuery' }
        - { $ref: '#/components/parameters/TestModeHeader' }
        - { $ref: '#/components/parameters/SimulateQuery' }
        - { $ref: '#/components/parameters/SimulateWebhooksQuery' }
      requestBody:
        required: true
        content:
          application/xml:
            schema: { type: string, format: binary }
          application/json:
            schema: { $ref: '#/components/schemas/ErpInvoiceEnvelope' }
      responses:
        '200':
          description: 'Jen v testovacím režimu (`test=true` nebo integrace `test_only`) - nic se neodeslalo ani neuložilo. Viz `TestSubmitResponse`.'
          headers:
            X-Test-Mode: { $ref: '#/components/headers/XTestMode' }
            X-Would-Have-Sent: { $ref: '#/components/headers/XWouldHaveSent' }
            Idempotent-Replayed: { description: '`true` při přehrání původní testovací odpovědi', schema: { type: string, enum: ['true'] } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TestSubmitResponse' }
        '202':
          description: 'Přijato k odeslání (opakování se stejným klíčem vrací původní odpověď s hlavičkou `Idempotent-Replayed: true`).'
          headers:
            Location: { description: Adresa stavu faktury, schema: { type: string } }
            Idempotent-Replayed: { description: 'true při opakování se stejným Idempotency-Key', schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpInvoiceAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/invoices/batch:
    post:
      tags: [ERP]
      operationId: erpSubmitInvoiceBatch
      summary: Dávkové odeslání (scope `send`), částečný úspěch = 207
      description: |
        Až `max_batch_items` (výchozí 50, viz `GET /erp/me`) položek `{ client_reference, xml_base64, idempotency_key, connection_id? }`.
        Každá položka je zpracována a idempotentní **samostatně** (stejně jako `POST /erp/invoices`); odpověď `207` nese výsledek po položkách
        (`status` accepted|error, `http_status`, u chyby `error` jako problem+json). Opakování celé dávky je bezpečné.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/TestQuery' }
        - { $ref: '#/components/parameters/TestModeHeader' }
        - { $ref: '#/components/parameters/SimulateQuery' }
        - { $ref: '#/components/parameters/SimulateWebhooksQuery' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpBatchRequest' }
      responses:
        '207':
          description: 'Výsledky po položkách (pořadí jako ve vstupu)'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpBatchResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/invoices/{invoiceId}:
    get:
      tags: [ERP]
      operationId: erpGetInvoice
      summary: Stav a události odeslané faktury (scope `send` nebo `status`)
      description: |
        Stejný model jako `GET /invoices/{id}`; jen odchozí faktury vlastního tenanta (jinak `404`).
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceDetail' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/outbox/changes:
    get:
      tags: [ERP]
      operationId: erpOutboxChanges
      summary: Proud změn stavů odeslaných faktur (scope `status`)
      description: |
        Změny stavů faktur odeslaných touto integrací (`scope=tenant` = všech odchozích faktur tenanta) od kurzoru. **Vždy si ulož `next_cursor`**
        (i při prázdné stránce; je neprůhledný a stabilní). Změny se zveřejňují se zpožděním `ERP_FEED_LAG_SECONDS` (výchozí 30 s), aby souběžné
        transakce nemohly způsobit ztrátu události. At-least-once, řazení podle času změny a id. Bez kurzoru se začíná od `since` (jinak od začátku historie).
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: cursor, in: query, schema: { type: string, maxLength: 2048 } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }
        - { name: since, in: query, description: 'Jen bez kurzoru: ISO 8601 datum nebo datum a čas', schema: { type: string, maxLength: 40 } }
        - { name: scope, in: query, schema: { type: string, enum: [own, tenant], default: own } }
      responses:
        '200':
          description: 'Stránka změn'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpOutboxPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/pending:
    get:
      tags: [ERP]
      operationId: erpInboxPending
      summary: Přijaté faktury, které tato integrace ještě nepotvrdila (scope `receive`)
      description: |
        Příchozí faktury tenanta seřazené podle `received_at` vzestupně (stabilně: `received_at`, `id`), které **tato integrace** nepotvrdila (ACK) –
        po založení integrace celá dostupná historie. Bez ACK se nabídnou znovu (at-least-once). Stav je per integrace (víc ERP u jednoho klienta si
        nepřebíjí převzetí). `received_invalid` a `received_without_xml` jsou vidět s příznakem (`status`, `xml_missing`); karanténní (po N NACK) se nenabízejí.
        Čtení **nemění** stav.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }
        - { name: cursor, in: query, schema: { type: string, maxLength: 2048 } }
        - { name: include, in: query, description: '`xml` = vložit XML jako base64 (do limitu velikosti odpovědi, jinak odkaz `xml_url`)', schema: { type: string, enum: [xml] } }
        - { name: charset, in: query, description: 'S `include=xml`: vložit odvozenou kopii XML v cílovém kódování (viz `GET /erp/me` capabilities.charsets); položka pak nese `xml_encoding` a `xml_derived_from_sha256`; nepřevoditelná položka má `xml_base64: null` a `xml_encoding_error` (nikdy tichá náhrada).', schema: { type: string, maxLength: 40 } }
      responses:
        '200':
          description: 'Stránka'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpInboxPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/by-period:
    get:
      tags: [ERP]
      operationId: erpInboxByPeriod
      summary: Přijaté faktury za zadané období (scope `receive`) – bez změny stavu převzetí
      description: |
        Dohledání a opakované stažení (např. celý měsíc). `from`/`to`: datum `YYYY-MM-DD` (den v Europe/Bratislava, `to` včetně) nebo ISO 8601 datum a čas
        (obě meze včetně). `date_field` = `received_at` (výchozí) | `issue_date`. `state` = `all` (výchozí) | `pending` | `acknowledged` | `conflict` (faktury s odlišnou duplicitou). Maximální rozsah
        `max_period_days` (výchozí 366; viz `GET /erp/me`), `limit` ≤ 500, řazení vzestupně podle zvoleného pole a `id`, stabilní kurzor.
        **Stažení neoznačuje faktury jako převzaté.** Volitelně `ack=true` = „stáhni a potvrď“: ACK se provede až PO předání celé odpovědi do spojení
        (server počká na `finish` odpovědi; při chybě nebo přerušeném spojení se neprovede; odpověď má hlavičku `X-Erp-Ack: deferred`; garance je „odesláno“, ne „klient zpracoval“),
        a JEN u položek ve stavu `pending`, které odpověď nese i s XML (`include=xml`, `xml_base64` ≠ null). Nikdy nepotvrdí položky v karanténě (`quarantined`),
        pronajaté (`leased`), v prodlevě po NACK (`nack_backoff`), „bez XML“ (`xml_missing`) ani bez vloženého XML (`xml_not_inline`) – ty jsou v odpovědi v poli
        `ack_skipped` s důvodem. Potvrzení nese `erp_reference.id = auto:by_period` a audit `erp.inbox.ack` s `delivery_confirmed: false`. Doporučený a bezpečný postup zůstává
        samostatné `POST /erp/inbox/ack` až po zpracování.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: from, in: query, required: true, schema: { type: string, maxLength: 40 } }
        - { name: to, in: query, required: true, schema: { type: string, maxLength: 40 } }
        - { name: date_field, in: query, schema: { type: string, enum: [received_at, issue_date], default: received_at } }
        - { name: state, in: query, schema: { type: string, enum: [all, pending, acknowledged, conflict], default: all } }
        - { name: ack, in: query, schema: { type: boolean, default: false } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }
        - { name: cursor, in: query, schema: { type: string, maxLength: 2048 } }
        - { name: include, in: query, description: '`xml` = vložit XML jako base64 (do limitu velikosti odpovědi, jinak odkaz `xml_url`)', schema: { type: string, enum: [xml] } }
        - { name: charset, in: query, description: 'S `include=xml`: vložit odvozenou kopii XML v cílovém kódování (viz `GET /erp/me` capabilities.charsets); položka pak nese `xml_encoding` a `xml_derived_from_sha256`; nepřevoditelná položka má `xml_base64: null` a `xml_encoding_error` (nikdy tichá náhrada).', schema: { type: string, maxLength: 40 } }
      responses:
        '200':
          description: 'Stránka'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpInboxPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/stats:
    get:
      tags: [ERP]
      operationId: erpInboxStats
      summary: Počty pending / leased / acknowledged / nack / quarantined (scope `receive`)
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpInboxStats' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/claim:
    post:
      tags: [ERP]
      operationId: erpInboxClaim
      summary: Převzetí dávky pending faktur s lease (volitelné, scope `receive`)
      description: |
        Vrátí až `limit` pending faktur a na `lease_seconds` je zamkne pro tuto integraci, aby paralelní workery ERP nestahovaly totéž.
        Po vypršení leasu se faktura nabídne znovu. Lease není ACK: převzetí se potvrzuje až `POST /erp/inbox/ack`.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
        - { name: lease_seconds, in: query, schema: { type: integer, minimum: 10, maximum: 3600, default: 300 } }
        - { name: include, in: query, schema: { type: string, enum: [xml] } }
        - { name: charset, in: query, description: 'S `include=xml`: vložit odvozenou kopii XML v cílovém kódování (viz `GET /erp/me` capabilities.charsets); položka pak nese `xml_encoding` a `xml_derived_from_sha256`; nepřevoditelná položka má `xml_base64: null` a `xml_encoding_error` (nikdy tichá náhrada).', schema: { type: string, maxLength: 40 } }
      responses:
        '200':
          description: 'Zamčené položky (může být méně než `limit`, i žádná)'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpClaimResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/ack:
    post:
      tags: [ERP]
      operationId: erpInboxAck
      summary: Potvrzení převzetí (ACK), idempotentní (scope `receive`)
      description: |
        Potvrdí převzetí faktur touto integrací. Odpověď rozděluje `acknowledged` (nově potvrzeno), `already_acknowledged` (beze změny, datum zůstává původní)
        a `not_found` (neexistuje, cizí tenant nebo není příchozí); faktura „bez XML“ bez dodatečného XML je v `rejected` (`xml_missing`, není co převzít). ACK nikdy nemění ani nemaže uložená XML; je konečný. Datum a čas ACK se zobrazí u faktury
        v portálu jako „převzato do ERP“.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpAckRequest' }
      responses:
        '200':
          description: 'Výsledek po položkách'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpAckResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/nack:
    post:
      tags: [ERP]
      operationId: erpInboxNack
      summary: ERP doklad nedokázalo zpracovat (NACK, scope `receive`)
      description: |
        Faktura zůstává pending (znovu se nabídne po exponenciální prodlevě), zvýší se počítadlo pokusů a důvod vidí admin v portálu.
        Po `nack_quarantine_after` pokusech (výchozí 5) přejde do karantény (nenabízí se) a tenantu se odešle upozornění.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpNackRequest' }
      responses:
        '200':
          description: 'Stav po NACK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpNackResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/conflicts/ack:
    post:
      tags: [ERP]
      operationId: erpInboxConflictsAck
      summary: Potvrdit převzetí odlišných duplicit (konflikty; scope `receive`)
      description: |
        Odlišná duplicita (`duplicates[].reason = different_content`) k už potvrzené faktuře se jako pending znovu nenabízí (ACK faktury je konečný). ERP ji najde přes
        `stats.conflicts` / `by-period?state=conflict`, stáhne `…/xml?duplicate_id=` a po zpracování ji potvrdí tímto voláním. Potvrzení je konečné a idempotentní
        (týká se jen této integrace); potvrzená duplicita zmizí ze `stats.conflicts` a z `state=conflict`. Původní XML faktury se nikdy nemění.
        `xml_supplement` se tímto voláním nepotvrzuje (řeší ho běžný `ack` faktury).
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpConflictAckRequest' }
      responses:
        '200':
          description: 'Výsledek potvrzení'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpConflictAckResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/{invoiceId}/xml:
    get:
      tags: [ERP]
      operationId: erpInboxXml
      summary: Původní XML příchozí faktury (přesné bajty, ETag = SHA-256; scope `receive`)
      description: |
        Nemění stav převzetí. `If-None-Match` s hodnotou SHA-256 vrací `304`. Doklad bez XML (`received_without_xml`) = `409 XML_NOT_AVAILABLE`, dokud nedorazí
        dodatečné XML (pak se vrací ono). `duplicate_id` = konkrétní dodatek / odlišná duplicita z pole `duplicates` položky.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: duplicate_id, in: query, schema: { type: string, format: uuid } }
        - name: charset
          in: query
          description: |
            Vrátit **odvozenou kopii** v cílovém kódování (`windows-1250`, `iso-8859-2`, `windows-1252`, `cp852`, `utf-16le`, `utf-16be`, `utf-8`; viz `GET /erp/me` → `capabilities.charsets`).
            Deklarace `encoding=` se přepíše, hlavičky `X-Derived-From-SHA256` (SHA-256 UTF-8 verze) a `X-Source-Encoding`; `ETag` je SHA-256 odvozených bajtů.
            Znak, který cílové kódování nemá => `422 ENCODING_NOT_REPRESENTABLE` se seznamem znaků (nikdy tichá náhrada). Odvozená kopie NENÍ doklad k archivaci.
          schema: { type: string, maxLength: 40 }
      responses:
        '200':
          description: XML beze změny (UTF-8) nebo odvozená kopie při `charset`
          headers:
            ETag: { description: 'SHA-256 XML v uvozovkách', schema: { type: string } }
            X-Derived-From-SHA256: { description: 'Jen s `charset`: SHA-256 UTF-8 verze, ze které je kopie odvozena', schema: { type: string } }
            X-Source-Encoding: { description: 'Jen s `charset`: kódování zdroje, ze kterého je kopie odvozena (vždy `utf-8`; cílové kódování je v Content-Type)', schema: { type: string } }
          content:
            application/xml:
              schema: { type: string, format: binary }
        '304': { description: Beze změny (ETag souhlasí) }
        '400': { $ref: '#/components/responses/BadRequest' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/{invoiceId}/revalidate:
    post:
      tags: [ERP]
      operationId: erpInboxRevalidate
      summary: Opakovaná kontrola příchozí faktury (scope `receive`)
      description: |
        Totéž co `POST /invoices/{invoiceId}/revalidate` pro integraci ERP: nový běh `inbound_recheck` nad uloženým XML, `validation_status` se změní jen při změně verdiktu.
        Nemění stav převzetí (ACK) ani XML. Rate limit 20/min na integraci. Cizí tenant, odchozí nebo neexistující faktura = `404`; bez XML = `409 XML_NOT_AVAILABLE`.
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - name: Idempotency-Key
          in: header
          required: false
          description: Volitelný. Stejný klíč + stejná faktura vrátí původní výsledek (`Idempotent-Replayed - true`) bez nového běhu; 1-200 znaků `[A-Za-z0-9._:-]`.
          schema: { type: string, minLength: 1, maxLength: 200, pattern: '^[A-Za-z0-9._:-]+$' }
      responses:
        '200':
          description: Nový běh uložen
          headers:
            Idempotent-Replayed: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvoiceRevalidation' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp/inbox/{invoiceId}/attachments/{attachmentId}:
    get:
      tags: [ERP]
      operationId: erpInboxAttachment
      summary: Příloha příchozí faktury (scope `receive`)
      security: [{ erpBearer: [] }, { erpBasic: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: attachmentId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Obsah přílohy s původním Content-Type (dokumentováno jako octet-stream)
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ ERP integrace (správa v UI, cookie session)
  /erp-integrations:
    get:
      tags: [ERP]
      operationId: listErpIntegrations
      summary: ERP integrace aktivního tenanta (tenant uživatel s právem zápisu a admin)
      description: |
        Role `tenant_viewer` nesmí (`403`). Přihlašovací údaje bez hodnot (prefix, jméno, stav, poslední použití) + počty pending/ACK/NACK.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegrationPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [ERP]
      operationId: createErpIntegration
      summary: Založení integrace (tajemství se zobrazí jen jednou)
      description: |
        1 integrace = 1 firma (tenant). `auth_methods`: `token` (`erp_…`, ≥ 256 bit) a/nebo `password` (jméno + generované heslo technického účtu).
        V odpovědi `secrets` je jediný výskyt tokenu/hesla (v DB jen prefix + hash).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpIntegrationCreate' }
      responses:
        '201':
          description: 'Vytvořeno'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegrationCreated' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}:
    get:
      tags: [ERP]
      operationId: getErpIntegration
      summary: Detail integrace
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegration' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    patch:
      tags: [ERP]
      operationId: updateErpIntegration
      summary: Úprava integrace (název, scopes, výchozí poštář, IP allowlist, status)
      description: |
        Změna scopes, allowlistu nebo `status=disabled` se projeví okamžitě (i pro už vydané tokeny).
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpIntegrationUpdate' }
      responses:
        '200':
          description: 'Upraveno'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegration' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [ERP]
      operationId: disableErpIntegration
      summary: Zrušení integrace (soft – status disabled, všechny přihlašovací údaje se zneplatní)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      responses:
        '200':
          description: 'Zrušeno (idempotentní); záznamy a stav převzetí zůstávají'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegration' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}/credentials:
    post:
      tags: [ERP]
      operationId: rotateErpCredential
      summary: Rotace přihlašovacího údaje (nový token / heslo; staré platí ještě `overlap_hours`, výchozí 24 h)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpCredentialRotate' }
      responses:
        '201':
          description: 'Nový údaj; `secrets` je jediný výskyt hodnoty'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpCredentialRotated' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}/credentials/{credentialId}:
    delete:
      tags: [ERP]
      operationId: revokeErpCredential
      summary: Okamžité zneplatnění jednoho přihlašovacího údaje
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
        - { name: credentialId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: 'Zneplatněno (idempotentní)'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegration' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}/test:
    post:
      tags: [ERP]
      operationId: testErpIntegration
      summary: Ověření připojení (diagnostika integrace na straně portálu)
      description: |
        Zkontroluje stav integrace, platné přihlašovací údaje, scopes, odchozí poštář a počty pending. Hodnoty tajemství nepoužívá.
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      responses:
        '200':
          description: 'Výsledek kontrol'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpIntegrationTestResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}/problems:
    get:
      tags: [ERP]
      operationId: listErpProblems
      summary: Faktury, které ERP odmítlo (NACK) nebo jsou v karanténě
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: 'Stránka'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpProblemPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-integrations/{integrationId}/problems/release:
    post:
      tags: [ERP]
      operationId: releaseErpProblems
      summary: Vrácení faktur z karantény / NACK mezi pending
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/ErpIntegrationId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ErpProblemRelease' }
      responses:
        '200':
          description: 'Uvolněno'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErpProblemReleaseResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ ERP NÁSTROJE (ADR 017)
  /erp-tools/vfp/manifest:
    get:
      tags: [ERP]
      operationId: getVfpToolManifest
      summary: Manifest balíčku VFP klienta (verze, SHA-256, velikost, soubory, kompatibilita s API, historie verzí)
      description: |
        Jen cookie session s právem zápisu v tenantu (admin / `tenant_user`); `tenant_viewer` `403`. Balíček je verzovaný asset v obrazu serveru; neprošel-li kontrolou
        SHA-256 při startu, server ho nenabízí (`503 SERVICE_UNAVAILABLE`).
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VfpToolManifest' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-tools/vfp/package:
    get:
      tags: [ERP]
      operationId: downloadVfpToolPackage
      summary: Stažení ZIP balíčku VFP klienta (ověřený SHA-256, auditováno)
      description: |
        `Content-Disposition: attachment`, `ETag: "<sha256>"`, `X-Content-SHA256`, `Digest: sha-256=<base64>`; podpora `If-None-Match` (`304`). Každé stažení se zapisuje do auditu
        (`erp_tools.vfp_client.download`). Vlastní rate limit (`429` + `Retry-After`). Jen cookie session s právem zápisu.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: version, in: query, required: false, schema: { type: string, pattern: '^\d+\.\d+\.\d+$' }, description: 'Verze balíčku (výchozí: poslední)' }
      responses:
        '200':
          description: ZIP
          headers:
            ETag: { schema: { type: string } }
            X-Content-SHA256: { schema: { type: string, pattern: '^[0-9a-f]{64}$' } }
            Digest: { schema: { type: string } }
            Content-Disposition: { schema: { type: string } }
          content:
            application/zip:
              schema: { type: string, format: binary }
        '304': { description: 'Beze změny (If-None-Match)' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-tools/vfp/files:
    get:
      tags: [ERP]
      operationId: getVfpToolFile
      summary: Text souboru z balíčku pro náhled (jen whitelist README*.md, demo_*.prg, main.prg, erpapi.ini.example, ...)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: path, in: query, required: true, schema: { type: string, maxLength: 80 } }
        - { name: version, in: query, required: false, schema: { type: string, pattern: '^\d+\.\d+\.\d+$' } }
      responses:
        '200':
          description: Text (UTF-8, `text/plain`, nikdy se nevykonává)
          content:
            text/plain:
              schema: { type: string }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /erp-tools/vfp/ini:
    get:
      tags: [ERP]
      operationId: getVfpToolIni
      summary: Předvyplněný erpapi.ini (URL portálu, název integrace, scopes; NIKDY tajemství)
      description: |
        S `integration_id` (integrace aktivního tenanta; cizí / neexistující `404`) doplní `User` aktivního technického účtu; heslo ani token se nevyplňují (`Password=`, `Token=` prázdné).
        `download=1` přidá `Content-Disposition: attachment; filename="erpapi.ini"`. Auditováno.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: integration_id, in: query, required: false, schema: { type: string, format: uuid } }
        - { name: download, in: query, required: false, schema: { type: string, enum: ['0', '1'] } }
      responses:
        '200':
          description: INI (text)
          content:
            text/plain:
              schema: { type: string }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ PROVIDER INFO (informace o poštářích, ADR 016)
  /providers/info:
    get:
      tags: [Connections]
      operationId: listProviderInfo
      summary: Informace o poštářích (přehled, schopnosti, retence, nápověda „?“, loga)
      description: |
        Strukturovaný obsah „Poštáři“ (poslední publikovaná verze) pro všechny moduly, zprostředkovatele pod Vertecem a informační záznamy poštářů bez modulu, plus texty
        nápovědy „?“ (`help`, SK/CZ/EN) a příznak `logos_enabled`. **Ceny a obchodní podmínky provozovatele (`pricing`, `commercial_terms`) vrací JEN role admin** – filtrování je
        na serveru (whitelist `toPublicProviderInfo`), tenant je nikdy nedostane. U každé informace je příznak jistoty (`certain` | `uncertain` | `unknown`), zdroj a datum ověření.
        Dostupné každému přihlášenému uživateli (cookie session).
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /providers/{type}/info:
    get:
      tags: [Connections]
      operationId: getProviderInfo
      summary: Informace o jednom poštáři (pro tenanta bez cen a obchodních podmínek)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfo' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /provider-assets/{sha256}:
    get:
      tags: [Connections]
      operationId: getProviderAsset
      summary: Logo poštáře (lokální asset adresovaný SHA-256; SVG sanitizované)
      description: |
        Vrací obrázek s `Content-Type` (`image/svg+xml` | `image/png` | `image/webp`), `nosniff`, `Content-Security-Policy: default-src 'none'` a neměnnou cache (obsah je adresovaný hashem).
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: sha256, in: path, required: true, schema: { type: string, pattern: '^[0-9a-f]{64}$' } }
      responses:
        '200':
          description: Obrázek
          content:
            image/svg+xml: { schema: { type: string, format: binary } }
            image/png: { schema: { type: string, format: binary } }
            image/webp: { schema: { type: string, format: binary } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info:
    get:
      tags: [Admin]
      operationId: adminListProviderInfo
      summary: Správa obsahu poštářů – přehled záznamů, JSON Schema editoru, stav AI aktualizace
      description: Jen role admin. `json_schema` (poštář) a `help_json_schema` (nápověda) slouží k vygenerování formuláře editoru.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminProviderInfoList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/ai-status:
    get:
      tags: [Admin]
      operationId: adminProviderInfoAiStatus
      summary: 'Stav AI aktualizace obsahu (Ollama): ready | disabled | not_configured | unavailable | model_missing'
      description: Vždy 200. „Ollama nedostupná“ není chyba aplikace. Při `enabled=false` se Ollama nevolá.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AiStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/refresh:
    post:
      tags: [Admin]
      operationId: adminProviderInfoRefresh
      summary: Zkontrolovat aktuálnost obsahu nyní (zařadí běh AI aktualizace; provede ho worker)
      description: |
        Zařadí běh (`202`, stav `queued`). Bez zapnuté AI (`ai_refresher.enabled`) vrací `409 AI_REFRESH_DISABLED`. Nedostupnost Ollamy se projeví
        až ve výsledku běhu (`unavailable`). V jednom okamžiku běží nejvýše jeden běh (`409 CONFLICT`).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderInfoRefreshRequest' }
      responses:
        '202':
          description: Běh zařazen
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/runs:
    get:
      tags: [Admin]
      operationId: adminListProviderInfoRuns
      summary: Log běhů AI aktualizace (co se četlo, co se změnilo, doba, model)
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/Limit' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoRunList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info-runs/{runId}:
    get:
      tags: [Admin]
      operationId: adminGetProviderInfoRun
      summary: Detail běhu AI aktualizace
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: runId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/patches:
    post:
      tags: [Admin]
      operationId: adminProviderInfoPatch
      summary: Patch polí obsahu se zdrojem (ověřený stejným postupem jako AI aktualizace)
      description: |
        Každá operace nese JSON pointer pole, novou hodnotu, URL zdroje (jen z allowlistu oficiálních domén poštáře) a doslovnou citaci. Server zdroj stáhne, ověří, že citace je ve zdroji
        a že číslo je v citaci. Neověřené operace se odmítnou (`rejected`), ostatní se aplikují jako nová verze `created_by_kind=ai` (nebo `pending_review` při `require_review`).
        Pointery smí mířit jen na pole uvedená v `ai_refresh.targets` poštáře (nikdy credentials, kód ani konfigurace spojení).
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderInfoPatchRequest' }
      responses:
        '200':
          description: Výsledek
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoPatchResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/export:
    get:
      tags: [Admin]
      operationId: adminExportProviderInfo
      summary: Export všech záznamů jako soubor (manifest + provider-info/<provider_type>.json)
      description: Export je jen admin a obsahuje plný obsah včetně cen (je to datový soubor zdroje pravdy). Tenant k němu nemá přístup.
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoExportBundle' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/import:
    post:
      tags: [Admin]
      operationId: adminImportProviderInfo
      summary: Import souboru obsahu (každý záznam jako nová verze `created_by_kind=import`; nevalidní se odmítne)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderInfoImportRequest' }
      responses:
        '200':
          description: Výsledek po záznamech
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoImportResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/assets:
    post:
      tags: [Admin]
      operationId: adminUploadProviderAsset
      summary: Nahrání loga (SVG se sanitizuje, PNG/WebP se kontroluje; limit 200 kB; ukládá se s SHA-256)
      description: Skript, externí odkaz, `foreignObject`, nepovolený typ, příliš velký soubor nebo nekonzistentní rozměry = `422 INVALID_ASSET`. Samotné nahrání nemění obsah poštáře – hash se použije v `logo` při `PUT`.
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderAssetUpload' }
      responses:
        '201':
          description: Uloženo
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderAsset' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/{type}:
    get:
      tags: [Admin]
      operationId: adminGetProviderInfo
      summary: Plný obsah záznamu (vč. cen a obchodních podmínek) + nepotvrzené změny od AI
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminProviderInfo' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Admin]
      operationId: adminPutProviderInfo
      summary: Uložení obsahu = nová verze (`human`); validace schématem, optimistický zámek `expected_version`
      description: Verze se nikdy nepřepisují (append-only). `verify=true` = potvrzení AI změn bez úpravy obsahu (nová lidská verze se stejným obsahem). Chyby schématu `422 INVALID_PROVIDER_INFO` s `errors[]`. Neexistující `type` vytvoří nový informační záznam.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderInfoPut' }
      responses:
        '200':
          description: Uloženo (nová verze)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminProviderInfo' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/{type}/export:
    get:
      tags: [Admin]
      operationId: adminExportProviderInfoOne
      summary: Export jednoho záznamu (obsah poslední publikované verze)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      responses:
        '200':
          description: JSON obsah záznamu (`provider-info/<type>.json`)
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/{type}/versions:
    get:
      tags: [Admin]
      operationId: adminListProviderInfoVersions
      summary: Historie verzí záznamu (nejnovější první; bez obsahu)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoVersionList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/{type}/versions/{version}:
    get:
      tags: [Admin]
      operationId: adminGetProviderInfoVersion
      summary: Obsah jedné verze (pro diff a vrácení)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
        - { name: version, in: path, required: true, schema: { type: integer, minimum: 1 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProviderInfoVersionDetail' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/provider-info/{type}/revert:
    post:
      tags: [Admin]
      operationId: adminRevertProviderInfo
      summary: Vrácení = NOVÁ verze s obsahem zvolené verze (publikuje i verzi `pending_review`)
      description: Verze, které vrácení přepsalo a které vznikly automaticky (AI), se označí `reverted`. Nic se nemaže.
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: type, in: path, required: true, schema: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProviderInfoRevert' }
      responses:
        '200':
          description: Nová verze
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AdminProviderInfo' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /admin/backups/status:
    get:
      tags: [Backups]
      operationId: adminGetBackupStatus
      summary: 'Stav zálohování (engine, poslední úspěšná záloha, další běh, kritický stav, upozornění)'
      description: 'Vždy `200`: když engine neběží / není inicializovaný, je `engine.state` `unavailable` | `not_initialized` | `unauthorized` | `error` a `state` = `unknown` (ne 5xx). `state` = `critical`, když je poslední úspěšná záloha starší než `stale_after_hours` (nastavení `backup_notifications`) nebo engine hlásí zastaralost. Jen role admin.'
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destination-types:
    get:
      tags: [Backups]
      operationId: adminListBackupDestinationTypes
      summary: 'Schéma formuláře cílů (NAS + protokol, OneDrive, Google Drive, S3, WebDAV, SFTP, SMB, rsync, lokální)'
      description: 'Průchod `GET /v1/destination-types` enginu (snake_case). UI z něj generuje formulář „Přidat cíl“. Pole `secret: true` jsou write-only. Engine nedostupný = `503 BACKUP_ENGINE_UNAVAILABLE`.'
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationTypeList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations:
    get:
      tags: [Backups]
      operationId: adminListBackupDestinations
      summary: 'Seznam cílů záloh (bez tajemství)'
      description: 'Tajná pole jen jako `credentials_set`.'
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Backups]
      operationId: adminCreateBackupDestination
      summary: 'Přidat cíl záloh'
      description: 'Validace zod + schématem typu z enginu; SSRF kontrola `host`/`url`/`endpoint` (bez link-local a metadata adres, v přísném profilu i bez loopbacku). Tajná pole jen v `secrets` (write-only, nikdy se nevrací ani neauditují). Vytvoření se audituje (`backup.destination.create`, jen metadata). `409` = cíl už existuje, `422` = neplatné parametry.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupDestinationCreate' }
      responses:
        '201':
          description: Vytvořeno
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationSaved' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}:
    patch:
      tags: [Backups]
      operationId: adminUpdateBackupDestination
      summary: 'Změnit / deaktivovat cíl (`enabled: false`) nebo vymazat tajné pole (`clear_secrets`)'
      description: 'Vynechané tajné pole = beze změny. Deaktivace nikdy nemaže zálohy na cíli. Audit `backup.destination.update`.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupDestinationUpdate' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationSaved' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Backups]
      operationId: adminRemoveBackupDestination
      summary: 'Zrušit cíl (odstraní jen konfiguraci cíle v enginu; ZÁLOHY NA CÍLI ZŮSTÁVAJÍ)'
      description: 'Vyžaduje `?confirm=<id>`. Nemaže žádná data ani zálohy; zmizí jen uložené přihlašovací údaje (a OAuth token) cíle. Audit `backup.destination.remove`. Raději použijte deaktivaci (`PATCH enabled=false`).'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
        - { name: confirm, in: query, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' }, description: Musí se rovnat id cíle }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationRemoved' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}/test:
    post:
      tags: [Backups]
      operationId: adminTestBackupDestination
      summary: 'Test spojení + test zápisu/čtení (zápis, výpis, čtení, smazání zkušebního souboru)'
      description: 'Vždy `200` s výsledkem (`ok` true/false; chyba bez tajemství). Přísnější rate limit. Audit `backup.destination.test`.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupTestResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}/backups:
    get:
      tags: [Backups]
      operationId: adminListBackupDestinationBackups
      summary: 'Zálohy nalezené na cíli (jen kompletní)'
      description: 'Průchod `GET /v1/destinations/{id}/backups`.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupBackupList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}/oauth/start:
    post:
      tags: [Backups]
      operationId: adminStartBackupOAuth
      summary: 'OAuth device code: zahájení (OneDrive / Google Drive)'
      description: 'Vrací `user_code` a `verification_uri` k zobrazení správci (otevře odkaz na svém zařízení a zadá kód). Průběh sleduje `GET .../oauth/status`. Jen OneDrive a Google Drive (kromě služebního účtu) – jinak `422`. Audit `backup.oauth.start`. Reálné účty se nezakládají; testováno proti fake OAuth.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupOAuthSession' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}/oauth/status:
    get:
      tags: [Backups]
      operationId: adminGetBackupOAuthStatus
      summary: 'OAuth device code: stav (`pending` | `authorized` | `expired` | `error` | `none`)'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupOAuthSession' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/destinations/{id}/oauth/revoke:
    post:
      tags: [Backups]
      operationId: adminRevokeBackupOAuth
      summary: 'Zrušit oprávnění (smaže uložený OAuth token v enginu)'
      description: 'Smaže token z konfigurace enginu; oprávnění aplikace je nutné zrušit i v účtu Microsoft / Google (viz docs/INSTALL.md). Zálohy na cíli zůstávají. Audit `backup.oauth.revoke`.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupDestinationSaved' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/run:
    post:
      tags: [Backups]
      operationId: adminRunBackup
      summary: 'Zálohovat nyní'
      description: 'Zařadí ruční běh (`202`); průběh v `GET /admin/backups/runs` a `status`. Engine zaneprázdněn = `409 CONFLICT`. Rate limit 6/min. Audit `backup.run`.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupRunRequest' }
      responses:
        '202':
          description: Přijato
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/runs:
    get:
      tags: [Backups]
      operationId: adminListBackupRuns
      summary: 'Historie běhů záloh a zkušebních obnov'
      description: 'Nejnovější první; `limit` 1–200 (výchozí 50).'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupRunList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/runs/{runId}:
    get:
      tags: [Backups]
      operationId: adminGetBackupRun
      summary: 'Detail běhu (metadata manifestu: počty, SHA-256, výsledky cílů)'
      description: 'Slouží i ke stažení metadat manifestu. Šifrovaný manifest na cíli se otevírá offline klíčem správce.'
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: runId, in: path, required: true, schema: { type: string, pattern: '^run-[a-z0-9]{3,20}$' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/verify:
    post:
      tags: [Backups]
      operationId: adminVerifyBackup
      summary: 'Lehká kontrola integrity zálohy (stažení, SHA-256, dešifrování) bez obnovy do DB'
      description: 'Synchronní výsledek. Úplnou kontrolu s obnovou do dočasné DB dělá `POST /admin/backups/restore-test`. Audit `backup.verify`.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupVerifyRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupIntegrityResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/restore-test:
    post:
      tags: [Backups]
      operationId: adminRestoreTest
      summary: 'Zkušební restore nyní (do dočasné DB v odděleném kontejneru; porovná počty a hashe)'
      description: 'Asynchronní (`202`); výsledek v `GET /admin/backups/runs` (`verifications`). Nikdy se neobnovuje do provozní DB. Audit `backup.restore_test`. Rate limit 4/min.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupVerifyRequest' }
      responses:
        '202':
          description: Přijato
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/policy:
    get:
      tags: [Backups]
      operationId: adminGetBackupPolicy
      summary: 'Politika: plán (cron UTC), retence GFS, ověřování, XML archiv, zastaralost'
      description: 'Roční zálohy a archiv XML se uchovávají nejméně 10 let (výchozí `yearly_years: 10`); `warnings` obsahuje trvalá varování.'
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupPolicy' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Backups]
      operationId: adminPutBackupPolicy
      summary: 'Změna politiky (částečná aktualizace)'
      description: 'Retence ročních záloh nebo archivu XML kratší než 10 let se odmítne `422 RETENTION_BELOW_LEGAL_MINIMUM`, dokud není výslovně potvrzena (`retention.confirm_short_yearly` / `xml.confirm_short_retention`); potvrzená kratší retence trvale varuje (`warnings`). Poslední úspěšná a poslední ověřená záloha se nikdy nemaže. Audit `backup.policy.update`.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupPolicyUpdate' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupPolicySaved' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/backups/kit:
    post:
      tags: [Backups]
      operationId: adminBackupKit
      summary: 'Recovery kit: vytvořit (režim age) / nahrát na cíle – POUZE ŘÍZENÍ'
      description: 'Soukromý klíč ani heslo kitu přes API nikdy neputuje; odpověď nese jen metadata. Kit z API neobsahuje tajemství hostitele (`APP_MASTER_KEY`…): úplný kit sestaví `infra/scripts/backup-kit` (RUNBOOK „Správa recovery kitu“; kit uchovává ITgastro s.r.o.). Audit `backup.kit`.'
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupKitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupKitResult' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502': { $ref: '#/components/responses/BadGateway' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /internal/backups/notifications:
    post:
      tags: [Backups]
      operationId: receiveBackupEngineNotification
      summary: Notifikační webhook enginu záloh (platformní události -> notification_outbox)
      description: |
        **Bez uživatelské session.** Volá ho jen engine `efakt-backup` v interní síti (`Authorization: Bearer <backup_webhook_token>`, porovnání v konstantním čase; bez nastaveného
        tokenu na serveru `404`). Události `backup.failed`, `backup.stale`, `verify.failed` se převedou na platformní upozornění `backup.failed`, `backup.stale`, `backup.restore_test_failed`
        (příjemci = adresy správců ze `system_settings`; bez SMTP `suppressed` + viditelný stav) a deduplikují se (běh/cíl). `recovery` a `test` se jen zaznamenají (`ignored`).
        Respektuje nastavení `backup_notifications` (zapnutí, typy). Reverzní proxy tuto cestu nepublikuje. Rate limit na IP.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackupEngineNotification' }
      responses:
        '200':
          description: Přijato (engine pak považuje událost za předanou)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackupEngineNotificationAck' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # ------------------------------------------------------------------ FORWARDING (přeposílání faktur e-mailem, ADR 037)
  /forwarding/settings:
    get:
      tags: [Forwarding]
      operationId: getForwardingSettings
      summary: Účinné nastavení přeposílání pro aktivní tenant + stav fronty
      description: "Vyžaduje oprávnění forwarding.view, forwarding.send nebo forwarding.manage (uděluje platformní admin) a cookie session."
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardSettingsInfo' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/rules:
    get:
      tags: [Forwarding]
      operationId: listForwardRules
      summary: Pravidla přeposílání
      description: "Vyžaduje oprávnění forwarding.view nebo forwarding.manage (uděluje platformní admin) a cookie session."
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRuleList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Forwarding]
      operationId: createForwardRule
      summary: Založení pravidla přeposílání
      description: "Vyžaduje oprávnění forwarding.manage (bez omezení rozsahu) (uděluje platformní admin) a cookie session. Obsah musí splňovat politiku admina (FORWARDING_NOT_ALLOWED)."
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardRuleCreate' }
      responses:
        '201':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRule' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /forwarding/rules/{ruleId}:
    get:
      tags: [Forwarding]
      operationId: getForwardRule
      summary: Detail pravidla
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: ruleId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRule' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    patch:
      tags: [Forwarding]
      operationId: updateForwardRule
      summary: Změna pravidla
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: ruleId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardRuleUpdate' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRule' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
    delete:
      tags: [Forwarding]
      operationId: archiveForwardRule
      summary: Archivace pravidla (data se nemažou)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: ruleId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '204': { description: "OK bez obsahu" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/rules/{ruleId}/test:
    post:
      tags: [Forwarding]
      operationId: testForwardRule
      summary: Zkušební zpráva ověřeným příjemcům pravidla
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: ruleId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRuleTestResult' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/recipients:
    get:
      tags: [Forwarding]
      operationId: listForwardRecipients
      summary: Příjemci a stav ověření adresy
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRecipientList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Forwarding]
      operationId: createForwardRecipient
      summary: Přidání příjemce (odešle se potvrzovací e-mail – double opt-in)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardRecipientCreate' }
      responses:
        '201':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRecipient' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /forwarding/recipients/{recipientId}:
    delete:
      tags: [Forwarding]
      operationId: revokeForwardRecipient
      summary: Zrušení příjemce (zneplatní odkazy a čekající doručení)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: recipientId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRecipient' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/recipients/{recipientId}/resend-confirmation:
    post:
      tags: [Forwarding]
      operationId: resendForwardConfirmation
      summary: Znovu odeslat potvrzení adresy
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: recipientId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRecipient' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/recipients/{recipientId}/reset-credentials:
    post:
      tags: [Forwarding]
      operationId: resetForwardRecipientCredentials
      summary: Poslat příjemci nastavení nových přístupových údajů
      description: "Vyžaduje forwarding.manage. Příjemci se pošle potvrzovací e-mail, na jehož stránce si zvolí nové heslo (případně TOTP); staré údaje platí, dokud nastavení nedokončí. Heslo se nikdy neposílá e-mailem. Správcovský reset nevyžaduje důkaz druhého faktoru."
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: recipientId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardRecipient' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/deliveries:
    get:
      tags: [Forwarding]
      operationId: listForwardDeliveries
      summary: Historie přeposlání (doručení)
      description: "Vyžaduje oprávnění forwarding.view (uděluje platformní admin) a cookie session."
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
        - { name: status, in: query, schema: { type: string, enum: [queued, sent, failed, suppressed, bounced, cancelled] } }
        - { name: kind, in: query, schema: { type: string, enum: [invoice, password, optin, digest, sample] } }
        - { name: rule_id, in: query, schema: { type: string, format: uuid } }
        - { name: recipient_id, in: query, schema: { type: string, format: uuid } }
        - { name: invoice_id, in: query, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardDeliveryPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/deliveries/{deliveryId}/retry:
    post:
      tags: [Forwarding]
      operationId: retryForwardDelivery
      summary: Opakování neúspěšného / potlačeného doručení
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: deliveryId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardDelivery' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/forward:
    post:
      tags: [Forwarding]
      operationId: forwardInvoice
      summary: Jednorázové přeposlání faktury ověřenému příjemci
      description: "Vyžaduje oprávnění forwarding.send (uděluje platformní admin) a cookie session. Příjemce musí mít potvrzenou adresu; směr faktury a režim obsahu musí admin povolit."
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardManualRequest' }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /invoices/{invoiceId}/share-links:
    get:
      tags: [Forwarding]
      operationId: listInvoiceShareLinks
      summary: Sdílené odkazy faktury
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedLinkPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /invoices/{invoiceId}/share-links/{linkId}:
    delete:
      tags: [Forwarding]
      operationId: revokeInvoiceShareLink
      summary: Zneplatnění sdíleného odkazu
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/InvoiceId' }
        - { name: linkId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SharedLinkRevoke' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedLink' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /forwarding/links:
    get:
      tags: [Forwarding]
      operationId: listShareLinks
      summary: Přehled sdílených odkazů tenanta
      security: [{ cookieAuth: [] }]
      parameters:
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
        - { name: invoice_id, in: query, schema: { type: string, format: uuid } }
        - { name: state, in: query, schema: { type: string, enum: [active, expired, revoked, exhausted, locked] } }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedLinkPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/links/{linkId}:
    delete:
      tags: [Forwarding]
      operationId: revokeShareLink
      summary: Zneplatnění sdíleného odkazu
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: linkId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SharedLinkRevoke' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedLink' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /forwarding/links/{linkId}/reset-password:
    post:
      tags: [Forwarding]
      operationId: resetShareLinkPassword
      summary: Nové heslo odkazu (odešle se samostatným e-mailem)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: linkId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '202':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/links/{linkId}/access-log:
    get:
      tags: [Forwarding]
      operationId: listShareLinkAccessLog
      summary: Protokol přístupů k odkazu (append-only, IP jen jako zkrácený HMAC)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: linkId, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/Limit' }
        - { $ref: '#/components/parameters/Cursor' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedLinkAccessPage' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/grants:
    get:
      tags: [Forwarding]
      operationId: listForwardGrants
      summary: Udělená oprávnění přeposílání (jen admin)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardGrantList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Forwarding]
      operationId: setForwardGrant
      summary: Udělení / změna oprávnění per člen nebo role (jen admin)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardGrantUpsert' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardGrant' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /forwarding/grants/{grantId}:
    delete:
      tags: [Forwarding]
      operationId: revokeForwardGrant
      summary: Odebrání oprávnění (jen admin)
      security: [{ cookieAuth: [] }]
      parameters:
        - { name: grantId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '204': { description: "OK bez obsahu" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/tenant-settings:
    get:
      tags: [Forwarding]
      operationId: getForwardTenantSettings
      summary: Nastavení přeposílání aktivního tenanta (jen admin; zužuje systémové)
      security: [{ cookieAuth: [] }]
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardTenantSettings' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Forwarding]
      operationId: putForwardTenantSettings
      summary: Uložení nastavení přeposílání tenanta (jen admin)
      security: [{ cookieAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ForwardTenantSettingsUpdate' }
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ForwardTenantSettings' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '422': { $ref: '#/components/responses/Unprocessable' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
  /shared/{token}:
    get:
      tags: [Forwarding]
      operationId: getSharedInvoicePage
      summary: Sdílená kopie faktury (HTML)
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). Neexistující token vrací stejnou stránku jako formulář hesla (ochrana proti enumeraci)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      responses:
        '200':
          description: "Formulář hesla nebo vizualizace faktury"
          content:
            text/html: { schema: { type: string } }
        '404':
          description: "Odkaz bez hesla není platný"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /shared/{token}/unlock:
    post:
      tags: [Forwarding]
      operationId: unlockSharedInvoice
      summary: Zadání hesla ke sdílené kopii
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). Odkaz s přístupem zvoleným příjemcem vyžaduje jeho heslo a případně 6místný kód TOTP (nebo záložní kód). Po 5 chybách během 15 minut se odkaz i přístupové údaje na 15 minut zamknou; chyba je vždy stejná (neexistující / uzamčený / chybné údaje)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema: { type: object, properties: { password: { type: string, maxLength: 400 }, code: { type: string, maxLength: 12 }, recovery: { type: string, maxLength: 24 } } }
      responses:
        '303': { description: 'Heslo správné: nastaví se krátká cookie a přesměruje na stránku odkazu' }
        '401':
          description: "Ověření selhalo nebo odkaz není platný"
          content:
            text/html: { schema: { type: string } }
        '410':
          description: "Heslo správné, ale odkaz vypršel / byl zneplatněn / vyčerpán"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /shared/{token}/reset:
    post:
      tags: [Forwarding]
      operationId: resetSharedInvoiceAccess
      summary: Žádost o obnovení přístupu k odkazu (zapomenuté heslo)
      description: "Veřejná stránka (bez session, bez JavaScriptu). Odpověď je VŽDY stejná (neexistující / neplatný odkaz, jiný režim, příliš časté žádosti): je-li odkaz platný a patří k přístupu zvolenému příjemcem, odešle se na adresu příjemce potvrzovací zpráva s nastavením nového přístupu (heslo se e-mailem neposílá). U přístupu s TOTP vyžaduje následné nastavení důkaz druhého faktoru."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      responses:
        '200':
          description: "Konstantní potvrzení"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /shared/{token}/view:
    get:
      tags: [Forwarding]
      operationId: getSharedInvoiceView
      summary: Vizualizace faktury pro sandbox iframe (spotřebuje jedno zobrazení)
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). "
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      responses:
        '200':
          description: "HTML vizualizace (CSP default-src none)"
          content:
            text/html: { schema: { type: string } }
        '404':
          description: "Odkaz není platný / nemáte oprávnění"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /shared/{token}/download/{kind}:
    get:
      tags: [Forwarding]
      operationId: downloadSharedInvoice
      summary: Stažení XML / HTML / PDF (spotřebuje jedno zobrazení)
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). XML je přesně archivovaný originál (SHA-256 v hlavičce X-Content-SHA256-XML)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
        - { name: kind, in: path, required: true, schema: { type: string, enum: [xml, html, pdf] } }
      responses:
        '200':
          description: Soubor
          content:
            application/xml: { schema: { type: string, format: binary } }
            text/html: { schema: { type: string } }
            application/pdf: { schema: { type: string, format: binary } }
        '404':
          description: "Odkaz není platný / nemáte oprávnění"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /forwarding/confirm/{token}:
    get:
      tags: [Forwarding]
      operationId: getForwardConfirmPage
      summary: Potvrzení adresy příjemce – stránka s tlačítkem
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). GET nic nemění (e-mailové skenery odkazy otevírají)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      responses:
        '200':
          description: "Stránka s tlačítkem"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Forwarding]
      operationId: postForwardConfirm
      summary: Potvrzení adresy příjemce
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). Token je jednorázový s expirací. Je-li povolen způsob hesla `recipient` (výchozí), příjemce na stránce zvolí VLASTNÍ heslo (min. délka, kontrola slabých hesel, Argon2id) a volitelně TOTP (QR vložené jako SVG, záložní kódy se zobrazí jednou); heslo se nikdy neposílá e-mailem. Postup: krok `start` (auth, password, password2; u resetu přístupu s TOTP i proof_code / proof_recovery) a případně krok `totp` (code). Reset přístupu = nové potvrzení adresy."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema: { type: object, properties: { 'List-Unsubscribe': { type: string }, step: { type: string, enum: [start, totp] }, auth: { type: string, enum: [password, password_totp, totp] }, password: { type: string, maxLength: 400 }, password2: { type: string, maxLength: 400 }, code: { type: string, maxLength: 12 }, proof_code: { type: string, maxLength: 12 }, proof_recovery: { type: string, maxLength: 24 } } }
      responses:
        '200':
          description: "Hotovo, případně další krok (QR kód TOTP)"
          content:
            text/html: { schema: { type: string } }
        '422':
          description: "Heslo nevyhovuje politice / hesla se neshodují / chybný kód (formulář se zobrazí znovu s chybou)"
          content:
            text/html: { schema: { type: string } }
        '410':
          description: "Odkaz není platný nebo vypršel"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /forwarding/unsubscribe/{token}:
    get:
      tags: [Forwarding]
      operationId: getForwardUnsubscribePage
      summary: Odhlášení z přeposílání – stránka s tlačítkem
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). GET nic nemění (e-mailové skenery odkazy otevírají)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      responses:
        '200':
          description: "Stránka s tlačítkem"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Forwarding]
      operationId: postForwardUnsubscribe
      summary: Odhlášení z přeposílání
      description: "Veřejná stránka (bez session, bez JavaScriptu, přísná CSP, no-store, noindex). Podporuje i RFC 8058 one-click (List-Unsubscribe=One-Click)."
      security: []
      parameters:
        - { name: token, in: path, required: true, schema: { type: string, maxLength: 500 } }
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema: { type: object, properties: { 'List-Unsubscribe': { type: string } } }
      responses:
        '200':
          description: "Hotovo"
          content:
            text/html: { schema: { type: string } }
        '410':
          description: "Odkaz není platný nebo vypršel"
          content:
            text/html: { schema: { type: string } }
        '429':
          description: "Rate limit"
          content:
            text/html: { schema: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }

  # ------------------------------------------------------------------ SANDBOX (veřejný vývojářský sandbox, ADR 040)
  /public/sandbox/config:
    get:
      tags: [Sandbox]
      operationId: getPublicSandboxConfig
      summary: Veřejná konfigurace samoobslužné registrace sandboxu
      description: "Bez autentizace. Na serveru bez povolené registrace `404 SANDBOX_REGISTRATION_DISABLED`. Vrací poskytovatele CAPTCHA (výchozí `none` = bez třetí strany; volitelně `turnstile` s veřejným `site_key`; `fake` jen vývoj/test), token ochrany formuláře (`challenge`, ADR 045), verzi podmínek, výchozí kvóty a lhůtu neaktivity."
      security: []
      responses:
        '200':
          description: Konfigurace
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxPublicConfig' } }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /public/sandbox/registrations:
    post:
      tags: [Sandbox]
      operationId: registerSandbox
      summary: Žádost o sandbox vývojáře (krok 1 double opt-in)
      description: |
        Veřejné, bez autentizace. Ověří ochranu formuláře (honeypot, časová past, volitelný proof-of-work; případně volitelnou CAPTCHA), souhlas s podmínkami, doménu e-mailu (blokace jednorázových domén), limity per IP a per e-mail a odešle ověřovací odkaz na zadanou adresu (jediná adresa, na kterou sandbox kdy posílá).
        Odpověď je VŽDY stejná `202` (nelze zjistit, zda e-mail existuje). Sandbox vznikne až po ověření odkazem (`POST /public/sandbox/verify`).
      security: []
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxRegistrationRequest' } }
      responses:
        '202':
          description: Ověřovací e-mail byl (případně) odeslán
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistrationAccepted' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422':
          description: 'Doména e-mailu není povolena (EMAIL_DOMAIN_NOT_ALLOWED)'
          content:
            application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /public/sandbox/verify:
    post:
      tags: [Sandbox]
      operationId: verifySandbox
      summary: Ověření e-mailu a vznik sandbox tenanta (krok 2 double opt-in)
      description: |
        Jednorázový token z e-mailu. Vytvoří izolovaný sandbox tenant (příznak `sandbox`, `X-Environment: sandbox`), uživatele, spojení na mock-hub, API klíč a ERP integraci šablony `developer` (`test_only`).
        Přihlašovací údaje a klíče jsou v odpovědi JEDINOU příležitostí (`Cache-Control: no-store`); opakované použití tokenu = `410 SANDBOX_VERIFY_INVALID`.
      security: []
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxVerifyRequest' } }
      responses:
        '201':
          description: Sandbox vytvořen
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxProvisioned' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '410':
          description: 'Odkaz je neplatný, vypršel nebo byl použit (SANDBOX_VERIFY_INVALID)'
          content:
            application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /sandbox/usage:
    get:
      tags: [Sandbox]
      operationId: getSandboxUsage
      summary: Kvóty a využití vlastního sandboxu
      description: "Cookie session i API klíč. U tenanta, který není samoobslužný sandbox, vrací `sandbox=false` a prázdné kvóty."
      responses:
        '200':
          description: Kvóty a využití
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxUsage' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/sandboxes:
    get:
      tags: [Admin, Sandbox]
      operationId: adminListSandboxes
      summary: Seznam sandboxů vývojářů (jen admin)
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/SandboxStatus' } }
        - { name: search, in: query, schema: { type: string, maxLength: 100 } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        '200':
          description: Stránka
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistrationList' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '409': { $ref: '#/components/responses/Conflict' }
  /admin/sandboxes/expire-inactive:
    post:
      tags: [Admin, Sandbox]
      operationId: adminExpireInactiveSandboxes
      summary: Vypršení neaktivních sandboxů (ručně / z plánovače)
      description: "Zablokuje (tenant `suspended`, uživatel `disabled`) sandboxy bez aktivity delší než lhůta. DATA SE NEMAŽOU. `dry_run=true` jen vypíše."
      requestBody:
        required: false
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxExpireRequest' } }
      responses:
        '200':
          description: Výsledek
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxExpireResult' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '409': { $ref: '#/components/responses/Conflict' }
  /admin/sandboxes/{sandboxId}:
    get:
      tags: [Admin, Sandbox]
      operationId: adminGetSandbox
      summary: Detail sandboxu
      parameters:
        - { name: sandboxId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Sandbox
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistration' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '409': { $ref: '#/components/responses/Conflict' }
  /admin/sandboxes/{sandboxId}/block:
    post:
      tags: [Admin, Sandbox]
      operationId: adminBlockSandbox
      summary: Zablokovat sandbox (tenant suspended, uživatel disabled; data zůstávají)
      parameters:
        - { name: sandboxId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxBlockRequest' } }
      responses:
        '200':
          description: Sandbox
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistration' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '409': { $ref: '#/components/responses/Conflict' }
  /admin/sandboxes/{sandboxId}/unblock:
    post:
      tags: [Admin, Sandbox]
      operationId: adminUnblockSandbox
      summary: Odblokovat sandbox (obnoví tenanta i uživatele, prodlouží lhůtu)
      parameters:
        - { name: sandboxId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Sandbox
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistration' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /admin/sandboxes/{sandboxId}/extend:
    post:
      tags: [Admin, Sandbox]
      operationId: adminExtendSandbox
      summary: Prodloužit sandbox (nevyprší dříve než za N dní)
      parameters:
        - { name: sandboxId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxExtendRequest' } }
      responses:
        '200':
          description: Sandbox
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistration' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
  /admin/sandboxes/{sandboxId}/quotas:
    put:
      tags: [Admin, Sandbox]
      operationId: adminSetSandboxQuotas
      summary: Přepis kvót a lhůty neaktivity (null = výchozí)
      parameters:
        - { name: sandboxId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: '#/components/schemas/SandboxQuotasUpdate' } }
      responses:
        '200':
          description: Sandbox
          content:
            application/json: { schema: { $ref: '#/components/schemas/SandboxRegistration' } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '409': { $ref: '#/components/responses/Conflict' }

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: efakt_session
      description: Session cookie uživatele. Unsafe metody vyžadují `X-CSRF-Token` = hodnota cookie `efakt_csrf`.
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: efk_*
      description: 'API klíč tenanta: `Authorization: Bearer efk_<prefix>_<secret>`.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternativa k Bearer pro systémy, které neumí Authorization.
    erpBearer:
      type: http
      scheme: bearer
      bearerFormat: erp_*
      description: 'Token ERP integrace (`erp_<prefix>_<secret>`, ≥ 256 bit) nebo krátkodobý token z `POST /erp/auth/token`. Jen pro `/erp/*`.'
    erpBasic:
      type: http
      scheme: basic
      description: 'HTTP Basic: jméno + heslo technického účtu ERP integrace (Argon2id, rate limit před hashem, zámek po chybách). Jen pro `/erp/*`; povinně HTTPS.'

  headers:
    RateLimitLimit: { description: Limit požadavků v okně, schema: { type: integer } }
    RateLimitRemaining: { description: Zbývající požadavky v okně, schema: { type: integer } }
    RateLimitReset: { description: Sekundy do resetu okna, schema: { type: integer } }
    XTestMode: { description: 'Vždy `true` u testovací odpovědi', schema: { type: string, enum: ['true'] } }
    XWouldHaveSent: { description: '`true`, pokud by ostré volání prošlo; `false` při blokujícím nálezu', schema: { type: string, enum: ['true', 'false'] } }
    RetryAfter: { description: "Sekundy, po kterých lze zkusit znovu", schema: { type: integer } }
    SetCookie: { description: 'Nastavuje `efakt_session` (HttpOnly) a `efakt_csrf` (čitelná JS)', schema: { type: string } }

  parameters:
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
    Cursor:
      name: cursor
      in: query
      description: Neprůhledný cursor z `next_cursor`. Neplatný => `400 INVALID_CURSOR`.
      schema: { type: string, maxLength: 2048 }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Klient generuje unikátní hodnotu (doporučeno UUID v4) pro každý logický pokus o odeslání. 1–255 znaků `[A-Za-z0-9._:-]`.
      schema: { type: string, minLength: 1, maxLength: 255, pattern: '^[A-Za-z0-9._:-]+$' }
    InvoiceId: { name: invoiceId, in: path, required: true, schema: { type: string, format: uuid } }
    TestQuery: { name: test, in: query, description: 'Testovací režim: provede se vše kromě odeslání (nic se neodešle ani neuloží). Hodnoty `true|false|1|0`, jiné = `400 INVALID_TEST_FLAG`. Totéž hlavička `X-Test-Mode` a pole `test` v JSON; při rozporu vyhrává `true`.', schema: { type: string, enum: ['true', 'false', '1', '0'] } }
    TestModeHeader: { name: X-Test-Mode, in: header, description: 'Viz parametr `test`.', schema: { type: string, enum: ['true', 'false', '1', '0'] } }
    SimulateQuery: { name: simulate, in: query, description: 'Jen s `test=true`: simulovaný výsledek (výchozí `delivered`).', schema: { $ref: '#/components/schemas/TestSimulate' } }
    SimulateWebhooksQuery: { name: simulate_webhooks, in: query, description: 'Jen s `test=true`: rozeslat webhookům tenanta testovací události (`test:true`, hlavička `X-Test: 1`). Výchozí vypnuto.', schema: { type: boolean } }
    ConnectionId: { name: connectionId, in: path, required: true, schema: { type: string, format: uuid } }
    WebhookId: { name: webhookId, in: path, required: true, schema: { type: string, format: uuid } }
    TenantId: { name: tenantId, in: path, required: true, schema: { type: string, format: uuid } }
    ErpIntegrationId: { name: integrationId, in: path, required: true, schema: { type: string, format: uuid } }
    UserId: { name: userId, in: path, required: true, schema: { type: string, format: uuid } }

  responses:
    BadRequest:
      description: Chybný požadavek. Validace těla, dotazu i cesty = vždy `400 BAD_REQUEST` s `errors[]` (ADR 005 bod 2); dále `INVALID_CURSOR`, `IDEMPOTENCY_KEY_REQUIRED`.
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    Unauthorized:
      description: Nepřihlášen / neplatný klíč (`UNAUTHENTICATED`, `INVALID_CREDENTIALS`, `TOTP_INVALID`, `API_KEY_INVALID`, ...)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    Forbidden:
      description: Nedostatečná práva (`FORBIDDEN`, `INSUFFICIENT_SCOPE`, `CSRF_FAILED`, `TENANT_SUSPENDED`)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    NotFound:
      description: Nenalezeno (včetně záznamů cizího tenanta)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    Conflict:
      description: Konflikt (`TENANT_REQUIRED` = není zvolen aktivní tenant, `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_IN_PROGRESS`, `DUPLICATE_INVOICE`, `CONFLICT`, `EMAIL_ALREADY_EXISTS`, `CONNECTION_DISABLED`, `EXPORT_NOT_READY`, ...)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    PayloadTooLarge:
      description: Tělo přesahuje limit (`PAYLOAD_TOO_LARGE`)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    UnsupportedMediaType:
      description: Nepodporovaný Content-Type (`UNSUPPORTED_MEDIA_TYPE`)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    Unprocessable:
      description: |
        Sémantická chyba (syntakticky správný požadavek, který nelze provést; validace tvaru je `400`). U faktur `findings` obsahuje konkrétní pravidla (např. `BR-O-02`, `BR-23`) a `code` je
        `VALIDATION_FAILED`, nebo specifický portálový kód (`SELLER_MISMATCH`, `ISSUE_DATE_NOT_TODAY`, ...).
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    TooManyRequests:
      description: Rate limit (`RATE_LIMITED`)
      headers:
        Retry-After: { $ref: '#/components/headers/RetryAfter' }
        RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
        RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
        RateLimit-Reset: { $ref: '#/components/headers/RateLimitReset' }
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    NotImplemented:
      description: Poštář funkci nenabízí (`LOOKUP_NOT_SUPPORTED`)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    BadGateway:
      description: Chyba poštáře (`PROVIDER_AUTH_FAILED`, `PROVIDER_UNAVAILABLE`, `PROVIDER_ERROR`)
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }
    ServiceUnavailable:
      description: Dočasně nedostupné (`VALIDATOR_UNAVAILABLE`, `SERVICE_UNAVAILABLE`); nic nebylo uloženo ani odesláno.
      headers:
        Retry-After: { $ref: '#/components/headers/RetryAfter' }
      content:
        application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } }

  schemas:
    # ---------------------------------------------------------------- enums / primitives
    Direction: { type: string, enum: [inbound, outbound] }
    InvoiceSource: { type: string, enum: [provider_poll, api_submit, manual_import] }
    OutboundStatus:
      type: string
      enum: [queued, validating, sending, sent, delivered, delivery_failed, rejected_by_provider, failed_permanent]
    InboundStatus:
      type: string
      description: received_without_xml = poštář předal jen metadata (XML > 4 MB, push payload:null); XML je nutné stáhnout u poštáře (`provider_portal_url`) a nahrát ručním importem.
      enum: [received, received_invalid, received_without_xml]
    InvoiceStatus:
      description: Sjednocení `OutboundStatus` a `InboundStatus`.
      oneOf:
        - { $ref: '#/components/schemas/OutboundStatus' }
        - { $ref: '#/components/schemas/InboundStatus' }
    ValidationStatus:
      type: string
      description: pending = ještě nevalidováno; valid; valid_with_warnings; invalid.
      enum: [pending, valid, valid_with_warnings, invalid]
    DocumentTypeCode:
      type: string
      description: |
        UNCL1001 – 380 faktura, 381 dobropis, 383 debet, 384 opravná, 388 faktura k přijaté platbě, 389 samofakturace, 393 factoring, 261 samofakturační dobropis.
        `unknown` = příchozí doklad, jehož typ nelze určit nebo ho portál nepodporuje (M-03; původní kód viz `unparsed_reason`).
        Odesílání: 384 se **nepřijímá** (Peppol BIS 3.0.20 ho odmítá pravidlem PEPPOL-EN16931-P0112) – použijte dobropis 381 + novou fakturu 380; 389/261 jen s `TenantSettings.allow_self_billing`.
      enum: ['380', '381', '383', '384', '388', '389', '393', '261', 'unknown']
    ProviderType:
      type: string
      pattern: '^[a-z][a-z0-9_]{1,62}$'
      description: |
        Stabilní id MODULU poštáře (např. `mock`, `ionite_epodatelna24`, `softip_digitalny_postar`). Není uzavřený enum: seznam
        platných hodnot vrací `GET /providers`; neznámý typ => `422 UNKNOWN_PROVIDER_TYPE` (ADR 009).
    Environment: { type: string, enum: [sandbox, production] }
    ConnectionHealth:
      type: string
      description: ok = poslední poll uspěl; never_synced = ještě neběžel; degraded = N selhání po sobě; error = poslední pokus selhal (pod prahem degraded) nebo AUTH_FAILED; disabled = vypnuto.
      enum: [ok, never_synced, degraded, error, disabled]
    Role: { type: string, enum: [admin, tenant_user, tenant_viewer] }
    TenantStatus: { type: string, enum: [active, suspended] }
    FindingSeverity: { type: string, enum: [error, warning, info] }
    FindingSource: { type: string, enum: [xsd, schematron_en16931, schematron_peppol, schematron_sk, portal, party, registry, routing, obligation, tdd_sk, provider_dryrun, external] }
    ApiKeyScope: { type: string, enum: ['invoices:read', 'invoices:send', 'participants:read', 'connections:read', 'webhooks:manage'] }
    WebhookEventType: { type: string, enum: [invoice.sent, invoice.delivered, invoice.delivery_failed, invoice.received, ping] }
    WebhookDeliveryStatus: { type: string, enum: [pending, succeeded, failed, dead] }
    JobStatus: { type: string, enum: [queued, running, succeeded, failed, dead] }
    JobType: { type: string, enum: [poll_connection, send_invoice, poll_delivery_status, deliver_webhook, build_export, validate_invoice, process_provider_webhook, registry_import, forward_invoice, revalidate_invoices] }
    ExportStatus: { type: string, enum: [queued, running, ready, failed, expired] }
    ExportFormat: { type: string, enum: [xml_zip, csv] }
    Permission:
      type: string
      description: |
        Oprávnění přihlášeného uživatele v aktivním tenantu (UI podle nich zobrazuje akce; autoritativní kontrola je vždy na serveru).
        `admin` = správce portálu (sekce Administrace).
      enum: ['invoices:read', 'invoices:send', 'invoices:import', 'invoices:export', 'connections:read', 'connections:test', 'api_keys:manage', 'webhooks:manage', 'participants:read', admin, 'forwarding.view', 'forwarding.send', 'forwarding.manage']
    ReceiveMode:
      type: string
      description: |
        Jak spojení přijímá příchozí doklady: `pull` = portál je periodicky stahuje (poller), `push` = poštář je posílá webhookem
        na `/provider-webhooks/...` (portál nestahuje), `none` = spojení příjem nenabízí (jen odesílání).
      enum: [pull, push, none]
    SessionKind:
      type: string
      description: '`full` = plně přihlášen; `enrollment` = omezená session po přihlášení, kdy politika vyžaduje zápis TOTP (povoleno jen `/auth/me`, `/auth/totp/enroll`, `/auth/totp/confirm`, `/auth/logout`).'
      enum: [full, enrollment]
    DeliveryEventType: { type: string, enum: [status_changed, provider_message, warning, retry_scheduled, note, forwarded] }
    DeliveryEventSource: { type: string, enum: [portal, worker, provider] }
    ErrorCode:
      type: string
      description: Katalog kódů chyb a varování (viz docs/CONTRACTS.md pro mapování na HTTP status).
      enum:
        - BAD_REQUEST
        - INVALID_CURSOR
        - UNAUTHENTICATED
        - INVALID_CREDENTIALS
        - TOTP_INVALID
        - SESSION_EXPIRED
        - API_KEY_INVALID
        - API_KEY_REVOKED
        - FORBIDDEN
        - INSUFFICIENT_SCOPE
        - CSRF_FAILED
        - TENANT_SUSPENDED
        - TENANT_REQUIRED
        - NOT_FOUND
        - CONFLICT
        - INBOUND_CONNECTION_EXISTS
        - EMAIL_ALREADY_EXISTS
        - DIC_ALREADY_EXISTS
        - WEAK_PASSWORD
        - IDEMPOTENCY_KEY_REQUIRED
        - IDEMPOTENCY_CONFLICT
        - IDEMPOTENCY_IN_PROGRESS
        - DUPLICATE_INVOICE
        - PAYLOAD_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - XML_MALFORMED
        - UNSUPPORTED_DOCUMENT_TYPE
        - VALIDATION_FAILED
        - OBLIGATION_FORBIDDEN
        - SELLER_MISMATCH
        - BUYER_MISMATCH
        - ISSUE_DATE_NOT_TODAY
        - DELIVERY_DATE_OVER_15_DAYS
        - RECIPIENT_NOT_REGISTERED
        - NO_OUTBOUND_CONNECTION
        - CONNECTION_DISABLED
        - SSRF_BASE_URL_NOT_ALLOWED
        - INVALID_CREDENTIALS_FORMAT
        - UNKNOWN_PROVIDER_TYPE
        - INVALID_CONNECTION_SETTINGS
        - EXPORT_TOO_LARGE
        - EXPORT_NOT_READY
        - INVALID_STATE_TRANSITION
        - RATE_LIMITED
        - PROVIDER_AUTH_FAILED
        - PROVIDER_RATE_LIMITED
        - PROVIDER_UNAVAILABLE
        - PROVIDER_REJECTED
        - PROVIDER_ERROR
        - PROVIDER_OPERATION_NOT_SUPPORTED
        - WEBHOOK_SIGNATURE_INVALID
        - LOOKUP_NOT_SUPPORTED
        - VALIDATOR_UNAVAILABLE
        - SERVICE_UNAVAILABLE
        - INTERNAL_ERROR
        - XML_NOT_AVAILABLE
        - SELF_BILLING_NOT_ENABLED
        - INVALID_SETTING
        - SMTP_NOT_CONFIGURED
        - INVALID_TOKEN
        - IP_NOT_ALLOWED
        - ERP_CLIENT_DISABLED
        - ACCOUNT_LOCKED
        - INVALID_PROVIDER_INFO
        - INVALID_ASSET
        - AI_REFRESH_DISABLED
        - BACKUP_ENGINE_UNAVAILABLE
        - BACKUP_ENGINE_ERROR
        - RETENTION_BELOW_LEGAL_MINIMUM
        - ENCODING_UNSUPPORTED
        - ENCODING_AMBIGUOUS
        - ENCODING_INVALID
        - ENCODING_INVALID_CHARACTER
        - ENCODING_NOT_REPRESENTABLE
        - INVALID_TEST_FLAG
        - TEST_ONLY_CREDENTIAL
        - TEST_SEND_BLOCKED
        - SANDBOX_REAL_CONNECTION
        - TEST_RUN_EXPIRED
        - FORWARDING_DISABLED
        - FORWARDING_NOT_ALLOWED
        - RECIPIENT_NOT_VERIFIED
        - CAPTCHA_FAILED
        - EMAIL_DOMAIN_NOT_ALLOWED
        - SANDBOX_REGISTRATION_DISABLED
        - SANDBOX_VERIFY_INVALID
        - SANDBOX_QUOTA_EXCEEDED
    # ---------------------------------------------------------------- sandbox (veřejná samoobslužná registrace vývojářů, ADR 040)
    SandboxStatus:
      type: string
      enum: [pending, active, expired, blocked]
    SandboxQuotas:
      type: object
      required: [invoices_per_day, max_xml_kb, max_integrations, max_api_keys]
      properties:
        invoices_per_day: { type: integer, minimum: 0, description: 'Počet odeslání za den (Europe/Bratislava), včetně testovacích běhů' }
        max_xml_kb: { type: integer, minimum: 1, description: 'Největší povolená velikost XML v KB' }
        max_integrations: { type: integer, minimum: 0, description: 'Počet aktivních ERP integrací' }
        max_api_keys: { type: integer, minimum: 0, description: 'Počet aktivních API klíčů' }
    SandboxQuotasUpdate:
      type: object
      additionalProperties: false
      description: 'Přepis kvót správcem; `null` = vrátit výchozí hodnotu z konfigurace.'
      properties:
        invoices_per_day: { type: [integer, 'null'], minimum: 0, maximum: 100000 }
        max_xml_kb: { type: [integer, 'null'], minimum: 1, maximum: 51200 }
        max_integrations: { type: [integer, 'null'], minimum: 0, maximum: 100 }
        max_api_keys: { type: [integer, 'null'], minimum: 0, maximum: 100 }
        inactivity_days: { type: [integer, 'null'], minimum: 1, maximum: 3650 }
    SandboxUsageCounts:
      type: object
      required: [invoices_today, api_keys, integrations]
      properties:
        invoices_today: { type: integer, minimum: 0 }
        api_keys: { type: integer, minimum: 0 }
        integrations: { type: integer, minimum: 0 }
    SandboxChallenge:
      type: object
      required: [token, min_seconds, pow_bits, expires_in]
      properties:
        token: { type: string, description: 'Podepsaný (HMAC) jednorázový token formuláře' }
        min_seconds: { type: integer, minimum: 0, description: 'Nejdříve za tolik sekund od vystavení se formulář smí odeslat (časová past)' }
        pow_bits: { type: integer, minimum: 0, maximum: 28, description: 'Počet nulových bitů SHA-256(token + ":" + řešení); 0 = bez proof-of-work' }
        expires_in: { type: integer, minimum: 1, description: 'Platnost tokenu v sekundách' }
    SandboxPublicConfig:
      type: object
      required: [enabled, environment, captcha, challenge, terms_version, inactivity_days, quotas, docs_url, mock_url, contact_email]
      properties:
        enabled: { type: boolean }
        environment: { type: string, enum: [sandbox] }
        captcha:
          type: object
          required: [provider, site_key]
          properties:
            provider: { type: string, enum: [turnstile, fake, none] }
            site_key: { type: [string, 'null'], description: 'Veřejný site key (jen s volitelným providerem turnstile)' }
        challenge:
          description: 'Ochrana formuláře bez třetí strany (ADR 045); null = vypnutá (jen dev/test)'
          oneOf:
            - type: 'null'
            - { $ref: '#/components/schemas/SandboxChallenge' }
        terms_version: { type: string }
        inactivity_days: { type: integer, minimum: 1 }
        quotas: { $ref: '#/components/schemas/SandboxQuotas' }
        docs_url: { type: [string, 'null'] }
        mock_url: { type: [string, 'null'] }
        contact_email: { type: [string, 'null'] }
    SandboxRegistrationRequest:
      type: object
      required: [email, company_name, accept_terms]
      properties:
        email: { type: string, format: email, maxLength: 254 }
        company_name: { type: string, minLength: 2, maxLength: 120 }
        accept_terms: { type: boolean, enum: [true] }
        language: { type: string, enum: [sk, cs, en] }
        captcha_token: { type: string, maxLength: 4096, description: 'Jen s volitelným providerem turnstile (token z widgetu); výchozí provider none ho nepoužívá' }
        form_token: { type: string, maxLength: 1024, description: 'Token z GET /public/sandbox/config -> challenge.token' }
        form_solution: { type: string, maxLength: 32, description: 'Řešení proof-of-work (je-li challenge.pow_bits > 0)' }
        website: { type: string, maxLength: 200, description: 'Skryté pole (honeypot); musí zůstat prázdné' }
    SandboxRegistrationAccepted:
      type: object
      required: [status, message]
      properties:
        status: { type: string, enum: [verification_sent] }
        message: { type: string }
    SandboxVerifyRequest:
      type: object
      required: [token]
      properties:
        token: { type: string, pattern: '^[A-Za-z0-9_-]{20,100}$' }
    SandboxProvisioned:
      type: object
      required: [tenant, login, api_key, erp_integration, endpoints, quotas, inactivity_days, reactivated]
      properties:
        tenant:
          type: object
          required: [id, name, dic, ico, ic_dph, peppol_id]
          properties:
            id: { type: string, format: uuid }
            name: { type: string }
            dic: { type: string }
            ico: { type: string }
            ic_dph: { type: string }
            peppol_id: { type: string }
        login:
          type: object
          required: [email, password]
          properties:
            email: { type: string }
            password: { type: string, description: 'Zobrazí se JEDNOU' }
        api_key:
          type: object
          required: [id, name, key_prefix, key, scopes, test_only, expires_at]
          properties:
            id: { type: string, format: uuid }
            name: { type: string }
            key_prefix: { type: string }
            key: { type: string, description: 'Zobrazí se JEDNOU' }
            scopes: { type: array, items: { type: string } }
            test_only: { type: boolean }
            expires_at: { type: [string, 'null'], format: date-time }
        erp_integration:
          type: object
          required: [id, name, token, test_only]
          properties:
            id: { type: string, format: uuid }
            name: { type: string }
            token: { type: [string, 'null'], description: 'Zobrazí se JEDNOU' }
            test_only: { type: boolean }
        endpoints:
          type: object
          required: [api_base, erp_base, mock_base, docs_url]
          properties:
            api_base: { type: string }
            erp_base: { type: string }
            mock_base: { type: [string, 'null'] }
            docs_url: { type: [string, 'null'] }
        quotas: { $ref: '#/components/schemas/SandboxQuotas' }
        inactivity_days: { type: integer, minimum: 1 }
        reactivated: { type: boolean, description: 'true = obnova dříve vypršelého sandboxu (staré klíče zneplatněny, data zůstala)' }
    SandboxUsage:
      type: object
      required: [sandbox, status, quotas, usage, last_activity_at, expires_at]
      properties:
        sandbox: { type: boolean }
        status: { oneOf: [{ $ref: '#/components/schemas/SandboxStatus' }, { type: 'null' }] }
        quotas: { oneOf: [{ $ref: '#/components/schemas/SandboxQuotas' }, { type: 'null' }] }
        usage: { oneOf: [{ $ref: '#/components/schemas/SandboxUsageCounts' }, { type: 'null' }] }
        last_activity_at: { type: [string, 'null'], format: date-time }
        expires_at: { type: [string, 'null'], format: date-time }
    SandboxRegistration:
      type: object
      required: [id, email, company_name, language, status, tenant_id, tenant_name, tenant_dic, created_at, verified_at, last_activity_at, expires_at, keep_until, expired_at, blocked_at, blocked_reason, quotas, quota_overrides, inactivity_days, usage]
      properties:
        id: { type: string, format: uuid }
        email: { type: string }
        company_name: { type: string }
        language: { type: string, enum: [sk, cs, en] }
        status: { $ref: '#/components/schemas/SandboxStatus' }
        tenant_id: { type: [string, 'null'], format: uuid }
        tenant_name: { type: [string, 'null'] }
        tenant_dic: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        verified_at: { type: [string, 'null'], format: date-time }
        last_activity_at: { type: [string, 'null'], format: date-time }
        expires_at: { type: [string, 'null'], format: date-time, description: 'Kdy sandbox vyprší bez další aktivity (nebo prodloužení)' }
        keep_until: { type: [string, 'null'], format: date-time }
        expired_at: { type: [string, 'null'], format: date-time }
        blocked_at: { type: [string, 'null'], format: date-time }
        blocked_reason: { type: [string, 'null'] }
        quotas: { $ref: '#/components/schemas/SandboxQuotas' }
        quota_overrides: { $ref: '#/components/schemas/SandboxQuotasUpdate' }
        inactivity_days: { type: integer, minimum: 1 }
        usage: { oneOf: [{ $ref: '#/components/schemas/SandboxUsageCounts' }, { type: 'null' }] }
    SandboxRegistrationList:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/SandboxRegistration' } }
        next_cursor: { type: [string, 'null'] }
    SandboxBlockRequest:
      type: object
      required: [reason]
      properties:
        reason: { type: string, minLength: 3, maxLength: 200 }
    SandboxExtendRequest:
      type: object
      required: [days]
      properties:
        days: { type: integer, minimum: 1, maximum: 365 }
    SandboxExpireRequest:
      type: object
      properties:
        dry_run: { type: boolean }
    SandboxExpireResult:
      type: object
      required: [checked, expired, dry_run, ids]
      properties:
        checked: { type: integer, minimum: 0 }
        expired: { type: integer, minimum: 0 }
        dry_run: { type: boolean }
        ids: { type: array, items: { type: string, format: uuid } }
    Money:
      type: string
      description: Desetinné číslo jako řetězec, tečka, nejvýše 6 desetinných míst (částky 2, jednotkové ceny až 6). Záporné pro dobropisy jen tam, kde je v XML záporné.
      pattern: '^-?[0-9]{1,15}(\.[0-9]{1,6})?$'
      examples: ['1230.00']

    # ---------------------------------------------------------------- errors
    ProblemFieldError:
      type: object
      required: [pointer, message]
      properties:
        pointer: { type: string, description: 'JSON Pointer do těla nebo `query:<name>` / `header:<name>`' }
        message: { type: string }
    Problem:
      type: object
      description: "RFC 9457 + `code`. `Content-Type: application/problem+json`."
      required: [type, title, status, code]
      properties:
        type: { type: string, description: 'URI; konvence `https://efakt.local/problems/<code-lowercase-dashes>`' }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string, description: Cesta požadavku }
        code: { $ref: '#/components/schemas/ErrorCode' }
        request_id: { type: string }
        errors:
          type: array
          description: Chyby polí (pro `BAD_REQUEST`, `INVALID_CREDENTIALS_FORMAT`, ...)
          items: { $ref: '#/components/schemas/ProblemFieldError' }
        findings:
          type: array
          description: Validační nálezy (pro `VALIDATION_FAILED` a portálové kontroly faktury)
          items: { $ref: '#/components/schemas/ValidationFinding' }
        existing_invoice_id: { type: string, format: uuid, description: 'Jen u `DUPLICATE_INVOICE` a `IDEMPOTENCY_CONFLICT`' }
        retry_after_seconds: { type: integer }
        offset: { type: integer, minimum: 0, description: 'Jen u `ENCODING_*`: bajtový offset prvního problematického bajtu/znaku ve vstupu.' }
        characters:
          type: array
          description: 'Jen u `ENCODING_NOT_REPRESENTABLE`: znaky, které cílové kódování nemá (nikdy se nenahrazují).'
          items: { $ref: '#/components/schemas/EncodingUnrepresentableChar' }

    # ---------------------------------------------------------------- invoice building blocks
    Address:
      type: object
      required: [street, city, postal_code, country_code]
      properties:
        street: { type: [string, 'null'] }
        city: { type: [string, 'null'] }
        postal_code: { type: [string, 'null'] }
        country_code: { type: [string, 'null'], description: ISO 3166-1 alpha-2 }
    Party:
      type: object
      required: [name, dic, ic_dph, ico, peppol_id, address]
      properties:
        name: { type: string }
        dic: { type: [string, 'null'], description: 'DIČ (SK: 10 číslic)' }
        ic_dph: { type: [string, 'null'], description: 'IČ DPH, např. SK2020123457' }
        ico: { type: [string, 'null'] }
        peppol_id: { type: [string, 'null'], description: '`0245:<DIČ>` (z EndpointID schemeID=0245)' }
        address: { oneOf: [{ $ref: '#/components/schemas/Address' }, { type: 'null' }] }
    VatBreakdownItem:
      type: object
      required: [category, rate, taxable_amount, tax_amount, exemption_reason_code, exemption_reason]
      properties:
        category: { type: string, description: 'S, E, K, G, AE, O, Z, ...' }
        rate: { type: [string, 'null'], description: 'Sazba v % jako řetězec, null u kategorií bez sazby (O)' }
        taxable_amount: { $ref: '#/components/schemas/Money' }
        tax_amount: { $ref: '#/components/schemas/Money' }
        exemption_reason_code: { type: [string, 'null'], description: VATEX kód }
        exemption_reason: { type: [string, 'null'] }
    Totals:
      type: object
      required: [currency, total_net, total_vat, total_gross, prepaid_amount, payable_amount, vat_breakdown]
      properties:
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        total_net: { $ref: '#/components/schemas/Money' }
        total_vat: { $ref: '#/components/schemas/Money' }
        total_gross: { $ref: '#/components/schemas/Money' }
        prepaid_amount: { oneOf: [{ $ref: '#/components/schemas/Money' }, { type: 'null' }] }
        payable_amount: { $ref: '#/components/schemas/Money' }
        vat_breakdown:
          type: array
          items: { $ref: '#/components/schemas/VatBreakdownItem' }
    InvoiceLine:
      type: object
      required: [line_id, name, quantity, unit_code, unit_price, line_net, vat_category, vat_rate]
      properties:
        line_id: { type: string }
        name: { type: string }
        quantity: { type: string }
        unit_code: { type: [string, 'null'], description: "UN/ECE Rec 20 (BR-23)" }
        unit_price: { $ref: '#/components/schemas/Money' }
        line_net: { $ref: '#/components/schemas/Money' }
        vat_category: { type: string }
        vat_rate: { type: [string, 'null'] }
    AttachmentMeta:
      type: object
      required: [id, filename, mime_type, size_bytes, sha256, download_url]
      properties:
        id: { type: string, format: uuid }
        filename: { type: string }
        mime_type: { type: string }
        size_bytes: { type: integer }
        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        download_url: { type: string }
    ValidationFinding:
      type: object
      required: [rule_id, severity, message, location, source]
      properties:
        rule_id: { type: string, description: 'Schematron pravidlo (`BR-O-02`, `BR-23`, `PEPPOL-EN16931-R001`, ...) nebo portálový kód z `ErrorCode` (`SELLER_MISMATCH`, `RECIPIENT_NOT_REGISTERED`, ...)' }
        severity: { $ref: '#/components/schemas/FindingSeverity' }
        message: { type: string }
        location: { type: [string, 'null'], description: XPath do dokumentu }
        source: { $ref: '#/components/schemas/FindingSource' }
        layer: { type: string, description: 'Vrstva předodesílací validace (format, sk, party_format, registry, routing, obligation, timing, tdd_sk, provider_dryrun, external, engine)' }
        messages:
          type: object
          description: Text nálezu ve všech jazycích; `message` je v jazyce `Accept-Language` (výchozí en).
          properties:
            sk: { type: string }
            cs: { type: string }
            en: { type: string }
        blocking: { type: boolean, description: Nález blokuje odeslání }
        blocking_reason: { type: string, enum: [statutory, policy], description: 'statutory = zákonný zákaz (nelze vypnout), policy = konfigurace/přísný režim' }
        overridable: { type: boolean, description: 'Lze závažnost přepsat konfigurací?' }
        code_class: { type: string }
        params:
          type: object
          description: 'Parametry nálezu; `alias` = alternativní kód (PTY-* pro ID-*, TIM-*, RTE-* pro starší kódy portálu)'
          additionalProperties:
            type: [string, number, boolean, 'null']
    ValidationResult:
      type: object
      required: [status, error_count, warning_count, validated_at, findings]
      properties:
        status: { $ref: '#/components/schemas/ValidationStatus' }
        error_count: { type: integer }
        warning_count: { type: integer }
        validated_at: { type: [string, 'null'], format: date-time }
        findings:
          type: array
          items: { $ref: '#/components/schemas/ValidationFinding' }
    DeliveryEvent:
      type: object
      description: Neměnný záznam stavu/události (tabulka `invoice_events`), včetně MLS informací z poštáře.
      required: [id, at, type, source, from_status, to_status, reason_code, message, details]
      properties:
        id: { type: string, format: uuid }
        at: { type: string, format: date-time }
        type: { $ref: '#/components/schemas/DeliveryEventType' }
        source: { $ref: '#/components/schemas/DeliveryEventSource' }
        from_status: { oneOf: [{ $ref: '#/components/schemas/InvoiceStatus' }, { type: 'null' }] }
        to_status: { oneOf: [{ $ref: '#/components/schemas/InvoiceStatus' }, { type: 'null' }] }
        reason_code: { type: [string, 'null'], description: 'Např. `RECIPIENT_NOT_REGISTERED`, `PROVIDER_REJECTED`' }
        message: { type: [string, 'null'] }
        details: { type: [object, 'null'], additionalProperties: true, description: 'Prostá data z poštáře (bez tajemství)' }
    InvoiceLinks:
      type: object
      required: [self, xml, html]
      properties:
        self: { type: string }
        xml: { type: string }
        html: { type: string }
    ErrorSummary:
      type: object
      required: [code, message, at]
      properties:
        code: { type: string }
        message: { type: string }
        at: { type: string, format: date-time }

    InvoiceListItem:
      type: object
      required:
        - id
        - direction
        - source
        - status
        - validation_status
        - doc_type_code
        - invoice_number
        - issue_date
        - due_date
        - currency
        - seller
        - buyer
        - total_net
        - total_vat
        - total_gross
        - has_attachments
        - connection_id
        - invoice_uuid5
        - external_reference
        - received_at
        - sent_at
        - delivered_at
        - created_at
        - xml_missing
        - metadata_incomplete
        - has_conflicting_duplicates
        - superseded
      properties:
        id: { type: string, format: uuid }
        direction: { $ref: '#/components/schemas/Direction' }
        source: { $ref: '#/components/schemas/InvoiceSource' }
        status: { $ref: '#/components/schemas/InvoiceStatus' }
        validation_status: { $ref: '#/components/schemas/ValidationStatus' }
        doc_type_code: { $ref: '#/components/schemas/DocumentTypeCode' }
        invoice_number: { type: string }
        issue_date: { type: string, format: date }
        due_date: { type: [string, 'null'], format: date }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        seller: { $ref: '#/components/schemas/Party' }
        buyer: { $ref: '#/components/schemas/Party' }
        total_net: { $ref: '#/components/schemas/Money' }
        total_vat: { $ref: '#/components/schemas/Money' }
        total_gross: { $ref: '#/components/schemas/Money' }
        has_attachments: { type: boolean }
        connection_id: { type: [string, 'null'], format: uuid }
        invoice_uuid5: { type: [string, 'null'], format: uuid, description: "UUID v5 dle Peppol SK architektury (ID-BDID-01); null dokud není ověřen jmenný prostor (viz OPEN-QUESTIONS)" }
        external_reference: { type: [string, 'null'], description: 'Hodnota `X-External-Reference` / `metadata.external_reference`' }
        received_at: { type: [string, 'null'], format: date-time }
        sent_at: { type: [string, 'null'], format: date-time }
        delivered_at: { type: [string, 'null'], format: date-time }
        created_at: { type: string, format: date-time }
        xml_missing: { type: boolean, description: 'Záznam bez XML (stav `received_without_xml`): poštář XML nepředal, viz detail `payload_omitted_reason`/`provider_portal_url`.' }
        metadata_incomplete: { type: boolean, description: 'Metadata (typ, strany) se nepodařilo přečíst z XML; hodnoty jsou zástupné (`unparsed_reason`).' }
        has_conflicting_duplicates: { type: boolean, description: 'Existuje další doklad se stejným klíčem a JINÝM obsahem (původní XML zůstává beze změny).' }
        superseded: { type: boolean, description: 'Odeslání bylo nahrazeno novým pokusem (stejné číslo/datum po failed_permanent/rejected_by_provider).' }
        erp_deliveries:
          type: array
          description: 'Příznak „převzato do ERP“ (ADR 015): integrace, které potvrdily převzetí příchozí faktury (ACK), s datem a časem (UTC). Prázdné = nepřevzato. Nemění XML ani hash.'
          items: { $ref: '#/components/schemas/ErpDelivery' }
    ConflictingDuplicate:
      type: object
      required: [id, reason, source, received_at, xml_sha256, xml_size_bytes, download_url]
      properties:
        id: { type: string, format: uuid }
        reason: { type: string, enum: [different_content, xml_supplement] }
        source: { type: string }
        received_at: { type: string, format: date-time }
        xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        xml_size_bytes: { type: integer }
        download_url: { type: string }
    InboundMonitoring:
      type: object
      description: |
        Heartbeat příjmu u spojení, které přijímá jen přes push webhook (např. ePodatelna24). Zmeškaný webhook nelze zjistit ani
        dohrát (poskytovatel nemá list/GET) – proto `can_detect_missed_webhooks=false`; UI má upozornit a nabídnout ruční import.
      required: [mode, can_detect_missed_webhooks, last_webhook_at, age_seconds, pending_events, dead_events]
      properties:
        mode: { type: string, enum: [push_only] }
        can_detect_missed_webhooks: { type: boolean }
        last_webhook_at: { type: [string, 'null'], format: date-time }
        age_seconds: { type: [integer, 'null'], description: 'Stáří posledního přijatého webhooku' }
        pending_events: { type: integer, description: 'Uložené, ještě nezpracované události (čekají na validátor/job)' }
        dead_events: { type: integer, description: 'Události, které se nepodařilo zpracovat (dead-letter, ruční opakování v administraci)' }
    InvoiceDetail:
      allOf:
        - { $ref: '#/components/schemas/InvoiceListItem' }
        - type: object
          required:
            - xml_sha256
            - xml_size_bytes
            - remote_id
            - buyer_reference
            - delivery_date
            - billing_references
            - note
            - totals
            - lines
            - attachments
            - validation
            - delivery_events
            - last_error
            - links
            - payload_omitted_reason
            - provider_portal_url
            - unparsed_reason
            - conflicting_duplicates
            - supersedes_invoice_id
            - superseded_by_invoice_id
          properties:
            payload_omitted_reason: { type: [string, 'null'], description: 'Proč poštář XML nepředal (např. `payload_too_large`).' }
            provider_portal_url: { type: [string, 'null'], description: 'Odkaz na portál poskytovatele, kde lze XML stáhnout (jen u `xml_missing`).' }
            unparsed_reason: { type: [string, 'null'], description: 'Důvod, proč metadata nejsou z XML (neznámý typ dokladu, nečitelné XML).' }
            conflicting_duplicates:
              type: array
              items: { $ref: '#/components/schemas/ConflictingDuplicate' }
            supersedes_invoice_id: { type: [string, 'null'], format: uuid }
            superseded_by_invoice_id: { type: [string, 'null'], format: uuid }
            encoding:
              description: 'Jak bylo určeno kódování přijatého XML; `null` u dokladů z poštáře a starších dokladů.'
              oneOf: [ { $ref: '#/components/schemas/EncodingInfo' }, { type: 'null' } ]
            xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
            xml_size_bytes: { type: integer }
            remote_id: { type: [string, 'null'], description: ID u poštáře }
            buyer_reference: { type: [string, 'null'], description: BT-10 }
            delivery_date: { type: [string, 'null'], format: date }
            billing_references:
              type: array
              description: BT-25 reference na předchozí faktury
              items: { type: string }
            note: { type: [string, 'null'] }
            totals: { $ref: '#/components/schemas/Totals' }
            lines:
              type: array
              items: { $ref: '#/components/schemas/InvoiceLine' }
            attachments:
              type: array
              items: { $ref: '#/components/schemas/AttachmentMeta' }
            validation: { $ref: '#/components/schemas/ValidationResult' }
            delivery_events:
              type: array
              description: Chronologicky vzestupně
              items: { $ref: '#/components/schemas/DeliveryEvent' }
            last_error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }
            links: { $ref: '#/components/schemas/InvoiceLinks' }
    InvoicePage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/InvoiceListItem' }
        next_cursor: { type: [string, 'null'] }
    TestSimulate:
      type: string
      enum: [delivered, undeliverable, rejected, provider_error, timeout, late_issue]
      default: delivered
      description: |
        Simulovaný průběh po (nevykonaném) odeslání: `delivered` (queued, sending, sent, delivered), `undeliverable` (delivery_failed RECIPIENT_NOT_REGISTERED),
        `rejected` (rejected_by_provider), `provider_error` (opakované dočasné chyby, pak failed_permanent RETRIES_EXHAUSTED),
        `timeout` (failed_permanent OUTCOME_UNKNOWN), `late_issue` (failed_permanent ISSUE_DATE_NOT_TODAY).
    TestWouldSend:
      type: object
      required: [connection_id, provider_type, sender_peppol_id, receiver_peppol_id, route]
      properties:
        connection_id: { type: string, format: uuid }
        provider_type: { type: string }
        sender_peppol_id: { type: string }
        receiver_peppol_id: { type: [string, 'null'] }
        route:
          type: object
          required: [selected_by, environment, mock, recipient_check]
          properties:
            selected_by: { type: string, enum: [request, integration_default, tenant_default] }
            environment: { type: string, enum: [sandbox, production] }
            mock: { type: boolean }
            recipient_check: { type: string, enum: [registered, not_registered, unknown, skipped] }
    TestSimulatedEvent:
      type: object
      required: [seq, at, type, from_status, to_status, reason_code, message, webhook_event]
      properties:
        seq: { type: integer, minimum: 1 }
        at: { type: string, format: date-time }
        type: { type: string, enum: [status_changed, retry_scheduled, warning] }
        from_status: { type: [string, 'null'] }
        to_status: { type: [string, 'null'] }
        reason_code: { type: [string, 'null'] }
        message: { type: string }
        webhook_event: { type: [string, 'null'], description: 'Událost webhooku, kterou by přechod vyvolal (`invoice.sent` ...).' }
    TestWebhookResult:
      type: object
      required: [requested, endpoints, delivered, failed, completed]
      properties:
        requested: { type: boolean }
        endpoints: { type: integer }
        delivered: { type: integer }
        failed: { type: integer }
        completed: { type: boolean }
    TestSubmitResponse:
      type: object
      description: Výsledek testovacího odeslání. Nikdy nevznikla faktura ani úloha; ID `test_<uuid>` nelze použít u `/invoices/{id}`.
      required: [id, test, status, would_have_sent, forced_by, simulate, would_send, validation, encoding, simulated_events, webhooks, created_at, expires_at, links]
      properties:
        id: { type: string, pattern: '^test_[0-9a-f-]{36}$' }
        test: { type: boolean, enum: [true] }
        status: { type: string, enum: [test_accepted] }
        would_have_sent: { type: boolean, description: '`false` při blokujícím nálezu validace (ostré volání by selhalo).' }
        forced_by: { type: [string, 'null'], enum: [test_only_credential, null] }
        simulate: { $ref: '#/components/schemas/TestSimulate' }
        would_send: { oneOf: [ { $ref: '#/components/schemas/TestWouldSend' }, { type: 'null' } ] }
        validation: { $ref: '#/components/schemas/ValidationReport' }
        encoding: { type: [object, 'null'], additionalProperties: true }
        simulated_events: { type: array, items: { $ref: '#/components/schemas/TestSimulatedEvent' } }
        webhooks: { $ref: '#/components/schemas/TestWebhookResult' }
        created_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        links: { type: object, required: [self], properties: { self: { type: string } } }
        client_reference: { type: [string, 'null'] }
    TestRun:
      allOf:
        - $ref: '#/components/schemas/TestSubmitResponse'
        - type: object
          required: [endpoint]
          properties:
            endpoint: { type: string, enum: [invoices, erp_invoices, erp_batch] }
    InvoiceSubmitEnvelope:
      type: object
      required: [xml_base64]
      properties:
        xml_base64: { type: string, contentEncoding: base64, description: 'UBL XML – přesné bajty v base64 (standardní abeceda)' }
        test: { type: boolean, description: 'Testovací režim (viz parametr `test`): provede se vše kromě odeslání.' }
        simulate: { $ref: '#/components/schemas/TestSimulate' }
        simulate_webhooks: { type: boolean, description: 'Jen s `test`: rozeslat testovací webhooky (`test:true`, `X-Test: 1`).' }
        connection_id: { type: string, format: uuid }
        external_reference: { type: string, maxLength: 200 }
        encoding: { type: string, maxLength: 40, description: 'Kódování bajtů v `xml_base64` (např. `windows-1250`); ekvivalent `charset` v Content-Type. Viz `EncodingInfo`.' }
        options:
          type: object
          properties:
            skip_recipient_lookup: { type: boolean, default: false, description: Nevolat lookupParticipant před uložením }
            confidential_supply: { type: boolean, description: '`true` = utajované plnění => e-fakturu nelze vystavit (`OBLIGATION_FORBIDDEN`); `false` = uživatel potvrdil, že není.' }
            recipient_sis_vo: { type: boolean, description: '`true` = příjemce je SIS / Vojenské spravodajství => zákaz; `false` = potvrzeno, že není.' }
            check_routing: { type: boolean, description: 'Výslovně ověřit příjemce v Peppolu (vrstva `routing`).' }
    InvoiceAccepted:
      type: object
      required: [id, status, direction, doc_type_code, invoice_number, issue_date, seller_peppol_id, buyer_peppol_id, connection_id, xml_sha256, warnings, links]
      properties:
        id: { type: string, format: uuid }
        status: { $ref: '#/components/schemas/OutboundStatus' }
        direction: { type: string, enum: [outbound] }
        doc_type_code: { $ref: '#/components/schemas/DocumentTypeCode' }
        invoice_number: { type: string }
        issue_date: { type: string, format: date }
        seller_peppol_id: { type: string }
        buyer_peppol_id: { type: [string, 'null'] }
        connection_id: { type: string, format: uuid }
        xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        warnings:
          type: array
          description: Nálezy se severity `warning`/`info` (např. `RECIPIENT_NOT_REGISTERED`, `ISSUE_DATE_NOT_TODAY` při policy=warn).
          items: { $ref: '#/components/schemas/ValidationFinding' }
        links: { $ref: '#/components/schemas/InvoiceLinks' }
        validation_run_id: { type: string, format: uuid, description: Záznam předodesílací validace (`validation_runs`) }
        encoding: { $ref: '#/components/schemas/EncodingInfo' }

    EncodingInfo:
      type: object
      description: |
        Jak portál určil kódování přijatého XML a co s ním udělal (docs/CODEPAGE-INPUT-SPEC.md). Odeslaná/uložená verze (`xml_sha256`) je vždy UTF-8;
        při `transcoded=true` se původní bajty uchovávají beze změny jako nemazatelný zdrojový dokument (`GET /invoices/{id}/source-xml`).
      required: [source, origin, transcoded, bom_stripped, warnings]
      properties:
        source: { type: string, enum: [utf-8, windows-1250, iso-8859-2, windows-1252, cp852, utf-16le, utf-16be], description: Kódování původních bajtů }
        origin: { type: string, enum: [param, envelope, bom, declaration, tenant_default, detected_utf8], description: 'Čím bylo kódování určeno: `param` (charset v Content-Type), `envelope` (pole `encoding`), BOM, deklarace XML, výchozí kódování tenanta, platnost UTF-8.' }
        declared: { type: [string, 'null'], description: 'Hodnota `encoding=` v XML deklaraci originálu, jak byla napsána.' }
        transcoded: { type: boolean, description: 'Uložené bajty se liší od původních (převod kódování, odstranění BOM, přepis deklarace).' }
        bom_stripped: { type: boolean }
        source_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        result_sha256: { type: string, pattern: '^[0-9a-f]{64}$', description: 'SHA-256 UTF-8 verze (= `xml_sha256`).' }
        transcoder_version: { type: string }
        warnings:
          type: array
          description: '`ENCODING_TRANSCODED`, `ENCODING_DECLARATION_MISMATCH`, `ENCODING_SUSPICIOUS`.'
          items: { $ref: '#/components/schemas/ValidationFinding' }
    EncodingUnrepresentableChar:
      type: object
      required: [char, code_point, count, first_offset]
      properties:
        char: { type: string }
        code_point: { type: string, example: 'U+03A9' }
        count: { type: integer }
        first_offset: { type: integer, description: Pozice prvního výskytu v textu dokumentu (kódové jednotky UTF-16) }

    ExportRequest:
      type: object
      required: [format]
      description: Právě jedno z `invoice_ids` / `filter`.
      properties:
        format: { $ref: '#/components/schemas/ExportFormat' }
        invoice_ids:
          type: array
          maxItems: 10000
          items: { type: string, format: uuid }
        filter:
          type: object
          description: Stejné názvy a sémantika jako query parametry `GET /invoices` (bez limit/cursor/sort).
          additionalProperties: true
    ExportJob:
      type: object
      required: [id, status, format, invoice_count, size_bytes, created_at, finished_at, expires_at, download_url, error]
      properties:
        id: { type: string, format: uuid }
        status: { $ref: '#/components/schemas/ExportStatus' }
        format: { $ref: '#/components/schemas/ExportFormat' }
        invoice_count: { type: [integer, 'null'] }
        size_bytes: { type: [integer, 'null'] }
        created_at: { type: string, format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        expires_at: { type: [string, 'null'], format: date-time, description: "Po expiraci se soubor smaže (export je jen odvozenina; originály zůstávají)" }
        download_url: { type: [string, 'null'] }
        error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }

    ExportPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/ExportJob' }
        next_cursor: { type: [string, 'null'] }
    InvoiceSummary:
      type: object
      description: Počty faktur aktivního tenanta (viz `GET /invoices/summary`).
      required: [total, by_direction, by_status, last_activity_at]
      properties:
        total: { type: integer, minimum: 0 }
        by_direction:
          type: object
          required: [inbound, outbound]
          properties:
            inbound: { type: integer, minimum: 0 }
            outbound: { type: integer, minimum: 0 }
        by_status:
          type: object
          description: Klíče = všechny hodnoty `InvoiceStatus` (i s nulou).
          additionalProperties: { type: integer, minimum: 0 }
        last_activity_at: { type: [string, 'null'], format: date-time, description: 'Čas poslední přijaté/odeslané faktury (null, pokud žádná není)' }
    Participant:
      type: object
      required: [peppol_id, registered, capabilities, checked_at, connection_id]
      properties:
        peppol_id: { type: string }
        registered: { type: boolean }
        capabilities:
          type: array
          description: Document type / process identifikátory, pokud je poštář vrátí
          items: { type: string }
        checked_at: { type: string, format: date-time }
        connection_id: { type: string, format: uuid }

    # ---------------------------------------------------------------- validation / registry (V-REG)
    PartyFinding:
      type: object
      required: [code, severity, message]
      properties:
        code: { type: string, description: 'Kód nálezu `@efakt/ids` (ID-*)' }
        severity: { type: string, enum: [error, warning, info] }
        message: { type: string }
    PartySource:
      type: object
      required: [name, as_of, rows]
      properties:
        name: { type: string, description: 'fs_ds_dphs | fs_ds_dsrdp | fs_ds_dphv | fs_ds_dphz' }
        as_of: { type: string, format: date-time, description: 'Den stavu dat (DatumAktualizacieZoznamu, 00:00 UTC)' }
        rows: { type: [integer, 'null'] }
    PartyRegistry:
      type: object
      required: [found, dic_assigned, vat_status, regime, since, deleted_at, group_vat, cancellation_pending, person_kind, stale, degraded, as_of, sources]
      properties:
        found: { type: boolean }
        dic_assigned: { type: [boolean, 'null'], description: 'Je DIČ přiděleno (registr ds_dsrdp)? null = nelze určit' }
        vat_status: { type: string, enum: [registered, deleted, not_found, unknown] }
        regime: { type: [string, 'null'], enum: ['§4', '§4b', '§5', '§7', '§7a', unknown, null] }
        since: { type: [string, 'null'], format: date }
        deleted_at: { type: [string, 'null'], format: date }
        group_vat: { type: [boolean, 'null'], description: 'IČ DPH je sdílené (skupina DPH §4b)' }
        cancellation_pending: { type: boolean, description: 'Plátce je v seznamu s důvodem ke zrušení registrace (ds_dphz)' }
        person_kind: { type: [string, 'null'], enum: [legal, natural, null] }
        stale: { type: boolean, description: 'Data jsou starší než nastavená čerstvost' }
        degraded: { type: boolean, description: 'Některý zdroj chybí / je příliš starý – "not_found" je nespolehlivé' }
        as_of: { type: [string, 'null'], format: date-time }
        sources:
          type: array
          items: { $ref: '#/components/schemas/PartySource' }
    PartyPeppol:
      type: object
      required: [registered, provider, source, reason, checked_at]
      properties:
        registered: { type: [boolean, 'null'] }
        provider: { type: [string, 'null'] }
        source: { type: string, enum: [smp, directory, cache, none] }
        reason: { type: [string, 'null'] }
        checked_at: { type: string, format: date-time }
    PartyValidation:
      type: object
      required: [normalized, format, registry, consistency, peppol, name, address, attribution]
      properties:
        normalized:
          type: object
          required: [ico, dic, ic_dph, peppol_id]
          properties:
            ico: { type: [string, 'null'] }
            dic: { type: [string, 'null'] }
            ic_dph: { type: [string, 'null'] }
            peppol_id: { type: [string, 'null'], description: '`0245:<DIČ>` (nikdy z IČ DPH)' }
        format:
          type: object
          required: [ok, findings]
          properties:
            ok: { type: boolean }
            findings:
              type: array
              items: { $ref: '#/components/schemas/PartyFinding' }
        registry: { $ref: '#/components/schemas/PartyRegistry' }
        consistency:
          type: object
          required: [icdph_vs_dic, ico_matches]
          properties:
            icdph_vs_dic: { type: [string, 'null'], enum: [match, mismatch, group, foreign_para5, unknown, null] }
            ico_matches: { type: [boolean, 'null'] }
        peppol:
          oneOf:
            - { $ref: '#/components/schemas/PartyPeppol' }
            - { type: 'null' }
        name: { type: [string, 'null'], description: 'Jen právnická osoba a jen s include=name' }
        address: { type: [string, 'null'] }
        attribution: { type: array, items: { type: string }, description: 'Povinné uvedení zdrojů / licencí' }
    RegistryRunSummary:
      type: object
      required: [id, status, trigger, started_at, finished_at, duration_ms, rows, bytes_downloaded, sha256, error_code, error]
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [running, ok, not_modified, rejected, failed] }
        trigger: { type: string, enum: [schedule, retry, manual] }
        started_at: { type: string, format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        duration_ms: { type: [integer, 'null'] }
        rows: { type: [integer, 'null'] }
        bytes_downloaded: { type: [number, 'null'] }
        sha256: { type: [string, 'null'] }
        error_code: { type: [string, 'null'] }
        error: { type: [string, 'null'] }
    RegistrySourceStatus:
      type: object
      required: [source, enabled, has_snapshot, as_of, rows, age_days, stale, activated_at, last_checked_at, last_attempt_status, consecutive_failures]
      properties:
        source: { type: string }
        enabled: { type: boolean }
        has_snapshot: { type: boolean }
        as_of: { type: [string, 'null'], format: date }
        rows: { type: [integer, 'null'] }
        age_days: { type: [integer, 'null'] }
        stale: { type: boolean }
        activated_at: { type: [string, 'null'], format: date-time }
        last_checked_at: { type: [string, 'null'], format: date-time }
        last_attempt_status: { type: [string, 'null'] }
        consecutive_failures: { type: integer }
    RegistryStatus:
      type: object
      required: [generated_at, enabled, freshness_days, import_time, sources, recent_runs, import_queued]
      properties:
        generated_at: { type: string, format: date-time }
        enabled: { type: boolean }
        freshness_days: { type: integer }
        import_time: { type: string, description: 'HH:MM Europe/Bratislava' }
        sources:
          type: array
          items: { $ref: '#/components/schemas/RegistrySourceStatus' }
        recent_runs:
          type: array
          items: { $ref: '#/components/schemas/RegistryRunSummary' }
        import_queued: { type: boolean }
    RegistryImportRequest:
      type: object
      additionalProperties: false
      properties:
        sources:
          type: array
          maxItems: 4
          items: { type: string, enum: [ds_dphs, ds_dsrdp, ds_dphv, ds_dphz] }
        force: { type: boolean }
        accept_row_delta: { type: boolean }
    RegistryImportAccepted:
      type: object
      required: [queued, already_queued]
      properties:
        queued: { type: boolean }
        already_queued: { type: boolean }

    # ---------------------------------------------------------------- connections
    Connection:
      type: object
      description: Zákaznický pohled. Nikdy neobsahuje credentials, `base_url` ani kurzory.
      required: [id, provider_type, provider_label, environment, direction_capabilities, is_default_outbound, enabled, health, last_success_at, last_attempt_at, next_poll_at, consecutive_failures, last_error, capabilities, receive_mode, inbound_monitoring]
      properties:
        id: { type: string, format: uuid }
        provider_type: { $ref: '#/components/schemas/ProviderType' }
        provider_label: { type: string, description: 'Lidský název, např. "ePodatelna24"' }
        environment: { $ref: '#/components/schemas/Environment' }
        direction_capabilities:
          type: array
          items: { $ref: '#/components/schemas/Direction' }
        is_default_outbound: { type: boolean }
        enabled: { type: boolean }
        health: { $ref: '#/components/schemas/ConnectionHealth' }
        last_success_at: { type: [string, 'null'], format: date-time }
        last_attempt_at: { type: [string, 'null'], format: date-time }
        next_poll_at: { type: [string, 'null'], format: date-time }
        consecutive_failures: { type: integer }
        last_error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }], description: "Sanitizovaná (bez tajemství)" }
        capabilities: { oneOf: [{ $ref: '#/components/schemas/AdapterCapabilities' }, { type: 'null' }], description: 'Co poštář umí (UI podle toho nabízí např. lookup účastníka); null = adaptér není dostupný' }
        receive_mode: { $ref: '#/components/schemas/ReceiveMode' }
        inbound_monitoring: { oneOf: [{ $ref: '#/components/schemas/InboundMonitoring' }, { type: 'null' }], description: 'Jen u push-only příjmu; jinak null.' }
    AdminConnection:
      type: object
      required: [id, tenant_id, provider_type, provider_label, environment, direction_capabilities, is_default_outbound, enabled, health, last_success_at, last_attempt_at, next_poll_at, consecutive_failures, last_error, receive_mode, inbound_monitoring, base_url, poll_interval_seconds, initial_sync_days, credentials_configured, credential_fields, settings, provider_webhook_configured, capabilities, cursor_in, cursor_out, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        provider_type: { $ref: '#/components/schemas/ProviderType' }
        provider_label: { type: string }
        environment: { $ref: '#/components/schemas/Environment' }
        direction_capabilities:
          type: array
          items: { $ref: '#/components/schemas/Direction' }
        is_default_outbound: { type: boolean }
        enabled: { type: boolean }
        health: { $ref: '#/components/schemas/ConnectionHealth' }
        last_success_at: { type: [string, 'null'], format: date-time }
        last_attempt_at: { type: [string, 'null'], format: date-time }
        next_poll_at: { type: [string, 'null'], format: date-time }
        consecutive_failures: { type: integer }
        last_error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }
        receive_mode: { $ref: '#/components/schemas/ReceiveMode' }
        inbound_monitoring: { oneOf: [{ $ref: '#/components/schemas/InboundMonitoring' }, { type: 'null' }] }
        base_url: { type: [string, 'null'] }
        poll_interval_seconds: { type: integer, minimum: 60 }
        initial_sync_days: { type: integer, minimum: 0, maximum: 3650 }
        credentials_configured: { type: boolean }
        credential_fields:
          type: array
          description: Názvy nastavených polí credentials (nikdy hodnoty)
          items: { type: string }
        settings: { $ref: '#/components/schemas/ConnectionSettings' }
        provider_webhook_configured: { type: boolean, description: Má vygenerovaný tajný segment cesty pro provider-webhooks }
        capabilities: { oneOf: [{ $ref: '#/components/schemas/AdapterCapabilities' }, { type: 'null' }], description: 'Dle provider_type (null u neznámého adaptéru)' }
        cursor_in: { type: [string, 'null'], description: "Neprůhledný kurzor adaptéru (jen diagnostika)" }
        cursor_out: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    AdminConnectionPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/AdminConnection' }
        next_cursor: { type: [string, 'null'] }
    CredentialsMock:
      type: object
      description: Credentials pro `mock`. Všechna pole volitelná.
      additionalProperties: false
      properties:
        world_id: { type: string, description: "Sdílený in-memory „svět“ mock poštáře (výchozí = id spojení)" }
        seed: { type: integer }
        mode: { type: string, enum: [pull, push_only], description: 'pull (výchozí) nebo push-only (bez list/fetch/status, jen webhooky)' }
        webhook_secret: { type: string }
        tenant_dic: { type: string, pattern: '^[0-9]{10}$', description: 'DIČ příjemce demo dokladů (výchozí 2020123457); doklad pro jiný DIČ se tenantovi spojení neuloží (H-04)' }
        scenario: { type: string, enum: [normal, auth_failed, flaky, down] }
        seed_incoming: { type: integer, minimum: 0, maximum: 500, description: 'Demo/QA: počet příchozích faktur z posledních dní vložených do světa při jeho vzniku' }
        seed_old_incoming: { type: integer, minimum: 0, maximum: 500, description: 'Demo/QA: počet příchozích faktur starších než 31denní okno (nesmí se stáhnout)' }
        seed_outgoing: { type: integer, minimum: 0, maximum: 500, description: 'Demo/QA: počet odchozích faktur (historie u poštáře, stav delivered)' }
    CredentialsIoniteEpodatelna24:
      type: object
      description: |
        PLACEHOLDER – pole se upřesní podle docs/providers/epodatelna24.md (píše agent PROVIDER-RESEARCH). Zatím obecná
        sada; backend ukládá objekt šifrovaně tak, jak přišel (po validaci proti tomuto schématu).
      additionalProperties: true
      properties:
        token: { type: string }
        api_key: { type: string }
        webhook_secret: { type: string, description: 'HMAC secret `whsec_...` k ověření webhooků poštáře (X-EP24-Signature)' }
        username: { type: string }
        password: { type: string }
        client_id: { type: string }
        client_secret: { type: string }
        baseUrl: { type: string }
    CredentialsGeneric:
      type: object
      description: Pro `epostak`, `doklado`, `verteco`, `generic_peppol_rest` (dosud bez adaptéru). Obecná sada.
      additionalProperties: true
      properties:
        token: { type: string }
        client_id: { type: string }
        client_secret: { type: string }
        webhook_secret: { type: string }
        username: { type: string }
        password: { type: string }
        baseUrl: { type: string }
    CredentialsInput:
      type: object
      additionalProperties: true
      anyOf:
        - { $ref: '#/components/schemas/CredentialsMock' }
        - { $ref: '#/components/schemas/CredentialsIoniteEpodatelna24' }
        - { $ref: '#/components/schemas/CredentialsGeneric' }
      description: "Write-only. Tvar určuje MODUL poštáře (`GET /providers` -> `credentials.fields` / `credentials.json_schema`); server vždy validuje schématem modulu (`422 INVALID_CREDENTIALS_FORMAT`). Příklady: viz `CredentialsMock`, `CredentialsIoniteEpodatelna24`."
    ConnectionSettings:
      type: object
      additionalProperties: true
      description: "Nastavení spojení (není tajné), validuje ho modul (`GET /providers` -> `settings`; `422 INVALID_CONNECTION_SETTINGS`). Společná: `poll_interval_seconds`, `initial_sync_days`, `acknowledge_incoming`."
    ConnectionCreate:
      type: object
      required: [tenant_id, provider_type, environment, direction_capabilities]
      properties:
        tenant_id: { type: string, format: uuid }
        provider_type: { $ref: '#/components/schemas/ProviderType' }
        environment: { $ref: '#/components/schemas/Environment' }
        direction_capabilities:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: '#/components/schemas/Direction' }
        is_default_outbound: { type: boolean, default: false }
        enabled: { type: boolean, default: true }
        base_url: { type: string, format: uri }
        poll_interval_seconds: { type: integer, minimum: 60, default: 300 }
        initial_sync_days: { type: integer, minimum: 0, maximum: 3650, default: 31 }
        credentials: { $ref: '#/components/schemas/CredentialsInput' }
        settings: { $ref: '#/components/schemas/ConnectionSettings' }
    ConnectionUpdate:
      type: object
      minProperties: 1
      properties:
        environment: { $ref: '#/components/schemas/Environment' }
        direction_capabilities:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: '#/components/schemas/Direction' }
        is_default_outbound: { type: boolean }
        enabled: { type: boolean }
        base_url: { type: string, format: uri }
        poll_interval_seconds: { type: integer, minimum: 60 }
        initial_sync_days: { type: integer, minimum: 0, maximum: 3650 }
        credentials: { $ref: '#/components/schemas/CredentialsInput' }
        settings: { $ref: '#/components/schemas/ConnectionSettings' }
    ProviderFieldCondition:
      type: object
      required: [field, equals]
      properties:
        field: { type: string }
        equals:
          type: array
          minItems: 1
          items: { oneOf: [{ type: string }, { type: number }, { type: boolean }] }
    ProviderFieldOption:
      type: object
      required: [value, label]
      properties:
        value: { type: string }
        label: { type: string }
    ProviderFieldSpec:
      type: object
      description: Popis jednoho pole formuláře spojení. `secret = true` je write-only (UI ho nikdy nezobrazí zpět).
      required: [name, type, label, required, secret]
      properties:
        name: { type: string, pattern: '^[A-Za-z][A-Za-z0-9_]{0,63}$' }
        type: { type: string, enum: [string, secret, url, integer, number, boolean, enum] }
        label: { type: string }
        help: { type: string }
        placeholder: { type: string }
        required: { type: boolean }
        secret: { type: boolean }
        default: { oneOf: [{ type: string }, { type: number }, { type: boolean }] }
        options:
          type: array
          items: { $ref: '#/components/schemas/ProviderFieldOption' }
        min: { type: number }
        max: { type: number }
        pattern: { type: string }
        group: { type: string }
        visible_when: { $ref: '#/components/schemas/ProviderFieldCondition' }
        required_when: { $ref: '#/components/schemas/ProviderFieldCondition' }
    ProviderFieldSet:
      type: object
      required: [fields, json_schema]
      properties:
        fields:
          type: array
          items: { $ref: '#/components/schemas/ProviderFieldSpec' }
        json_schema: { type: object, additionalProperties: true, description: 'JSON Schema 2020-12 odvozený z `fields` (secret pole mají `writeOnly: true`)' }
    ProviderDescriptor:
      type: object
      description: Veřejný popis modulu poštáře (bez tajemství). Z něj admin UI generuje formulář spojení.
      required: [provider_type, display_name, description, environments, capabilities, receive_mode, credentials, settings, default_settings, allowed_hosts]
      properties:
        provider_type: { $ref: '#/components/schemas/ProviderType' }
        display_name: { type: string }
        description: { type: string }
        docs_url: { type: string }
        environments:
          type: array
          items: { $ref: '#/components/schemas/Environment' }
        capabilities: { $ref: '#/components/schemas/AdapterCapabilities' }
        receive_mode: { $ref: '#/components/schemas/ReceiveMode' }
        credentials: { $ref: '#/components/schemas/ProviderFieldSet' }
        settings: { $ref: '#/components/schemas/ProviderFieldSet' }
        default_settings: { type: object, additionalProperties: true }
        allowed_hosts:
          type: array
          items: { type: string }
        retention_days: { type: integer, minimum: 1, description: 'Retence obsahu dokladů u poštáře ve dnech; poller nesmí stát déle (varování po 7 dnech bez úspěšného pollingu, kritické po 12; ADR 012).' }
    ProviderList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/ProviderDescriptor' }
    ResetCursorRequest:
      type: object
      required: [direction]
      properties:
        direction: { type: string, enum: [inbound, outbound, both] }
        since: { type: string, format: date-time, description: Volitelné; jinak `now - initial_sync_days` }
    AdapterCapabilities:
      type: object
      description: Co poštář (adaptér) umí. Poller/odesílač podle toho volí režim (pull vs. push-only). Viz ADR 002.
      required: [pull_incoming, pull_outgoing, send, status_pull, participant_lookup, webhook_push, validate_dry_run, acknowledge, idempotent_send]
      properties:
        pull_incoming: { type: boolean, description: 'Lze stahovat příchozí (listIncoming + fetchDocument)' }
        pull_outgoing: { type: boolean, description: 'Lze stahovat historii odchozích (listOutgoing)' }
        send: { type: boolean }
        status_pull: { type: boolean, description: 'getStatus funguje; jinak stav jen z webhooku' }
        participant_lookup: { type: boolean }
        webhook_push: { type: boolean, description: 'Poštář posílá události (příjem, stav) na náš provider-webhook endpoint' }
        validate_dry_run: { type: boolean }
        acknowledge: { type: boolean }
        idempotent_send: { type: boolean, description: 'Opakované send se stejným idempotencyKey nikdy neodešle dvakrát' }
    QuarantinedDocument:
      type: object
      required: [id, tenant_id, tenant_name, connection_id, kind, status, remote_id, reason_code, reason, attempts, invoice_id, assigned_tenant_id, has_xml, created_at]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid, description: 'Tenant spojení, kterým doklad přišel' }
        tenant_name: { type: string }
        connection_id: { type: string, format: uuid }
        kind: { type: string, enum: [party_mismatch, poison_document] }
        status: { type: string, enum: [retrying, quarantined, assigned, dismissed] }
        remote_id: { type: [string, 'null'] }
        reason_code: { type: string, description: 'např. RECEIVER_MISMATCH, BUYER_MISMATCH, VALIDATOR_FAILED' }
        reason: { type: [string, 'null'] }
        attempts: { type: integer }
        invoice_id: { type: [string, 'null'], format: uuid }
        assigned_tenant_id: { type: [string, 'null'], format: uuid }
        has_xml: { type: boolean }
        created_at: { type: string, format: date-time }
    QuarantinedDocumentPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/QuarantinedDocument' }
        next_cursor: { type: [string, 'null'] }
    ProviderEvent:
      type: object
      required: [id, tenant_id, connection_id, kind, status, remote_id, attempts, error, invoice_id, has_raw_body, received_at]
      properties:
        id: { type: string }
        tenant_id: { type: string, format: uuid }
        connection_id: { type: string, format: uuid }
        kind: { type: string, enum: [incoming_document, delivery_status, ignored] }
        status: { type: string, enum: [pending, processed, xml_missing, pending_match, dead, ignored, quarantined] }
        remote_id: { type: [string, 'null'] }
        attempts: { type: integer }
        error: { type: [string, 'null'] }
        invoice_id: { type: [string, 'null'], format: uuid }
        has_raw_body: { type: boolean }
        received_at: { type: string, format: date-time }
    ProviderEventPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/ProviderEvent' }
        next_cursor: { type: [string, 'null'] }
    ProviderWebhookInfo:
      type: object
      required: [connection_id, path, secret, created_at]
      properties:
        connection_id: { type: string, format: uuid }
        path: { type: string, description: 'Např. `/api/v1/provider-webhooks/<connectionId>/<secret>`; doplní se veřejný host a zadá se v UI poštáře' }
        secret: { type: string, description: 'Tajný segment cesty (jen v této odpovědi). NENÍ to HMAC secret poštáře – ten je v `credentials`.' }
        created_at: { type: string, format: date-time }
    ProviderWebhookAck:
      type: object
      required: [status, events]
      properties:
        status: { type: string, enum: [accepted, duplicate, ignored] }
        events: { type: integer, description: Počet normalizovaných událostí uložených z tohoto doručení }
    ConnectionTestResult:
      type: object
      required: [ok, checked_at, latency_ms, error_kind, message, account_label, capabilities]
      properties:
        ok: { type: boolean }
        checked_at: { type: string, format: date-time }
        latency_ms: { type: [integer, 'null'] }
        error_kind:
          type: [string, 'null']
          enum: [AUTH_FAILED, RATE_LIMITED, TRANSIENT, PERMANENT, NOT_FOUND, VALIDATION, NOT_SUPPORTED, null]
        message: { type: [string, 'null'], description: Sanitizovaná zpráva }
        account_label: { type: [string, 'null'], description: Např. název účtu u poštáře }
        capabilities: { $ref: '#/components/schemas/AdapterCapabilities' }
    PollingOverviewItem:
      type: object
      required: [connection_id, tenant_id, tenant_name, provider_type, enabled, health, last_run_at, last_success_at, next_poll_at, lag_seconds, consecutive_failures, last_error, documents_fetched_24h, errors_24h, running]
      properties:
        connection_id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        tenant_name: { type: string }
        provider_type: { $ref: '#/components/schemas/ProviderType' }
        enabled: { type: boolean }
        health: { $ref: '#/components/schemas/ConnectionHealth' }
        last_run_at: { type: [string, 'null'], format: date-time }
        last_success_at: { type: [string, 'null'], format: date-time }
        next_poll_at: { type: [string, 'null'], format: date-time }
        lag_seconds: { type: [integer, 'null'], description: 'now - last_success_at' }
        consecutive_failures: { type: integer }
        last_error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }
        documents_fetched_24h: { type: integer }
        errors_24h: { type: integer }
        running: { type: boolean }
    Job:
      type: object
      required: [id, type, status, tenant_id, connection_id, attempts, max_attempts, run_at, started_at, finished_at, last_error, payload_summary, created_at]
      properties:
        id: { type: string, format: uuid }
        type: { $ref: '#/components/schemas/JobType' }
        status: { $ref: '#/components/schemas/JobStatus' }
        tenant_id: { type: [string, 'null'], format: uuid }
        connection_id: { type: [string, 'null'], format: uuid }
        attempts: { type: integer }
        max_attempts: { type: integer }
        run_at: { type: string, format: date-time }
        started_at: { type: [string, 'null'], format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        last_error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }
        payload_summary: { type: [object, 'null'], additionalProperties: true, description: 'Bezpečné shrnutí payloadu (např. invoice_id), bez tajemství' }
        created_at: { type: string, format: date-time }
    JobPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Job' }
        next_cursor: { type: [string, 'null'] }
    AuditLogEntry:
      type: object
      required: [id, at, actor_user_id, actor_type, actor_label, tenant_id, action, entity_type, entity_id, ip, request_id, details]
      properties:
        id: { type: string, format: uuid }
        at: { type: string, format: date-time }
        actor_user_id: { type: [string, 'null'], format: uuid }
        actor_type: { type: string, enum: [user, api_key, worker, system, erp_client] }
        actor_label: { type: [string, 'null'], description: 'E-mail nebo prefix API klíče' }
        tenant_id: { type: [string, 'null'], format: uuid }
        action: { type: string, description: 'např. `invoice.xml.read`, `connection.update`, `auth.login`' }
        entity_type: { type: [string, 'null'] }
        entity_id: { type: [string, 'null'] }
        ip: { type: [string, 'null'] }
        request_id: { type: [string, 'null'] }
        details: { type: [object, 'null'], additionalProperties: true }
    AuditLogPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/AuditLogEntry' }
        next_cursor: { type: [string, 'null'] }
    ValidationSummaryItem:
      type: object
      required: [rule_id, severity, source, message_sample, count, invoice_count, tenant_count, last_seen_at]
      properties:
        rule_id: { type: string }
        severity: { $ref: '#/components/schemas/FindingSeverity' }
        source: { $ref: '#/components/schemas/FindingSource' }
        message_sample: { type: string }
        count: { type: integer }
        invoice_count: { type: integer }
        tenant_count: { type: integer }
        last_seen_at: { type: string, format: date-time }

    # ---------------------------------------------------------------- předodesílací validace (V-CORE, ADR 032)
    ValidationLayerReport:
      type: object
      required: [name, status, duration_ms]
      properties:
        name: { type: string, description: 'Id vrstvy: `xsd_schematron`, `sk_national`, `party_format`, `registry`, `routing`, `obligation`, `timing`, `tdd_sk`, `provider_dryrun:<modul>`, `external:<id>`' }
        status: { type: string, enum: [ok, skipped, unavailable, error] }
        duration_ms: { type: integer, minimum: 0 }
        as_of: { type: string, format: date-time, description: Stáří dat vrstvy (např. registry) }
        meta: { type: object, additionalProperties: true, description: 'Důvod přeskočení (`reason`), verze artefaktů apod.' }
    ValidationObligation:
      type: object
      required: [decision, reasons]
      properties:
        decision: { type: string, enum: [FORBIDDEN, MANDATORY, OPTIONAL, NOT_APPLICABLE, UNDETERMINED] }
        reasons: { type: array, items: { type: string }, description: 'Kódy `OBL-*`' }
    ValidationDisagreement:
      type: object
      required: [layers, local, provider, rule_ids]
      properties:
        layers: { type: array, items: { type: string } }
        local: { type: string, enum: [ok, error] }
        provider: { type: string, enum: [ok, error] }
        rule_ids: { type: array, items: { type: string } }
    ValidationRecipient:
      type: object
      required: [peppol_id, registered, source]
      properties:
        peppol_id: { type: [string, 'null'] }
        registered: { type: [boolean, 'null'] }
        source: { type: [string, 'null'], description: 'smp | adapter' }
        as_of: { type: string, format: date-time }
    ValidationReport:
      type: object
      required: [verdict, can_send, mode, findings, layers, artefact_versions, disagreements, generated_at]
      properties:
        verdict: { type: string, enum: [pass, pass_with_warnings, blocked] }
        can_send: { type: boolean }
        mode: { type: string, enum: [dryrun, enforce, inbound_recheck, inbound_ingest] }
        findings:
          type: array
          description: Řazeno error, warning, info. Texty podle `Accept-Language`, všechny jazyky v `messages`.
          items: { $ref: '#/components/schemas/ValidationFinding' }
        layers:
          type: array
          items: { $ref: '#/components/schemas/ValidationLayerReport' }
        artefact_versions: { type: object, additionalProperties: true, description: 'Verze validátoru, Peppol BIS, SK pravidel, TDD, enginu' }
        obligation: { $ref: '#/components/schemas/ValidationObligation' }
        disagreements:
          type: array
          items: { $ref: '#/components/schemas/ValidationDisagreement' }
        recipient: { $ref: '#/components/schemas/ValidationRecipient' }
        encoding: { $ref: '#/components/schemas/EncodingInfo' }
        generated_at: { type: string, format: date-time }
    ValidationRun:
      type: object
      description: Uložený běh předodesílací validace faktury (`validation_runs` + `validation_findings`). XML se neukládá, jen `xml_sha256`.
      required: [id, invoice_id, mode, verdict, can_send, xml_sha256, doc_type, connection_id, layers, disagreements, artefact_versions, duration_ms, created_at, findings]
      properties:
        id: { type: string, format: uuid }
        invoice_id: { type: [string, 'null'], format: uuid }
        mode: { type: string, enum: [dryrun, enforce, inbound_recheck, inbound_ingest] }
        verdict: { type: string, enum: [pass, pass_with_warnings, blocked] }
        can_send: { type: boolean }
        xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        doc_type: { type: [string, 'null'] }
        connection_id: { type: [string, 'null'], format: uuid }
        layers:
          type: array
          items: { $ref: '#/components/schemas/ValidationLayerReport' }
        disagreements:
          type: array
          items: { $ref: '#/components/schemas/ValidationDisagreement' }
        artefact_versions: { type: [object, 'null'], additionalProperties: true }
        duration_ms: { type: [integer, 'null'], minimum: 0 }
        created_at: { type: string, format: date-time }
        findings:
          type: array
          description: Řazeno error, warning, info (stejně jako v reportu).
          items: { $ref: '#/components/schemas/ValidationFinding' }
    ValidationRunList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/ValidationRun' }
    InvoiceRevalidation:
      type: object
      description: Výsledek opakované kontroly příchozí faktury (ADR 042).
      required: [invoice_id, run, validation_status_before, validation_status_after, status_changed]
      properties:
        invoice_id: { type: string, format: uuid }
        run: { $ref: '#/components/schemas/ValidationRun' }
        validation_status_before: { $ref: '#/components/schemas/ValidationStatus' }
        validation_status_after: { $ref: '#/components/schemas/ValidationStatus' }
        status_changed: { type: boolean }
    RevalidationFilter:
      type: object
      properties:
        direction: { type: string, enum: [inbound] }
        issue_date_from: { type: string, pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' }
        issue_date_to: { type: string, pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' }
        validation_status: { $ref: '#/components/schemas/ValidationStatus' }
    RevalidateInvoicesRequest:
      type: object
      properties:
        filter: { $ref: '#/components/schemas/RevalidationFilter' }
        limit: { type: integer, minimum: 1, maximum: 5000, description: 'Nejvýše tolik faktur (výchozí 1000; sandbox tenant 100).' }
    RevalidationJob:
      type: object
      required: [id, status, filter, limit, total, processed, changed, unchanged, failed, changes, failures, created_at, started_at, finished_at, error]
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [queued, running, done, failed] }
        filter: { $ref: '#/components/schemas/RevalidationFilter' }
        limit: { type: integer, minimum: 1, maximum: 5000 }
        total: { type: [integer, 'null'], minimum: 0, description: 'Počet faktur vybraných filtrem (po spuštění úlohy)' }
        processed: { type: integer, minimum: 0 }
        changed: { type: integer, minimum: 0, description: 'Faktury, kterým se změnil validation_status' }
        unchanged: { type: integer, minimum: 0 }
        failed: { type: integer, minimum: 0 }
        changes:
          type: array
          description: Nejvýše 500 položek
          items:
            type: object
            required: [invoice_id, from, to]
            properties:
              invoice_id: { type: string, format: uuid }
              from: { $ref: '#/components/schemas/ValidationStatus' }
              to: { $ref: '#/components/schemas/ValidationStatus' }
        failures:
          type: array
          description: Nejvýše 500 položek
          items:
            type: object
            required: [invoice_id, code]
            properties:
              invoice_id: { type: string, format: uuid }
              code: { type: string }
        created_at: { type: string, format: date-time }
        started_at: { type: [string, 'null'], format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        error: { oneOf: [{ $ref: '#/components/schemas/ErrorSummary' }, { type: 'null' }] }
    RevalidationJobPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/RevalidationJob' }
        next_cursor: { type: [string, 'null'] }
    ValidateInvoiceRequest:
      type: object
      required: [xml_base64]
      properties:
        xml_base64: { type: string, contentEncoding: base64 }
        encoding: { type: string, maxLength: 40, description: 'Kódování bajtů v `xml_base64` (např. `windows-1250`); ekvivalent `charset` v Content-Type. Viz `EncodingInfo`.' }
        connection_id: { type: string, format: uuid }
        options:
          type: object
          description: Požadavek smí nastavení jen ZPŘÍSNIT (nikdy nevypnout vrstvu ani nesnížit závažnost).
          properties:
            layers: { type: array, items: { type: string }, description: 'Vrstvy, které se mají zapnout' }
            strict: { type: boolean }
            require_provider_dryrun: { type: boolean }
            provider_dryrun: { type: string, enum: [auto, manual, off, force] }
            locale: { type: string, enum: [sk, cs, en] }
            skip_recipient_lookup: { type: boolean }
            confidential_supply: { type: boolean, description: '`true` = utajované plnění => e-fakturu nelze vystavit (OBL-FORBIDDEN); `false` = potvrzeno, že není.' }
            recipient_sis_vo: { type: boolean, description: '`true` = příjemce je SIS / Vojenské spravodajství => zákaz; `false` = potvrzeno, že není.' }
            check_routing: { type: boolean, description: 'Výslovně ověřit příjemce v Peppolu (SMP / poštář). Bez něj se vrstva `routing` spouští jen při `routing_default=always`.' }
    ValidationRouting:
      type: object
      required: [dic, peppol_id, registered, source, as_of]
      properties:
        dic: { type: string }
        peppol_id: { type: string }
        registered: { type: [boolean, 'null'], description: '`null` = nelze zjistit (SMP vypnuto a poštář bez lookup, nebo výpadek)' }
        source: { type: [string, 'null'], description: 'smp | adapter' }
        as_of: { type: [string, 'null'], format: date-time }
        provider: { type: string, description: 'Poštář příjemce podle SMP (je-li znám)' }
        access_point_url: { type: string }
        reason: { type: string, description: 'Proč `registered=null` (smp_disabled, unavailable, no_lookup_source, invalid_dic)' }
    ValidationLayerInfo:
      type: object
      required: [id, kind, enabled, mode]
      properties:
        id: { type: string }
        kind: { type: string }
        enabled: { type: boolean }
        mode: { type: string }
    ValidationProviderInfo:
      type: object
      required: [connection_id, name, provider_type, dry_run_supported, cost_class, default_mode]
      properties:
        connection_id: { type: string, format: uuid }
        name: { type: string }
        provider_type: { type: string }
        dry_run_supported: { type: boolean }
        cost_class: { type: string, enum: [free, metered, unknown] }
        default_mode: { type: string, enum: [run, manual, off] }
    ValidationRegistrySource:
      type: object
      required: [name, as_of, age_days]
      properties:
        name: { type: string }
        as_of: { type: string, format: date-time }
        age_days: { type: integer }
        rows: { type: integer }
    ValidationLayers:
      type: object
      required: [generated_at, validator, registry, layers, providers, settings]
      properties:
        generated_at: { type: string, format: date-time }
        validator:
          type: object
          required: [status, version, artefact_versions]
          properties:
            status: { type: string, enum: [up, down] }
            version: { type: [string, 'null'] }
            artefact_versions: { type: [object, 'null'], additionalProperties: true }
        registry:
          type: object
          required: [status, sources]
          properties:
            status: { type: string, enum: [up, stale, not_configured, down] }
            sources:
              type: array
              items: { $ref: '#/components/schemas/ValidationRegistrySource' }
        layers:
          type: array
          items: { $ref: '#/components/schemas/ValidationLayerInfo' }
        providers:
          type: array
          items: { $ref: '#/components/schemas/ValidationProviderInfo' }
        settings: { type: object, additionalProperties: true, description: Účinné nastavení tenanta }
    PresendSettingsDoc:
      type: object
      required: [scope, tenant_id, values, effective, version, updated_at]
      properties:
        scope: { type: string, enum: [system, tenant] }
        tenant_id: { type: [string, 'null'], format: uuid }
        values: { type: object, additionalProperties: true }
        effective: { type: object, additionalProperties: true }
        version: { type: integer, minimum: 0 }
        updated_at: { type: [string, 'null'], format: date-time }
    PresendSettingsUpdate:
      type: object
      required: [values]
      properties:
        values: { type: object, additionalProperties: true }
        expected_version: { type: integer, minimum: 0 }
    ExcludedRecipient:
      type: object
      required: [id, dic, ico, label, created_at]
      properties:
        id: { type: string, format: uuid }
        dic: { type: [string, 'null'] }
        ico: { type: [string, 'null'] }
        label: { type: string }
        created_at: { type: string, format: date-time }
    ExcludedRecipientList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/ExcludedRecipient' }
    ExcludedRecipientCreate:
      type: object
      required: [label]
      properties:
        dic: { type: string, pattern: '^[0-9]{10}$' }
        ico: { type: string, pattern: '^[0-9]{8}$' }
        label: { type: string, minLength: 1, maxLength: 200 }

    # ---------------------------------------------------------------- tenants / users / auth
    TenantSettings:
      type: object
      required: [issue_date_policy, warn_delivery_over_15_days, max_attachment_mb]
      properties:
        allow_self_billing: { type: boolean, description: 'Tenant smí odesílat samofakturaci (typy 389/261), kde je on odběratel (výchozí false). Validace jede profilem Peppol BIS Self-Billing 3.0.' }
        issue_date_policy:
          type: string
          enum: [reject, warn]
          description: Co dělat, když `IssueDate` != dnešní den (Europe/Bratislava). Výchozí `reject`.
        warn_delivery_over_15_days: { type: boolean, description: "Varovat, je-li od DeliveryDate/tax point víc než 15 dní (výchozí true)" }
        max_attachment_mb: { type: integer, minimum: 1, maximum: 100, description: Výchozí 100 }
        default_input_encoding:
          type: [string, 'null']
          description: 'Kódování XML vstupu, které se použije jen když volající nezadal `charset`/`encoding` a dokument nemá BOM ani deklaraci (CODEPAGE-INPUT-SPEC §0.4). `null`/`utf-8` = detekce platnosti UTF-8.'
        reject_unspecified_encoding: { type: boolean, description: 'Při true vrací vstup bez parametru, BOM a deklarace kódování vždy `422 ENCODING_AMBIGUOUS` (výchozí false).' }
        notification_language: { type: string, enum: [sk, cs, en], description: 'Jazyk e-mailových upozornění klientovi (NS-4). Bez hodnoty se odvodí ze země klienta (CZ = cs), jinak platí jazyk platformy.' }
    Tenant:
      type: object
      required: [id, name, dic, ico, ic_dph, is_vat_payer, vat_group_member, status, peppol_id, address, contact_email, settings, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        dic: { type: string, pattern: '^[0-9]{10}$' }
        ico: { type: [string, 'null'], pattern: '^[0-9]{8}$' }
        ic_dph: { type: [string, 'null'], pattern: '^SK[0-9]{10}$' }
        is_vat_payer: { type: boolean }
        vat_group_member: { type: boolean, description: 'Člen skupiny DPH (§ 4b): `ic_dph` je sdílené IČ DPH skupiny (typicky 7020…) a nemusí být „SK“+DIČ; EndpointID na faktuře je DIČ člena. Členství lze zjistit i z registru (`§4b`).' }
        sandbox: { type: boolean, description: 'Sandbox tenant: odeslání vždy do mock poštáře (simulovaný průběh), `test` není nutný; odpovědi nesou `X-Environment: sandbox`. Nastavuje jen platformní admin; produkční profil s takovým tenantem nenastartuje.' }
        status: { $ref: '#/components/schemas/TenantStatus' }
        peppol_id: { type: string, description: '`0245:<DIČ>` (odvozené, jen čtení)' }
        address: { oneOf: [{ $ref: '#/components/schemas/Address' }, { type: 'null' }] }
        contact_email: { type: [string, 'null'], format: email }
        settings: { $ref: '#/components/schemas/TenantSettings' }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    TenantCreate:
      type: object
      required: [name, dic, contact_email]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        dic: { type: string, pattern: '^[0-9]{10}$' }
        ico: { type: string, pattern: '^[0-9]{8}$' }
        ic_dph: { type: string, pattern: '^SK[0-9]{10}$' }
        is_vat_payer: { type: boolean, default: true }
        vat_group_member: { type: boolean, default: false }
        sandbox: { type: boolean, default: false }
        address: { $ref: '#/components/schemas/Address' }
        contact_email: { type: string, format: email, maxLength: 254, description: 'POVINNÝ kontaktní e-mail klienta = jediný příjemce tenantových upozornění (ADR 014). Měnit lze přes PATCH.' }
        settings: { $ref: '#/components/schemas/TenantSettings' }
    TenantUpdate:
      type: object
      minProperties: 1
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        ico: { type: string, pattern: '^[0-9]{8}$' }
        ic_dph: { type: string, pattern: '^SK[0-9]{10}$' }
        is_vat_payer: { type: boolean }
        vat_group_member: { type: boolean }
        sandbox: { type: boolean }
        status: { $ref: '#/components/schemas/TenantStatus' }
        address: { $ref: '#/components/schemas/Address' }
        contact_email: { type: string, format: email, maxLength: 254, description: 'Nelze vynulovat (povinné); hodnota *@efakt.invalid je zástupná po migraci a admin ji má nahradit.' }
        settings: { $ref: '#/components/schemas/TenantSettings' }
    TenantPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Tenant' }
        next_cursor: { type: [string, 'null'] }
    TenantSummary:
      type: object
      required: [id, name, dic, peppol_id, status, role]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        dic: { type: string }
        peppol_id: { type: string }
        status: { $ref: '#/components/schemas/TenantStatus' }
        role: { $ref: '#/components/schemas/Role' }
    Membership:
      type: object
      required: [user_id, tenant_id, role, email, created_at, revoked_at]
      properties:
        user_id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        role: { type: string, enum: [tenant_user, tenant_viewer] }
        email: { type: string, format: email }
        created_at: { type: string, format: date-time }
        revoked_at: { type: [string, 'null'], format: date-time }
    MembershipUpsert:
      type: object
      required: [role]
      properties:
        role: { type: string, enum: [tenant_user, tenant_viewer] }
    UserMembership:
      type: object
      description: Aktivní (nezrušené) členství uživatele v tenantu.
      required: [tenant_id, tenant_name, role]
      properties:
        tenant_id: { type: string, format: uuid }
        tenant_name: { type: string }
        role: { type: string, enum: [tenant_user, tenant_viewer] }
    User:
      type: object
      required: [id, email, name, role, disabled, totp_enabled, memberships, last_login_at, created_at]
      properties:
        id: { type: string, format: uuid }
        email: { type: string, format: email }
        name: { type: [string, 'null'] }
        role: { type: string, enum: [admin, user], description: 'Globální role: `admin` (správce portálu) nebo `user` (práva dána členstvími)' }
        disabled: { type: boolean }
        totp_enabled: { type: boolean }
        memberships:
          type: array
          description: 'Aktivní členství v tenantech (správa: `/admin/tenants/{id}/memberships`). Administrátor může mít prázdné pole (vidí všechny tenanty).'
          items: { $ref: '#/components/schemas/UserMembership' }
        last_login_at: { type: [string, 'null'], format: date-time }
        created_at: { type: string, format: date-time }
    UserCreated:
      description: Odpověď na založení uživatele. `initial_password` je vyplněno jen když `password` v požadavku chybělo; zobrazí se JEDINOU odpovědí (v DB jen hash).
      allOf:
        - { $ref: '#/components/schemas/User' }
        - type: object
          required: [initial_password]
          properties:
            initial_password: { type: [string, 'null'], description: 'Vygenerované počáteční heslo (min. 12 znaků), nebo null, pokud heslo zadal administrátor nebo byla odeslána pozvánka' }
            invitation_sent: { type: boolean, description: 'true = je-li nastaveno SMTP a heslo chybělo, uživatel dostal e-mail s jednorázovým odkazem pro nastavení hesla (`initial_password` je pak null; ADR 014)' }
    SettingKey:
      type: string
      enum: [smtp, platform_admin_emails, default_language, default_timezone, security, ai_refresher, branding, backup_notifications, presend_validation, registries, input_encoding, forwarding]
    SettingSource:
      type: string
      description: 'Odkud se účinná hodnota bere: `db` (uloženo v admin UI), `env` (proměnné prostředí/runtime secret), `default` (výchozí/nenastaveno).'
      enum: [db, env, default]
    SettingState:
      type: string
      enum: [not_configured, disabled, configured, unknown]
    SettingStatus:
      type: object
      required: [state, source, last_success_at, last_error, last_error_at]
      properties:
        state: { $ref: '#/components/schemas/SettingState' }
        source: { $ref: '#/components/schemas/SettingSource' }
        last_success_at: { type: [string, 'null'], format: date-time }
        last_error: { type: [string, 'null'], description: 'Poslední chyba (bez tajemství)' }
        last_error_at: { type: [string, 'null'], format: date-time }
    SystemSetting:
      type: object
      description: Jedno nastavení systému. `values` nikdy neobsahuje tajná pole (jen `secrets_set` = jména nastavených tajných polí). `version` 0 = nikdy neuloženo (platí výchozí/env).
      required: [key, schema_version, version, source, values, secrets_set, fields, status, updated_at, updated_by]
      properties:
        key: { $ref: '#/components/schemas/SettingKey' }
        schema_version: { type: integer, minimum: 1 }
        version: { type: integer, minimum: 0 }
        source: { $ref: '#/components/schemas/SettingSource' }
        values: { type: object, additionalProperties: true }
        secrets_set: { type: array, items: { type: string } }
        fields:
          type: array
          items: { $ref: '#/components/schemas/ProviderFieldSpec' }
        status: { oneOf: [{ $ref: '#/components/schemas/SettingStatus' }, { type: 'null' }] }
        updated_at: { type: [string, 'null'], format: date-time }
        updated_by: { type: [string, 'null'], description: 'E-mail admina, který nastavení naposledy změnil' }
    SystemSettingList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/SystemSetting' }
    SystemSettingUpdate:
      type: object
      required: [values]
      properties:
        values: { type: object, additionalProperties: true }
        secrets: { type: object, additionalProperties: { type: string, maxLength: 1024 }, description: 'Write-only tajná pole (nastavit/nahradit). Nepřítomné pole = beze změny.' }
        clear_secrets: { type: array, items: { type: string }, description: 'Jména tajných polí ke smazání' }
        expected_version: { type: integer, minimum: 0, description: 'Optimistický zámek (neshoda = 409)' }
    SmtpTestRequest:
      type: object
      required: [to]
      properties:
        to: { type: string, format: email, maxLength: 254 }
    SettingsTestResult:
      type: object
      required: [ok, code, message, detail, duration_ms, tested_at, info]
      properties:
        ok: { type: boolean }
        code: { type: string, description: 'Strojový kód: OK, SMTP_NOT_CONFIGURED, DNS_FAILED, SSRF_BLOCKED, CONNECT_FAILED, TIMEOUT, TLS_FAILED, AUTH_FAILED, REJECTED, OLLAMA_UNAVAILABLE, OLLAMA_BAD_RESPONSE, ...' }
        message: { type: string, description: 'Srozumitelná zpráva bez tajemství' }
        detail: { type: [string, 'null'] }
        duration_ms: { type: integer }
        tested_at: { type: string, format: date-time }
        info: { type: [object, 'null'], additionalProperties: true, description: 'Např. Ollama: `models` (jména), `model_available`.' }
    NotificationStatus:
      type: string
      enum: [pending, sent, failed, suppressed]
    NotificationScope:
      type: string
      enum: [tenant, platform]
    Notification:
      type: object
      description: Záznam outboxu. `params` jsou jen identifikátory (bez osobních údajů z faktur) a nikdy neobsahují jednorázové odkazy.
      required: [id, type, scope, tenant_id, tenant_name, recipients, language, params, status, attempts, next_attempt_at, error, reason_code, dedupe_key, occurrences, created_at, sent_at]
      properties:
        id: { type: string, format: uuid }
        type: { type: string }
        scope: { $ref: '#/components/schemas/NotificationScope' }
        tenant_id: { type: [string, 'null'], format: uuid }
        tenant_name: { type: [string, 'null'] }
        recipients: { type: array, items: { type: string } }
        language: { type: string, enum: [sk, cs, en] }
        params: { type: object, additionalProperties: true }
        status: { $ref: '#/components/schemas/NotificationStatus' }
        attempts: { type: integer }
        next_attempt_at: { type: string, format: date-time }
        error: { type: [string, 'null'] }
        reason_code: { type: [string, 'null'] }
        dedupe_key: { type: [string, 'null'] }
        occurrences: { type: integer }
        created_at: { type: string, format: date-time }
        sent_at: { type: [string, 'null'], format: date-time }
    NotificationPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Notification' }
        next_cursor: { type: [string, 'null'] }
    NotificationFlushResult:
      type: object
      required: [flushed, skipped]
      properties:
        flushed: { type: integer }
        skipped: { type: integer }
    PasswordResetRequest:
      type: object
      required: [email]
      properties:
        email: { type: string, format: email, maxLength: 254 }
    PasswordResetConfirm:
      type: object
      required: [token, password]
      properties:
        token: { type: string, minLength: 20, maxLength: 200 }
        password: { type: string, minLength: 12, maxLength: 200 }
    UserCreate:
      type: object
      required: [email]
      properties:
        email: { type: string, format: email }
        name: { type: string }
        role: { type: string, enum: [admin, user], default: user }
        password: { type: string, minLength: 12, maxLength: 200 }
    UserUpdate:
      type: object
      minProperties: 1
      properties:
        name: { type: string }
        role: { type: string, enum: [admin, user] }
        disabled: { type: boolean }
        reset_totp: { type: boolean, description: 'true => smaže TOTP tajemství, uživatel si ho zapíše znovu' }
        password: { type: string, minLength: 12, maxLength: 200 }
    UserPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/User' }
        next_cursor: { type: [string, 'null'] }
    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password: { type: string }
    LoginResponse:
      type: object
      required: [status, challenge_token, me]
      properties:
        status: { type: string, enum: [authenticated, totp_required, totp_enrollment_required] }
        challenge_token: { type: [string, 'null'], description: 'Pro `totp_required`; platí 5 minut, jednorázový' }
        me: { oneOf: [{ $ref: '#/components/schemas/Me' }, { type: 'null' }], description: Vyplněno jen při `authenticated` }
    TotpRequest:
      type: object
      required: [challenge_token, code]
      properties:
        challenge_token: { type: string }
        code: { type: string, description: 'Šestimístný TOTP nebo záložní kód', minLength: 6, maxLength: 20 }
    TotpEnrollment:
      type: object
      required: [secret_base32, otpauth_uri]
      properties:
        secret_base32: { type: string }
        otpauth_uri: { type: string }
    SwitchTenantRequest:
      type: object
      required: [tenant_id]
      properties:
        tenant_id: { type: string, format: uuid }
    Me:
      type: object
      required: [user, active_tenant, tenants, permissions, session_kind, csrf_token]
      properties:
        user: { $ref: '#/components/schemas/User' }
        permissions:
          type: array
          description: Oprávnění v aktivním tenantu (prázdné bez aktivního tenanta a v session `enrollment`). Administrátor má všechna včetně `admin`.
          items: { $ref: '#/components/schemas/Permission' }
        session_kind: { $ref: '#/components/schemas/SessionKind' }
        active_tenant: { oneOf: [{ $ref: '#/components/schemas/TenantSummary' }, { type: 'null' }], description: 'null pokud uživatel nemá žádného tenanta nebo ještě žádný nezvolil' }
        tenants:
          type: array
          items: { $ref: '#/components/schemas/TenantSummary' }
        csrf_token: { type: string, description: "Stejná hodnota jako cookie `efakt_csrf` (pro SPA po reloadu)" }

    # ---------------------------------------------------------------- API keys
    ApiKey:
      type: object
      required: [id, name, key_prefix, scopes, created_at, last_used_at, expires_at, revoked_at]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        key_prefix: { type: string, description: 'První znaky klíče pro identifikaci, např. `efk_a1b2c3d4`' }
        scopes:
          type: array
          items: { $ref: '#/components/schemas/ApiKeyScope' }
        created_at: { type: string, format: date-time }
        last_used_at: { type: [string, 'null'], format: date-time }
        expires_at: { type: [string, 'null'], format: date-time }
        revoked_at: { type: [string, 'null'], format: date-time }
        test_only: { type: boolean, description: 'Pověření jen pro testovací režim: všechna odeslání jsou vynucena do `test`, ostrý pokus (`test=false`) = `403 TEST_ONLY_CREDENTIAL`.' }
    ApiKeyCreate:
      type: object
      required: [name, scopes]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: '#/components/schemas/ApiKeyScope' }
        expires_at: { type: string, format: date-time }
        test_only: { type: boolean }
        template: { type: string, enum: [developer], description: 'Šablona „vývojářský klíč“: `test_only=true`, scopes `invoices:send`+`invoices:read` a platnost 90 dní, pokud nejsou zadány.' }
    ApiKeyCreated:
      allOf:
        - { $ref: '#/components/schemas/ApiKey' }
        - type: object
          required: [key]
          properties:
            key: { type: string, description: 'Plná hodnota `efk_<prefix>_<secret>` – zobrazí se pouze v této odpovědi' }

    # ---------------------------------------------------------------- webhooks
    WebhookEndpoint:
      type: object
      required: [id, url, events, description, enabled, created_at, disabled_at, secret_hint]
      properties:
        id: { type: string, format: uuid }
        url: { type: string, format: uri }
        events:
          type: array
          items: { $ref: '#/components/schemas/WebhookEventType' }
        description: { type: [string, 'null'] }
        enabled: { type: boolean }
        created_at: { type: string, format: date-time }
        disabled_at: { type: [string, 'null'], format: date-time }
        secret_hint: { type: string, description: 'Posledních 4 znaky tajemství (`…ab12`)' }
    WebhookCreate:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri, maxLength: 2000 }
        events:
          type: array
          minItems: 1
          uniqueItems: true
          items: { $ref: '#/components/schemas/WebhookEventType' }
        description: { type: string, maxLength: 200 }
    WebhookCreated:
      allOf:
        - { $ref: '#/components/schemas/WebhookEndpoint' }
        - type: object
          required: [secret]
          properties:
            secret: { type: string, description: '`whsec_<base64url>` – jen jednou' }
    WebhookDelivery:
      type: object
      required: [id, webhook_id, tenant_id, event_id, event_type, status, attempts, next_attempt_at, last_attempt_at, last_response_status, last_error, created_at]
      properties:
        id: { type: string, format: uuid }
        webhook_id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        event_id: { type: string, format: uuid }
        event_type: { $ref: '#/components/schemas/WebhookEventType' }
        status: { $ref: '#/components/schemas/WebhookDeliveryStatus' }
        attempts: { type: integer }
        next_attempt_at: { type: [string, 'null'], format: date-time }
        last_attempt_at: { type: [string, 'null'], format: date-time }
        last_response_status: { type: [integer, 'null'] }
        last_error: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
    WebhookDeliveryPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/WebhookDelivery' }
        next_cursor: { type: [string, 'null'] }
    WebhookInvoiceData:
      type: object
      description: Obsah `data` pro `invoice.*` události. Neobsahuje XML – stáhne se přes `GET /invoices/{id}/xml`.
      required: [invoice_id, direction, status, doc_type_code, invoice_number, issue_date, seller_peppol_id, buyer_peppol_id, total_gross, currency, connection_id, external_reference, reason_code, message, links]
      properties:
        invoice_id: { type: string, format: uuid }
        direction: { $ref: '#/components/schemas/Direction' }
        status: { $ref: '#/components/schemas/InvoiceStatus' }
        doc_type_code: { $ref: '#/components/schemas/DocumentTypeCode' }
        invoice_number: { type: string }
        issue_date: { type: string, format: date }
        seller_peppol_id: { type: [string, 'null'] }
        buyer_peppol_id: { type: [string, 'null'] }
        total_gross: { $ref: '#/components/schemas/Money' }
        currency: { type: string }
        connection_id: { type: [string, 'null'], format: uuid }
        external_reference: { type: [string, 'null'] }
        reason_code: { type: [string, 'null'], description: 'U `invoice.delivery_failed`: `RECIPIENT_NOT_REGISTERED`, `PROVIDER_REJECTED`, ...' }
        message: { type: [string, 'null'] }
        links: { $ref: '#/components/schemas/InvoiceLinks' }
    WebhookEnvelope:
      type: object
      description: |
        Tělo POST na `url` webhooku (`Content-Type: application/json; charset=utf-8`).

        **Podpis:** hlavičky `X-Efakt-Event` (typ), `X-Efakt-Delivery` (id doručení, UUID), `X-Efakt-Timestamp` (UNIX sekundy),
        `X-Efakt-Signature: v1=<hex>` kde hex = HMAC-SHA256(secret, `<timestamp>.<raw body>`). Příjemce musí ověřit
        podpis nad **syrovým tělem** (konstantní čas) a odmítnout timestamp starší než 5 minut. Za úspěch se považuje 2xx do 10 s.
        **Retry:** 8 dalších pokusů po 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, 24 h (+-10 % jitter); poté `status=dead`
        (dead-letter, viditelné adminovi). Doručení je at-least-once: příjemce deduplikuje podle `id` (event_id).
      required: [id, type, created_at, tenant_id, api_version, data]
      properties:
        id: { type: string, format: uuid, description: event_id – stejný při všech retry }
        type: { $ref: '#/components/schemas/WebhookEventType' }
        created_at: { type: string, format: date-time }
        tenant_id: { type: string, format: uuid }
        api_version: { type: string, enum: [v1] }
        data:
          oneOf:
            - { $ref: '#/components/schemas/WebhookInvoiceData' }
            - type: object
              description: 'Pro `ping`'
              additionalProperties: true

    # ---------------------------------------------------------------- ERP API (ADR 015)
    ErpScope: { type: string, enum: [send, receive, status] }
    ErpClientStatus: { type: string, enum: [active, disabled] }
    ErpAuthMethod: { type: string, enum: [token, password] }
    ErpInboxState: { type: string, enum: [pending, leased, acknowledged, nack, quarantined] }
    ErpDelivery:
      type: object
      description: 'Příznak „převzato do ERP“: integrace a datum a čas potvrzení (UTC; UI zobrazuje Europe/Bratislava). Nemění XML ani hash.'
      required: [integration_id, integration_name, acknowledged_at]
      properties:
        integration_id: { type: string, format: uuid }
        integration_name: { type: string }
        acknowledged_at: { type: string, format: date-time }
    ErpCredentialInfo:
      type: object
      description: Metadata přihlašovacího údaje (nikdy hodnota ani hash).
      required: [id, kind, token_prefix, username, state, created_at, expires_at, revoked_at, last_used_at, last_used_ip, locked_until]
      properties:
        id: { type: string, format: uuid }
        kind: { $ref: '#/components/schemas/ErpAuthMethod' }
        token_prefix: { type: [string, 'null'] }
        username: { type: [string, 'null'] }
        state: { type: string, enum: [active, expired, revoked, locked] }
        created_at: { type: string, format: date-time }
        expires_at: { type: [string, 'null'], format: date-time }
        revoked_at: { type: [string, 'null'], format: date-time }
        last_used_at: { type: [string, 'null'], format: date-time }
        last_used_ip: { type: [string, 'null'] }
        locked_until: { type: [string, 'null'], format: date-time }
    ErpInboxCounts:
      type: object
      required: [pending, leased, acknowledged, nack, quarantined]
      properties:
        pending: { type: integer, minimum: 0 }
        leased: { type: integer, minimum: 0 }
        acknowledged: { type: integer, minimum: 0 }
        nack: { type: integer, minimum: 0 }
        quarantined: { type: integer, minimum: 0 }
    ErpIntegration:
      type: object
      required: [id, name, status, scopes, default_connection_id, ip_allowlist, backfill_from, nack_quarantine_after, created_at, disabled_at, last_used_at, credentials, inbox]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        status: { $ref: '#/components/schemas/ErpClientStatus' }
        scopes: { type: array, items: { $ref: '#/components/schemas/ErpScope' } }
        default_connection_id: { type: [string, 'null'], format: uuid }
        ip_allowlist: { type: array, items: { type: string } }
        backfill_from: { type: [string, 'null'], format: date-time }
        nack_quarantine_after: { type: integer }
        created_at: { type: string, format: date-time }
        disabled_at: { type: [string, 'null'], format: date-time }
        last_used_at: { type: [string, 'null'], format: date-time }
        credentials: { type: array, items: { $ref: '#/components/schemas/ErpCredentialInfo' } }
        inbox: { $ref: '#/components/schemas/ErpInboxCounts' }
        test_only: { type: boolean, description: 'Vývojářská integrace: všechna odeslání jsou vynucena do testovacího režimu.' }
    ErpIntegrationPage:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpIntegration' } }
    ErpIntegrationCreate:
      type: object
      required: [name, auth_methods]
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        scopes: { type: array, minItems: 1, maxItems: 3, items: { $ref: '#/components/schemas/ErpScope' } }
        default_connection_id: { type: string, format: uuid }
        ip_allowlist: { type: array, maxItems: 50, items: { type: string, maxLength: 60 } }
        auth_methods: { type: array, minItems: 1, maxItems: 2, items: { $ref: '#/components/schemas/ErpAuthMethod' } }
        token_expires_in_days: { type: integer, minimum: 1, maximum: 3650 }
        backfill_from: { type: string, format: date-time }
        nack_quarantine_after: { type: integer, minimum: 1, maximum: 100 }
        test_only: { type: boolean }
        template: { type: string, enum: [developer], description: 'Šablona „vývojářská integrace“: `test_only=true`, scopes send+status, token i heslo, token 90 dní, pokud nejsou zadány.' }
    ErpIntegrationUpdate:
      type: object
      required: []
      properties:
        name: { type: string, minLength: 1, maxLength: 120 }
        scopes: { type: array, minItems: 1, maxItems: 3, items: { $ref: '#/components/schemas/ErpScope' } }
        default_connection_id: { type: [string, 'null'], format: uuid }
        ip_allowlist: { type: array, maxItems: 50, items: { type: string, maxLength: 60 } }
        status: { $ref: '#/components/schemas/ErpClientStatus' }
        backfill_from: { type: [string, 'null'], format: date-time }
        nack_quarantine_after: { type: integer, minimum: 1, maximum: 100 }
        test_only: { type: boolean, description: 'Mění jen platformní admin (z tenantského API nelze příznak vypnout).' }
    ErpSecrets:
      type: object
      description: Tajemství – JEDINÝ výskyt (v DB jen prefix + hash). Nikdy se nevrací znovu.
      required: []
      properties:
        token: { type: string }
        username: { type: string }
        password: { type: string }
    ErpIntegrationCreated:
      allOf:
        - $ref: '#/components/schemas/ErpIntegration'
        - type: object
          required: [secrets]
          properties:
            secrets: { $ref: '#/components/schemas/ErpSecrets' }
    ErpCredentialRotate:
      type: object
      required: [kind]
      properties:
        kind: { $ref: '#/components/schemas/ErpAuthMethod' }
        overlap_hours: { type: integer, minimum: 0, maximum: 168, description: 'Jak dlouho platí dosavadní údaje téhož druhu (výchozí 24; 0 = ihned zneplatnit)' }
        expires_in_days: { type: integer, minimum: 1, maximum: 3650 }
    ErpCredentialRotated:
      type: object
      required: [credential, secrets, previous_valid_until]
      properties:
        credential: { $ref: '#/components/schemas/ErpCredentialInfo' }
        secrets: { $ref: '#/components/schemas/ErpSecrets' }
        previous_valid_until: { type: [string, 'null'], format: date-time }
    ErpTestCheck:
      type: object
      required: [id, ok, message]
      properties:
        id: { type: string }
        ok: { type: boolean }
        message: { type: string }
    ErpIntegrationTestResult:
      type: object
      required: [ok, checks, inbox, tested_at]
      properties:
        ok: { type: boolean }
        checks: { type: array, items: { $ref: '#/components/schemas/ErpTestCheck' } }
        inbox: { $ref: '#/components/schemas/ErpInboxCounts' }
        tested_at: { type: string, format: date-time }
    VfpToolFile:
      type: object
      required: [path, size, sha256]
      properties:
        path: { type: string }
        size: { type: integer, minimum: 0 }
        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
    VfpToolCompat:
      type: object
      required: [status, ok, portal_contract, contract_min, api]
      properties:
        status: { type: string, enum: [compatible, portal_older, api_major_differs, portal_newer_major] }
        ok: { type: boolean }
        portal_contract: { type: string }
        contract_min: { type: string }
        api: { type: string }
    VfpToolManifest:
      type: object
      required: [version, built_at, released_at, size_bytes, sha256, file_name, tested_with, changelog, api_compat, compat, files, previews, package_url, history]
      properties:
        version: { type: string }
        built_at: { type: string, format: date-time }
        released_at: { type: string, format: date-time }
        size_bytes: { type: integer, minimum: 1 }
        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        file_name: { type: string }
        tested_with: { type: string, description: 'Např. „Visual FoxPro 9.0 SP1 (build 5815); SP2 neověřeno“' }
        changelog: { type: string }
        api_compat:
          type: object
          required: [api, contract_min, contract_max]
          properties:
            api: { type: string }
            contract_min: { type: string }
            contract_max: { type: [string, 'null'] }
        compat: { $ref: '#/components/schemas/VfpToolCompat' }
        files: { type: array, items: { $ref: '#/components/schemas/VfpToolFile' } }
        previews: { type: array, items: { type: string } }
        package_url: { type: string }
        history:
          type: array
          items:
            type: object
            required: [version, built_at, sha256, size_bytes, changelog, tested_with, compat, latest]
            properties:
              version: { type: string }
              built_at: { type: string, format: date-time }
              sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
              size_bytes: { type: integer }
              changelog: { type: string }
              tested_with: { type: string }
              compat: { $ref: '#/components/schemas/VfpToolCompat' }
              latest: { type: boolean }
    ErpProblemItem:
      type: object
      required: [invoice_id, invoice_number, state, attempts, last_error, next_offer_at, updated_at]
      properties:
        invoice_id: { type: string, format: uuid }
        invoice_number: { type: string }
        state: { type: string, enum: [nack, quarantined] }
        attempts: { type: integer }
        last_error: { type: [string, 'null'] }
        next_offer_at: { type: [string, 'null'], format: date-time }
        updated_at: { type: string, format: date-time }
    ErpProblemPage:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpProblemItem' } }
        next_cursor: { type: [string, 'null'] }
    ErpProblemRelease:
      type: object
      required: [invoice_ids]
      properties:
        invoice_ids: { type: array, minItems: 1, maxItems: 200, items: { type: string, format: uuid } }
    ErpProblemReleaseResult:
      type: object
      required: [released]
      properties:
        released: { type: integer, minimum: 0 }
    ErpTokenRequest:
      type: object
      required: [username, password]
      properties:
        grant_type: { type: string, enum: [password] }
        username: { type: string, minLength: 1, maxLength: 100 }
        password: { type: string, minLength: 1, maxLength: 200 }
    ErpTokenResponse:
      type: object
      required: [access_token, token_type, expires_in, scope]
      properties:
        access_token: { type: string }
        token_type: { type: string, enum: [Bearer] }
        expires_in: { type: integer }
        scope: { type: string }
    ErpMeConnection:
      type: object
      required: [id, name, provider_type, capabilities, receive_mode, is_default_outbound, is_integration_default, enabled]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        provider_type: { type: string }
        capabilities: { type: array, items: { type: string, enum: [inbound, outbound] } }
        receive_mode: { type: [string, 'null'] }
        is_default_outbound: { type: boolean }
        is_integration_default: { type: boolean }
        enabled: { type: boolean }
    ErpMe:
      type: object
      required: [tenant, integration, connections, limits, server_time]
      properties:
        tenant: { type: object, required: [id, name, dic, peppol_id], properties: { id: { type: string, format: uuid }, name: { type: string }, dic: { type: string }, peppol_id: { type: string } } }
        integration: { type: object, required: [id, name, scopes, default_connection_id, auth_via, ip_allowlist], properties: { id: { type: string, format: uuid }, name: { type: string }, scopes: { type: array, items: { $ref: '#/components/schemas/ErpScope' } }, default_connection_id: { type: [string, 'null'], format: uuid }, auth_via: { type: string, enum: [token, basic] }, ip_allowlist: { type: array, items: { type: string } }, test_only: { type: boolean } } }
        connections: { type: array, items: { $ref: '#/components/schemas/ErpMeConnection' } }
        limits: { type: object, required: [max_batch_items, max_page_size, max_period_days, max_xml_bytes, lease_seconds_default, inline_xml_max_bytes], properties: { max_batch_items: { type: integer }, max_page_size: { type: integer }, max_period_days: { type: integer }, max_xml_bytes: { type: integer }, lease_seconds_default: { type: integer }, inline_xml_max_bytes: { type: integer } } }
        server_time: { type: string, format: date-time }
        capabilities:
          type: object
          description: 'Schopnosti serveru; `charsets` = kódování, která server na vstupu převádí do UTF-8 a umí vrátit jako odvozenou kopii (VFP klient podle toho posílá bajty beze změny s `charset`).'
          required: [charsets]
          properties:
            charsets: { type: array, items: { type: string } }
            bom_policy: { type: string, enum: [strip, keep] }
            source_xml: { type: boolean }
            test_mode: { type: boolean, description: 'Server umí testovací režim (`test`, `simulate`, `GET /test-runs/{id}`).' }
        test_mode:
          type: object
          required: [available, test_only, sandbox_tenant, rate_limit_per_minute, result_ttl_hours]
          properties:
            available: { type: boolean }
            test_only: { type: boolean, description: 'Pověření je `test_only`: ostrá odeslání jsou zakázána (403 TEST_ONLY_CREDENTIAL).' }
            sandbox_tenant: { type: boolean }
            rate_limit_per_minute: { type: integer }
            result_ttl_hours: { type: integer }
    ErpInvoiceEnvelope:
      type: object
      required: [xml_base64]
      properties:
        xml_base64: { type: string }
        connection_id: { type: string, format: uuid }
        tag: { type: string, maxLength: 64 }
        client_reference: { type: string, maxLength: 200 }
        encoding: { type: string, maxLength: 40, description: 'Kódování bajtů v `xml_base64` (viz `InvoiceSubmitEnvelope.encoding`).' }
        test: { type: boolean }
        simulate: { $ref: '#/components/schemas/TestSimulate' }
        simulate_webhooks: { type: boolean }
    ErpInvoiceAccepted:
      allOf:
        - $ref: '#/components/schemas/InvoiceAccepted'
        - type: object
          required: [client_reference, location]
          properties:
            client_reference: { type: [string, 'null'] }
            location: { type: string }
    ErpBatchItem:
      type: object
      required: [client_reference, xml_base64, idempotency_key]
      properties:
        client_reference: { type: string, minLength: 1, maxLength: 200 }
        xml_base64: { type: string }
        idempotency_key: { type: string, minLength: 1, maxLength: 200, pattern: '^[A-Za-z0-9._:-]+$' }
        connection_id: { type: string, format: uuid }
        tag: { type: string, maxLength: 64 }
        encoding: { type: string, maxLength: 40, description: 'Kódování bajtů této položky (per položka; viz `InvoiceSubmitEnvelope.encoding`).' }
        test: { type: boolean, description: 'Testovací režim jen pro tuto položku (globální `test` má přednost: true vyhrává).' }
        simulate: { $ref: '#/components/schemas/TestSimulate' }
        simulate_webhooks: { type: boolean }
    ErpBatchRequest:
      type: object
      description: Skutečný limit je `max_batch_items` z `GET /erp/me` (výchozí 50); nad limit `400`.
      required: [items]
      properties:
        items: { type: array, minItems: 1, maxItems: 500, items: { $ref: '#/components/schemas/ErpBatchItem' } }
        test: { type: boolean, description: 'Globální testovací režim pro celou dávku (také `?test=true` / `X-Test-Mode`).' }
        simulate: { $ref: '#/components/schemas/TestSimulate' }
        simulate_webhooks: { type: boolean }
    ErpBatchItemResult:
      type: object
      required: [client_reference, status, http_status, replayed, id, invoice_status, accepted, error]
      properties:
        client_reference: { type: string }
        status: { type: string, enum: [accepted, error, test_accepted] }
        http_status: { type: integer }
        replayed: { type: boolean }
        id: { type: [string, 'null'], format: uuid }
        invoice_status: { oneOf: [ { $ref: '#/components/schemas/OutboundStatus' }, { type: 'null' } ] }
        accepted: { oneOf: [ { $ref: '#/components/schemas/ErpInvoiceAccepted' }, { type: 'null' } ] }
        error: { oneOf: [ { $ref: '#/components/schemas/Problem' }, { type: 'null' } ] }
        test: { type: boolean, description: 'Jen u testovací položky; `id` je null, výsledek je v `test_result`.' }
        test_result: { oneOf: [ { $ref: '#/components/schemas/TestSubmitResponse' }, { type: 'null' } ] }
    ErpBatchResponse:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpBatchItemResult' } }
    ErpOutboxChange:
      type: object
      description: Změna stavu odeslané faktury (`id` = id faktury).
      required: [event_id, id, client_reference, invoice_number, status, previous_status, at, reason, message]
      properties:
        event_id: { type: string }
        id: { type: string, format: uuid }
        client_reference: { type: [string, 'null'] }
        invoice_number: { type: string }
        status: { $ref: '#/components/schemas/InvoiceStatus' }
        previous_status: { oneOf: [ { $ref: '#/components/schemas/InvoiceStatus' }, { type: 'null' } ] }
        at: { type: string, format: date-time }
        reason: { type: [string, 'null'] }
        message: { type: [string, 'null'] }
    ErpOutboxPage:
      type: object
      required: [items, next_cursor, has_more]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpOutboxChange' } }
        next_cursor: { type: string }
        has_more: { type: boolean }
    ErpParty:
      type: object
      required: [name, dic, ic_dph, peppol_id]
      properties:
        name: { type: string }
        dic: { type: [string, 'null'] }
        ic_dph: { type: [string, 'null'] }
        peppol_id: { type: [string, 'null'] }
    ErpInboxItem:
      type: object
      required: [id, invoice_number, doc_type_code, status, validation_status, issue_date, due_date, currency, seller, buyer, total_net, total_vat, total_gross, received_at, xml_missing, xml_sha256, xml_size_bytes, xml_url, xml_base64, attachments, erp_state, acknowledged_at, attempts]
      properties:
        id: { type: string, format: uuid }
        invoice_number: { type: string }
        doc_type_code: { $ref: '#/components/schemas/DocumentTypeCode' }
        status: { type: string, enum: [received, received_invalid, received_without_xml] }
        validation_status: { $ref: '#/components/schemas/ValidationStatus' }
        issue_date: { type: string, format: date }
        due_date: { type: [string, 'null'], format: date }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        seller: { $ref: '#/components/schemas/ErpParty' }
        buyer: { $ref: '#/components/schemas/ErpParty' }
        total_net: { $ref: '#/components/schemas/Money' }
        total_vat: { $ref: '#/components/schemas/Money' }
        total_gross: { $ref: '#/components/schemas/Money' }
        received_at: { type: string, format: date-time }
        xml_missing: { type: boolean }
        xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        xml_size_bytes: { type: integer }
        xml_url: { type: [string, 'null'] }
        xml_base64: { type: [string, 'null'], description: 'Jen s include=xml a do limitu velikosti odpovědi; jinak null (stáhněte přes xml_url).' }
        xml_encoding: { type: string, description: 'Jen s `charset`: kódování odvozené kopie v `xml_base64` (jinak je XML UTF-8).' }
        xml_derived_from_sha256: { type: string, pattern: '^[0-9a-f]{64}$', description: 'Jen s `charset`: SHA-256 UTF-8 verze, ze které je kopie odvozena (= `xml_sha256`).' }
        xml_encoding_error:
          type: object
          description: 'Jen s `charset`: kopii nelze vytvořit (`ENCODING_NOT_REPRESENTABLE`); `xml_base64` je null.'
          required: [code, detail]
          properties:
            code: { type: string }
            detail: { type: string }
            characters: { type: array, items: { $ref: '#/components/schemas/EncodingUnrepresentableChar' } }
        attachments: { type: array, items: { $ref: '#/components/schemas/AttachmentMeta' } }
        erp_state: { $ref: '#/components/schemas/ErpInboxState' }
        acknowledged_at: { type: [string, 'null'], format: date-time }
        attempts: { type: integer }
        duplicates:
          type: array
          description: 'Dodatečná XML a odlišné duplicity téže faktury; stahují se přes `xml_url`.'
          items:
            type: object
            required: [id, reason, received_at, xml_sha256, xml_size_bytes, xml_url]
            properties:
              id: { type: string, format: uuid }
              reason: { type: string, enum: [different_content, xml_supplement] }
              received_at: { type: string, format: date-time }
              xml_sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
              xml_size_bytes: { type: integer }
              xml_url: { type: string }
              acknowledged: { type: boolean, description: 'Jen `different_content`: tato integrace už duplicitu potvrdila (`POST /erp/inbox/conflicts/ack`).' }
    ErpInboxPage:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpInboxItem' } }
        next_cursor: { type: [string, 'null'] }
        ack_skipped:
          type: array
          description: 'Jen `by-period?ack=true`: položky, které se NEpotvrdí, a proč.'
          items:
            type: object
            required: [id, reason]
            properties:
              id: { type: string, format: uuid }
              reason: { type: string, enum: [quarantined, leased, nack_backoff, xml_missing, xml_not_inline] }
    ErpClaimResult:
      type: object
      required: [items, lease_seconds, lease_expires_at]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ErpInboxItem' } }
        lease_seconds: { type: integer }
        lease_expires_at: { type: [string, 'null'], format: date-time }
    ErpAckRequest:
      type: object
      required: [ids]
      properties:
        ids: { type: array, minItems: 1, maxItems: 500, items: { type: string, format: uuid } }
        erp_reference: { type: object, required: [id], properties: { id: { type: string, minLength: 1, maxLength: 200 } } }
    ErpAckResult:
      type: object
      required: [acknowledged, already_acknowledged, not_found, acknowledged_at]
      properties:
        acknowledged: { type: array, items: { type: string, format: uuid } }
        already_acknowledged: { type: array, items: { type: string, format: uuid } }
        not_found: { type: array, items: { type: string, format: uuid } }
        acknowledged_at: { type: string, format: date-time }
        rejected:
          type: array
          description: 'Faktury „bez XML“ bez dodatečného XML – nelze potvrdit.'
          items:
            type: object
            required: [id, reason]
            properties:
              id: { type: string, format: uuid }
              reason: { type: string, enum: [xml_missing] }
    ErpConflictAckRequest:
      type: object
      required: [duplicate_ids]
      properties:
        duplicate_ids: { type: array, minItems: 1, maxItems: 500, items: { type: string, format: uuid }, description: 'Identifikátory z `duplicates[].id` s `reason = different_content`.' }
        erp_reference: { type: object, required: [id], properties: { id: { type: string, minLength: 1, maxLength: 200 } } }
    ErpConflictAckResult:
      type: object
      required: [acknowledged, already_acknowledged, not_found, acknowledged_at]
      properties:
        acknowledged: { type: array, items: { type: string, format: uuid } }
        already_acknowledged: { type: array, items: { type: string, format: uuid } }
        not_found: { type: array, items: { type: string, format: uuid }, description: 'Neznámé duplicity, cizí tenant, nebo duplicity jiného druhu než `different_content`.' }
        acknowledged_at: { type: string, format: date-time }
    ErpNackRequest:
      type: object
      required: [id, reason]
      properties:
        id: { type: string, format: uuid }
        reason: { type: string, minLength: 1, maxLength: 500 }
    ErpNackResult:
      type: object
      required: [id, state, attempts, retry_at]
      properties:
        id: { type: string, format: uuid }
        state: { type: string, enum: [nack, quarantined] }
        attempts: { type: integer }
        retry_at: { type: [string, 'null'], format: date-time }
    ErpInboxStats:
      type: object
      required: [pending, leased, acknowledged, nack, quarantined, total_eligible, oldest_pending_received_at, last_ack_at]
      properties:
        pending: { type: integer, minimum: 0 }
        leased: { type: integer, minimum: 0 }
        acknowledged: { type: integer, minimum: 0 }
        nack: { type: integer, minimum: 0 }
        quarantined: { type: integer, minimum: 0 }
        total_eligible: { type: integer, minimum: 0 }
        oldest_pending_received_at: { type: [string, 'null'], format: date-time }
        last_ack_at: { type: [string, 'null'], format: date-time }
        withheld_xml_missing: { type: integer, minimum: 0, description: 'Faktury „bez XML“ bez dodatečného XML (nenabízejí se, nejsou v `pending`).' }
        conflicts: { type: integer, minimum: 0, description: 'Faktury s NEpotvrzenou odlišnou duplicitou (`by-period?state=conflict`); po `POST /erp/inbox/conflicts/ack` klesá.' }

    # ---------------------------------------------------------------- informace o poštářích (ADR 016)
    I18nText:
      type: object
      required: [sk, cs, en]
      properties:
        sk: { type: string, maxLength: 4000 }
        cs: { type: string, maxLength: 4000 }
        en: { type: string, maxLength: 4000 }
    SourceRef:
      type: object
      required: [url]
      properties:
        url: { type: string, maxLength: 500 }
        label: { type: string, maxLength: 200 }
        retrieved_at: { type: string, pattern: '^\d{4}-\d{2}-\d{2}$' }
    HelpTopic:
      type: object
      required: [title, body, links]
      properties:
        title: { $ref: '#/components/schemas/I18nText' }
        body: { $ref: '#/components/schemas/I18nText' }
        links:
          type: array
          items:
            type: object
            required: [url, label]
            properties:
              url: { type: string }
              label: { $ref: '#/components/schemas/I18nText' }
    ProviderInfo:
      type: object
      required: [provider_type, kind, version, updated_at, ai_unverified, content]
      properties:
        provider_type: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' }
        kind: { type: string, enum: [module, reseller, info_only, help] }
        version: { type: integer, minimum: 1 }
        updated_at: { type: string, format: date-time }
        ai_unverified: { type: boolean, description: 'Jen admin: poslední publikovaná verze vznikla automaticky (AI) a člověk ji nepotvrdil. Tenantovi vždy false.' }
        content:
          type: object
          additionalProperties: true
          description: |
            Obsah poštáře podle zod schématu `ProviderInfoContentSchema` (packages/contracts/src/schemas/provider-info.ts; JSON Schema `schemas/provider-info.schema.json`).
            **Tenant dostane jen veřejnou část** (bez `pricing`, `commercial_terms`, `ai_refresh` a položek s `audience: admin`); admin plný obsah. Chybějící údaj = `null`/nepřítomné pole = UI „nezjištěno“.
    ProviderInfoList:
      type: object
      required: [items, help, logos_enabled, generated_at]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ProviderInfo' } }
        help:
          type: object
          additionalProperties: { $ref: '#/components/schemas/HelpTopic' }
          description: Témata nápovědy „?“ (klíč = id tématu), SK/CZ/EN z jednoho zdroje.
        logos_enabled: { type: boolean }
        generated_at: { type: string, format: date-time }
    ProviderInfoChange:
      type: object
      required: [pointer, label, before, after, risky, reason, source_url, quote]
      properties:
        pointer: { type: string }
        label: { type: [string, 'null'] }
        before: { description: Hodnota před změnou (JSON) }
        after: { description: Hodnota po změně (JSON) }
        risky: { type: boolean, description: 'Riziková změna (cena, retence, odstranění funkce) – „doporučeno ověřit“.' }
        reason: { type: [string, 'null'] }
        source_url: { type: [string, 'null'] }
        quote: { type: [string, 'null'] }
    ProviderInfoVersion:
      type: object
      required: [id, provider_type, version, status, created_by_kind, created_by_label, created_at, change_summary, source_refs, changes, reverted_from, run_id]
      properties:
        id: { type: string, format: uuid }
        provider_type: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' }
        version: { type: integer, minimum: 1 }
        status: { type: string, enum: [published, pending_review, reverted] }
        created_by_kind: { type: string, enum: [human, ai, import] }
        created_by_label: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        change_summary: { type: string }
        source_refs: { type: array, items: { $ref: '#/components/schemas/SourceRef' } }
        changes: { type: array, items: { $ref: '#/components/schemas/ProviderInfoChange' } }
        reverted_from: { type: [integer, 'null'] }
        run_id: { type: [string, 'null'], format: uuid }
    ProviderInfoVersionList:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ProviderInfoVersion' } }
    ProviderInfoVersionDetail:
      allOf:
        - { $ref: '#/components/schemas/ProviderInfoVersion' }
        - type: object
          required: [content]
          properties:
            content: { type: object, additionalProperties: true }
    AdminProviderInfo:
      type: object
      required: [provider_type, kind, version, status, created_by_kind, created_at, ai_unverified, ai_changes, content]
      properties:
        provider_type: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' }
        kind: { type: string, enum: [module, reseller, info_only, help] }
        version: { type: integer, minimum: 1 }
        status: { type: string, enum: [published, pending_review, reverted] }
        created_by_kind: { type: string, enum: [human, ai, import] }
        created_at: { type: string, format: date-time }
        ai_unverified: { type: boolean }
        ai_changes:
          type: array
          description: Změny od AI od poslední lidské verze (nejnovější první).
          items:
            allOf:
              - { $ref: '#/components/schemas/ProviderInfoChange' }
              - type: object
                required: [version, at]
                properties:
                  version: { type: integer }
                  at: { type: string, format: date-time }
        content: { type: object, additionalProperties: true }
    AiStatus:
      type: object
      required: [state, enabled, message, model, schedule, next_run_hint, checked_at]
      properties:
        state: { type: string, enum: [ready, disabled, not_configured, unavailable, model_missing] }
        enabled: { type: boolean }
        message: { type: string }
        model: { type: [string, 'null'] }
        schedule: { type: [string, 'null'] }
        next_run_hint: { type: [string, 'null'] }
        checked_at: { type: string, format: date-time }
    AdminProviderInfoSummary:
      type: object
      required: [provider_type, kind, display_name, version, created_by_kind, created_at, last_verified_at, ai_unverified, pending_versions]
      properties:
        provider_type: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' }
        kind: { type: string, enum: [module, reseller, info_only, help] }
        display_name: { type: string }
        version: { type: integer }
        created_by_kind: { type: string, enum: [human, ai, import] }
        created_at: { type: string, format: date-time }
        last_verified_at: { type: [string, 'null'], pattern: '^\d{4}-\d{2}-\d{2}$' }
        ai_unverified: { type: boolean }
        pending_versions: { type: integer }
    AdminProviderInfoList:
      type: object
      required: [items, json_schema, help_json_schema, ai, logos_enabled]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/AdminProviderInfoSummary' } }
        json_schema: { type: object, additionalProperties: true }
        help_json_schema: { type: object, additionalProperties: true }
        ai: { $ref: '#/components/schemas/AiStatus' }
        logos_enabled: { type: boolean }
    ProviderInfoPut:
      type: object
      required: [content]
      properties:
        content: { type: object, additionalProperties: true }
        change_summary: { type: string, maxLength: 2000 }
        expected_version: { type: integer, minimum: 0 }
        verify: { type: boolean }
    ProviderInfoRevert:
      type: object
      required: [to_version]
      properties:
        to_version: { type: integer, minimum: 1 }
        change_summary: { type: string, maxLength: 2000 }
    ProviderInfoRun:
      type: object
      required: [id, trigger, status, provider_types, model, ollama_host, pages, summary, error_code, error_message, created_at, started_at, finished_at, duration_ms]
      properties:
        id: { type: string, format: uuid }
        trigger: { type: string, enum: [schedule, manual, patch] }
        status: { type: string, enum: [queued, running, succeeded, partial, failed, aborted, unavailable, selftest_failed] }
        provider_types: { type: array, items: { type: string } }
        model: { type: [string, 'null'] }
        ollama_host: { type: [string, 'null'] }
        pages: { type: array, items: { type: object, additionalProperties: true } }
        summary: { type: object, additionalProperties: true }
        error_code: { type: [string, 'null'] }
        error_message: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        started_at: { type: [string, 'null'], format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        duration_ms: { type: [integer, 'null'] }
    ProviderInfoRunList:
      type: object
      required: [items, ai]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/ProviderInfoRun' } }
        ai: { $ref: '#/components/schemas/AiStatus' }
    ProviderInfoRefreshRequest:
      type: object
      properties:
        provider_types: { type: array, maxItems: 30, items: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' } }
    ProviderInfoPatchOp:
      type: object
      required: [pointer, value, source_url, quote]
      properties:
        pointer: { type: string, pattern: '^/[A-Za-z0-9_@/.-]{1,200}$' }
        value: { oneOf: [{ type: number }, { type: boolean }, { type: string, maxLength: 500 }] }
        source_url: { type: string, maxLength: 500 }
        quote: { type: string, minLength: 3, maxLength: 1000 }
    ProviderInfoPatchRequest:
      type: object
      required: [provider_type, ops]
      properties:
        provider_type: { type: string, pattern: '^[a-z][a-z0-9_]{1,62}$' }
        ops: { type: array, minItems: 1, maxItems: 50, items: { $ref: '#/components/schemas/ProviderInfoPatchOp' } }
        require_review: { type: boolean }
    ProviderInfoPatchResult:
      type: object
      required: [version, status, applied, rejected]
      properties:
        version: { type: [integer, 'null'] }
        status: { type: [string, 'null'], enum: [published, pending_review, reverted, null] }
        applied: { type: array, items: { $ref: '#/components/schemas/ProviderInfoChange' } }
        rejected:
          type: array
          items:
            type: object
            required: [pointer, reason]
            properties:
              pointer: { type: string }
              reason: { type: string }
    ProviderInfoExportBundle:
      type: object
      required: [manifest, files]
      properties:
        manifest:
          type: object
          required: [format, exported_at, files]
          properties:
            format: { type: integer, enum: [1] }
            exported_at: { type: string, format: date-time }
            files:
              type: array
              items:
                type: object
                required: [path, provider_type, version, sha256]
                properties:
                  path: { type: string }
                  provider_type: { type: string }
                  version: { type: integer }
                  sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        files:
          type: object
          description: 'Klíč = cesta souboru (`provider-info/<provider_type>.json`), hodnota = obsah.'
          additionalProperties: { type: object, additionalProperties: true }
    ProviderInfoImportRequest:
      type: object
      required: [files]
      properties:
        manifest: { type: object, additionalProperties: true }
        files: { type: object, additionalProperties: { type: object, additionalProperties: true } }
        change_summary: { type: string, maxLength: 2000 }
    ProviderInfoImportResult:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            type: object
            required: [provider_type, status, version, error]
            properties:
              provider_type: { type: string }
              status: { type: string, enum: [imported, unchanged, rejected] }
              version: { type: [integer, 'null'] }
              error: { type: [string, 'null'] }
    ProviderAssetUpload:
      type: object
      required: [content_type, data_base64]
      properties:
        content_type: { type: string, enum: [image/svg+xml, image/png, image/webp] }
        data_base64: { type: string, minLength: 4, maxLength: 300000 }
        source_url: { type: string, maxLength: 500 }
        license_note: { type: string, maxLength: 2000 }
    ProviderAsset:
      type: object
      required: [sha256, content_type, size_bytes, width, height, url]
      properties:
        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        content_type: { type: string, enum: [image/svg+xml, image/png, image/webp] }
        size_bytes: { type: integer }
        width: { type: [integer, 'null'] }
        height: { type: [integer, 'null'] }
        url: { type: string }

    VertecoBillingModel:
      type: string
      enum: [per_company, per_company_client, per_document]
    VertecoTenantState:
      type: string
      enum: [not_created, awaiting_activation, active, paused, smp_elsewhere, smp_pending, smp_rejected, receiving_elsewhere, inactive, released]
    VertecoFee:
      type: object
      required: [amount_eur, period, vat_excluded, paid_until]
      properties:
        amount_eur: { type: number }
        period: { type: string, const: year }
        vat_excluded: { type: boolean }
        paid_until: { type: [string, 'null'], format: date }
    VertecoPartnerCounts:
      type: object
      required: [total, awaiting_activation, active, paused, smp_elsewhere, released]
      properties:
        total: { type: integer }
        awaiting_activation: { type: integer }
        active: { type: integer }
        paused: { type: integer }
        smp_elsewhere: { type: integer }
        released: { type: integer }
    VertecoPartner:
      type: object
      required: [configured, status, environment, base_url, public_base_url, token_set, token_id, fs_key_set, reseller_key_set, webhook_secret_set, fs_webhook_configured, partner_webhook_configured, notification_webhook_url, billing_model, pending_billing_model, pending_billing_from, vpds_url, reseller_name, reseller_active, fee, credit_known, credit_eur, last_checked_at, last_error, counts, pending_events, dead_events, updated_at]
      properties:
        configured: { type: boolean, description: Je zadán partnerský token }
        status: { type: string, enum: [not_configured, ok, error] }
        environment: { type: string, enum: [sandbox, production] }
        base_url: { type: [string, 'null'] }
        public_base_url: { type: [string, 'null'] }
        token_set: { type: boolean }
        token_id: { type: [string, 'null'] }
        fs_key_set: { type: boolean }
        reseller_key_set: { type: boolean }
        webhook_secret_set: { type: boolean }
        fs_webhook_configured: { type: boolean }
        partner_webhook_configured: { type: boolean }
        notification_webhook_url: { type: [string, 'null'] }
        billing_model: { $ref: '#/components/schemas/VertecoBillingModel' }
        pending_billing_model: { oneOf: [{ $ref: '#/components/schemas/VertecoBillingModel' }, { type: 'null' }] }
        pending_billing_from: { type: [string, 'null'], format: date }
        vpds_url: { type: [string, 'null'] }
        reseller_name: { type: [string, 'null'] }
        reseller_active: { type: [boolean, 'null'] }
        fee: { $ref: '#/components/schemas/VertecoFee' }
        credit_known: { type: boolean, description: API Verteca kredit partnerského účtu neposkytuje (vždy false) }
        credit_eur: { type: [number, 'null'] }
        last_checked_at: { type: [string, 'null'], format: date-time }
        last_error: { type: [string, 'null'] }
        counts: { $ref: '#/components/schemas/VertecoPartnerCounts' }
        pending_events: { type: integer }
        dead_events: { type: integer }
        updated_at: { type: [string, 'null'], format: date-time }
    VertecoPartnerUpdate:
      type: object
      properties:
        environment: { type: string, enum: [sandbox, production] }
        base_url: { type: [string, 'null'], maxLength: 300 }
        public_base_url: { type: [string, 'null'], maxLength: 300 }
        token: { type: string, minLength: 8, maxLength: 300, writeOnly: true }
        token_id: { type: [string, 'null'], maxLength: 40 }
        fs_key: { type: [string, 'null'], pattern: '^[0-9a-fA-F]{32,128}$', writeOnly: true }
        reseller_key: { type: [string, 'null'], minLength: 8, maxLength: 200, writeOnly: true }
        webhook_secret: { type: [string, 'null'], minLength: 8, maxLength: 300, writeOnly: true }
        fee_paid_until: { type: [string, 'null'], format: date }
        billing_model: { $ref: '#/components/schemas/VertecoBillingModel' }
        generate_webhook_urls: { type: boolean }
        register_notification_webhook: { type: boolean }
        refresh: { type: boolean }
    VertecoIssuedWebhookUrls:
      type: object
      required: [fs_webhook_url, partner_webhook_url]
      properties:
        fs_webhook_url: { type: [string, 'null'], description: URL pro Verteco/FS (zobrazí se jen jednou) }
        partner_webhook_url: { type: [string, 'null'] }
    VertecoPartnerSaved:
      allOf:
        - { $ref: '#/components/schemas/VertecoPartner' }
        - type: object
          required: [issued_webhook_urls, warnings]
          properties:
            issued_webhook_urls:
              oneOf: [{ $ref: '#/components/schemas/VertecoIssuedWebhookUrls' }, { type: 'null' }]
            warnings: { type: array, items: { type: string } }
    VertecoCompany:
      type: object
      required: [tenant_id, tenant_name, tenant_dic, company_id, status, state, smp_status, paused, receiving_elsewhere, peppol_participant_id, legal_name, connection_id, vpds_url, can_migrate, verified_at, activated_at, released_at, last_event_at, last_event, last_synced_at, created_at]
      properties:
        tenant_id: { type: string, format: uuid }
        tenant_name: { type: string }
        tenant_dic: { type: string }
        company_id: { type: string, format: uuid }
        status: { type: string, enum: [pending_verification, active, inactive, released] }
        state: { $ref: '#/components/schemas/VertecoTenantState' }
        smp_status: { type: [string, 'null'], enum: [registered, pending, elsewhere, external, rejected, null] }
        paused: { type: boolean }
        receiving_elsewhere: { type: boolean }
        peppol_participant_id: { type: [string, 'null'] }
        legal_name: { type: [string, 'null'] }
        connection_id: { type: [string, 'null'], format: uuid }
        vpds_url: { type: [string, 'null'] }
        can_migrate: { type: boolean }
        verified_at: { type: [string, 'null'], format: date-time }
        activated_at: { type: [string, 'null'], format: date-time }
        released_at: { type: [string, 'null'], format: date-time }
        last_event_at: { type: [string, 'null'], format: date-time }
        last_event: { type: [string, 'null'] }
        last_synced_at: { type: [string, 'null'], format: date-time }
        created_at: { type: string, format: date-time }
    VertecoCompanyPage:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/VertecoCompany' } }
        next_cursor: { type: [string, 'null'] }
    VertecoCompanyCreate:
      type: object
      required: [tenant_id, iban]
      properties:
        tenant_id: { type: string, format: uuid }
        iban: { type: string, minLength: 15, maxLength: 34 }
        ico: { type: string, pattern: '^[0-9]{8}$' }
        legal_name: { type: string, minLength: 1, maxLength: 500 }
        street: { type: string, minLength: 1, maxLength: 255 }
        postal_code: { type: string, minLength: 1, maxLength: 16 }
        city: { type: string, minLength: 1, maxLength: 128 }
    VertecoConfirmRequest:
      type: object
      required: [confirm_dic]
      properties:
        confirm_dic: { type: string, pattern: '^[0-9]{10}$', description: Opsané DIČ klienta (druhý krok potvrzení destruktivní akce) }
    VertecoReceivingProviderRequest:
      type: object
      required: [elsewhere]
      properties:
        elsewhere: { type: boolean }
    VertecoSmpMigrateRequest:
      type: object
      required: [migration_code, confirm]
      properties:
        migration_code: { type: string, minLength: 1, maxLength: 64, writeOnly: true }
        confirm: { type: boolean, description: Musí být true }
    VertecoUsageRow:
      type: object
      required: [tenant_id, tenant_name, company_id, dic, legal_name, sent, received, amount_cents]
      properties:
        tenant_id: { type: [string, 'null'], format: uuid }
        tenant_name: { type: [string, 'null'] }
        company_id: { type: string, format: uuid }
        dic: { type: [string, 'null'] }
        legal_name: { type: [string, 'null'] }
        sent: { type: integer }
        received: { type: integer }
        amount_cents: { type: [integer, 'null'], description: ODHAD podle modelu účtování }
    VertecoUsageTotals:
      type: object
      required: [sent, received, amount_cents]
      properties:
        sent: { type: integer }
        received: { type: integer }
        amount_cents: { type: [integer, 'null'] }
    VertecoUsageReport:
      type: object
      required: [month, from, to, billing_model, source, fetched_at, rows, totals, billing_estimate_cents]
      properties:
        month: { type: string, pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$' }
        from: { type: [string, 'null'] }
        to: { type: [string, 'null'] }
        billing_model: { $ref: '#/components/schemas/VertecoBillingModel' }
        source: { type: string, enum: [live, snapshot] }
        fetched_at: { type: string, format: date-time }
        rows: { type: array, items: { $ref: '#/components/schemas/VertecoUsageRow' } }
        totals: { $ref: '#/components/schemas/VertecoUsageTotals' }
        billing_estimate_cents: { type: [integer, 'null'] }
    VertecoPartnerEvent:
      type: object
      required: [id, source, event_type, company_id, tenant_id, tenant_name, status, attempts, size_bytes, received_at, next_attempt_at, processed_at, error, upstream_status]
      properties:
        id: { type: string }
        source: { type: string, enum: [fs_webhook, partner_webhook] }
        event_type: { type: [string, 'null'] }
        company_id: { type: [string, 'null'], format: uuid }
        tenant_id: { type: [string, 'null'], format: uuid }
        tenant_name: { type: [string, 'null'] }
        status: { type: string, enum: [pending, processed, ignored, dead] }
        attempts: { type: integer }
        size_bytes: { type: integer }
        received_at: { type: string, format: date-time }
        next_attempt_at: { type: string, format: date-time }
        processed_at: { type: [string, 'null'], format: date-time }
        error: { type: [string, 'null'] }
        upstream_status: { type: [integer, 'null'] }
    VertecoPartnerEventPage:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/VertecoPartnerEvent' } }
        next_cursor: { type: [string, 'null'] }
    VertecoTenantStatus:
      type: object
      required: [available, state, smp_status, paused, vpds_url, partner_name, activated_at]
      properties:
        available: { type: boolean }
        state: { $ref: '#/components/schemas/VertecoTenantState' }
        smp_status: { type: [string, 'null'], enum: [registered, pending, elsewhere, external, rejected, null] }
        paused: { type: boolean }
        vpds_url: { type: [string, 'null'] }
        partner_name: { type: [string, 'null'] }
        activated_at: { type: [string, 'null'], format: date-time }
    VertecoFsWebhookAck:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [received, forbidden, too_large] }

    # ---------------------------------------------------------------- zálohy (ADR 019)
    BackupDestField:
      type: object
      description: 'Pole formuláře cíle (z `GET /v1/destination-types` enginu). `secret: true` = write-only.'
      required: [key, label, type, required, secret, managed]
      properties:
        key: { type: string }
        label: { type: string }
        type: { type: string, enum: [string, text, number, boolean] }
        required: { type: boolean }
        secret: { type: boolean }
        managed: { type: boolean, description: 'Spravuje engine (např. OAuth token); ve formuláři se nezadává' }
        default: {}
        enum: { type: array, items: { type: string } }
        help: { type: string }
        when:
          type: object
          description: 'Pole se zobrazí jen když `params[klíč]` odpovídá hodnotě (nebo jedné z hodnot)'
          additionalProperties:
            oneOf:
              - { type: string }
              - { type: array, items: { type: string } }
    BackupProtocolField:
      type: object
      required: [key, enum, default]
      properties:
        key: { type: string }
        enum: { type: array, items: { type: string } }
        default: { type: string }
    BackupDestinationTypeInfo:
      type: object
      required: [type, label, protocol_field, fields, fields_by_protocol]
      properties:
        type: { type: string, enum: [nas, sftp, webdav, s3, smb, rsync, local, onedrive, gdrive] }
        label: { type: [string, 'null'] }
        protocol_field:
          oneOf:
            - { $ref: '#/components/schemas/BackupProtocolField' }
            - { type: 'null' }
        fields: { type: array, items: { $ref: '#/components/schemas/BackupDestField' } }
        fields_by_protocol:
          type: [object, 'null']
          additionalProperties: { type: array, items: { $ref: '#/components/schemas/BackupDestField' } }
    BackupDestinationTypeList:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/BackupDestinationTypeInfo' } }
    BackupDestination:
      type: object
      description: 'Cíl záloh BEZ tajemství (tajná pole jen jako `credentials_set`).'
      required: [id, type, kind, label, enabled, append_only, schedule, params, credentials_set, unverified_kind, same_host, retention, bandwidth_limit]
      properties:
        id: { type: string }
        type: { type: string, enum: [nas, sftp, webdav, s3, smb, rsync, local, onedrive, gdrive] }
        kind: { type: string, description: 'Skutečný druh (u `nas` zvolený protokol)' }
        label: { type: [string, 'null'] }
        enabled: { type: boolean }
        append_only: { type: boolean }
        schedule: { type: [string, 'null'] }
        params: { type: object, additionalProperties: true }
        credentials_set: { type: object, additionalProperties: { type: boolean } }
        unverified_kind: { type: boolean, description: 'OneDrive/Google Drive – ověřeno jen proti simulaci' }
        same_host: { type: boolean, description: 'Lokální cíl na témže hostiteli – není kopie mimo hostitele (3-2-1)' }
        retention: { type: [object, 'null'], additionalProperties: true }
        bandwidth_limit: { type: [string, 'null'] }
    BackupDestinationList:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/BackupDestination' } }
    BackupDestinationCreate:
      type: object
      required: [id, type, params]
      properties:
        id: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' }
        type: { type: string, enum: [nas, sftp, webdav, s3, smb, rsync, local, onedrive, gdrive] }
        label: { type: string, maxLength: 80 }
        enabled: { type: boolean }
        append_only: { type: boolean }
        schedule: { type: string, maxLength: 100, description: 'Cron (5 polí, UTC); prázdné = výchozí plán politiky' }
        retention: { type: object, additionalProperties: true }
        bandwidth_limit: { type: string, maxLength: 20 }
        params: { type: object, additionalProperties: true, description: 'Netajné parametry dle `destination-types` (u `nas` vč. `protocol`)' }
        secrets:
          type: object
          writeOnly: true
          description: 'Tajná pole (heslo, SSH klíč, tokeny, client secret). Write-only, šifrují se v enginu, nikdy se nevrací ani neauditují.'
          additionalProperties: { type: string, maxLength: 20000, writeOnly: true }
    BackupDestinationUpdate:
      type: object
      properties:
        label: { type: string, maxLength: 80 }
        enabled: { type: boolean }
        append_only: { type: boolean }
        schedule: { type: [string, 'null'], maxLength: 100 }
        retention: { type: object, additionalProperties: true }
        bandwidth_limit: { type: string, maxLength: 20 }
        params: { type: object, additionalProperties: true }
        secrets:
          type: object
          writeOnly: true
          additionalProperties: { type: string, maxLength: 20000, writeOnly: true }
        clear_secrets: { type: array, items: { type: string, maxLength: 64 } }
    BackupDestinationSaved:
      type: object
      required: [destination, warnings]
      properties:
        destination: { $ref: '#/components/schemas/BackupDestination' }
        warnings: { type: array, items: { type: string } }
    BackupDestinationRemoved:
      type: object
      required: [id, removed, note]
      properties:
        id: { type: string }
        removed: { type: boolean }
        note: { type: string }
    BackupTestStep:
      type: object
      required: [step, ok]
      properties:
        step: { type: string }
        ok: { type: boolean }
        ms: { type: integer }
        error: { type: string }
    BackupTestResult:
      type: object
      required: [ok, error, steps, ms, deleted, kind, tested_at]
      properties:
        ok: { type: boolean }
        error: { type: [string, 'null'] }
        steps: { type: array, items: { $ref: '#/components/schemas/BackupTestStep' } }
        ms: { type: integer }
        deleted: { type: [boolean, string, 'null'] }
        kind: { type: [string, 'null'] }
        tested_at: { type: string, format: date-time }
    BackupBackupItem:
      type: object
      required: [id, ts, size, complete, verified]
      properties:
        id: { type: string, description: 'UTC yyyymmddThhmmssZ' }
        ts: { type: string, format: date-time }
        size: { type: [integer, 'null'] }
        complete: { type: boolean }
        verified: { type: boolean }
    BackupBackupList:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/BackupBackupItem' } }
    BackupOAuthSession:
      type: object
      required: [id, status, user_code, verification_uri, message, expires_in, error, drive_id]
      properties:
        id: { type: [string, 'null'] }
        status: { type: string, enum: [none, pending, authorized, expired, error] }
        user_code: { type: [string, 'null'] }
        verification_uri: { type: [string, 'null'] }
        message: { type: [string, 'null'] }
        expires_in: { type: [integer, 'null'] }
        error: { type: [string, 'null'] }
        drive_id: { type: [string, 'null'] }
    BackupEngineInfo:
      type: object
      required: [state, message, checked_at]
      properties:
        state: { type: string, enum: [ok, unavailable, not_initialized, unauthorized, error] }
        message: { type: [string, 'null'] }
        checked_at: { type: string, format: date-time }
    BackupDestinationStatus:
      type: object
      required: [id, type, kind, enabled, append_only, schedule, next_run_at, last_success_at, last_size, last_backup_id, last_error, last_run_duration_ms, last_verified_at, last_verify_status, failures_total, stale, unverified_kind]
      properties:
        id: { type: string }
        type: { type: string }
        kind: { type: string }
        enabled: { type: boolean }
        append_only: { type: boolean }
        schedule: { type: string }
        next_run_at: { type: [string, 'null'], format: date-time }
        last_success_at: { type: [string, 'null'], format: date-time }
        last_size: { type: [integer, 'null'] }
        last_backup_id: { type: [string, 'null'] }
        last_error: { type: [string, 'null'] }
        last_run_duration_ms: { type: [integer, 'null'] }
        last_verified_at: { type: [string, 'null'], format: date-time }
        last_verify_status: { type: [string, 'null'] }
        failures_total: { type: integer }
        stale: { type: boolean }
        unverified_kind: { type: boolean }
    BackupPending:
      type: object
      required: [id, destinations, since]
      properties:
        id: { type: string }
        destinations: { type: array, items: { type: string } }
        since: { type: string, format: date-time }
    BackupEvent:
      type: object
      required: [at, kind, msg]
      properties:
        at: { type: string, format: date-time }
        kind: { type: string }
        msg: { type: string }
        destination: { type: string }
    BackupNotificationResult:
      type: object
      required: [channel, status]
      properties:
        channel: { type: string }
        status: { type: string }
        detail: { type: string }
    BackupNotificationRecord:
      type: object
      required: [at, event, subject, recipients, results]
      properties:
        at: { type: string, format: date-time }
        event: { type: string }
        subject: { type: string }
        recipients: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/BackupNotificationResult' } }
    BackupNotificationsStatus:
      type: object
      required: [engine_smtp, webhook, recent]
      properties:
        engine_smtp: { type: boolean, description: 'Engine umí posílat e-mail sám (doporučeno vypnuto: e-maily posílá portál přes webhook)' }
        webhook: { type: boolean, description: 'Engine volá webhook portálu' }
        recent: { type: array, items: { $ref: '#/components/schemas/BackupNotificationRecord' } }
    BackupStatus:
      type: object
      required: [engine, state, busy, profile, last_success_at, last_size, next_run_at, next_verify_at, last_verified_at, last_verify_status, last_kit_at, stale_after_hours, stale, destinations, pending, warnings, notifications, portal_smtp_configured, platform_admins_configured, events]
      properties:
        engine: { $ref: '#/components/schemas/BackupEngineInfo' }
        state: { type: string, enum: [ok, warning, critical, unknown] }
        busy: { type: [string, 'null'] }
        profile: { type: string, enum: [dev, production], description: 'Vývojový profil: UI zobrazí „DEV – ne pro produkci“' }
        last_success_at: { type: [string, 'null'], format: date-time }
        last_size: { type: [integer, 'null'] }
        next_run_at: { type: [string, 'null'], format: date-time }
        next_verify_at: { type: [string, 'null'], format: date-time }
        last_verified_at: { type: [string, 'null'], format: date-time }
        last_verify_status: { type: [string, 'null'] }
        last_kit_at: { type: [string, 'null'], format: date-time }
        stale_after_hours: { type: integer }
        stale: { type: boolean }
        destinations: { type: array, items: { $ref: '#/components/schemas/BackupDestinationStatus' } }
        pending: { type: array, items: { $ref: '#/components/schemas/BackupPending' } }
        warnings: { type: array, items: { type: string } }
        notifications: { $ref: '#/components/schemas/BackupNotificationsStatus' }
        portal_smtp_configured: { type: boolean, description: 'SMTP portálu je nastaveno (e-maily o selhání se odesílají)' }
        platform_admins_configured: { type: boolean }
        offline_key_configured: { type: boolean, description: 'BK-02: je nastaven offline klíč správce (age příjemce); bez něj engine ZÁLOHOVÁNÍ ODMÍTÁ a stav je `critical`' }
        verify_key_persistent: { type: boolean, description: 'FS-M4: zkušební restore používá trvalý soukromý klíč age uložený u enginu (přijaté riziko, ADR 021)' }
        events: { type: array, items: { $ref: '#/components/schemas/BackupEvent' } }
    BackupRunDestination:
      type: object
      required: [id, status]
      properties:
        id: { type: string }
        status: { type: string }
        attempts: { type: integer }
        error: { type: string }
        started_at: { type: string, format: date-time }
        finished_at: { type: string, format: date-time }
    BackupRun:
      type: object
      required: [id, kind, trigger, status, started_at, finished_at, duration_ms, targets, backup_id, size, sha256, invoices, tenants, xml_aggregate_sha256, error, destinations]
      properties:
        id: { type: string }
        kind: { type: string }
        trigger: { type: string }
        status: { type: string, enum: [running, success, partial, failed, interrupted] }
        started_at: { type: string, format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        duration_ms: { type: [integer, 'null'] }
        targets: { type: array, items: { type: string } }
        backup_id: { type: [string, 'null'] }
        size: { type: [integer, 'null'] }
        sha256: { type: [string, 'null'], description: 'SHA-256 šifrovaného artefaktu' }
        invoices: { type: [integer, 'null'] }
        tenants: { type: [integer, 'null'] }
        xml_aggregate_sha256: { type: [string, 'null'], description: 'Agregovaný SHA-256 přes xml_sha256 všech faktur' }
        source_aggregate_sha256: { type: [string, 'null'], description: 'Agregovaný SHA-256 přes source_sha256 zdrojových dokumentů (původní bajty XML v převedeném kódování, tabulka invoice_source_documents); null u záloh bez zdrojových dokumentů nebo ze starší verze enginu' }
        error: { type: [string, 'null'] }
        destinations: { type: array, items: { $ref: '#/components/schemas/BackupRunDestination' } }
    BackupVerifyCheck:
      type: object
      required: [name, expected, actual, ok]
      properties:
        name: { type: string }
        expected: {}
        actual: {}
        ok: { type: boolean }
    BackupVerification:
      type: object
      required: [id, kind, trigger, status, destination, backup_id, started_at, finished_at, duration_ms, invoices, checks_total, checks_failed, temp_db_dropped, error, checks]
      properties:
        id: { type: string }
        kind: { type: string }
        trigger: { type: string }
        status: { type: string, enum: [running, success, partial, failed, interrupted] }
        destination: { type: string }
        backup_id: { type: [string, 'null'] }
        started_at: { type: string, format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        duration_ms: { type: [integer, 'null'] }
        invoices: { type: [integer, 'null'] }
        checks_total: { type: [integer, 'null'] }
        checks_failed: { type: [integer, 'null'] }
        temp_db_dropped: { type: [boolean, 'null'] }
        error: { type: [string, 'null'] }
        checks: { type: array, items: { $ref: '#/components/schemas/BackupVerifyCheck' } }
    BackupRunList:
      type: object
      required: [runs, verifications]
      properties:
        runs: { type: array, items: { $ref: '#/components/schemas/BackupRun' } }
        verifications: { type: array, items: { $ref: '#/components/schemas/BackupVerification' } }
    BackupRunRequest:
      type: object
      properties:
        destinations: { type: array, maxItems: 50, items: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' }, description: 'Prázdné = všechny zapnuté cíle' }
        xml: { type: boolean, description: 'Navíc export archivu XML po tenantech' }
    BackupVerifyRequest:
      type: object
      properties:
        destination: { type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$' }
        backup: { type: string, pattern: '^\d{8}T\d{6}Z$', description: 'Výchozí = nejnovější záloha cíle' }
    BackupAccepted:
      type: object
      required: [accepted]
      properties:
        accepted: { type: boolean }
    BackupIntegrityResult:
      type: object
      required: [ok, destination, backup_id, invoices, ms, error, note]
      properties:
        ok: { type: boolean }
        destination: { type: [string, 'null'] }
        backup_id: { type: [string, 'null'] }
        invoices: { type: [integer, 'null'] }
        ms: { type: integer }
        error: { type: [string, 'null'] }
        note: { type: [string, 'null'] }
    BackupRetention:
      type: object
      required: [daily, weekly, monthly, yearly_years, min_keep_last, min_keep_verified, mode]
      properties:
        daily: { type: integer, minimum: 0, maximum: 3650 }
        weekly: { type: integer, minimum: 0, maximum: 1000 }
        monthly: { type: integer, minimum: 0, maximum: 600 }
        yearly_years:
          description: 'Roky uchování ročních záloh (nebo `all`). Méně než 10 vyžaduje `confirm_short_yearly`.'
          oneOf:
            - { type: integer, minimum: 1, maximum: 100 }
            - { type: string, enum: [all] }
        min_keep_last: { type: integer, minimum: 1, maximum: 1000 }
        min_keep_verified: { type: integer, minimum: 0, maximum: 1000 }
        mode: { type: string, enum: [gfs, keep-all] }
        confirm_short_yearly: { type: boolean }
    BackupPolicy:
      type: object
      required: [schedule, retention, verify, xml, stale_hours, admin_recipients_count, warnings]
      properties:
        schedule:
          type: object
          required: [db, verify, xml, retry, timezone]
          properties:
            db: { type: string }
            verify: { type: [string, 'null'] }
            xml: { type: [string, 'null'] }
            retry: { type: string }
            timezone: { type: string }
        retention: { $ref: '#/components/schemas/BackupRetention' }
        verify:
          type: object
          required: [destination, max_age_hours]
          properties:
            destination: { type: [string, 'null'] }
            max_age_hours: { type: integer }
        xml:
          type: object
          required: [enabled, retention_years, auto_delete]
          properties:
            enabled: { type: boolean }
            retention_years: { type: integer }
            auto_delete: { type: boolean }
        stale_hours: { type: integer }
        admin_recipients_count: { type: integer, description: 'Počet veřejných age klíčů příjemců (offline klíč správce); klíče se nevracejí' }
        allow_private_targets: { type: array, items: { type: string }, description: 'FS-L2: allowlist (IP, CIDR, název hostitele) pro cíle záloh v privátní/kontejnerové síti (lokální NAS); doplňuje env BACKUP_TARGET_ALLOW' }
        warnings: { type: array, items: { type: string } }
    BackupPolicyUpdate:
      type: object
      properties:
        schedule:
          type: object
          properties:
            db: { type: string, maxLength: 100 }
            verify: { type: [string, 'null'], maxLength: 100 }
            xml: { type: [string, 'null'], maxLength: 100 }
            retry: { type: string, maxLength: 100 }
        retention:
          type: object
          description: 'Částečná změna retence (stejná pole jako `BackupRetention`)'
          properties:
            daily: { type: integer, minimum: 0, maximum: 3650 }
            weekly: { type: integer, minimum: 0, maximum: 1000 }
            monthly: { type: integer, minimum: 0, maximum: 600 }
            yearly_years:
              oneOf:
                - { type: integer, minimum: 1, maximum: 100 }
                - { type: string, enum: [all] }
            min_keep_last: { type: integer, minimum: 1, maximum: 1000 }
            min_keep_verified: { type: integer, minimum: 0, maximum: 1000 }
            mode: { type: string, enum: [gfs, keep-all] }
            confirm_short_yearly: { type: boolean }
        verify:
          type: object
          properties:
            destination: { type: [string, 'null'] }
        xml:
          type: object
          properties:
            enabled: { type: boolean }
            retention_years: { type: integer, minimum: 1, maximum: 100 }
            auto_delete: { type: boolean }
            confirm_short_retention: { type: boolean }
        stale_hours: { type: integer, minimum: 1, maximum: 720 }
        allow_private_targets: { type: array, maxItems: 50, items: { type: string, maxLength: 100 }, description: 'Nahradí allowlist privátních cílů (IP, CIDR nebo název hostitele)' }
    BackupPolicySaved:
      type: object
      required: [policy, warnings]
      properties:
        policy: { $ref: '#/components/schemas/BackupPolicy' }
        warnings: { type: array, items: { type: string } }
    BackupKitRequest:
      type: object
      required: [action]
      properties:
        action: { type: string, enum: [create, upload] }
        mode: { type: string, enum: [age], description: 'Jen režim age (příjemci = offline klíč správce + verify identita). Režim s heslem je jen v CLI (infra/scripts/backup-kit).' }
    BackupKitResult:
      type: object
      required: [action, name, mode, size, files, uploaded, contains_host_secrets, note]
      properties:
        action: { type: string, enum: [create, upload] }
        name: { type: [string, 'null'] }
        mode: { type: [string, 'null'] }
        size: { type: [integer, 'null'] }
        files: { type: array, items: { type: string } }
        uploaded: { type: [object, 'null'], additionalProperties: true }
        contains_host_secrets: { type: boolean }
        note: { type: string }
    BackupEngineNotification:
      type: object
      description: 'Tělo webhooku enginu (`{event, recipients, subject, body, params, source}`).'
      required: [event, params, source]
      properties:
        event: { type: string, enum: [backup.failed, backup.stale, verify.failed, recovery, test] }
        recipients: { type: array, maxItems: 50, items: { type: string, maxLength: 254 } }
        subject: { type: string, maxLength: 500 }
        body: { type: string, maxLength: 20000 }
        params: { type: object, additionalProperties: true }
        source: { type: string, maxLength: 64 }
    BackupEngineNotificationAck:
      type: object
      required: [status, notification_id, type]
      properties:
        status: { type: string, enum: [queued, suppressed, deduplicated, ignored] }
        notification_id: { type: [string, 'null'] }
        type: { type: [string, 'null'] }

    # ---- forwarding (ADR 037)
    ForwardFilters:
      type: "object"
      properties:
        supplier_dic: {"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[0-9A-Za-z]{2,14}$"}}
        supplier_ico: {"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[0-9]{6,8}$"}}
        supplier_name_contains: {"maxItems":20,"type":"array","items":{"type":"string","minLength":2,"maxLength":80}}
        min_amount: {"type":"string","pattern":"^-?[0-9]{1,15}(\\.[0-9]{1,6})?$"}
        max_amount: {"type":"string","pattern":"^-?[0-9]{1,15}(\\.[0-9]{1,6})?$"}
        doc_types: {"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[0-9]{3}$"}}
        validity: {"type":"string","enum":["all","valid_only","invalid_only"]}
        vat_categories: {"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,2}$"}}
        connection_ids: {"maxItems":50,"type":"array","items":{"type":"string","format":"uuid"}}
        currencies: {"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$"}}
    ForwardRule:
      type: "object"
      properties:
        id: {"type":"string","format":"uuid"}
        name: {"type":"string"}
        enabled: {"type":"boolean"}
        direction: {"type":"string","enum":["inbound","outbound"]}
        events: {"type":"array","items":{"type":"string","enum":["received","sent","delivered","delivery_failed"]}}
        link_mode: {"type":"string","enum":["none","password","open"]}
        attachments: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}},"required":["xml","html","pdf"]}
        mode: {"type":"string"}
        password_delivery: {"type":"string","enum":["recipient","admin_set","email"]}
        second_factor: {"type":"string","enum":["none","totp"]}
        has_fixed_password: {"type":"boolean"}
        link_valid_hours: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_max_views: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        downloads: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}},"required":["xml","html","pdf"]}
        filters: {"$ref":"#/components/schemas/ForwardFilters"}
        frequency: {"type":"string","enum":["each","digest_hourly","digest_daily"]}
        digest_hour: {"type":"integer","minimum":0,"maximum":23}
        language: {"anyOf":[{"type":"string","enum":["sk","cs","en"]},{"type":"null"}]}
        subject_prefix: {"type":["string","null"]}
        metadata_fields: {"type":"array","items":{"type":"string","enum":["supplier","number","amount","date","due_date","buyer","doc_type"]}}
        recipient_ids: {"type":"array","items":{"type":"string","format":"uuid"}}
        version: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        created_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
        updated_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
      required: ["id","name","enabled","direction","events","link_mode","attachments","mode","password_delivery","second_factor","has_fixed_password","link_valid_hours","link_max_views","downloads","filters","frequency","digest_hour","language","subject_prefix","metadata_fields","recipient_ids","version","created_at","updated_at"]
    ForwardRuleList:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"enabled":{"type":"boolean"},"direction":{"type":"string","enum":["inbound","outbound"]},"events":{"type":"array","items":{"type":"string","enum":["received","sent","delivered","delivery_failed"]}},"link_mode":{"type":"string","enum":["none","password","open"]},"attachments":{"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}},"required":["xml","html","pdf"]},"mode":{"type":"string"},"password_delivery":{"type":"string","enum":["recipient","admin_set","email"]},"second_factor":{"type":"string","enum":["none","totp"]},"has_fixed_password":{"type":"boolean"},"link_valid_hours":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"link_max_views":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"downloads":{"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}},"required":["xml","html","pdf"]},"filters":{"$ref":"#/components/schemas/ForwardFilters"},"frequency":{"type":"string","enum":["each","digest_hourly","digest_daily"]},"digest_hour":{"type":"integer","minimum":0,"maximum":23},"language":{"anyOf":[{"type":"string","enum":["sk","cs","en"]},{"type":"null"}]},"subject_prefix":{"type":["string","null"]},"metadata_fields":{"type":"array","items":{"type":"string","enum":["supplier","number","amount","date","due_date","buyer","doc_type"]}},"recipient_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","enabled","direction","events","link_mode","attachments","mode","password_delivery","second_factor","has_fixed_password","link_valid_hours","link_max_views","downloads","filters","frequency","digest_hour","language","subject_prefix","metadata_fields","recipient_ids","version","created_at","updated_at"]}}
      required: ["items"]
    ForwardRuleCreate:
      type: "object"
      properties:
        name: {"type":"string","minLength":1,"maxLength":120}
        enabled: {"type":"boolean"}
        direction: {"type":"string","enum":["inbound","outbound"]}
        events: {"minItems":1,"type":"array","items":{"type":"string","enum":["received","sent","delivered","delivery_failed"]}}
        link_mode: {"type":"string","enum":["none","password","open"]}
        attachments: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}}}
        password_delivery: {"type":"string","enum":["recipient","admin_set","email"]}
        second_factor: {"type":"string","enum":["none","totp"]}
        fixed_password: {"type":"string","minLength":10,"maxLength":128}
        link_valid_hours: {"type":"integer","minimum":1,"maximum":720}
        link_max_views: {"type":"integer","minimum":1,"maximum":1000}
        downloads: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}}}
        filters: {"$ref":"#/components/schemas/ForwardFilters"}
        frequency: {"type":"string","enum":["each","digest_hourly","digest_daily"]}
        digest_hour: {"type":"integer","minimum":0,"maximum":23}
        language: {"anyOf":[{"type":"string","enum":["sk","cs","en"]},{"type":"null"}]}
        subject_prefix: {"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}
        metadata_fields: {"minItems":1,"type":"array","items":{"type":"string","enum":["supplier","number","amount","date","due_date","buyer","doc_type"]}}
        recipient_ids: {"maxItems":50,"type":"array","items":{"type":"string","format":"uuid"}}
      required: ["name"]
    ForwardRuleUpdate:
      type: "object"
      properties:
        name: {"type":"string","minLength":1,"maxLength":120}
        enabled: {"type":"boolean"}
        direction: {"type":"string","enum":["inbound","outbound"]}
        events: {"minItems":1,"type":"array","items":{"type":"string","enum":["received","sent","delivered","delivery_failed"]}}
        link_mode: {"type":"string","enum":["none","password","open"]}
        attachments: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}}}
        password_delivery: {"type":"string","enum":["recipient","admin_set","email"]}
        second_factor: {"type":"string","enum":["none","totp"]}
        fixed_password: {"type":"string","minLength":10,"maxLength":128}
        link_valid_hours: {"type":"integer","minimum":1,"maximum":720}
        link_max_views: {"type":"integer","minimum":1,"maximum":1000}
        downloads: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}}}
        filters: {"$ref":"#/components/schemas/ForwardFilters"}
        frequency: {"type":"string","enum":["each","digest_hourly","digest_daily"]}
        digest_hour: {"type":"integer","minimum":0,"maximum":23}
        language: {"anyOf":[{"type":"string","enum":["sk","cs","en"]},{"type":"null"}]}
        subject_prefix: {"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}
        metadata_fields: {"minItems":1,"type":"array","items":{"type":"string","enum":["supplier","number","amount","date","due_date","buyer","doc_type"]}}
        recipient_ids: {"maxItems":50,"type":"array","items":{"type":"string","format":"uuid"}}
        expected_version: {"type":"integer","minimum":1,"maximum":9007199254740991}
    ForwardRecipient:
      type: "object"
      properties:
        id: {"type":"string","format":"uuid"}
        email: {"type":"string"}
        display_name: {"type":["string","null"]}
        status: {"type":"string","enum":["pending","verified","unsubscribed","revoked"]}
        confirmation_expired: {"type":"boolean"}
        verification_sent_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        verification_expires_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        verified_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        unsubscribed_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        credential_state: {"type":"string","enum":["none","password","totp","password_totp"]}
        credential_set_at: {"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}
        created_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
      required: ["id","email","display_name","status","confirmation_expired","verification_sent_at","verification_expires_at","verified_at","unsubscribed_at","credential_state","credential_set_at","created_at"]
    ForwardRecipientList:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","verified","unsubscribed","revoked"]},"confirmation_expired":{"type":"boolean"},"verification_sent_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"verification_expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"verified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"unsubscribed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"credential_state":{"type":"string","enum":["none","password","totp","password_totp"]},"credential_set_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","email","display_name","status","confirmation_expired","verification_sent_at","verification_expires_at","verified_at","unsubscribed_at","credential_state","credential_set_at","created_at"]}}
      required: ["items"]
    ForwardRecipientCreate:
      type: "object"
      properties:
        email: {"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}
        display_name: {"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}
      required: ["email"]
    ForwardDelivery:
      type: "object"
      properties:
        id: {"type":"string","format":"uuid"}
        kind: {"type":"string","enum":["invoice","password","optin","digest","sample"]}
        status: {"type":"string","enum":["queued","sent","failed","suppressed","bounced","cancelled"]}
        trigger_event: {"type":"string"}
        mode: {"type":["string","null"]}
        rule_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        rule_name: {"type":["string","null"]}
        recipient_id: {"type":"string","format":"uuid"}
        recipient_email: {"type":"string"}
        invoice_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        invoice_number: {"type":["string","null"]}
        link_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        reason_code: {"type":["string","null"]}
        error: {"type":["string","null"]}
        attempts: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        message_id: {"type":["string","null"]}
        sent_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        next_attempt_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        created_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
      required: ["id","kind","status","trigger_event","mode","rule_id","rule_name","recipient_id","recipient_email","invoice_id","invoice_number","link_id","reason_code","error","attempts","message_id","sent_at","next_attempt_at","created_at"]
    ForwardDeliveryPage:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["invoice","password","optin","digest","sample"]},"status":{"type":"string","enum":["queued","sent","failed","suppressed","bounced","cancelled"]},"trigger_event":{"type":"string"},"mode":{"type":["string","null"]},"rule_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"rule_name":{"type":["string","null"]},"recipient_id":{"type":"string","format":"uuid"},"recipient_email":{"type":"string"},"invoice_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_number":{"type":["string","null"]},"link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason_code":{"type":["string","null"]},"error":{"type":["string","null"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message_id":{"type":["string","null"]},"sent_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","kind","status","trigger_event","mode","rule_id","rule_name","recipient_id","recipient_email","invoice_id","invoice_number","link_id","reason_code","error","attempts","message_id","sent_at","next_attempt_at","created_at"]}}
        next_cursor: {"type":["string","null"]}
      required: ["items","next_cursor"]
    ForwardManualRequest:
      type: "object"
      properties:
        recipient_id: {"type":"string","format":"uuid"}
        link_mode: {"type":"string","enum":["none","password","open"]}
        attachments: {"type":"object","properties":{"xml":{"type":"boolean"},"html":{"type":"boolean"},"pdf":{"type":"boolean"}}}
        language: {"type":"string","enum":["sk","cs","en"]}
      required: ["recipient_id"]
    ForwardAccepted:
      type: "object"
      properties:
        delivery: {"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["invoice","password","optin","digest","sample"]},"status":{"type":"string","enum":["queued","sent","failed","suppressed","bounced","cancelled"]},"trigger_event":{"type":"string"},"mode":{"type":["string","null"]},"rule_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"rule_name":{"type":["string","null"]},"recipient_id":{"type":"string","format":"uuid"},"recipient_email":{"type":"string"},"invoice_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_number":{"type":["string","null"]},"link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reason_code":{"type":["string","null"]},"error":{"type":["string","null"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message_id":{"type":["string","null"]},"sent_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","kind","status","trigger_event","mode","rule_id","rule_name","recipient_id","recipient_email","invoice_id","invoice_number","link_id","reason_code","error","attempts","message_id","sent_at","next_attempt_at","created_at"]}
      required: ["delivery"]
    ForwardRuleTestResult:
      type: "object"
      properties:
        queued: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        skipped_unverified: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
      required: ["queued","skipped_unverified"]
    SharedLink:
      type: "object"
      properties:
        id: {"type":"string","format":"uuid"}
        invoice_id: {"type":"string","format":"uuid"}
        invoice_number: {"type":["string","null"]}
        recipient_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        recipient_email: {"type":["string","null"]}
        rule_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        mode: {"type":"string","enum":["password","open","recipient"]}
        state: {"type":"string","enum":["active","expired","revoked","exhausted","locked"]}
        expires_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
        max_views: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        view_count: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        failed_attempts: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        locked_until: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        last_access_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        revoked_at: {"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}
        revoked_reason: {"type":["string","null"]}
        allow_xml: {"type":"boolean"}
        allow_html: {"type":"boolean"}
        allow_pdf: {"type":"boolean"}
        created_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
      required: ["id","invoice_id","invoice_number","recipient_id","recipient_email","rule_id","mode","state","expires_at","max_views","view_count","failed_attempts","locked_until","last_access_at","revoked_at","revoked_reason","allow_xml","allow_html","allow_pdf","created_at"]
    SharedLinkList:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"invoice_number":{"type":["string","null"]},"recipient_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recipient_email":{"type":["string","null"]},"rule_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"mode":{"type":"string","enum":["password","open","recipient"]},"state":{"type":"string","enum":["active","expired","revoked","exhausted","locked"]},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"max_views":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"view_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locked_until":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"last_access_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"revoked_reason":{"type":["string","null"]},"allow_xml":{"type":"boolean"},"allow_html":{"type":"boolean"},"allow_pdf":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","invoice_id","invoice_number","recipient_id","recipient_email","rule_id","mode","state","expires_at","max_views","view_count","failed_attempts","locked_until","last_access_at","revoked_at","revoked_reason","allow_xml","allow_html","allow_pdf","created_at"]}}
      required: ["items"]
    SharedLinkPage:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"invoice_number":{"type":["string","null"]},"recipient_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"recipient_email":{"type":["string","null"]},"rule_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"mode":{"type":"string","enum":["password","open","recipient"]},"state":{"type":"string","enum":["active","expired","revoked","exhausted","locked"]},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"max_views":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"view_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locked_until":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"last_access_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"revoked_reason":{"type":["string","null"]},"allow_xml":{"type":"boolean"},"allow_html":{"type":"boolean"},"allow_pdf":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","invoice_id","invoice_number","recipient_id","recipient_email","rule_id","mode","state","expires_at","max_views","view_count","failed_attempts","locked_until","last_access_at","revoked_at","revoked_reason","allow_xml","allow_html","allow_pdf","created_at"]}}
        next_cursor: {"type":["string","null"]}
      required: ["items","next_cursor"]
    SharedLinkRevoke:
      type: "object"
      properties:
        reason: {"type":"string","maxLength":200}
    SharedLinkAccessEntry:
      type: "object"
      properties:
        id: {"type":"string"}
        at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
        event: {"type":"string"}
        ip_hash: {"type":["string","null"]}
        user_agent: {"type":["string","null"]}
      required: ["id","at","event","ip_hash","user_agent"]
    SharedLinkAccessPage:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"event":{"type":"string"},"ip_hash":{"type":["string","null"]},"user_agent":{"type":["string","null"]}},"required":["id","at","event","ip_hash","user_agent"]}}
        next_cursor: {"type":["string","null"]}
      required: ["items","next_cursor"]
    ForwardScope:
      type: "object"
      properties:
        rule_ids: {"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}
        recipient_ids: {"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}
        connection_ids: {"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}
    ForwardGrant:
      type: "object"
      properties:
        id: {"type":"string","format":"uuid"}
        user_id: {"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}
        user_email: {"type":["string","null"]}
        role: {"anyOf":[{"type":"string","enum":["tenant_user","tenant_viewer"]},{"type":"null"}]}
        permission: {"type":"string","enum":["forwarding.view","forwarding.send","forwarding.manage"]}
        scope: {"$ref":"#/components/schemas/ForwardScope"}
        granted_at: {"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}
      required: ["id","user_id","user_email","role","permission","scope","granted_at"]
    ForwardGrantList:
      type: "object"
      properties:
        items: {"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"user_email":{"type":["string","null"]},"role":{"anyOf":[{"type":"string","enum":["tenant_user","tenant_viewer"]},{"type":"null"}]},"permission":{"type":"string","enum":["forwarding.view","forwarding.send","forwarding.manage"]},"scope":{"$ref":"#/components/schemas/ForwardScope"},"granted_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","user_id","user_email","role","permission","scope","granted_at"]}}
      required: ["items"]
    ForwardGrantUpsert:
      type: "object"
      properties:
        user_id: {"type":"string","format":"uuid"}
        role: {"type":"string","enum":["tenant_user","tenant_viewer"]}
        permission: {"type":"string","enum":["forwarding.view","forwarding.send","forwarding.manage"]}
        scope: {"$ref":"#/components/schemas/ForwardScope"}
      required: ["permission"]
    ForwardTenantSettings:
      type: "object"
      properties:
        values: {"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}
        version: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
      required: ["values","version"]
    ForwardTenantSettingsUpdate:
      type: "object"
      properties:
        values: {"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}
        expected_version: {"type":"integer","minimum":0,"maximum":9007199254740991}
      required: ["values"]
    ForwardSettingsInfo:
      type: "object"
      properties:
        enabled: {"type":"boolean"}
        system_enabled: {"type":"boolean"}
        tenant_enabled: {"type":"boolean"}
        smtp_configured: {"type":"boolean"}
        sandbox: {"type":"boolean"}
        allow_inbound: {"type":"boolean"}
        allow_outbound: {"type":"boolean"}
        allowed_modes: {"type":"array","items":{"type":"string","enum":["link_password","link","attachment_xml","attachment_html","attachment_pdf"]}}
        enforce_password: {"type":"boolean"}
        allow_invalid: {"type":"boolean"}
        recipient_domains_allow: {"type":"array","items":{"type":"string"}}
        recipient_domains_block: {"type":"array","items":{"type":"string"}}
        max_rules: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        max_recipients: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        max_emails_per_hour: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        max_emails_per_day: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_valid_hours_default: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_valid_hours_max: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_open_valid_hours_default: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_max_views_default: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        link_max_views_max: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        max_attachment_bytes: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        password_methods: {"type":"array","items":{"type":"string","enum":["recipient","admin_set","email"]}}
        allow_totp: {"type":"boolean"}
        require_totp: {"type":"boolean"}
        min_password_length: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        sent_last_hour: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        sent_last_day: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        queued: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        deferred: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        suppressed_recent: {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}
        my_permissions: {"type":"array","items":{"type":"string","enum":["forwarding.view","forwarding.send","forwarding.manage"]}}
      required: ["enabled","system_enabled","tenant_enabled","smtp_configured","sandbox","allow_inbound","allow_outbound","allowed_modes","enforce_password","allow_invalid","recipient_domains_allow","recipient_domains_block","max_rules","max_recipients","max_emails_per_hour","max_emails_per_day","link_valid_hours_default","link_valid_hours_max","link_open_valid_hours_default","link_max_views_default","link_max_views_max","max_attachment_bytes","password_methods","allow_totp","require_totp","min_password_length","sent_last_hour","sent_last_day","queued","deferred","suppressed_recent","my_permissions"]

webhooks:
  invoiceEvent:
    post:
      operationId: webhookInvoiceEvent
      summary: Událost faktury (invoice.sent, invoice.delivered, invoice.delivery_failed, invoice.received, ping)
      description: Portál volá URL registrovaného webhooku. Viz `WebhookEnvelope`.
      parameters:
        - { name: X-Efakt-Event, in: header, required: true, schema: { $ref: '#/components/schemas/WebhookEventType' } }
        - { name: X-Efakt-Delivery, in: header, required: true, schema: { type: string, format: uuid } }
        - { name: X-Efakt-Timestamp, in: header, required: true, schema: { type: integer } }
        - { name: X-Efakt-Signature, in: header, required: true, schema: { type: string, pattern: '^v1=[0-9a-f]{64}$' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEnvelope' }
      responses:
        '2XX': { description: Přijato }