openapi: 3.1.0
info:
  title: efakturia.sk — API pre integrátora
  version: "2026-10-20"
  description: |
    Odosielanie a príjem e-faktúr cez sieť Peppol z vlastného ERP/CRM.
    Návod s postupom: https://efakturia.sk/integracia/navod.md

    - Autentifikácia: `Authorization: Bearer efk_…` (API kľúč firmy, Nastavenia → API kľúče).
    - Kľúč patrí firme a koná s právami správcu firmy.
    - Limit: 10 000 požiadaviek na kľúč za kalendárny mesiac, kľúč integrácie
      (plán INTEGRATION, nastavuje prevádzkovateľ) 300 000. Po prekročení 429.
    - Chyby: `{ "error": "text po slovensky" }`, prípadne `code` a `details`.
    - Bez kľúča (a bez prihlásenia) vráti každý endpoint 401.
servers:
  - url: https://efakturia.sk
security:
  - apiKey: []

tags:
  - name: Vydané faktúry
  - name: Prijaté doklady
  - name: Webhooky
  - name: Peppol

paths:
  /api/faktury:
    get:
      tags: [Vydané faktúry]
      summary: Zoznam vydaných faktúr (všetky, od najnovšej)
      responses:
        "200":
          description: Pole faktúr
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/Invoice" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Vydané faktúry]
      summary: Nová faktúra (koncept, ešte sa neodosiela)
      description: |
        Bez `invoiceNumber` dostane ďalšie číslo z radu firmy. Dodávateľ a
        odberateľ sa spárujú s kontaktmi podľa IČO (neexistujúci sa založí,
        existujúci sa aktualizuje). Súčty sa počítajú na serveri.

        Na odoslanie cez Peppol musí mať odberateľ vyplnené DIČ — slovenské
        firmy sa v sieti adresujú `0245:DIČ`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/InvoiceCreate" }
            example:
              invoiceNumber: "2026103049"
              invoiceType: INVOICE
              issueDate: "2026-10-20"
              dueDate: "2026-11-03"
              orderReference: PO-4500123
              supplier: { name: Moja firma s. r. o., ico: "12345678", dic: "2020123456", icDph: SK2020123456 }
              customer: { name: Zákazník s. r. o., ico: "87654321", dic: "2021987654", street: Hlavná 1, city: Žilina, postalCode: "01001" }
              iban: SK3112000000198742637541
              variableSymbol: "2026103049"
              lines:
                - { description: Služba, quantity: 1, unitPrice: 100, vatRate: 23 }
      responses:
        "201":
          description: Vytvorená faktúra
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Invoice" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "409":
          description: Číslo faktúry už vo firme existuje
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "429": { $ref: "#/components/responses/RateLimited" }

  /api/faktury/{id}:
    parameters: [{ $ref: "#/components/parameters/InvoiceId" }]
    get:
      tags: [Vydané faktúry]
      summary: Detail faktúry vrátane položiek a stavu doručenia
      responses:
        "200":
          description: Faktúra
          content: { application/json: { schema: { $ref: "#/components/schemas/Invoice" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/faktury/{id}/peppol:
    parameters: [{ $ref: "#/components/parameters/InvoiceId" }]
    post:
      tags: [Vydané faktúry]
      summary: Odoslanie faktúry do siete Peppol
      description: |
        Vytvorí UBL (Peppol BIS Billing 3) a odovzdá ho do siete. Typ dokladu
        sa berie z faktúry: INVOICE → 380, CREDIT_NOTE → CreditNote 381
        (s odkazom na pôvodnú faktúru), PREPAYMENT → 386. PROFORMA sa
        neposiela (400).

        Kredit: pred odoslaním sa overí, že stačí na jeden doklad (inak 402
        `INSUFFICIENT_CREDIT` a nič neodíde). Cena sa strhne až po úspešnom
        odovzdaní — rovnako ako pri odoslaní z aplikácie.

        Už odoslaná faktúra vráti 400 („už bola odoslaná") a do siete nič
        druhýkrát nepôjde. Ten istý doklad neposielajte súbežne; po timeoute
        najprv skontrolujte `peppolMessageId` v detaile faktúry.

        `messageId` je id dokladu v sieti; doručenie príde asynchrónne
        (webhook `invoice.delivered` / `invoice.rejected`, alebo pole
        `peppolStatus` v detaile faktúry).
      responses:
        "200":
          description: Odovzdané do siete
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SendResult" }
        "400":
          description: Faktúra už bola odoslaná, je proforma, odberateľ nemá DIČ alebo doklad nespĺňa pravidlá DPH (`details`)
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402":
          description: Nedostatok kreditu (`code` = INSUFFICIENT_CREDIT)
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: Systémová faktúra (za dobitie kreditu) — posiela sa sama
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "502":
          description: Sieť doklad neprevzala (text v `error`). Dá sa zopakovať.
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "503":
          description: Odosielanie je dočasne nedostupné
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }

  /api/faktury/{id}/status:
    parameters: [{ $ref: "#/components/parameters/InvoiceId" }]
    put:
      tags: [Vydané faktúry]
      summary: Ručná zmena stavu (napr. uhradená)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [DRAFT, SENT, DELIVERED, PAID, CANCELLED] }
      responses:
        "200": { description: Upravená faktúra }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/faktury/{id}/xml:
    parameters: [{ $ref: "#/components/parameters/InvoiceId" }]
    get:
      tags: [Vydané faktúry]
      summary: UBL (Peppol BIS 3) vydanej faktúry, bez vložených príloh
      responses:
        "200":
          description: XML
          content: { application/xml: { schema: { type: string } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/faktury/{id}/pdf:
    parameters: [{ $ref: "#/components/parameters/InvoiceId" }]
    get:
      tags: [Vydané faktúry]
      summary: PDF vydanej faktúry (`?stiahnut=1` ako príloha)
      responses:
        "200":
          description: PDF
          content: { application/pdf: { schema: { type: string, format: binary } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/faktury/nahrat:
    post:
      tags: [Vydané faktúry]
      summary: Odoslanie hotového UBL / ISDOC zo súboru
      description: |
        Pre systémy, ktoré si UBL generujú samé. `action=analyze` súbor len
        skontroluje (nič neuloží), `action=send` ho uloží ako vydanú faktúru
        a odošle — UBL Peppol BIS 3 ide do siete bez zmeny. Kredit ako pri
        `/api/faktury/{id}/peppol`. Max. 10 MB.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                action: { type: string, enum: [analyze, send], default: analyze }
      responses:
        "200":
          description: "`analyze`: náhľad a zoznam chýb; `send`: { ok, invoiceId, invoiceNumber, messageId, balance }"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402":
          description: Nedostatok kreditu (`code` = INSUFFICIENT_CREDIT)
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "413": { description: Súbor je väčší ako 10 MB }

  /api/prijate:
    get:
      tags: [Prijaté doklady]
      summary: Zoznam prijatých dokladov, od najstaršieho
      description: |
        Na pravidelné preberanie: `?acknowledged=false` vráti len doklady,
        ktorých prevzatie ste ešte nepotvrdili (`POST /api/prijate/ack`).
        Stránkovanie cez `cursor` = `nextCursor` predošlej strany; je bezpečné
        aj keď medzi stranami doklady potvrdzujete. XML v zozname nie je.
      parameters:
        - name: acknowledged
          in: query
          schema: { type: string, enum: ["true", "false"] }
        - name: since
          in: query
          description: Prijaté od (ISO 8601 dátum alebo dátum a čas s pásmom)
          schema: { type: string, examples: ["2026-10-01", "2026-10-20T08:00:00+02:00"] }
        - name: status
          in: query
          description: Pracovný stav v aplikácii (nastavuje človek)
          schema: { type: string, enum: [NEW, ACCEPTED, REJECTED, PAID] }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Strana dokladov
          content:
            application/json:
              schema:
                type: object
                required: [data, nextCursor]
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/ReceivedDocument" } }
                  nextCursor: { type: [string, "null"], description: "null = posledná strana" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/prijate/ack:
    post:
      tags: [Prijaté doklady]
      summary: Potvrdenie prevzatia dokladov integráciou
      description: |
        Idempotentné — už potvrdený doklad si ponechá prvý čas potvrdenia.
        Pracovný stav (`status`) v aplikácii nemení.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ids]
              properties:
                ids: { type: array, minItems: 1, maxItems: 200, items: { type: string } }
      responses:
        "200":
          description: Výsledok
          content:
            application/json:
              schema:
                type: object
                properties:
                  acknowledged: { type: integer, description: Novo potvrdené }
                  alreadyAcknowledged: { type: integer }
                  notFound: { type: array, items: { type: string } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/prijate/{id}:
    parameters: [{ $ref: "#/components/parameters/ReceivedId" }]
    get:
      tags: [Prijaté doklady]
      summary: Detail prijatého dokladu (vrátane `ublXml`)
      responses:
        "200":
          description: Doklad
          content: { application/json: { schema: { $ref: "#/components/schemas/ReceivedDocument" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
    put:
      tags: [Prijaté doklady]
      summary: Pracovný stav v aplikácii
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [NEW, ACCEPTED, REJECTED, PAID] }
      responses:
        "200": { description: Upravený doklad }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/prijate/{id}/xml:
    parameters: [{ $ref: "#/components/parameters/ReceivedId" }]
    get:
      tags: [Prijaté doklady]
      summary: Pôvodné XML dokladu (UBL Invoice / CreditNote), presne ako prišlo
      responses:
        "200":
          description: XML
          content: { application/xml: { schema: { type: string } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/prijate/{id}/pdf:
    parameters: [{ $ref: "#/components/parameters/ReceivedId" }]
    get:
      tags: [Prijaté doklady]
      summary: PDF dokladu — vložené dodávateľom, inak vykreslené z XML
      responses:
        "200":
          description: PDF
          content: { application/pdf: { schema: { type: string, format: binary } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/prijate/{id}/response:
    parameters: [{ $ref: "#/components/parameters/ReceivedId" }]
    post:
      tags: [Prijaté doklady]
      summary: Odpoveď dodávateľovi cez Peppol (Invoice Response)
      description: Pri RE (odmietnutá), UQ (reklamovaná) a CA (prijatá s výhradou) je `note` povinný.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [AB, IP, UQ, CA, RE, AP, PD] }
                note: { type: string }
      responses:
        "200":
          description: "{ success, status, queued }"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/webhooks:
    get:
      tags: [Webhooky]
      summary: Webhooky firmy
      responses:
        "200": { description: "Pole webhookov (bez tajomstva), pri každom aj `pendingCount` a `failedCount` z fronty" }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Webhooky]
      summary: Nový webhook — tajomstvo na podpis vráti len raz
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                  description: |
                    Len `https://` na verejnú adresu, bez mena a hesla. Odmietnuté sú
                    localhost, mená bez bodky, `.local`/`.internal`, privátne, loopback,
                    link-local (aj 169.254.169.254), CGNAT, multicast, rezervované rozsahy
                    a ich IPv6 ekvivalenty. Overuje sa pri uložení aj pri každom odoslaní;
                    presmerovania sa nesledujú.
                events: { type: array, items: { $ref: "#/components/schemas/WebhookEventName" } }
      responses:
        "201":
          description: Vytvorený
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  url: { type: string }
                  events: { type: array, items: { type: string } }
                  secret: { type: string, description: Uložte si ho, druhýkrát sa nezobrazí }
        "400":
          description: |
            Neplatné údaje. Pri nepovolenej adrese `code: WEBHOOK_URL_NOT_ALLOWED` a
            `details.reason`: not_https, credentials, local_name, forbidden_address,
            unresolvable, invalid.
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
    put:
      tags: [Webhooky]
      summary: Zapnutie / vypnutie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, active]
              properties:
                id: { type: string }
                active: { type: boolean }
      responses:
        "200": { description: Upravený webhook }
        "404": { $ref: "#/components/responses/NotFound" }
    delete:
      tags: [Webhooky]
      summary: Zmazanie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string }
      responses:
        "200": { description: "{ success: true }" }
        "404": { $ref: "#/components/responses/NotFound" }

  /api/webhooks/deliveries:
    get:
      tags: [Webhooky]
      summary: Fronta doručení — čo sa opakuje a čo zlyhalo
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [PENDING, DELIVERED, FAILED] } }
        - { name: webhookId, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
      responses:
        "200":
          description: Najnovšie doručenia
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/WebhookDeliveryState" } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Webhooky]
      summary: Zlyhané doručenia znova do fronty (rovnaké id udalosti)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action, ids]
              properties:
                action: { type: string, enum: [retry] }
                ids: { type: array, items: { type: string }, maxItems: 200 }
      responses:
        "200": { description: "{ requeued: počet }" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/peppol/status:
    get:
      tags: [Peppol]
      summary: Stav registrácie vlastnej firmy v sieti Peppol
      responses:
        "200": { description: "{ registrations: [...] } — aktívna registrácia má status ACTIVE" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /api/peppol/lookup:
    get:
      tags: [Peppol]
      summary: Je odberateľ v sieti Peppol? (verejné, bez kľúča)
      security: []
      parameters:
        - name: id
          in: query
          required: true
          description: DIČ (10 číslic) pri schéme 0245
          schema: { type: string }
        - name: scheme
          in: query
          schema: { type: string, enum: ["0245", "0158", "0116"], default: "0245" }
      responses:
        "200":
          description: Výsledok
          content:
            application/json:
              schema:
                type: object
                properties:
                  participantId: { type: string, examples: ["0245:2021987654"] }
                  registered: { type: boolean }
                  error: { type: string }
        "400": { $ref: "#/components/responses/BadRequest" }

webhooks:
  invoice.delivered:
    post:
      summary: Odoslaný doklad prevzal prístupový bod odberateľa (raz)
      requestBody: { $ref: "#/components/requestBodies/WebhookDelivery" }
      responses: { "2XX": { description: Prijaté } }
  invoice.rejected:
    post:
      summary: Doklad odmietnutý — sieťou (`rejectedBy` network) alebo odberateľom (RE, `rejectedBy` buyer)
      requestBody: { $ref: "#/components/requestBodies/WebhookDelivery" }
      responses: { "2XX": { description: Prijaté } }
  invoice.response_received:
    post:
      summary: Nová obchodná odpoveď odberateľa (AP, CA, UQ, RE, PD, AB, IP)
      requestBody: { $ref: "#/components/requestBodies/WebhookDelivery" }
      responses: { "2XX": { description: Prijaté } }
  document.received:
    post:
      summary: Prišiel nový doklad (Peppol alebo nahratý súbor)
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/WebhookEnvelope"
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        receivedInvoiceId: { type: string }
                        invoiceNumber: { type: string }
                        sender: { type: object, properties: { name: { type: string }, ico: { type: [string, "null"] } } }
                        totalInclVat: { type: number }
                        currency: { type: string }
                        dueDate: { type: string, format: date }
                        source: { type: string, enum: [peppol, upload] }
                        xmlUrl: { type: string }
                        pdfUrl: { type: string }
      responses: { "2XX": { description: Prijaté } }
  invoice.sent:
    post:
      summary: Faktúra odovzdaná do siete (alebo ručne označená ako odoslaná)
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEnvelope" }
      responses: { "2XX": { description: Prijaté } }
  invoice.paid:
    post:
      summary: Faktúra uhradená (ručne, alebo odberateľ oznámil úhradu PD — `source` peppol_pd)
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEnvelope" }
      responses: { "2XX": { description: Prijaté } }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: "API kľúč firmy: `Authorization: Bearer efk_…`"

  parameters:
    InvoiceId:
      name: id
      in: path
      required: true
      schema: { type: string }
    ReceivedId:
      name: id
      in: path
      required: true
      schema: { type: string }

  responses:
    Unauthorized:
      description: Chýba alebo je neplatný API kľúč
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    BadRequest:
      description: Neplatné údaje (text v `error`, pri validácii aj `details`)
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    NotFound:
      description: Nenájdené (alebo patrí inej firme)
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    RateLimited:
      description: Prekročený mesačný limit požiadaviek kľúča
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }

  requestBodies:
    WebhookDelivery:
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/WebhookEnvelope"
              - type: object
                properties:
                  data: { $ref: "#/components/schemas/DeliveryEventData" }

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error: { type: string }
        code: { type: string, examples: [INSUFFICIENT_CREDIT, PROFORMA_NOT_SENDABLE] }
        details: {}

    Party:
      type: object
      required: [name, ico]
      properties:
        name: { type: string }
        ico: { type: string, description: IČO — podľa neho sa páruje kontakt }
        dic: { type: string, description: DIČ — odberateľ ho musí mať na odoslanie cez Peppol }
        icDph: { type: string, description: "IČ DPH; dodávateľ s IČ DPH = platiteľ DPH" }
        street: { type: string }
        city: { type: string }
        postalCode: { type: string }
        country: { type: string, default: SK }

    InvoiceLine:
      type: object
      required: [description, quantity, unitPrice, vatRate]
      properties:
        description: { type: string }
        quantity: { type: number, description: Záporné pri dobropise alebo odpočte zálohy }
        unitPrice: { type: number, description: Cena za jednotku bez DPH }
        vatRate: { type: number, examples: [23, 19, 5, 0] }
        taxRegime:
          type: string
          description: |
            Daňový režim položky, ak nejde o bežnú sadzbu. Najčastejšie:
            S_STANDARD, O_NOT_VAT_PAYER (dodávateľ nie je platiteľ DPH),
            AE_REVERSE_CHARGE (prenesenie daňovej povinnosti), K_INTRA_COMMUNITY,
            G_EXPORT, Z_ZERO_RATE, E_* (oslobodenia podľa § 28–42 ZDPH).
        discountType: { type: [string, "null"], enum: [PERCENT, AMOUNT, null] }
        discountValue: { type: [number, "null"] }

    InvoiceCreate:
      type: object
      required: [issueDate, dueDate, supplier, customer, lines]
      properties:
        invoiceNumber: { type: string, description: Bez neho ďalšie číslo z radu firmy }
        invoiceType:
          type: string
          enum: [INVOICE, CREDIT_NOTE, PREPAYMENT, PROFORMA]
          default: INVOICE
          description: |
            INVOICE faktúra (380), CREDIT_NOTE dobropis (381, položky so zápornými
            množstvami a presne jedno z `relatedInvoiceId` / `originalInvoice`),
            PREPAYMENT daňový doklad k prijatej platbe (386), PROFORMA zálohová
            výzva — nie je daňový doklad, cez Peppol sa neposiela.
        relatedInvoiceId:
          type: string
          description: |
            Pri dobropise id pôvodnej faktúry v Efakturii (rovnaká firma). Pri
            CREDIT_NOTE sa uvádza presne jedno z `relatedInvoiceId` a
            `originalInvoice`, inak `400`.
        originalInvoice:
          type: object
          required: [number, issueDate]
          description: |
            Dobropis k faktúre vystavenej v inom programe (pôvodná faktúra nie je
            v Efakturii). Ide do UBL ako BillingReference/InvoiceDocumentReference
            (BT-25 číslo, BT-26 dátum vystavenia). Len pri CREDIT_NOTE, nie spolu
            s `relatedInvoiceId`. Dôvod opravy je povinný a patrí do `note`.
          properties:
            number: { type: string, maxLength: 100, description: "BT-25 číslo pôvodnej faktúry" }
            issueDate: { type: string, format: date, description: "BT-26 dátum vystavenia pôvodnej faktúry, nie neskôr ako issueDate dobropisu" }
        issueDate: { type: string, format: date }
        taxPointDate: { type: string, format: date, description: "BT-7 dátum zdaniteľného plnenia (dodania), ak sa líši od dátumu vystavenia; prázdne = dátum vystavenia" }
        dueDate: { type: string, format: date }
        note: { type: string, description: "BT-22 poznámka; pri dobropise s `originalInvoice` povinný dôvod opravy" }
        orderReference: { type: string, maxLength: 100, description: "BT-13 číslo objednávky odberateľa" }
        supplier: { $ref: "#/components/schemas/Party" }
        customer: { $ref: "#/components/schemas/Party" }
        iban: { type: string }
        variableSymbol: { type: string }
        lines: { type: array, minItems: 1, items: { $ref: "#/components/schemas/InvoiceLine" } }
        delivery:
          type: object
          description: Povinné pri dodaní do iného členského štátu (K_INTRA_COMMUNITY)
          properties:
            actualDeliveryDate: { type: string, format: date }
            countryCode: { type: string }
            name: { type: string }
            street: { type: string }
            city: { type: string }
            postalCode: { type: string }
        discountType: { type: [string, "null"], enum: [PERCENT, AMOUNT, null] }
        discountValue: { type: [number, "null"] }

    Invoice:
      type: object
      description: Uložená faktúra (výber polí; odpoveď obsahuje aj ďalšie)
      properties:
        id: { type: string }
        invoiceNumber: { type: string }
        invoiceType: { type: string, enum: [INVOICE, CREDIT_NOTE, PREPAYMENT, PROFORMA] }
        status: { type: string, enum: [DRAFT, SENT, DELIVERED, PAID, CANCELLED] }
        issueDate: { type: string, format: date-time }
        taxPointDate: { type: [string, "null"], format: date-time, description: "Dátum zdaniteľného plnenia; null = dátum vystavenia" }
        dueDate: { type: string, format: date-time }
        currency: { type: string }
        totalExclVat: { type: number }
        totalVat: { type: number }
        totalInclVat: { type: number }
        peppolMessageId: { type: [string, "null"] }
        peppolSentAt: { type: [string, "null"], format: date-time }
        peppolStatus: { type: [string, "null"], description: Posledný stav zo siete }
        peppolDeliveredAt: { type: [string, "null"], format: date-time }
        peppolError: { type: [string, "null"] }
        peppolResponseCode: { type: [string, "null"], enum: [AB, IP, UQ, CA, RE, AP, PD, null] }
        peppolResponseNote: { type: [string, "null"] }
        peppolResponseAt: { type: [string, "null"], format: date-time }
        supplier: { $ref: "#/components/schemas/Party" }
        customer: { $ref: "#/components/schemas/Party" }
        lines: { type: array, items: { $ref: "#/components/schemas/InvoiceLine" } }

    SendResult:
      type: object
      properties:
        success: { type: boolean }
        messageId: { type: string, description: Id dokladu v sieti }
        delivery: { type: string, enum: [delivered, rejected, pending] }
        credit:
          type: object
          properties:
            charged: { type: number, description: "Strhnutá suma v EUR vrátane DPH (od 1. 11. 2026 až 4 desatinné miesta, napr. 0.1845)" }
            balance: { type: number, description: Zostatok kreditu po odpočte }

    ReceivedDocument:
      type: object
      properties:
        id: { type: string }
        invoiceNumber: { type: string }
        senderName: { type: string }
        senderIco: { type: [string, "null"] }
        issueDate: { type: string, format: date-time }
        dueDate: { type: string, format: date-time }
        currency: { type: string }
        totalExclVat: { type: number }
        totalVat: { type: number }
        totalInclVat: { type: number }
        status: { type: string, enum: [NEW, ACCEPTED, REJECTED, PAID] }
        peppolMessageId: { type: [string, "null"] }
        receivedAt: { type: string, format: date-time }
        apiAcknowledgedAt: { type: [string, "null"], format: date-time }
        responseStatus: { type: [string, "null"], description: Vaša odoslaná odpoveď dodávateľovi }

    WebhookEventName:
      type: string
      enum:
        - invoice.created
        - invoice.sent
        - invoice.delivered
        - invoice.rejected
        - invoice.response_received
        - invoice.paid
        - invoice.overdue
        - invoice.cancelled
        - invoice.reminder_sent
        - document.received
        - received.created

    WebhookEnvelope:
      type: object
      description: |
        Hlavičky: `X-Webhook-Event` (názov), `X-Webhook-Id` (= `id`),
        `X-Webhook-Attempt` (číslo pokusu, 1–6),
        `X-Webhook-Signature: sha256=<hex HMAC-SHA256(tajomstvo, surové telo)>`.
        Úspech = `2xx` do 10 s. Inak sa rovnaká správa (rovnaké `id`, telo aj
        podpis) zopakuje po 1 min, 5 min, 30 min, 2 h a 12 h, potom FAILED.
        Presmerovania sa nesledujú.
      required: [id, event, timestamp, data]
      properties:
        id: { type: string, description: "Id udalosti, pri opakovaní rovnaké; pri zmenách doručenia a document.received odvodené od dokladu — duplicitu zahoďte" }
        event: { $ref: "#/components/schemas/WebhookEventName" }
        timestamp: { type: string, format: date-time }
        data: { type: object }

    WebhookDeliveryState:
      type: object
      properties:
        id: { type: string, description: Id doručenia (pre retry) }
        webhookId: { type: string }
        eventId: { type: string, description: "= X-Webhook-Id" }
        event: { $ref: "#/components/schemas/WebhookEventName" }
        status: { type: string, enum: [PENDING, DELIVERED, FAILED] }
        attempts: { type: integer }
        nextAttemptAt: { type: [string, "null"], format: date-time }
        lastStatus: { type: [integer, "null"], description: HTTP status poslednej odpovede }
        lastError: { type: [string, "null"] }
        lastAttemptAt: { type: [string, "null"], format: date-time }
        deliveredAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }

    DeliveryEventData:
      type: object
      properties:
        invoiceId: { type: string }
        invoiceNumber: { type: string }
        invoiceType: { type: string }
        messageId: { type: [string, "null"] }
        peppolStatus: { type: [string, "null"] }
        rejectedBy: { type: string, enum: [network, buyer] }
        reason: { type: [string, "null"], description: Pri rejectedBy network }
        response:
          type: object
          description: Odpoveď odberateľa (pri invoice.response_received a pri odmietnutí odberateľom)
          properties:
            code: { type: string, enum: [AB, IP, UQ, CA, RE, AP, PD] }
            note: { type: [string, "null"] }
            at: { type: [string, "null"], format: date-time }
