openapi: 3.0.3
info:
  title: Zaslat API v1
  version: "1.0.0"
  contact:
    name: Zaslat API Support
    url: https://docs.zaslat.cz/api/v1/content
    email: support@zaslat.cz
  description: |-
    API rozhraní **Zaslat API v1** pro získávání nabídek přepravy, vytváření a správu zásilek,
    žádosti o svoz, výdejní/podací místa a adresář kontaktů.

    ## 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í ([app.zaslat.cz](https://app.zaslat.cz)) v sekci **API**
    (Nastavení uživatele).

    ## Rozšířené specifikace

    Endpoint `POST /shipments/create` má dvě rozšířené varianty popsané samostatně:

    - [Objednávka celní zásilky](/api/v1/customs_shipment_order) — objekt `customs` potřebný pro
      celní řízení u zahraničních zásilek.
    - [Objednávka ze svozové adresy](/api/v1/order_from_pickup_address) — vlastní tisk štítků
      (typ `OCCASIONAL`) při svozu ze smluvní adresy.

servers:
  - url: https://test.zaslat.cz/api/v1
    description: Testovací prostředí (API klíč z app-test.zaslat.cz)
security:
  - ApiKeyAuth: []
tags:
  - name: Nabídka přepravy
    description: Získání nabídek dopravců s cenou a termínem doručení.
  - name: Zásilky
    description: Vytváření zásilek, štítky, seznam, detail, tracking, storno a manifest.
  - name: Svozy
    description: Žádosti o svoz zásilek od svozové adresy.
  - name: Podací a výdejní místa
    description: Číselník podacích a výdejních míst dopravců.
  - name: Adresář
    description: Správa uložených kontaktů.
paths:
  /rates/get:
    post:
      tags: [Nabídka přepravy]
      summary: Nabídka přepravy
      description: |-
        Vrátí nabídky dopravců (cena, termín svozu a doručení) na základě zadaných adres, balíků a
        případných doplňkových služeb.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RatesGetRequest"
            examples:
              vnitrostatni:
                summary: Vnitrostátní zásilka (CZ → CZ)
                value:
                  currency: CZK
                  pickup_date: "2026-07-10"
                  from:
                    country: CZ
                  to:
                    country: CZ
                  packages:
                    - weight: 1
                      width: 10
                      height: 20
                      length: 30
              mezinarodni-dobirka:
                summary: Mezinárodní zásilka s dobírkou (CZ → SK)
                value:
                  currency: CZK
                  pickup_date: "2026-07-10"
                  from:
                    country: CZ
                  to:
                    country: SK
                  services:
                    - code: COD
                      data:
                        value:
                          value: 1500
                          currency: CZK
                  packages:
                    - weight: 1
                      width: 10
                      height: 20
                      length: 30
              vydejni-misto:
                summary: Doručení na výdejní místo
                value:
                  currency: CZK
                  from:
                    country: CZ
                  to:
                    country: CZ
                  delivery_branch: KM11730100
                  packages:
                    - weight: 2
                      width: 20
                      height: 15
                      length: 30
      responses:
        "200":
          description: Seznam nabídek přepravy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  rates:
                    type: array
                    items:
                      $ref: "#/components/schemas/Rate"
              example:
                status: 200
                message: Found 3 offers
                rates:
                  - carrier: GLS
                    service: Export SK
                    service_id: 21
                    pickup_date: "2026-07-10"
                    pickup_from_time: "08:00:00"
                    pickup_to_time: "18:00:00"
                    delivery_date: "2026-07-13"
                    price:
                      value: 178.51
                      currency: CZK
                    price_vat:
                      value: 216
                      currency: CZK
                    insurance_limit:
                      value: 50000
                      currency: CZK
                    weight_limit: 40
                    trackable: true
                    printable: true
                    shipment_category: exportEu
                  - carrier: DPD
                    service: Classic SK
                    service_id: 8
                    pickup_date: "2026-07-10"
                    pickup_from_time: "08:00:00"
                    pickup_to_time: "17:00:00"
                    delivery_date: "2026-07-13"
                    price:
                      value: 189.90
                      currency: CZK
                    price_vat:
                      value: 229.78
                      currency: CZK
                    insurance_limit:
                      value: 50000
                      currency: CZK
                    weight_limit: 31.5
                    trackable: true
                    printable: true
                    shipment_category: exportEu
                  - carrier: PPL
                    service: Parcel Connect
                    service_id: 14
                    pickup_date: "2026-07-10"
                    pickup_from_time: "09:00:00"
                    pickup_to_time: "18:00:00"
                    delivery_date: "2026-07-14"
                    price:
                      value: 205.00
                      currency: CZK
                    price_vat:
                      value: 248.05
                      currency: CZK
                    insurance_limit:
                      value: 50000
                      currency: CZK
                    weight_limit: 30
                    trackable: true
                    printable: true
                    shipment_category: exportEu
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/create:
    post:
      tags: [Zásilky]
      summary: Vytvoření objednávky zásilek
      description: |-
        Vytvoří jednu nebo více zásilek. Pokud nebude uvedena platba nebo měna, použijí se
        výchozí hodnoty účtu. Pokud je požadavek autentizován přes `x-apikey`, není nutné uvádět
        `payer` — plátcem se automaticky stává přihlášený uživatel.

        Pro celní zásilky a svoz s vlastním tiskem štítků viz
        [rozšířené specifikace](#description/rozsirene-specifikace) výše.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShipmentsCreateRequest"
            examples:
              zakladni:
                summary: Základní objednávka (kontakt z adresáře)
                value:
                  currency: CZK
                  payment_type: ONLINE
                  shipments:
                    - pickup_date: "2026-07-10"
                      from:
                        id: 1001
                      to:
                        firstname: Jaroslav
                        surname: Novotný
                        company: Zaslat s.r.o.
                        street: Jindřišská 12/1027
                        city: Praha 4
                        zip: "14000"
                        country: CZ
                        phone: "+420777152225"
                        email: novotny@dummymail.com
                      packages:
                        - weight: 1
                          width: 10
                          height: 20
                          length: 30
              dobirka-pojisteni:
                summary: Dobírka a připojištění
                value:
                  currency: CZK
                  payment_type: CREDIT
                  shipments:
                    - carrier: GLS
                      pickup_date: "2026-07-10"
                      from:
                        id: 1001
                      to:
                        firstname: Jaroslav
                        surname: Novotný
                        street: Jindřišská 12/1027
                        city: Praha 4
                        zip: "14000"
                        country: CZ
                        phone: "+420777152225"
                        email: novotny@dummymail.com
                      services:
                        - code: COD
                          data:
                            bank_account: "12-34567890"
                            bank_code: "0100"
                            bank_variable: "20260001"
                            value:
                              value: 1500
                              currency: CZK
                        - code: INS
                          data:
                            value: 12500
                            currency: CZK
                      packages:
                        - weight: 1
                          width: 10
                          height: 20
                          length: 30
                      reference: "objednavka-2026-0001"
              vydejni-misto:
                summary: Doručení na výdejní místo
                value:
                  currency: CZK
                  payment_type: CREDIT
                  shipments:
                    - carrier: ZASILKOVNA
                      pickup_date: "2026-07-10"
                      delivery_branch: "12345"
                      from:
                        id: 1001
                      to:
                        firstname: Karel
                        surname: Dvořák
                        country: CZ
                        phone: "+420602111222"
                        email: karel.dvorak@example.com
                      packages:
                        - weight: 2
                          width: 20
                          height: 15
                          length: 30
              celni-zasilka:
                summary: Celní zásilka (mimo EU) s objektem customs
                value:
                  currency: CZK
                  payment_type: ONLINE
                  shipments:
                    - type: ONDEMAND
                      pickup_date: "2026-07-10"
                      reference: Export
                      from:
                        company: Zaslat s.r.o.
                        firstname: Aleš
                        surname: Vomáčka
                        street: Sukova 49/4
                        city: Brno
                        zip: "60200"
                        country: CZ
                        phone: "+420777888999"
                        email: ales@example.com
                      to:
                        firstname: Brandon
                        surname: Walsch
                        street: Lincoln st 1
                        city: Beverly Hills
                        zip: "90210"
                        country: US
                        phone: "+13105550187"
                        email: brandon@walsch.com
                      packages:
                        - weight: 1
                          width: 10
                          height: 10
                          length: 10
                      customs:
                        reason: commercial
                        invoice: create
                        invoice_files: []
                        currency: EUR
                        items:
                          - name: Commercial goods 1
                            country: CZ
                            quantity: "1"
                            value: "10"
                            hs_code: "0102"
                        additional_info:
                          - type: eori
                            value: CZ123456789
              svozova-adresa:
                summary: Svozová adresa s vlastním tiskem štítků (OCCASIONAL)
                value:
                  currency: CZK
                  payment_type: INVOICE
                  shipments:
                    - type: OCCASIONAL
                      carrier: DPD
                      pickup_date: "2026-07-10"
                      from:
                        id: 123654
                      to:
                        firstname: Jaroslav
                        surname: Novotný
                        street: Jindřišská 12/1027
                        city: Praha 4
                        zip: "14000"
                        country: CZ
                        phone: "+420777152225"
                        email: novotny@dummymail.com
                      packages:
                        - weight: 1
                          width: 10
                          height: 20
                          length: 30
      responses:
        "200":
          description: Zásilky byly úspěšně vytvořeny.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/StatusMessageResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          order:
                            type: string
                            description: Hash identifikátor objednávky.
                          order_number:
                            type: string
                            description: Číslo objednávky.
                          shipments:
                            type: array
                            description: Identifikátory (`tracking_number`) vytvořených zásilek.
                            items:
                              type: string
              example:
                status: 200
                message: Order was successfully created
                data:
                  order: 2eb6987d41c8e6a5361f7e4b95c0f41bfd
                  order_number: OP23100000X
                  shipments:
                    - IZ0123456789
                    - IZ1234567890
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/label:
    post:
      tags: [Zásilky]
      summary: Získání štítků
      description: |-
        Vrátí tiskové štítky pro vybrané zásilky, ve formátu PDF nebo jako URL ke stažení.
        Štítek je dostupný až poté, co dopravce potvrdí přijetí dat o zásilce (stav `EXPORTED`
        a novější).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipments]
              properties:
                shipments:
                  type: array
                  description: Pole identifikátorů zásilek (`tracking_number`).
                  items:
                    type: string
                position:
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 1
                  description: Pozice prvního štítku na tiskovém archu.
                format:
                  type: string
                  enum: [pdf, url, stream]
                  default: pdf
                  description: |-
                    Formát návratové hodnoty — `pdf` vrátí base64 zakódovaný soubor, `url` odkaz
                    ke stažení, `stream` odpoví přímo binárním PDF (bez JSON obálky).
                paper_size:
                  type: string
                  enum: [A4, A6]
                  default: A4
                  description: Formát papíru štítku.
            examples:
              url:
                summary: Štítek jako odkaz ke stažení
                value:
                  shipments: ["IZ0123456789"]
                  format: url
                  paper_size: A4
              pdf:
                summary: Štítky jako PDF (base64), 2 ks od druhé pozice archu
                value:
                  shipments: ["IZ0123456789", "IZ1234567890"]
                  format: pdf
                  position: 2
                  paper_size: A4
      responses:
        "200":
          description: Štítek(y) byly vygenerovány.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: string
                    description: Odkaz ke stažení (`format=url`) nebo base64 zakódovaný soubor (`format=pdf`).
              examples:
                url:
                  summary: Odpověď s odkazem ke stažení (format=url)
                  value:
                    status: 200
                    message: OK. Found 1 label(s).
                    data: https://www.zaslat.cz/labels/download/2eb6987d41c8e6a5361f7e4b95c0f41bfd
                pdf:
                  summary: Odpověď s PDF v base64 (format=pdf)
                  value:
                    status: 200
                    message: OK. Found 2 label(s).
                    data: data:application/pdf;base64,ZGF0YTphcHBsaWNhdGlvbi9wZGY7YmFz…
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/list:
    get:
      tags: [Zásilky]
      summary: Seznam zásilek
      description: Vrátí stránkovaný seznam zásilek, který lze filtrovat podle stavu, data nebo identifikátorů.
      parameters:
        - name: status
          in: query
          required: false
          description: Filtrace podle stavu zásilky.
          schema:
            type: string
            enum: [OPEN, ACTIVE, DELIVERED, STORNO]
        - name: offset
          in: query
          required: false
          description: Posun výsledků pro procházení starších zásilek.
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          description: Maximální počet vrácených zásilek.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
        - name: from_date
          in: query
          required: false
          description: Počáteční datum filtru (od data vytvoření).
          schema:
            type: string
            format: date
        - name: to_date
          in: query
          required: false
          description: Koncové datum filtru.
          schema:
            type: string
            format: date
        - name: reference_number
          in: query
          required: false
          description: Filtrace podle vlastní reference zásilky (`reference`).
          schema:
            type: string
        - name: tracking_number
          in: query
          required: false
          description: Filtrace podle identifikátoru zásilky.
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Fulltextové vyhledávání v `reference_number` nebo `tracking_number`.
          schema:
            type: string
        - name: tracking
          in: query
          required: false
          allowEmptyValue: true
          description: Přiložit ke každé zásilce pole `tracking_information` s tracking historií.
          schema:
            type: string
      responses:
        "200":
          description: Seznam zásilek.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShipmentListResponse"
              example:
                status: 200
                message: OK. Found 2 of total 10 item(s).
                data:
                  IZ076151CA1F:
                    carrier: GLS
                    service_id: 7
                    pickup_date: "2026-07-02"
                    delivery_date: "2026-07-03"
                    status: INTRANSIT
                    reference: objednavka-2026-0001
                    from:
                      firstname: František
                      surname: Novotný
                      city: Praha 4
                      zip: "14000"
                      country: CZ
                    to:
                      firstname: Karel
                      surname: Novotný
                      city: Brno
                      zip: "60200"
                      country: CZ
                    packages:
                      - status: INTRANSIT
                        weight: 1
                        width: 10
                        height: 20
                        length: 30
                  IZ1234567890:
                    carrier: DPD
                    service_id: 8
                    pickup_date: "2026-07-01"
                    delivery_date: "2026-07-02"
                    status: DELIVERED
                    from:
                      firstname: František
                      surname: Novotný
                      city: Praha 4
                      zip: "14000"
                      country: CZ
                    to:
                      firstname: Alena
                      surname: Šimková
                      city: Ostrava
                      zip: "70200"
                      country: CZ
                    packages:
                      - status: DELIVERED
                        weight: 2
                        width: 20
                        height: 15
                        length: 30
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/detail:
    post:
      tags: [Zásilky]
      summary: Detail zásilek
      description: |-
        Vrátí podrobné informace k vybraným zásilkám. S query parametrem `tracking` odpověď
        u každé zásilky obsahuje navíc pole `tracking_information` s kompletní tracking
        historií (stejný tvar jako odpověď endpointu `/shipments/tracking`).

        U zásilek do boxů / výdejních míst vybraných dopravců (Zásilkovna, Balíkovna) obsahuje
        objekt [Package](#/components/schemas/Package) v odpovědi navíc parametr
        `package_password` — heslo pro vložení balíku/vratky.
      parameters:
        - name: tracking
          in: query
          required: false
          allowEmptyValue: true
          description: Přiložit tracking historii ke každé zásilce (stačí přítomnost parametru).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipments]
              properties:
                shipments:
                  type: array
                  description: Pole identifikátorů zásilek.
                  items:
                    type: string
            example:
              shipments: ["IZ076151CA1F"]
      responses:
        "200":
          description: Detail zásilek.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShipmentListResponse"
              example:
                status: 200
                message: OK. Found 1 item(s).
                data:
                  IZ076151CA1F:
                    carrier: GLS
                    service_id: 21
                    pickup_date: "2026-07-02"
                    delivery_date: "2026-07-03"
                    status: INTRANSIT
                    reference: objednavka-2026-0001
                    from:
                      firstname: František
                      surname: Novotný
                      street: Jindřišská 12/1027
                      city: Praha 4
                      zip: "14000"
                      country: CZ
                      phone: "+420777152225"
                      email: novotny@dummymail.com
                    to:
                      firstname: Karel
                      surname: Novotný
                      street: Jánská 42
                      city: Brno
                      zip: "60200"
                      country: CZ
                      phone: "+420603001552"
                      email: karel.novotny@dummymail.com
                    services:
                      - code: ins
                        data:
                          value: 12000
                          currency: CZK
                    packages:
                      - status: INTRANSIT
                        weight: 1
                        width: 10
                        height: 20
                        length: 30
                        carrier_tracking: https://gls-group.eu/CZ/cs/sledovani-zasilek?match=123456789
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/tracking:
    post:
      tags: [Zásilky]
      summary: Tracking zásilek
      description: Vrátí aktuální stav a historii tracking událostí vybraných zásilek.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipments]
              properties:
                shipments:
                  type: array
                  description: Pole identifikátorů zásilek.
                  items:
                    type: string
            example:
              shipments: ["IZ076151CA1F"]
      responses:
        "200":
          description: Stav a historie zásilek.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrackingResponse"
              example:
                status: 200
                message: OK. Found 1 item(s).
                data:
                  IZ076151CA1F:
                    status: INTRANSIT
                    returned: false
                    packages:
                      - - date: "2026-07-04"
                          time: "15:00:00"
                          name: Balík byl přijat pobočkou GLS.
                          status: INTRANSIT
                          location: Česká republika
                        - date: "2026-07-02"
                          time: "12:00:00"
                          name: Údaje k balíku byly zadány do systému GLS.
                          status: EXPORTED
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/storno:
    post:
      tags: [Zásilky]
      summary: Storno zásilek
      description: Zruší vybrané zásilky, pokud ještě nebyly předány k přepravě.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipments]
              properties:
                shipments:
                  type: array
                  description: Pole identifikátorů zásilek ke stornování.
                  items:
                    type: string
            example:
              shipments: ["IZ11B85AF140", "IZ12FF58B1A9"]
      responses:
        "200":
          description: Zásilky byly stornovány.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMessageResponse"
              example:
                status: 200
                message: OK. Cancelled.
        "400":
          description: Chybný požadavek — zásilku již nelze stornovat nebo chyba ve vstupních datech.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMessageResponse"
              example:
                status: 400
                message: Request validation error.
                errors:
                  - "shipment[0]: Shipment cannot be cancelled. It's being transported or it has already been delivered."
        "401":
          $ref: "#/components/responses/Unauthorized"
  /shipments/manifest:
    post:
      tags: [Zásilky]
      summary: Předávací protokol (manifest)
      description: Vygeneruje předávací protokol (soupiska) pro vybrané zásilky.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipments]
              properties:
                shipments:
                  type: array
                  description: Pole identifikátorů zásilek.
                  items:
                    type: string
                format:
                  type: string
                  enum: [pdf, url]
                  default: pdf
                  description: Formát výsledného manifestu.
            example:
              shipments: ["IZ0123456789", "IZ1234567890"]
              format: pdf
      responses:
        "200":
          description: Manifest byl vygenerován.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: string
                    description: Odkaz ke stažení (`format=url`) nebo base64 zakódovaný soubor (`format=pdf`).
              example:
                status: 200
                message: OK. Created.
                data: data:application/pdf;base64,ZGF0YTphcHBsaWNhdGlvbi9wZGY7YmFz…
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /pickups/list:
    get:
      tags: [Svozy]
      summary: Seznam žádostí o svoz
      description: Vrátí seznam evidovaných žádostí o svoz.
      responses:
        "200":
          description: Seznam žádostí o svoz.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: object
                    description: Objekt žádostí o svoz klíčovaný jejich identifikátorem.
                    additionalProperties:
                      $ref: "#/components/schemas/Pickup"
              example:
                status: 200
                message: OK. Found 2 item(s).
                data:
                  "16":
                    id: 16
                    date: "2026-07-08"
                    carrier: DPD
                    address_id: 1001
                  "17":
                    id: 17
                    date: "2026-07-09"
                    carrier: PPL
                    address_id: 1001
        "401":
          $ref: "#/components/responses/Unauthorized"
  /pickups/add:
    post:
      tags: [Svozy]
      summary: Vytvoření žádosti o svoz
      description: Vytvoří jednu nebo více žádostí o svoz na svozové adrese.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pickups]
              properties:
                pickups:
                  type: array
                  items:
                    $ref: "#/components/schemas/Pickup"
            example:
              pickups:
                - date: "2026-07-10"
                  carrier: DPD
                  address_id: 1001
                - date: "2026-07-11"
                  carrier: PPL
                  address_id: 1001
      responses:
        "200":
          description: Žádosti o svoz byly vytvořeny.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: array
                    description: Pole identifikátorů nově vytvořených žádostí o svoz.
                    items:
                      type: integer
              example:
                status: 200
                message: 2 pickups successfuly added.
                data: [35, 36]
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /parcelpoints/list:
    get:
      tags: [Podací a výdejní místa]
      summary: Seznam podacích a výdejních míst
      description: Vrátí číselník podacích/výdejních míst, volitelně filtrovaný podle země nebo dopravce.
      parameters:
        - name: country
          in: query
          required: false
          description: Filtrace podle kódu země ([ISO 3166-1 alpha-2](https://cs.wikipedia.org/wiki/ISO_3166-1)).
          schema:
            type: string
            minLength: 2
            maxLength: 2
            example: CZ
        - name: carrier
          in: query
          required: false
          description: Filtrace podle dopravce.
          schema:
            $ref: "#/components/schemas/Carrier"
      responses:
        "200":
          description: Seznam podacích a výdejních míst.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: object
                    description: Objekt podacích/výdejních míst klíčovaný jejich identifikátorem.
                    additionalProperties:
                      $ref: "#/components/schemas/ParcelPoint"
              example:
                status: 200
                message: OK. Found 148 item(s).
                data:
                  "16604":
                    id: 16604
                    carrier: PPL
                    code: KM11730100
                    name: V Háji
                    street: 28. října 89/51
                    city: Plzeň
                    zip: "30100"
                    country: CZ
                    phone: null
                    location:
                      lat: "49.778694444444"
                      lng: "13.409666666667"
                    is_collection: true
                    is_locker: 0
                    is_depot: 0
                    card_payment: 1
                    wheelchair_access: 0
                    no_lunch_break: 1
                    open_saturday: 0
                    open_sunday: 0
                    opening_hours:
                      "1":
                        from1: "13:00"
                        to1: "22:00"
                        from2: null
                        to2: null
        "401":
          $ref: "#/components/responses/Unauthorized"
  /contacts/list:
    get:
      tags: [Adresář]
      summary: Seznam kontaktů
      description: Vrátí seznam uložených kontaktů v adresáři.
      responses:
        "200":
          description: Seznam kontaktů.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: OK
                  errors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Error"
                  data:
                    type: object
                    description: Objekt kontaktů klíčovaný jejich identifikátorem.
                    additionalProperties:
                      $ref: "#/components/schemas/Contact"
              example:
                status: 200
                message: OK. Found 2 item(s).
                data:
                  "1001":
                    id: 1001
                    firstname: Jaroslav
                    surname: Novotný
                    company: Zaslat s.r.o.
                    street: Jindřišská 12/1027
                    city: Praha 4
                    zip: "14000"
                    country: CZ
                    phone: "+420777152225"
                    email: novotny@dummymail.com
                  "1002":
                    id: 1002
                    firstname: Alena
                    surname: Šimková
                    street: Jánská 42
                    city: Brno
                    zip: "60200"
                    country: CZ
                    phone: "+420603001552"
                    email: simkova.alena@dummymail.com
        "401":
          $ref: "#/components/responses/Unauthorized"
  /contacts/add:
    post:
      tags: [Adresář]
      summary: Přidání kontaktů
      description: Přidá jeden nebo více kontaktů do adresáře.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contacts]
              properties:
                contacts:
                  type: array
                  items:
                    $ref: "#/components/schemas/Contact"
            example:
              contacts:
                - firstname: Jaroslav
                  surname: Novotný
                  company: Zaslat s.r.o.
                  street: Jindřišská 12/1027
                  city: Praha 4
                  zip: "14000"
                  country: CZ
                  phone: "+420777152225"
                  email: novotny@dummymail.com
                - firstname: Alena
                  surname: Šimková
                  street: Jánská 42
                  city: Brno
                  zip: "60200"
                  country: CZ
                  phone: "+420603001552"
                  email: simkova.alena@dummymail.com
      responses:
        "200":
          description: Kontakty byly vytvořeny.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactIdsResponse"
              example:
                status: 200
                message: 2 contacts successfuly added.
                data: [1000, 1001]
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /contacts/edit:
    post:
      tags: [Adresář]
      summary: Úprava kontaktů
      description: Upraví existující kontakty podle jejich `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contacts]
              properties:
                contacts:
                  type: array
                  items:
                    $ref: "#/components/schemas/Contact"
            example:
              contacts:
                - id: 1001
                  phone: "+420777888999"
      responses:
        "200":
          description: Kontakty byly upraveny.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactIdsResponse"
              example:
                status: 200
                message: 1 contacts successfuly updated.
                data: [1001]
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /contacts/delete:
    post:
      tags: [Adresář]
      summary: Smazání kontaktů
      description: Smaže vybrané kontakty z adresáře podle jejich `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contacts]
              properties:
                contacts:
                  type: array
                  description: Pole identifikátorů kontaktů ke smazání.
                  items:
                    type: integer
            example:
              contacts: [1001, 1002]
      responses:
        "200":
          description: Kontakty byly smazány.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMessageResponse"
              example:
                status: 200
                message: 2 contacts successfuly deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-apikey
      description: |-
        Produkční API klíč najdete ve správním rozhraní [app.zaslat.cz](https://app.zaslat.cz)
        v sekci **API** (Nastavení uživatele).
  responses:
    BadRequest:
      description: Chybný požadavek (chyba ve vstupních datech).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusMessageResponse"
          example:
            status: 400
            message: Chyba ve vstupních datech.
            errors:
              - field: contacts[0].email
                message: Neplatný formát e-mailu.
                value: f.novotny@seznam
    Unauthorized:
      description: Neautorizovaný požadavek (neplatný API klíč).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusMessageResponse"
          example:
            status: 401
            message: Neplatný API klíč.
  schemas:
    StatusMessageResponse:
      type: object
      description: Základní tvar odpovědi bez datové části.
      properties:
        status:
          type: integer
          description: HTTP stavový kód odpovědi.
          example: 200
        message:
          type: string
          description: Textová zpráva k provedené akci.
          example: OK
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
    ShipmentListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: OK
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
        data:
          type: object
          description: Objekt zásilek klíčovaný identifikátorem zásilky (`tracking_number`).
          additionalProperties:
            $ref: "#/components/schemas/Shipment"
    TrackingResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: OK
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
        data:
          type: object
          description: Objekt klíčovaný identifikátorem zásilky (`tracking_number`).
          additionalProperties:
            type: object
            properties:
              status:
                $ref: "#/components/schemas/ShipmentStatus"
              returned:
                type: boolean
                description: Příznak, že zásilka byla vrácena odesílateli.
              packages:
                type: array
                description: Historie tracking událostí — jedno pole událostí pro každý balík zásilky.
                items:
                  type: array
                  items:
                    $ref: "#/components/schemas/History"
    ContactIdsResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: OK
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
        data:
          type: array
          description: Pole identifikátorů dotčených kontaktů.
          items:
            type: integer
    RatesGetRequest:
      type: object
      required: [from, to, packages]
      description: "⚠️ Pole `from`/`to` v této metodě vyžadují pouze `country` — ostatní parametry kontaktu jsou nepovinné."
      properties:
        currency:
          type: string
          description: Kód měny ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) pro ceny v odpovědi.
        type:
          $ref: "#/components/schemas/ShipmentType"
        pickup_date:
          type: string
          format: date
          description: Požadované datum svozu.
        pickup_branch:
          type: string
          description: Kód podacího místa ([ParcelPoint](#/components/schemas/ParcelPoint).`code`).
        delivery_branch:
          type: string
          description: Kód výdejního místa.
        from:
          $ref: "#/components/schemas/Contact"
        to:
          $ref: "#/components/schemas/Contact"
        services:
          type: array
          items:
            $ref: "#/components/schemas/Service"
        packages:
          type: array
          items:
            $ref: "#/components/schemas/Package"
    ShipmentsCreateRequest:
      type: object
      required: [shipments]
      properties:
        currency:
          type: string
          description: Kód měny objednávky. Pokud není uvedena, použije se výchozí měna účtu.
        payment_type:
          $ref: "#/components/schemas/PaymentType"
        shipments:
          type: array
          items:
            $ref: "#/components/schemas/Shipment"
        payer:
          allOf:
            - $ref: "#/components/schemas/Contact"
          description: Kontakt plátce. Nepovinné, pokud je požadavek autentizován přes `x-apikey` — plátcem se pak stává přihlášený uživatel.
        voucher:
          type: string
          description: Slevový kód.
    Rate:
      type: object
      description: Nabídka přepravy konkrétním dopravcem.
      properties:
        carrier:
          $ref: "#/components/schemas/Carrier"
        service:
          type: string
          maxLength: 20
          description: Konkrétní přepravní služba dopravce.
        service_id:
          type: integer
          description: Identifikátor přepravní služby dopravce.
        pickup_date:
          type: string
          format: date
          description: Nejbližší možné datum svozu.
        pickup_from_time:
          type: string
          description: "Začátek okna pro svoz, formát H:m:s."
        pickup_to_time:
          type: string
          description: "Konec okna pro svoz, formát H:m:s."
        delivery_date:
          type: string
          format: date
          description: Předpokládané datum doručení.
        price:
          allOf: [$ref: "#/components/schemas/Money"]
          description: Cena přepravy bez DPH.
        price_vat:
          allOf: [$ref: "#/components/schemas/Money"]
          description: Cena přepravy včetně DPH.
        insurance_limit:
          allOf: [$ref: "#/components/schemas/Money"]
          description: Limit odpovědnosti dopravce včetně DPH.
        own_invoice_upload:
          type: boolean
          description: Příznak vlastní faktury.
        weight_limit:
          type: integer
          description: Váhový limit zásilky.
        pickup_branch:
          type: boolean
          description: Možnost předání na podacím místě.
        pickup_branch_required:
          type: boolean
          description: Povinnost předání na podacím místě.
        delivery_branch_required:
          type: boolean
          description: Povinnost doručení na výdejní místo.
        shipment_category:
          $ref: "#/components/schemas/ShipmentCategory"
        trackable:
          type: boolean
          description: Dostupnost trackingu zásilky.
        printable:
          type: boolean
          description: Dostupnost tisku štítku.
      example:
        carrier: GLS
        service: Business-Parcel
        service_id: 7
        pickup_date: "2016-07-11"
        delivery_date: "2016-07-12"
        pickup_from_time: "08:00:00"
        pickup_to_time: "18:00:00"
        price:
          value: 98.35
          currency: CZK
        price_vat:
          value: 119
          currency: CZK
        insurance_limit:
          value: 50000
          currency: CZK
        weight_limit: 15
        trackable: true
        printable: true
        shipment_category: domestic
    Contact:
      type: object
      description: |-
        Kontaktní osoba a adresa pro podání nebo doručení zásilky. Lze uvést buď existující
        kontakt odkazem na `id`, nebo plné údaje.
      properties:
        id:
          type: integer
          description: Identifikátor existujícího kontaktu z adresáře. Pokud je uveden, ostatní parametry jsou nepovinné.
        company:
          type: string
          maxLength: 75
          description: Název firmy.
        firstname:
          type: string
          maxLength: 50
          description: Jméno kontaktní osoby.
        surname:
          type: string
          maxLength: 50
          description: Příjmení kontaktní osoby.
        street:
          type: string
          maxLength: 100
          description: Ulice a číslo popisné.
        city:
          type: string
          maxLength: 50
          description: Město/obec.
        zip:
          type: string
          maxLength: 12
          description: PSČ.
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: Kód země ([ISO 3166-1 alpha-2](https://cs.wikipedia.org/wiki/ISO_3166-1)).
        phone:
          type: string
          maxLength: 50
          description: Telefonní kontakt.
        email:
          type: string
          maxLength: 50
          description: E-mailový kontakt.
        tin:
          type: string
          maxLength: 50
          description: IČ.
        vatin:
          type: string
          maxLength: 50
          description: DIČ.
      example:
        id: 1001
        firstname: Jaroslav
        surname: Novotný
        company: Zaslat s.r.o.
        street: Jindřišská 12/1027
        city: Praha 4
        zip: "14000"
        country: CZ
        phone: "+420777152225"
        email: novotny@dummymail.com
    Shipment:
      type: object
      required: [from, to, packages]
      description: Jedna zásilka v rámci objednávky.
      properties:
        carrier:
          $ref: "#/components/schemas/Carrier"
        service_id:
          type: integer
          description: Identifikátor konkrétní přepravní služby dopravce.
        type:
          $ref: "#/components/schemas/ShipmentType"
        pickup_date:
          type: string
          format: date
          description: Požadované datum svozu.
        pickup_branch:
          type: string
          description: Kód podacího místa — uveďte i `carrier`, pokud vybíráte konkrétní podací místo.
        delivery_branch:
          type: string
          description: Kód výdejního místa.
        pickup_branch_location:
          type: integer
          description: "⚠️ ID podacího místa (viz [mapa výdejních míst](https://www.zaslat.cz/vydejni-mista))."
        delivery_branch_location:
          type: integer
          description: "⚠️ ID výdejního místa."
        from:
          $ref: "#/components/schemas/Contact"
        to:
          $ref: "#/components/schemas/Contact"
        services:
          type: array
          items:
            $ref: "#/components/schemas/Service"
        packages:
          type: array
          items:
            $ref: "#/components/schemas/Package"
        reference:
          type: string
          maxLength: 255
          description: Vlastní označení zásilky.
        note:
          type: string
          maxLength: 255
          description: Poznámka pro řidiče/kurýra.
        customs:
          type: object
          description: >-
            Objekt celní deklarace pro zásilky podléhající celnímu řízení (mimo EU) — strukturu
            a číselníky popisuje [Objednávka celní zásilky](/api/v1/customs_shipment_order).
        status:
          $ref: "#/components/schemas/ShipmentStatus"
      example:
        carrier: GLS
        pickup_date: "2016-07-11"
        from:
          id: 1001
        to:
          firstname: Jaroslav
          surname: Novotný
          company: Zaslat s.r.o.
          street: Jindřišská 12/1027
          city: Praha 4
          zip: "14000"
          country: CZ
          phone: "+420777152225"
          email: novotny@dummymail.com
        services:
          - code: cod
            data:
              value:
                value: 1500
                currency: CZK
          - code: ins
            data:
              value: 12500
              currency: CZK
        packages:
          - weight: 1
            width: 10
            height: 20
            length: 30
    ParcelPoint:
      type: object
      description: Podací nebo výdejní místo dopravce.
      properties:
        id:
          type: integer
          description: Identifikátor místa.
        carrier:
          $ref: "#/components/schemas/Carrier"
        code:
          type: string
          description: Kód místa.
        name:
          type: string
          description: Název místa.
        street:
          type: string
        city:
          type: string
        zip:
          type: string
        country:
          type: string
          description: Kód země ([ISO 3166-1 alpha-2](https://cs.wikipedia.org/wiki/ISO_3166-1)).
        phone:
          type: string
          nullable: true
        location:
          type: object
          description: Souřadnice místa.
          properties:
            lat:
              type: string
            lng:
              type: string
        is_collection:
          type: boolean
          description: Místo umožňuje podání zásilky.
        is_locker:
          type: integer
          enum: [0, 1]
          description: "Výdejní box: `1` ano, `0` ne."
        is_depot:
          type: integer
          enum: [0, 1]
          description: "Sklad/depo: `1` ano, `0` ne."
        card_payment:
          type: integer
          enum: [0, 1]
          description: "Platba kartou: `1` ano, `0` ne."
        wheelchair_access:
          type: integer
          enum: [0, 1]
          description: "Bezbariérový přístup: `1` ano, `0` ne."
        no_lunch_break:
          type: integer
          enum: [0, 1]
          description: "Bez polední pauzy: `1` ano, `0` ne."
        open_saturday:
          type: integer
          enum: [0, 1]
          description: "Otevřeno v sobotu: `1` ano, `0` ne."
        open_sunday:
          type: integer
          enum: [0, 1]
          description: "Otevřeno v neděli: `1` ano, `0` ne."
        opening_hours:
          type: object
          description: Otevírací doba podle dne v týdnu (klíč `1`–`7`, pondělí = `1`).
          additionalProperties:
            $ref: "#/components/schemas/OpeningHours"
        pickup_branch_location_id:
          type: integer
          description: "⚠️ Identifikátor sdílený dopravci na stejné adrese."
      example:
        id: 16604
        carrier: PPL
        code: KM11730100
        name: "V Háji"
        street: 28. října 89/51
        city: Plzeň
        zip: "30100"
        country: CZ
        phone: null
        location:
          lat: "49.778694444444"
          lng: "13.409666666667"
        is_collection: true
        is_locker: 0
        is_depot: 0
        card_payment: 1
        wheelchair_access: 0
        no_lunch_break: 1
        open_saturday: 0
        open_sunday: 0
        opening_hours:
          "1":
            from1: "13:00"
            to1: "22:00"
            from2: null
            to2: null
    Package:
      type: object
      required: [weight, width, height, length]
      description: |-
        Jeden balík zásilky. Uvedené limity jsou obecné limity API — konkrétní přepravní služby
        mívají limity přísnější (viz `weight_limit` v nabídce [Rate](#/components/schemas/Rate)).
      properties:
        weight:
          type: number
          format: float
          minimum: 0.01
          maximum: 5000
          description: Váha [kg].
        width:
          type: number
          minimum: 1
          maximum: 1000
          description: Šířka [cm].
        height:
          type: number
          minimum: 1
          maximum: 1000
          description: Výška [cm].
        length:
          type: number
          minimum: 1
          maximum: 1000
          description: Délka [cm].
        value:
          $ref: "#/components/schemas/Money"
        content:
          type: string
          maxLength: 255
          description: Obsah balíku.
        status:
          allOf: [$ref: "#/components/schemas/ShipmentStatus"]
          description: "⚠️ Aktuální stav balíku (návratový parametr)."
        history:
          type: array
          description: "⚠️ Historie stavů balíku (návratový parametr)."
          items:
            $ref: "#/components/schemas/History"
        carrier_tracking:
          type: string
          description: "⚠️ URL trackingu u dopravce (návratový parametr)."
        package_password:
          type: string
          nullable: true
          description: >-
            ⚠️ Heslo pro vložení balíku / vratky do boxu / výdejního místa u vybraných dopravců
            (Zásilkovna, Balíkovna). Vyplněno pouze pro vlastníka zásilky, jinak `null`
            (návratový parametr).
      example:
        weight: 7.5
        width: 50
        height: 30
        length: 40
        status: CREATED
        value:
          value: 100
          currency: EUR
        carrier_tracking: https://www.carrier.com/example-tracking
        content: popis balíku
        package_password: "48291"
    History:
      type: object
      description: "⚠️ Jeden záznam trackingové historie zásilky (návratový parametr, pole rekonstruována z ukázky)."
      properties:
        date:
          type: string
          format: date
        time:
          type: string
        name:
          type: string
          description: Textový popis události.
        status:
          $ref: "#/components/schemas/ShipmentStatus"
        location:
          type: string
          description: Doplňující informace o místě.
      example:
        date: "2016-07-16"
        time: "15:17:00"
        name: Balík byl doručen
        status: DELIVERED
        location: Portugalsko
    Service:
      type: object
      required: [code, data]
      description: Doplňková placená služba k zásilce (dobírka, pojištění, sleva).
      properties:
        code:
          type: string
          maxLength: 20
          description: "Kód služby, viz [číselník služeb](#/components/schemas/ServiceCode)."
        data:
          type: object
          description: Parametry služby dle jejího typu — objekt `ServiceCOD`/`Money` nebo řetězec u slevového kódu.
      example:
        code: cod
        data:
          value:
            value: 100
            currency: EUR
    ServiceCOD:
      type: object
      required: [value]
      description: |-
        Parametry dobírky. Podrobná pravidla (povolené směry a měny, minimální částky, omezení
        dopravců) popisuje stránka [Dobírka (COD)](/api/v1/cod).
      properties:
        bank_account:
          type: string
          maxLength: 64
          description: |-
            Číslo účtu pro výplatu dobírky — český formát (`předčíslí-číslo` nebo jen číslo)
            spolu s `bank_code`, nebo IBAN (pak se `bank_code` neuvádí). Povinné při vytvoření
            zásilky; pokud máte číslo účtu uloženo v nastavení účtu, předvyplní se automaticky.
        bank_code:
          type: string
          maxLength: 4
          description: Čtyřmístný kód banky k účtu. Nevyplňuje se, pokud je v `bank_account` uveden IBAN.
        bank_variable:
          type: string
          maxLength: 10
          description: Variabilní symbol pro výplatu dobírky — pouze číslice, max. 10 znaků.
        bank_currency:
          type: string
          minLength: 3
          maxLength: 3
          description: Měna bankovního účtu ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)).
        include_shipping_costs:
          type: boolean
          default: false
          description: Připočíst k dobírkové částce i cenu přepravy.
        value:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |-
            Dobírková částka. Minimum je 30 CZK / 1 EUR; částka v CZK musí být celé číslo
            (bez desetinných míst).
      example:
        bank_account: "12-34567890"
        bank_code: "0100"
        bank_variable: "20260001"
        value:
          value: 1500
          currency: CZK
    Pickup:
      type: object
      description: Žádost o svoz zásilek.
      properties:
        id:
          type: integer
          description: "⚠️ Identifikátor žádosti o svoz (návratový parametr)."
        date:
          type: string
          format: date
          description: |-
            Požadované datum svozu ve formátu `YYYY-MM-DD`. Musí to být **pracovní den**,
            nesmí být v minulosti ani dnes; svoz na následující den lze objednat pouze
            do 18:00.
        carrier:
          $ref: "#/components/schemas/Carrier"
        address_id:
          type: integer
          description: Identifikátor existující svozové adresy (kontaktu).
      example:
        id: 12354
        date: "2017-01-31"
        carrier: DPD
        address_id: 1001
    OpeningHours:
      type: object
      description: Otevírací doba podacího/výdejního místa pro jeden den.
      required: [from1, to1]
      properties:
        from1:
          type: string
          description: "Začátek dopolední otevírací doby, formát H:m."
        to1:
          type: string
          description: "Konec dopolední/celodenní otevírací doby, formát H:m."
        from2:
          type: string
          nullable: true
          description: Začátek odpolední otevírací doby (pokud je uvedena, jde o polední pauzu).
        to2:
          type: string
          nullable: true
          description: Konec odpolední otevírací doby.
      example:
        from1: "13:00"
        to1: "22:00"
        from2: null
        to2: null
    Money:
      type: object
      required: [value, currency]
      description: Peněžní hodnota v dané měně.
      properties:
        value:
          type: number
          format: float
          description: Částka v dané měně.
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: Kód měny ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)).
      example:
        value: 1500
        currency: CZK
    Error:
      type: object
      description: Popis chyby vzniklé při zpracování požadavku.
      properties:
        field:
          type: string
          description: Název parametru, který chybu způsobil.
        message:
          type: string
          description: Textový popis chyby.
        value:
          type: string
          description: Hodnota parametru, která byla odeslána.
      example:
        field: contacts[0].email
        message: Neplatný formát e-mailu.
        value: f.novotny@seznam
    Carrier:
      type: string
      description: Kód přepravní společnosti.
      enum:
        [PPL, DPD, GLS, TOPTRANS, UPS, GLS-SK, LIFTAGO, FEDEX, WEDO, BALIKOVNA, ZASILKOVNA, SPS]
    PaymentType:
      type: string
      description: |-
        Způsob úhrady objednávky. Neautentizované požadavky (bez `x-apikey`) mohou použít pouze
        `ONLINE`; dostupnost `CREDIT` a `INVOICE` se řídí typem účtu/smlouvy zákazníka.
      enum: [ONLINE, CREDIT, INVOICE]
      x-enumDescriptions:
        ONLINE: Online platba platební bránou GoPay, v odpovědi je vrácena platební URL.
        CREDIT: Platba z předplaceného kreditu na účtu zákazníka.
        INVOICE: Platba na fakturu — pouze pro smluvní zákazníky.
    ShipmentStatus:
      type: string
      description: Stav zásilky/balíku.
      enum: [CREATED, EXPORTED, ONPICKUP, INTRANSIT, ONDELIVERY, DELIVERED, CANCELLED]
      x-enumDescriptions:
        CREATED: Zásilka vytvořena.
        EXPORTED: Dopravce potvrdil přijetí dat o zásilce.
        ONPICKUP: Zásilka čeká na svoz kurýrem.
        INTRANSIT: Zásilka na cestě do cílového depa.
        ONDELIVERY: Zásilka předána kurýrovi k doručení.
        DELIVERED: Zásilka doručena.
        CANCELLED: Zásilka zrušena.
    ShipmentType:
      type: string
      description: Typ svozu zásilky.
      enum: [ONDEMAND, OCCASIONAL, REGULAR]
      x-enumDescriptions:
        ONDEMAND: Jednorázový svoz — štítky tiskne dopravce.
        OCCASIONAL: Příležitostný svoz — štítky tiskne zákazník sám.
        REGULAR: Pravidelný svoz — štítky tiskne zákazník sám.
    ShipmentCategory:
      type: string
      description: Kategorie zásilky podle směru přepravy.
      enum: [domestic, exportEu, exportWorld, importEu, importWorld]
      x-enumDescriptions:
        domestic: Doručení v rámci jednoho státu.
        exportEu: Export zásilky do zemí EU.
        exportWorld: Export zásilky mimo země EU.
        importEu: Import zásilky ze zemí EU.
        importWorld: Import zásilky ze zemí mimo EU.
    ServiceCode:
      type: string
      description: Kód doplňkové služby.
      enum: [COD, INS, DSC]
      x-enumDescriptions:
        COD: "Dobírka do vybraných zemí (CZ, SK) — data typu ServiceCOD."
        INS: "Doplňkové pojištění nad rámec základního krytí — data typu Money."
        DSC: "Slevový kód — data je řetězec."
