openapi: 3.0.3
info:
  title: Zaslat Returns API
  version: "1.0.0"
  description: |-
    API rozhraní systému **Zaslat Returns** pro správu servisních zakázek (reklamace, záruční a
    pozáruční servis, poptávky služeb) a přidružených zásilek.

    ## Prostředí

    - **Produkční** rozhraní běží na doméně konkrétní společnosti, např.
      `https://nokia.zaslat.cz/api/v1/<resource>`.
    - **Testovací** rozhraní je dostupné na `https://returns-demo.zaslat.cz/api/v1/<resource>`.
      Upozornění: veškeré změny provedené v testovacím prostředí se každou noc mažou a prostředí
      je znovu vytvořeno.

    ## Autentizace

    Všechny požadavky je nutné posílat s autentizačním HTTP headerem `x-apikey`. Produkční API
    klíč najdete ve správním rozhraní v sekci **API** (Nastavení uživatele), testovací klíč je
    uveden níže u schématu zabezpečení `ApiKeyAuth`.

    > **⚠️ Poznámka k úplnosti specifikace:** Tato specifikace byla sestavena ze zdrojové Notion
    > dokumentace. Čtyři vložené tabulky (parametry filtrování zakázek, tělo požadavku pro úpravu
    > zakázky a objekty `customer` a `shipment`) nebyly v době vzniku specifikace čitelné kvůli
    > omezení Notion plánu — jejich pole byla proto rekonstruována z ukázkových JSON požadavků a
    > odpovědí v dokumentaci. Tyto části jsou v popisech níže označeny ⚠️ a doporučujeme je před
    > nasazením do produkčního klienta ověřit proti zdrojové tabulce nebo backendu.
servers:
  - url: https://{company}.zaslat.cz/api/v1
    description: Produkční prostředí
    variables:
      company:
        default: nazev-spolecnosti
        description: Subdomána konkrétní společnosti v systému Zaslat Returns
  - url: https://returns-demo.zaslat.cz/api/v1
    description: Testovací prostředí (data se každou noc mažou a znovu vytváří)
security:
  - ApiKeyAuth: []
tags:
  - name: Zakázky
    description: Vytváření, úprava a přehled servisních zakázek.
  - name: Aktivity
    description: Zprávy a záznamy o změnách stavu k zakázce.
  - name: Výrobky
    description: Číselníky modelů a kategorií výrobků.
paths:
  /commissions:
    get:
      tags: [Zakázky]
      summary: Seznam zakázek
      description: |-
        Vrací stránkovaný seznam zakázek. Seznam je možné filtrovat podle níže uvedených
        parametrů.

        ⚠️ Zdrojová tabulka „Query parametry pro filtrování" nebyla při tvorbě této specifikace
        čitelná. Níže uvedené parametry jsou pouze ty, které se objevují v ukázkových dotazech ve
        zdrojové dokumentaci — tabulka pravděpodobně obsahuje další filtry (např. rozsah dat do,
        servisní středisko, typ/model výrobku). Parametry `page` a `page_size` jsou odvozeny z
        názvů polí v odpovědi (`meta.page_current`, `meta.page_size`), jejich přesný název na
        vstupu nebyl ověřen.
      parameters:
        - name: status[]
          in: query
          required: false
          description: Filtrace podle stavu zakázky. Lze zadat opakovaně pro filtraci přes více stavů.
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: "#/components/schemas/CommissionStatus"
        - name: created_from
          in: query
          required: false
          description: Vrátí pouze zakázky vytvořené od tohoto data (včetně).
          schema:
            type: string
            format: date
            example: "2021-06-20"
        - name: number
          in: query
          required: false
          description: Filtrace podle čísla zakázky (i částečné shody, viz příklad `Z21D02`).
          schema:
            type: string
            example: "Z21D02"
        - name: page
          in: query
          required: false
          description: "⚠️ Číslo stránky výsledků (název parametru odvozen, neověřeno)."
          schema:
            type: integer
            minimum: 1
        - name: page_size
          in: query
          required: false
          description: "⚠️ Počet položek na stránku (název parametru odvozen, neověřeno)."
          schema:
            type: integer
      responses:
        "200":
          description: Seznam zakázek.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  meta:
                    $ref: "#/components/schemas/PageMeta"
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Commission"
              example:
                status: 200
                meta:
                  total: 83
                  count: 20
                  page_current: 1
                  page_total: 5
                  page_size: 20
                data:
                  - id: 6350
                    token: bfd41c8e6a5361f7e4b95c0f
                    type: warranty
                    number: Z21D083991
                    product_type_id: 3
                    product_model: MQ 3005 WH CREAM
                    product_serial_number: 123-xxx-456
                    external_id: moje znacka 45
                    status: incoming
                    substatus: null
                    date_buy: "2021-06-03"
                    created: "2026-07-01 09:15:32"
                    customer_id: 1234
                    customer_address:
                      firstname: Petr
                      surname: Novák
                      email: petr.novak@testapi.cz
                      phone: "777888999"
                      company: ""
                      tin: null
                      vatin: null
                      street: U Kolejí 12
                      city: Praha
                      zip: "16200"
                      country: CZ
                      latLng: [50.0989, 14.3323]
                    service_centre_id: 11
                    service_centre_address:
                      company: Servis Praha s.r.o.
                      firstname: ""
                      surname: ""
                      email: servis@example.com
                      phone: "+420222333444"
                      tin: "12345678"
                      vatin: CZ12345678
                      street: Průmyslová 1200/4
                      city: Praha 10
                      zip: "10200"
                      country: CZ
                      latLng: null
                    activities: []
                    shipments: []
  /commissions/{id}:
    get:
      tags: [Zakázky]
      summary: Detail zakázky
      description: Vrací detail jedné zakázky podle jejího interního ID.
      parameters:
        - name: id
          in: path
          required: true
          description: Interní ID zakázky.
          schema:
            type: integer
          example: 1234
      responses:
        "200":
          description: Detail zakázky.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    $ref: "#/components/schemas/Commission"
              example:
                status: 200
                data:
                  id: 6350
                  token: bfd41c8e6a5361f7e4b95c0f
                  type: warranty
                  number: Z21D083991
                  product_type_id: 3
                  product_model: MQ 3005 WH CREAM
                  product_serial_number: 123-xxx-456
                  external_id: moje znacka 45
                  status: processing
                  substatus: null
                  date_buy: "2021-06-03"
                  created: "2026-07-01 09:15:32"
                  customer_id: 1234
                  customer_address:
                    firstname: Petr
                    surname: Novák
                    email: petr.novak@testapi.cz
                    phone: "777888999"
                    company: ""
                    tin: null
                    vatin: null
                    street: U Kolejí 12
                    city: Praha
                    zip: "16200"
                    country: CZ
                    latLng: [50.0989, 14.3323]
                  service_centre_id: 11
                  service_centre_address:
                    company: Servis Praha s.r.o.
                    firstname: ""
                    surname: ""
                    email: servis@example.com
                    phone: "+420222333444"
                    tin: "12345678"
                    vatin: CZ12345678
                    street: Průmyslová 1200/4
                    city: Praha 10
                    zip: "10200"
                    country: CZ
                    latLng: null
                  activities:
                    - id: 18001
                      commission_id: 6350
                      commission_number: Z21D083991
                      type: status
                      created: "2026-07-01 09:15:32"
                      user_name: SYSTEM
                      is_internal: 0
                      is_customer: 0
                      message: Zakázka byla vytvořena.
                      files: []
                    - id: 18002
                      commission_id: 6350
                      commission_number: Z21D083991
                      type: message
                      created: "2026-07-02 14:02:10"
                      user_name: SERVIS
                      is_internal: 0
                      is_customer: 0
                      message: Přístroj přijat, zahajujeme diagnostiku.
                      files: []
                  shipments:
                    - id: 9101
                      commission_id: 6350
                      commission_number: Z21D083991
                      number: IZ0123456789
                      number_carrier: "12345678901234"
                      carrier: DPD
                      type: incoming
                      collection: dropoff
                      collection_date: null
                      status: delivered
                      tracking:
                        - date: "2026-07-02"
                          time: "08:45:00"
                          location: Depo Praha
                          name: Zásilka byla doručena do servisu.
                          status: delivered
                      label: https://returns-demo.zaslat.cz/labels/download/bfd41c8e
                      label_printed: 1
                      from:
                        firstname: Petr
                        surname: Novák
                        street: U Kolejí 12
                        city: Praha
                        zip: "16200"
                        country: CZ
                      to:
                        company: Servis Praha s.r.o.
                        street: Průmyslová 1200/4
                        city: Praha 10
                        zip: "10200"
                        country: CZ
                      cod: 0
                      cod_currency: CZK
                      cod_variable: null
                      cod_bank_account_id: null
                      weight: 5
                      last_error: null
                      created: "2026-07-01 09:15:40"
  /commissions/create:
    post:
      tags: [Zakázky]
      summary: Vytvoření zakázky
      description: |-
        Vytvoří novou zakázku a případně objedná dopravu od zákazníka do servisu.

        Zakázku lze vytvořit i bez objednávky dopravy (`shipment_from_customer: false`) — jde
        potom o **jednosměrnou** zakázku, sloužící pouze k zaslání výrobku zákazníkovi zpět.
        **Obousměrná** zakázka obsahuje na konci servisního procesu jak dopravu od zákazníka, tak
        dopravu zpět k zákazníkovi.

        Při vytvoření zakázky včetně dopravy (`shipment_from_customer: true`) je zakázka po
        doručení zásilky do servisu automaticky přepnuta do stavu `processing`. V době od
        vytvoření do doručení je zakázka ve stavu `incoming` — zakázky vytvořené servisním
        střediskem přes API jsou totiž automaticky schválené (na rozdíl od zakázek zadaných
        koncovým zákazníkem přes frontend, které čekají ve stavu `pending` na schválení).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCommissionRequest"
            example:
              customer:
                company: ""
                firstname: "Petr"
                surname: "Novák"
                street: "U Kolejí 12"
                city: "Praha"
                zip: "16200"
                country: "CZ"
                phone: "777888999"
                email: "petr.novak@testapi.cz"
              shipment_from_customer: true
              shipment:
                collection: "dropoff"
                collection_date: null
              date_buy: "2021-06-03"
              product_id: 11
              type: "warranty"
              invoice_file_token: "ljHIOHi5fsfsjuhe578fsdSFFgs"
              external_id: null
              message: "Pristroj nefunguje."
      responses:
        "200":
          description: Úspěšné vytvoření zakázky.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    $ref: "#/components/schemas/Commission"
              example:
                status: 200
                data:
                  id: 6351
                  token: c0f41bfd2eb6987d41c8e6a5
                  type: warranty
                  number: Z26D084102
                  product_type_id: 3
                  product_model: MQ 3005 WH CREAM
                  product_serial_number: null
                  external_id: null
                  status: incoming
                  substatus: null
                  date_buy: "2021-06-03"
                  created: "2026-07-06 10:12:05"
                  customer_id: 1235
                  customer_address:
                    firstname: Petr
                    surname: Novák
                    email: petr.novak@testapi.cz
                    phone: "777888999"
                    company: ""
                    street: U Kolejí 12
                    city: Praha
                    zip: "16200"
                    country: CZ
                  service_centre_id: 11
                  service_centre_address:
                    company: Servis Praha s.r.o.
                    street: Průmyslová 1200/4
                    city: Praha 10
                    zip: "10200"
                    country: CZ
                  activities:
                    - id: 18101
                      commission_id: 6351
                      commission_number: Z26D084102
                      type: status
                      created: "2026-07-06 10:12:05"
                      user_name: SYSTEM
                      is_internal: 0
                      is_customer: 0
                      message: Zakázka byla vytvořena.
                      files: []
                  shipments:
                    - id: 9102
                      commission_id: 6351
                      commission_number: Z26D084102
                      number: IZ1234567890
                      number_carrier: null
                      carrier: DPD
                      type: incoming
                      collection: dropoff
                      collection_date: null
                      status: created
                      tracking: []
                      label: https://returns-demo.zaslat.cz/labels/download/c0f41bfd
                      label_printed: 0
                      cod: 0
                      cod_currency: CZK
                      weight: 5
                      last_error: null
                      created: "2026-07-06 10:12:08"
        "400":
          description: Chyba validace vstupních dat.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorResponse"
              example:
                message: Request validation error.
                status: 400
                errors:
                  - field: invoice_file_token
                    message: Je zapotřebí vyplnit Invoice File Token.
                type: common\exceptions\ValidationException
  /commissions/edit:
    post:
      tags: [Zakázky]
      summary: Úprava zakázky
      description: |-
        Slouží ke změně údajů zakázky a k objednání dopravy ze servisu zpět k zákazníkovi.

        Pokud je objednávána doprava zpět k zákazníkovi (`shipment_to_customer: true`), zakázka se
        po doručení zásilky zpět zákazníkovi automaticky uzavře a vygenerují se příslušné
        notifikace. Bez zásilky zákazníkovi zůstává zakázka otevřená až do ručního uzavření
        (servisním střediskem, nebo nastavením `status` přes toto API).

        Objednaná odchozí zásilka se vytvoří na nejbližší termín svozu; zakázka musí být ve stavu
        `outgoing` (lze nastavit současně s objektem `shipment`) a automaticky se exportuje
        dopravci.

        ⚠️ Zdrojová tabulka „BODY" pro tento endpoint nebyla při tvorbě této specifikace čitelná.
        Pole požadavku níže byla rekonstruována z ukázkových JSON požadavků v dokumentaci —
        doporučujeme ověřit proti zdrojové tabulce, zejména u pole `product_model` (v ukázce se
        objevuje jako vstupní pole, ačkoli se stejnojmenné pole jinak jeví jako odvozené z
        `product_id`/`external_key`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EditCommissionRequest"
            example:
              number: "Z21D083991"
              product_id: 11
              product_model: "MQ 3005 WH CREAM"
              product_serial_number: "123-xxx-456"
              type: "warranty"
              external_id: "moje znacka 45"
              date_buy: "2021-06-03"
              status: "outgoing"
              customer:
                firstname: "Jaroslav"
                surname: "Novák"
                company: "Zaslat s.r.o."
                street: "Jindřišská 12/1027"
                city: "Praha 4"
                zip: "14000"
                phone: "+420777152225"
                email: "novotny@dummymail.com"
                country: "CZ"
              shipment_to_customer: true
              shipment:
                collection: "pickup"
                weight: 21
      responses:
        "200":
          description: Úspěšné uložení změny.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "OK. Saved."
                  data:
                    $ref: "#/components/schemas/Commission"
              example:
                status: 200
                message: OK. Saved.
                data:
                  id: 6350
                  token: bfd41c8e6a5361f7e4b95c0f
                  type: warranty
                  number: Z21D083991
                  product_type_id: 3
                  product_model: MQ 3005 WH CREAM
                  product_serial_number: 123-xxx-456
                  external_id: moje znacka 45
                  status: outgoing
                  substatus: null
                  date_buy: "2021-06-03"
                  created: "2026-07-01 09:15:32"
                  customer_id: 1234
                  customer_address:
                    firstname: Jaroslav
                    surname: Novák
                    company: Zaslat s.r.o.
                    email: novotny@dummymail.com
                    phone: "+420777152225"
                    street: Jindřišská 12/1027
                    city: Praha 4
                    zip: "14000"
                    country: CZ
                  service_centre_id: 11
                  service_centre_address:
                    company: Servis Praha s.r.o.
                    street: Průmyslová 1200/4
                    city: Praha 10
                    zip: "10200"
                    country: CZ
                  activities: []
                  shipments:
                    - id: 9103
                      commission_id: 6350
                      commission_number: Z21D083991
                      number: IZ2345678901
                      number_carrier: null
                      carrier: DPD
                      type: outgoing
                      collection: pickup
                      collection_date: "2026-07-07"
                      status: created
                      tracking: []
                      label: null
                      label_printed: 0
                      cod: 0
                      cod_currency: CZK
                      weight: 21
                      last_error: null
                      created: "2026-07-06 11:40:12"
        "400":
          description: >-
            Chyba validace vstupních dat, editace zakázky nepříslušící servisu, nebo jiná chyba
            požadavku.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorResponse"
              examples:
                neopravnena_editace:
                  summary: Editace zakázky nepříslušící servisu
                  value:
                    status: 400
                    message: "Bad request."
                    data:
                      field: "number"
                      message: "You are not authorized edit commission bynumber"
                validace_vstupu:
                  summary: Validace vstupních dat
                  value:
                    message: "Request validation error."
                    status: 400
                    errors:
                      - field: "product_type_id"
                        message: "Je zapotřebí vyplnit Product Type Id."
                    type: "common\\exceptions\\ValidationException"
  /commissions/upload-file:
    post:
      tags: [Zakázky]
      summary: Nahrání souboru k zakázce
      description: >-
        Slouží k nahrání souboru potřebného u záručních oprav, zejména dokladu o nákupu výrobku.
        Vrácený `token` se následně použije v poli `invoice_file_token` při vytvoření zakázky.
        Povolené koncovky: PDF, JPG, JPEG. Maximální velikost souboru je 2 MB.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: Nahrávaný soubor (PDF, JPG nebo JPEG, max. 2 MB).
      responses:
        "200":
          description: Soubor byl uložen na externí úložiště.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadFileResponse"
              example:
                status: 200
                message: OK. Saved.
                token: ljHIOHi5fsfsjuhe578fsdSFFgs
                url: https://storage.zaslat.cz/returns/invoices/ljHIOHi5fsfsjuhe578fsdSFFgs.pdf
                execution_time: 0.42
  /activity/create:
    post:
      tags: [Aktivity]
      summary: Vytvoření aktivity (komentáře) k zakázce
      description: |-
        Slouží k doplnění informace pro servis nebo pro zákazníka — např. jak byla zakázka
        vyřízena, nebo zveřejnění výňatku ze servisního protokolu.

        Parametr `is_internal` rozlišuje, zda se komentář zobrazí jak servisnímu středisku, tak
        zákazníkovi (`0`), nebo pouze servisnímu středisku jako interní poznámka (`1`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateActivityRequest"
            example:
              commission_id: 6350
              type: "message"
              message: "Testovací message přes API customer"
              user_name: "SERVIS"
              is_internal: 0
      responses:
        "200":
          description: Aktivita byla uložena.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "OK. Saved."
                  data:
                    $ref: "#/components/schemas/Activity"
                  execution_time:
                    type: number
                    format: float
              example:
                status: 200
                message: OK. Saved.
                data:
                  id: 18102
                  commission_id: 6350
                  commission_number: Z21D083991
                  type: message
                  created: "2026-07-06 12:05:44"
                  user_name: SERVIS
                  is_internal: 0
                  is_customer: 0
                  message: Testovací message přes API customer
                  files: []
                execution_time: 0.18
  /product-model:
    get:
      tags: [Výrobky]
      summary: Seznam modelů výrobků
      description: >-
        Vylistuje modely výrobků. Seznam lze omezit na konkrétní značku parametrem `brand`
        (kódové označení značky typu výrobku) nebo dohledat podle EAN kódu.
      parameters:
        - name: brand
          in: query
          required: false
          description: Kódové označení značky produktů.
          schema:
            type: string
        - name: ean
          in: query
          required: false
          description: EAN kód produktu.
          schema:
            type: integer
      responses:
        "200":
          description: Seznam modelů výrobků.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProductModel"
                  execution_time:
                    type: number
                    format: float
              example:
                status: 200
                message: OK
                data:
                  - id: 11
                    value: MQ 3005 WH CREAM
                    external_key: "MTX-4587"
                    brand_code: demo
                    ean: "8590393254128"
                  - id: 12
                    value: MQ 4010 BK
                    external_key: "MTX-4588"
                    brand_code: demo
                    ean: "8590393254135"
                execution_time: 0.09
  /product-type:
    get:
      tags: [Výrobky]
      summary: Strom kategorií výrobků
      description: >-
        Vrací strom kategorií (typů) výrobků potřebný pro vytvoření nebo úpravu zakázky. Výpis lze
        omezit na konkrétní značku parametrem `brand`. Data jsou filtrována podle přihlášeného
        servisního střediska s ohledem na typy produktů, které mu správce přiřadil.
      parameters:
        - name: brand
          in: query
          required: false
          description: "Kódové označení značky produktů (na demo účtu lze vyzkoušet `demo`)."
          schema:
            type: string
      responses:
        "200":
          description: Strom kategorií výrobků.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "OK"
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProductTypeNode"
              example:
                status: 200
                message: OK
                data:
                  - value: "1"
                    label: Domácí spotřebiče
                    parent_id: null
                    children:
                      - value: "3"
                        label: Kuchyňské roboty
                        parent_id: "1"
                        children: []
                      - value: "4"
                        label: Mixéry
                        parent_id: "1"
                        children: []
                  - value: "2"
                    label: Zahradní technika
                    parent_id: null
                    children: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-apikey
      description: |-
        API klíč pro produkční prostředí najdete ve správním rozhraní v sekci API. Pro testovací
        prostředí (`returns-demo.zaslat.cz`) použijte:

        - E-mail: `apitest@apitest.cz`
        - Heslo: `apitest`
        - API klíč: `72xfT62wIlttqh06imGrjTrxn69kk1DAz9o5ITso`
  schemas:
    PageMeta:
      type: object
      description: Metadata stránkování seznamu.
      properties:
        total:
          type: integer
          description: Celkový počet záznamů odpovídajících filtru.
        count:
          type: integer
          description: Počet záznamů na aktuální stránce.
        page_current:
          type: integer
          description: Číslo aktuální stránky.
        page_total:
          type: integer
          description: Celkový počet stránek.
        page_size:
          type: integer
          description: Velikost stránky.
    Address:
      type: object
      description: Adresa zákazníka nebo servisního střediska (návratový tvar v detailu zakázky).
      properties:
        firstname:
          type: string
        surname:
          type: string
        email:
          type: string
        phone:
          type: string
        company:
          type: string
        tin:
          type: string
          nullable: true
          description: IČ.
        vatin:
          type: string
          nullable: true
          description: DIČ.
        street:
          type: string
        city:
          type: string
        zip:
          type: string
        country:
          type: string
          description: Kód země, např. ISO 3166-1 alpha-2 (`CZ`).
        latLng:
          type: array
          nullable: true
          items:
            type: number
            format: double
          minItems: 2
          maxItems: 2
          description: Zeměpisná šířka a délka adresy.
    CustomerInput:
      type: object
      description: |-
        Objekt zákazníka odesílaný při vytvoření nebo úpravě zakázky.

        ⚠️ Rekonstruováno z ukázkových požadavků v dokumentaci (zdrojová tabulka „CUSTOMER" nebyla
        čitelná) — pole `tin` a `vatin` jsou převzata z tvaru adresy v odpovědi a jejich
        zapisovatelnost přes toto API nebyla ověřena.
      required:
        - firstname
        - surname
      properties:
        firstname:
          type: string
        surname:
          type: string
        company:
          type: string
          description: Povinné místo `firstname` + `surname`, jde-li o firemního zákazníka.
        street:
          type: string
        city:
          type: string
        zip:
          type: string
        country:
          type: string
          description: Kód země, např. ISO 3166-1 alpha-2 (`CZ`).
        phone:
          type: string
        email:
          type: string
        tin:
          type: string
          description: "⚠️ IČ — nepotvrzeno jako vstupní pole."
        vatin:
          type: string
          description: "⚠️ DIČ — nepotvrzeno jako vstupní pole."
    ShipmentInput:
      type: object
      description: |-
        Objekt zásilky odesílaný při vytvoření zakázky (`shipment_from_customer: true`) nebo při
        objednání odchozí zásilky (`shipment_to_customer: true`).

        ⚠️ Rekonstruováno z ukázkových požadavků v dokumentaci (zdrojová tabulka „SHIPMENT" nebyla
        čitelná) — je pravděpodobné, že objekt podporuje další pole viditelná ve tvaru odpovědi
        (např. dobírku `cod`/`cod_currency`/`cod_variable`, vlastní adresy `from`/`to`), ale jejich
        zapisovatelnost a přesné názvy nebyly ověřeny.
      properties:
        collection:
          $ref: "#/components/schemas/Collection"
        collection_date:
          type: string
          format: date
          nullable: true
          description: Požadované datum vyzvednutí (`YYYY-MM-DD`), lze `null`.
        weight:
          type: number
          description: Hmotnost zásilky.
    CreateCommissionRequest:
      type: object
      required:
        - customer
        - shipment_from_customer
        - date_buy
        - message
        - type
      properties:
        customer:
          allOf:
            - $ref: "#/components/schemas/CustomerInput"
          description: Objekt určující adresu zákazníka.
        shipment_from_customer:
          type: boolean
          description: >-
            Příznak, zda má zakázka příchozí zásilku od zákazníka (`true` – obousměrná zakázka)
            nebo ne (`false` – jednosměrná zakázka).
        shipment:
          allOf:
            - $ref: "#/components/schemas/ShipmentInput"
          description: "Vyžadováno pouze pokud `shipment_from_customer: true`."
        date_buy:
          type: string
          format: date
          description: Datum zakoupení výrobku ve formátu `YYYY-MM-DD`.
        product_id:
          type: integer
          description: >-
            ID modelu výrobku (získané voláním `GET /product-model`). Je nutné zvolit právě jednu
            z variant `product_id` nebo `external_key` — model výrobku musí existovat a být
            přiřazen alespoň k jednomu servisnímu středisku.
        external_key:
          type: string
          description: Externí označení modelu výrobku (alternativa k `product_id`, viz výše).
        message:
          type: string
          description: Popis závady.
        type:
          $ref: "#/components/schemas/CommissionType"
        invoice_file_token:
          type: string
          description: >-
            Token souboru dokladu o nákupu, získaný voláním `POST /commissions/upload-file`.
            Povinné v případě záruční (`warranty`) zakázky.
        external_id:
          type: string
          nullable: true
          description: Značka zákazníka / externí identifikátor.
        product_serial_number:
          type: string
          description: Sériové číslo výrobku.
        pre_sale_service:
          type: boolean
          description: Předprodejní servis.
        refund_money:
          type: boolean
          description: Požadavek na vrácení kupní ceny výrobku po dokončení zakázky.
    EditCommissionRequest:
      type: object
      description: >-
        Alespoň jedno z polí `id` nebo `number` je povinné a zakázka musí příslušet servisnímu
        středisku volajícího uživatele.
      properties:
        id:
          type: integer
          description: Interní ID zakázky (alternativa k `number`).
        number:
          type: string
          description: Číslo zakázky (alternativa k `id`).
        product_id:
          type: integer
        product_model:
          type: string
          description: >-
            ⚠️ Objevuje se v ukázkovém požadavku jako vstupní pole; jinde v dokumentaci je stejné
            pole popsáno jako odvozené od `product_id`/`external_key` — nebylo možné ověřit, zda
            jde skutečně o přímo editovatelnou hodnotu.
        product_serial_number:
          type: string
        type:
          $ref: "#/components/schemas/CommissionType"
        external_id:
          type: string
          nullable: true
        date_buy:
          type: string
          format: date
        status:
          allOf:
            - $ref: "#/components/schemas/CommissionStatus"
          description: >-
            Nastavení jiného než aktuálního stavu zakázky vyvolá navazující akce (push notifikace,
            e-mailová notifikace).
        customer:
          allOf:
            - $ref: "#/components/schemas/CustomerInput"
          description: >-
            Uvádí se pouze v případě, že je potřeba editovat kontaktní údaje zákazníka. Povinné
            `firstname` + `surname`, nebo `company`.
        shipment_to_customer:
          type: boolean
          description: Příznak objednání odchozí zásilky zpět zákazníkovi.
        shipment:
          allOf:
            - $ref: "#/components/schemas/ShipmentInput"
          description: "Vyžadováno společně s `shipment_to_customer: true`."
    Commission:
      type: object
      description: Detail servisní zakázky.
      properties:
        id:
          type: integer
        token:
          type: string
          description: >-
            Token pro veřejné zobrazení zakázky zákazníkovi, např.
            `https://nokia.zaslat.cz/commissions/<token>`.
        type:
          $ref: "#/components/schemas/CommissionType"
        number:
          type: string
        product_type_id:
          type: integer
          description: ID kategorie produktu (viz `GET /product-type`).
        product_model:
          type: string
          description: Název modelu výrobku.
        product_serial_number:
          type: string
        external_id:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/CommissionStatus"
        substatus:
          type: string
          nullable: true
        date_buy:
          type: string
          format: date
        created:
          type: string
          description: Datum a čas vytvoření zakázky.
        customer_id:
          type: integer
        customer_address:
          $ref: "#/components/schemas/Address"
        service_centre_id:
          type: integer
          description: Interní ID servisního střediska.
        service_centre_address:
          $ref: "#/components/schemas/Address"
        activities:
          type: array
          items:
            $ref: "#/components/schemas/Activity"
        shipments:
          type: array
          items:
            $ref: "#/components/schemas/Shipment"
    ActivityFile:
      type: object
      properties:
        name:
          type: string
        mime:
          type: string
        url:
          type: string
    Activity:
      type: object
      description: Aktivita (zpráva nebo záznam o změně stavu) přiřazená k zakázce.
      properties:
        id:
          type: integer
        commission_id:
          type: integer
        commission_number:
          type: string
        type:
          $ref: "#/components/schemas/ActivityType"
        created:
          type: string
        user_name:
          type: string
        is_internal:
          type: integer
          enum: [0, 1]
          description: "`0` – veřejná (viditelná i zákazníkovi), `1` – interní."
        is_customer:
          type: integer
          nullable: true
          enum: [0, 1]
          description: "`0` – od servisního střediska, `1` – od zákazníka."
        message:
          type: string
        files:
          type: array
          items:
            $ref: "#/components/schemas/ActivityFile"
    CreateActivityRequest:
      type: object
      description: Alespoň jedno z polí `commission_id` nebo `commission_number` je povinné.
      properties:
        commission_id:
          type: integer
          description: Interní identifikátor existující zakázky (alternativa k `commission_number`).
        commission_number:
          type: string
          description: Číslo zakázky (alternativa k `commission_id`).
        type:
          $ref: "#/components/schemas/ActivityType"
        is_internal:
          type: integer
          enum: [0, 1]
          description: "`0` – veřejná, `1` – interní."
        user_name:
          type: string
          description: Jméno přispěvatele. Pokud není vyplněno, doplní se z popisu servisního centra.
        message:
          type: string
      required:
        - type
    TrackingEvent:
      type: object
      properties:
        date:
          type: string
          format: date
        time:
          type: string
        location:
          type: string
          description: Místo události (depo apod.).
        name:
          type: string
          description: Popis události.
        status:
          type: string
          description: Interní název stavu události.
    Shipment:
      type: object
      description: Zásilka přiřazená k zakázce (v návratovém tvaru).
      properties:
        id:
          type: integer
        commission_id:
          type: integer
        commission_number:
          type: string
        number:
          type: string
          description: Sledovací číslo v systému Zaslat.
        number_carrier:
          type: string
          nullable: true
          description: Sledovací číslo dopravce.
        carrier:
          type: string
          description: Název dopravce.
        type:
          $ref: "#/components/schemas/ShipmentDirection"
        collection:
          $ref: "#/components/schemas/Collection"
        collection_date:
          type: string
          format: date
          nullable: true
        status:
          $ref: "#/components/schemas/ShipmentStatus"
        tracking:
          type: array
          items:
            $ref: "#/components/schemas/TrackingEvent"
        label:
          type: string
          nullable: true
          description: Odkaz na stažení štítku k zásilce (pokud je vyžadován).
        label_printed:
          type: integer
          enum: [0, 1]
          description: "`0` – nevytištěn, `1` – vytištěn."
        from:
          $ref: "#/components/schemas/Address"
        to:
          $ref: "#/components/schemas/Address"
        cod:
          type: number
          description: Hodnota dobírky.
        cod_currency:
          type: string
        cod_variable:
          type: string
          nullable: true
          description: Variabilní symbol dobírky.
        cod_bank_account_id:
          type: integer
          nullable: true
        weight:
          type: number
        last_error:
          description: Chyba při exportu zásilky dopravci, pokud k selhání dojde.
          nullable: true
          oneOf:
            - type: string
            - type: array
              items: {}
        created:
          type: string
          description: Datum a čas vytvoření zásilky.
    ProductModel:
      type: object
      properties:
        id:
          type: integer
        value:
          type: string
          description: Název modelu.
        external_key:
          description: Externí označení modelu (ID z externího systému, např. Matrix).
          oneOf:
            - type: string
            - type: integer
        brand_code:
          type: string
        ean:
          type: string
    ProductTypeNode:
      type: object
      description: Uzel stromu kategorií výrobků (rekurzivní struktura).
      properties:
        value:
          type: string
        label:
          type: string
        parent_id:
          type: string
          nullable: true
        children:
          type: array
          items:
            $ref: "#/components/schemas/ProductTypeNode"
    UploadFileResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "OK. Saved."
        token:
          type: string
          description: Token souboru, použije se v poli `invoice_file_token`.
        url:
          type: string
          description: Adresa uloženého souboru na externím úložišti.
        execution_time:
          type: number
          format: float
    ValidationErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 400
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        data:
          type: object
          description: U některých chyb (např. neoprávněná editace) obsahuje pole `field`/`message` přímo.
          properties:
            field:
              type: string
            message:
              type: string
        type:
          type: string
          description: Interní identifikátor typu výjimky.
    CommissionType:
      type: string
      description: Typ zakázky.
      enum: [warranty, afterWarranty]
      x-enum-descriptions:
        warranty: oprava/servis v záruce
        afterWarranty: pozáruční servis/oprava
    CommissionStatus:
      type: string
      description: Stav zakázky.
      enum: [pending, incoming, processing, outgoing, finished, cancelled]
      x-enum-descriptions:
        pending: Nová zakázka, čeká na potvrzení a přiřazení servisnímu středisku.
        incoming: Čeká na příchozí zásilku (na cestě do servisu).
        processing: Po přijetí zásilky, probíhá vyhodnocení servisu.
        outgoing: Odchozí zásilka (na cestě k zákazníkovi).
        finished: Zakázka byla dokončena.
        cancelled: Zrušená zakázka.
    RepairAnywayAction:
      type: string
      description: >-
        Číselník: co udělat, pokud se na výrobek nevztahuje záruka. Určuje zákazník/objednatel
        služby při zaslání výrobku do servisu.
      enum: [repairAnyway, returnBack, ask]
      x-enum-descriptions:
        repairAnyway: >-
          Zákazník si přeje opravit výrobek i v případě, že se na opravu nevztahuje záruka —
          zákazník by měl dostat od servisu cenovou nabídku zpoplatněné služby.
        returnBack: >-
          Pokud není možné uplatnit záruku, vrátit výrobek zpět zákazníkovi — může být účtováno
          dopravné.
        ask: Zákaznická péče se nejdříve doptá, jak s výrobkem naložit.
    UnrepairableAction:
      type: string
      description: >-
        Číselník: co udělat, pokud je výrobek neopravitelný. Určuje zákazník/objednatel služby při
        zaslání výrobku do servisu.
      enum: [returnBack, dispose, ask]
      x-enum-descriptions:
        returnBack: Vrátit výrobek zpět zákazníkovi — může být účtováno dopravné.
        dispose: Ekologicky zlikvidovat.
        ask: Zákaznická péče se nejdříve doptá, jak s výrobkem naložit.
    Collection:
      type: string
      description: Číselník možností vyzvednutí zásilky.
      enum: [pickup, dropoff, pickupPlace]
      x-enum-descriptions:
        pickup: Vyzvednutí kurýrem na adrese, štítek doveze kurýr.
        dropoff: Odnos na sběrné místo, odesilatel si štítek vytiskne.
        pickupPlace: >-
          Vyzvednutí na sjednané svozové adrese, odesilatel si štítek vytiskne. Zákazník
          objednávající odchozí zásilky musí mít sjednáno svozové místo a zajišťuje si tisk štítků
          sám.
    Source:
      type: string
      description: >-
        Číselník kódů zdrojů vzniku zakázky. ⚠️ Dokumentován v Notionu jako samostatný číselník,
        ale nebyl přímo pozorován jako pole v odpovědi `GET /commissions/{id}` — pravděpodobně
        existuje jako vlastnost zakázky, ale jeho konkrétní umístění ve schématu nebylo ověřeno.
      enum: [public, client, admin, webform, api]
      x-enum-descriptions:
        public: Zakázka vytvořena z veřejné části aplikace (koncový zákazník).
        client: "Zakázka vytvořena skrze klientskou administraci (např. prodejny Makro, OKAY apod.)."
        admin: Zakázka vytvořena z administrátorského prostředí (správce, zákaznická linka, servisní středisko).
        webform: Zakázka vytvořena skrze embedovaný formulář (bezešvé vložení).
        api: Zakázka vytvořena skrze API rozhraní.
    ActivityType:
      type: string
      enum: [message, status]
      x-enum-descriptions:
        message: Zpráva od zákazníka nebo servisního střediska.
        status: Záznam o změně stavu zakázky, objednání zásilky atd.
    ShipmentDirection:
      type: string
      enum: [incoming, outgoing]
      x-enum-descriptions:
        incoming: Zásilka od zákazníka.
        outgoing: Zásilka ze servisního střediska zákazníkovi.
    ShipmentStatus:
      type: string
      description: >-
        Stav zásilky. ⚠️ Zdrojová dokumentace uvádí pouze výčet hodnot bez popisu jednotlivých
        stavů.
      enum:
        - pending
        - created
        - exported
        - onpickup
        - intransit
        - ondelivery
        - delivered
        - cancelled
