openapi: 3.0.2
info:
  version: 2.0.0
  title: 'Zaslat public API v2'
  description: 'Public API of the Zaslat shipping platform. Create draft shipments in the shipment cart — drafts are priced asynchronously and finished (completed, paid and ordered) in the Zaslat client zone — and manage collection requests. Every request must be authenticated with your API key sent in the `x-apikey` header.'
  contact:
    name: 'Zaslat API Support'
    url: 'https://docs.zaslat.cz/api/v2/content'
    email: support@zaslat.cz
servers:
  -
    url: 'https://test.zaslat.cz'
    description: 'Testing environment (API key from app-test.zaslat.cz)'
security:
  -
    ApiKeyAuth: []
paths:
  /api/v2/public/cart/create:
    post:
      summary: 'Create a draft shipment in the shipment cart.'
      tags:
        - Cart
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShipmentRequest'
            examples:
              'Example 1':
                value:
                  to:
                    firstname: Jan
                    surname: Novák
                    street: 'Sukova 4'
                    city: Brno
                    zip: '60200'
                    country: CZ
                    phone: '+420777777777'
                    email: jan.novak@example.com
                summary: 'Minimal draft — recipient only, sender and package are filled from the account defaults'
              'Example 2':
                value:
                  from:
                    company: 'Acme Corp'
                    firstname: John
                    surname: Doe
                    street: 'Drobného 555/49'
                    city: Brno
                    zip: '60200'
                    country: CZ
                    phone: '+420777777777'
                    email: warehouse@acme.example
                  to:
                    firstname: Jan
                    surname: Novák
                    street: 'Sukova 4'
                    city: Brno
                    zip: '60200'
                    country: CZ
                    phone: '+420777777777'
                    email: jan.novak@example.com
                  packages:
                    -
                      weight: 2.5
                      width: 30.0
                      height: 20.0
                      length: 40.0
                  referenceNumber: OBJ-2026-0001
                  currency: CZK
                  type: ONDEMAND
                  pickupDate: '2030-06-22'
                  fromTime: '10:00'
                  services:
                    -
                      code: COD
                      data:
                        value:
                          value: 1500
                          currency: CZK
                summary: 'Complete shipment with courier pickup and cash on delivery'
              'Example 3':
                value:
                  to:
                    firstname: Jan
                    surname: Novák
                    street: 'Sukova 4'
                    city: Brno
                    zip: '60200'
                    country: CZ
                    phone: '+420777777777'
                    email: jan.novak@example.com
                  packages:
                    -
                      weight: 1.0
                      width: 20.0
                      height: 20.0
                      length: 20.0
                  carrierCode: DPD
                  deliveryBranch: CZ10046
                summary: 'Delivery to a parcel point — deliveryBranch requires carrierCode'
              'Example 4':
                value:
                  to:
                    firstname: Jane
                    surname: Smith
                    street: '350 5th Ave'
                    city: 'New York'
                    zip: '10118'
                    country: US
                    phone: '+12125551234'
                    email: jane.smith@example.com
                  packages:
                    -
                      weight: 2.5
                      width: 30.0
                      height: 20.0
                      length: 40.0
                  carrierCode: FEDEX
                  currency: CZK
                  customs:
                    reason: commercial
                    invoice: own
                    currency: USD
                    items:
                      -
                        name: 'Wireless headphones'
                        country: CZ
                        quantity: 2
                        value: 99.9
                        hsCode: '8518.30'
                    additionalInfo:
                      -
                        type: eori
                        value: CZ1234567890
                    hasCustomsInvoice: true
                    invoiceFiles:
                      -
                        filename: commercial-invoice.pdf
                        content: JVBERi0xLjQ=
                    customsRepresentationFile:
                      filename: representation-authorization.pdf
                      content: JVBERi0xLjQ=
                summary: 'International shipment with a customs declaration and own customs invoice files (base64, FedEx/UPS only)'
      responses:
        200:
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateShipmentResponse'
              examples:
                'Example 1':
                  value:
                    id: 421337
                    source: API
                    referenceNumber: OBJ-2026-0001
                    errors: null
                    rates: null
                    modified: '2026-07-16 10:30:00'
                  summary: 'Draft created — rates are computed asynchronously and are null right after creation'
        400:
          description: 'Bad request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
              examples:
                'Example 1':
                  value:
                    message: 'Delivery branch not found or does not service the selected carrier.'
                    errors: []
                  summary: 'Invalid input — e.g. unknown branch code or malformed JSON'
        401:
          description: 'Authorization required.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
        500:
          description: 'Internal server error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
  /api/v2/public/collection-request/cancel:
    post:
      summary: 'Cancel a collection request.'
      tags:
        - 'Collection Request'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
      responses:
        204:
          description: 'Ok. No content.'
        400:
          description: 'Bad request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
        401:
          description: 'Authorization required.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
        500:
          description: 'Internal server error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: 'You can find your production API key in the [app.zaslat.cz](https://app.zaslat.cz) administration under the **API** section (user settings).'
      name: x-apikey
      in: header
  schemas:
    CreateShipmentRequest:
      type: object
      additionalProperties: false
      properties:
        from:
          description: 'Sender address. Omitted → filled from the account default sender.'
          type: object
          additionalProperties: false
          properties:
            id:
              type: integer
              description: 'ID of an existing address book entry'
              nullable: true
            company:
              type: string
              description: 'Company name'
              example: 'Acme Corp'
              nullable: true
            firstname:
              type: string
              description: 'First name'
              example: John
              nullable: true
            surname:
              type: string
              description: Surname
              example: Doe
              nullable: true
            street:
              type: string
              description: 'Street and house number'
              example: 'Sukova 4'
              nullable: true
            city:
              type: string
              description: City
              example: Brno
              nullable: true
            zip:
              type: string
              description: 'ZIP / postal code'
              example: '60200'
              nullable: true
            country:
              type: string
              description: 'Country code, ISO 3166-1 alpha-2'
              example: CZ
              nullable: true
            phone:
              type: string
              description: 'Phone number'
              example: '+420777777777'
              nullable: true
            email:
              type: string
              description: 'Email address'
              example: john.doe@example.com
              nullable: true
            tin:
              type: string
              description: 'Company registration number (IČO)'
              example: '03333333'
              nullable: true
            vatin:
              type: string
              description: 'VAT number (DIČ)'
              example: CZ03333333
              nullable: true
            saveAddress:
              type: boolean
              description: 'Store this address into the address book'
              nullable: true
        to:
          description: 'Recipient address'
          type: object
          additionalProperties: false
          properties:
            id:
              type: integer
              description: 'ID of an existing address book entry'
              nullable: true
            company:
              type: string
              description: 'Company name'
              example: 'Acme Corp'
              nullable: true
            firstname:
              type: string
              description: 'First name'
              example: John
              nullable: true
            surname:
              type: string
              description: Surname
              example: Doe
              nullable: true
            street:
              type: string
              description: 'Street and house number'
              example: 'Sukova 4'
              nullable: true
            city:
              type: string
              description: City
              example: Brno
              nullable: true
            zip:
              type: string
              description: 'ZIP / postal code'
              example: '60200'
              nullable: true
            country:
              type: string
              description: 'Country code, ISO 3166-1 alpha-2'
              example: CZ
              nullable: true
            phone:
              type: string
              description: 'Phone number'
              example: '+420777777777'
              nullable: true
            email:
              type: string
              description: 'Email address'
              example: john.doe@example.com
              nullable: true
            tin:
              type: string
              description: 'Company registration number (IČO)'
              example: '03333333'
              nullable: true
            vatin:
              type: string
              description: 'VAT number (DIČ)'
              example: CZ03333333
              nullable: true
            saveAddress:
              type: boolean
              description: 'Store this address into the address book'
              nullable: true
        packages:
          type: array
          description: 'Packages. Omitted → filled from the account default package.'
          items:
            type: object
            additionalProperties: false
            properties:
              weight:
                type: number
                description: 'Weight in kg'
                example: 1.0
                nullable: true
              width:
                type: number
                description: 'Width in cm'
                example: 20.0
                nullable: true
              height:
                type: number
                description: 'Height in cm'
                example: 20.0
                nullable: true
              length:
                type: number
                description: 'Length in cm'
                example: 20.0
                nullable: true
              type:
                type: integer
                description: 'Package type (0=default, 10=envelope, 11=envelope with documents, 20=tire, 21=tire with disc, 30=pallet)'
                nullable: true
              services:
                type: array
                description: 'Per-package additional services'
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    code:
                      type: string
                      description: 'Service code'
                      example: COD
                      nullable: true
                    data:
                      type: object
                      description: 'Service-specific payload. COD: {"value": {"value": 1500, "currency": "CZK"}} plus optional "bank_account", "bank_code", "bank_variable". INS (insurance): {"value": 5000, "currency": "CZK"}.'
                      nullable: true
                    id:
                      type: integer
                      description: 'Service ID'
                      nullable: true
                nullable: true
          nullable: true
        pickupBranch:
          type: string
          description: 'Code of the pickup branch (parcel point where the sender drops off the shipment), or "1" to use the account default pickup branch. Requires carrierCode.'
          example: CZ10037
          nullable: true
        deliveryBranch:
          type: string
          description: 'Code of the delivery branch (parcel point where the recipient collects the shipment). Requires carrierCode.'
          example: CZ10046
          nullable: true
        autoDeliveryBranch:
          type: boolean
          description: 'Automatically pick the nearest delivery point to the recipient address'
          nullable: true
        serviceId:
          type: integer
          description: 'Service (tariff) ID. Omitted → cheapest selectable service is chosen automatically.'
          nullable: true
        referenceNumber:
          type: string
          description: 'Reference number / variable symbol'
          example: OBJ-2026-0001
          nullable: true
        currency:
          type: string
          description: Currency
          example: CZK
          nullable: true
        carrierCode:
          type: string
          description: 'Carrier code'
          example: DPD
          nullable: true
        type:
          type: string
          description: 'Pickup type'
          enum:
            - ONDEMAND
            - REGULAR
            - OCCASIONAL
          example: ONDEMAND
          nullable: true
        pickupDate:
          type: string
          description: 'Pickup date (Y-m-d), must not be in the past'
          format: Y-m-d
          example: '2030-06-22'
          nullable: true
        fromTime:
          type: string
          description: 'Earliest pickup time (H:i)'
          format: 'H:i'
          example: '10:00'
          nullable: true
        services:
          type: array
          description: 'Shipment-level additional services'
          items:
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
                description: 'Service code'
                example: COD
                nullable: true
              data:
                type: object
                description: 'Service-specific payload. COD: {"value": {"value": 1500, "currency": "CZK"}} plus optional "bank_account", "bank_code", "bank_variable". INS (insurance): {"value": 5000, "currency": "CZK"}.'
                nullable: true
              id:
                type: integer
                description: 'Service ID'
                nullable: true
          nullable: true
        customs:
          description: 'Customs declaration (for international shipments)'
          type: object
          additionalProperties: false
          properties:
            reason:
              type: string
              description: 'Reason for the customs declaration'
              enum:
                - commercial
                - documents
                - gifts
                - samples
              example: commercial
              nullable: true
            invoice:
              type: string
              description: 'Customs invoice mode: "create" — the customs invoice is generated from the declared items (default), "own" — you supply your own invoice via invoiceFiles. Providing invoiceFiles implies "own".'
              enum:
                - create
                - own
              example: create
              nullable: true
            currency:
              type: string
              description: 'Customs currency'
              example: EUR
              nullable: true
            items:
              type: array
              description: 'Declared items'
              items:
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    description: 'Item name'
                    example: 'Commercial goods'
                    nullable: true
                  country:
                    type: string
                    description: 'Country of origin, ISO 3166-1 alpha-2'
                    example: CZ
                    nullable: true
                  quantity:
                    type: integer
                    description: Quantity
                    example: 1
                    nullable: true
                  value:
                    type: number
                    description: 'Unit value'
                    example: 100.0
                    nullable: true
                  hsCode:
                    type: string
                    description: 'HS (harmonized system) code'
                    nullable: true
              nullable: true
            additionalInfo:
              type: array
              description: 'Additional customs identifiers'
              items:
                type: object
                additionalProperties: false
                properties:
                  type:
                    type: string
                    description: 'Identifier type'
                    example: eori
                    nullable: true
                  value:
                    type: string
                    description: 'Identifier value'
                    example: CZ1234567890
                    nullable: true
              nullable: true
            hasCustomsInvoice:
              type: boolean
              description: 'Whether the shipment has a customs invoice'
              nullable: true
            invoiceFiles:
              type: array
              description: 'Own customs invoice files (max 5, total decoded size max 5 MB, PDF/JPG/PNG/GIF). Merged into a single PDF and sent to the carrier as the commercial invoice; providing them implies the shipment uses your own customs invoice. Supported only for carriers fedex and ups — carrierCode is required.'
              items:
                type: object
                additionalProperties: false
                properties:
                  filename:
                    type: string
                    description: 'File name including the extension'
                    example: commercial-invoice.pdf
                    nullable: true
                  content:
                    type: string
                    description: 'File content encoded as base64 (plain base64 string, no data: URI prefix)'
                    example: JVBERi0xLjQ=
                    nullable: true
              nullable: true
            customsRepresentationFile:
              description: 'Signed customs representation authorization file (decoded size max 5 MB, PDF/JPG/PNG/GIF). Supported only for carriers fedex and ups — carrierCode is required.'
              type: object
              additionalProperties: false
              properties:
                filename:
                  type: string
                  description: 'File name including the extension'
                  example: commercial-invoice.pdf
                  nullable: true
                content:
                  type: string
                  description: 'File content encoded as base64 (plain base64 string, no data: URI prefix)'
                  example: JVBERi0xLjQ=
                  nullable: true
    CreateShipmentResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - source
        - referenceNumber
        - errors
        - rates
        - modified
      properties:
        id:
          type: integer
          description: 'ID of the created draft shipment'
          example: 42
        source:
          type: string
          description: 'Shipment source'
          example: API
        referenceNumber:
          type: string
          description: 'Reference number / variable symbol, echoed back'
          example: OBJ-2026-0001
          nullable: true
        errors:
          description: 'Business validation messages; null when the draft is valid'
        rates:
          description: 'Computed price offers; null until the async quote job finishes'
        modified:
          type: string
          description: 'Last modification timestamp (Y-m-d H:i:s)'
          example: '2026-06-18 10:30:00'
    ProblemResponse:
      type: object
      additionalProperties: false
      required:
        - message
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - field
              - message
            properties:
              field:
                type: string
              message:
                type: string
    CancelRequest:
      type: object
      additionalProperties: false
      required:
        - carrier
        - date
      properties:
        carrier:
          type: string
          description: 'Valid carrier code.'
          enum:
            - dpd
            - gls
            - gls-sk
            - liftago
            - toptrans
            - ups
            - wedo
            - ppl
            - correos
            - seur
            - inpost
            - sps
        date:
          type: string
          format: Y-m-d
          example: '2025-10-25'
