openapi: "3.0.0"
info:
  version: "3.0.1"
  title: "Partner Dispatch Service"
  x-api-id: "7867f8da-0de6-4f65-886c-bc838119f693"
  x-audience: external-partner
  description: |
    The Partner Dispatch Service is part of ZEOS Fulfillment enabling Zalando partners (merchants) to store their own stocks in Zalando Warehouses
    and fulfill orders from these stocks.

    This API implements the part of the workflow where a partner or partner integrator sends shipping notices
    for concrete product items and quantities to be scheduled for shipping to a specific Zalando warehouse at a given point in time
    and to be supported and observed by ZFS service operations team.


    ## API workflow

    To get a better overview in the following the typical API workflow is shown.
    Please note that this diagram does not cover the complete process with all its possible branches but should depict
    the typical flow beginning with a merchant creating a shipping notice until the Zalando warehouse being ready to receive the shipment:

    [Diagram Flow](../../../zfs/shipping-notices/assets/shipping-notices-api-compact-flow.png)


    ## Resource Types

    ### Shipping Notice

    A shipping notice captures any base information required from a merchant to notify Zalando about pending deliveries in advance.

    ### Announced Item Set

    An announced item set lists the items and quantities planned to be shipped by a merchant as part of a shipping-notice.

    ### Announcement Confirmation

    This is a confirmation by the merchant to indicate that there will be no more changes done to the Shipping Notice resource
    and that the newest Announced Item Set is also final to continue with the workflow to request a delivery date.

    ### Dispatch Item Set

    A dispatch item set lists the items and quantities handed over to the carrier by the merchant as part of a shipping-notice.

    ### Dispatch Confirmation

    This is a confirmation by the merchant to indicate that there will be no more changes done to the item set to be dispatched.
    This is required to be able to continue with the workflow to create an inbound tour.

    ### Tour

    Represents a warehouse tour and its current status.

    ## Conflict Handling

    Any endpoint supporting HTTP PUT or HTTP POST method makes use of `ETag` and `If-Match` HTTP headers to detect collisions when two actors try to change a resource concurrently.

    For further explanation see also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

    Every GET request for a shipping-notice or any subresource of a shipping-notice will return an `ETag` determining the current shipping-notice version.

    With every `PUT` attempting to change an existing resource the actor needs to send the `If-Match` header containing the recent `ETag` of the shipping-notice. Only by fulfilling this requirement the `PUT` request will be accepted.

    With every POST attempting to create a subresource of a shipping-notice the actor needs to send the `If-Match` header containing the recent `ETag` of the shipping-notice. This action will update the `ETag` of the shipping-notice resource. Only by fulfilling this requirement the `POST` request will be accepted.

    If the `If-Match` header does not contain the recent `ETag` of the resource then an error is returned with HTTP status code 412 (Precondition Failed).
    If the `If-Match` header is omitted when attempting to change an existing resource then an error is returned with HTTP status code 428 (Precondition Required).

    There is only one `ETag` for the entire shipping-notice resource including all sub resources to enforce consistent versioning for all items of a shipping-notice. This is to prevent that separate items of a shipping-notice (for example an announced item set or a delivery date request) are created in parallel possibly leading to an unexpected or inconsistent result.

    ## Pagination

    HTTP GET requests querying resources to be returned as result set implement pagination. In this case a result set containg a list of result `items` and additionally an optional `next` href pointing to the next page of the query result.

servers:
  - url: 'https://api.merchants.zalando.com/zfs'
    description: Production instance
  - url: 'https://api-sandbox.merchants.zalando.com/zfs'
    description: Sandbox instance for merchant center

paths:
  '/shipping-notices':
    get:
      description: |
        Returns a paginated query result containing a list of shipping-notices matching the given query ordered by creation time in descending order.
        This endpoint is required by ZFS Service Operations to get an overview about shipping notices to be processed and to track progress.
        It can also be used by merchants to get access all his/her shipping-notice data.
      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Shipping Notice
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: zalando_advice_ids
          in: query
          explode: false
          schema:
            type: string
            example: '99200000,99200001,99200002'
          description: |
            A comma separated list of the numeric Zalando specific IDs to identify shipping notices during their lifecycle to be processed by zalando systems.

            In Zalando terms this ID is called `advice_id`. This ID is also used for communication between the merchant / integrator and Zalando Fulfillment Services support team.
        - name: search
          in: query
          explode: false
          schema:
            type: string
            example: '99200000,b2b-ref'
          description: |
            A comma separated list of search terms that will search shipping notices by their zalando advice ID or Merchant B2B References
        - name: merchant_ids
          in: query
          explode: false
          schema:
            type: string
            example: '00000000-0000-1000-8000-000000000001,00000000-0000-1000-8000-000000000002'
          description: A comma separated list of merchant UUIDs to query
        - name: location_ids
          in: query
          explode: false
          schema:
            type: string
            example: '32eff430-f835-44ce-947a-4a1fdce1c615,40899f30-9ff9-4094-9ad6-0694b9051152'
          description: A comma separated list of location UUIDs to query
        - name: ignore_dummy_notices
          in: query
          explode: false
          schema:
            type: boolean
            example: false
          description: If true, quarantine storage notices are ignored
        - name: states
          in: query
          explode: false
          schema:
            type: string
            example: ready_for_receive,processing_at_warehouse
            x-extensible-enum:
              - initial
              - ready_for_delivery_date
              - waiting_for_delivery_date
              - ready_for_dispatch
              - ready_for_receive
              - processing_at_warehouse
              - closed
              - cancelled
          description: A comma separated list of states to query. (see yaml for values)
        - name: booking_types
          in: query
          explode: false
          schema:
            $ref: '#/components/schemas/BookingType'
          description: Type of booking to be filtered - booking/ rebooking/ same_day_slot
        - name: sort
          in: query
          explode: false
          schema:
            type: string
            x-extensible-enum:
              - +zalando_advice_id
              - -zalando_advice_id
              - +earliest_delivery_date
              - -earliest_delivery_date
              - +confirmed_delivery_date
              - -confirmed_delivery_date
              - +state
              - -state
              - +zalando_merchant_name
              - -zalando_merchant_name
              - +announced_item_count
              - -announced_item_count
          description: A comma separated list of shipping notice fields to sort by with either or + (ascending) or - (descending) prefix. One and the same field can only be used once.
        - name: classification
          in: query
          explode: false
          schema:
            type: string
            example: announcements
            x-extensible-enum:
              - drafts
              - announcements
              - shipments
              - actions_required
          description: Groups Shipping Notices based on their current state and the actions required
        - name: confirmed_delivery_date
          in: query
          explode: false
          schema:
            type: string
            format: date
            example: '2023-01-12_2023-06-30'
          description: The start and end date range for the query, separated by '_'
        - name: limit
          in: query
          explode: false
          schema:
            type: integer
            minimum: 1
            example: 100
          description: The maximum number of results to return per page. Must be a positive integer starting from 1.
        - name: page
          in: query
          explode: false
          schema:
            type: integer
            minimum: 1
            example: 1
          description: The page number to retrieve. Must be a positive integer starting from 1.
      responses:
        200:
          description: |
            Returns a query result containing a list of shipping-notice resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingNoticeResponse'
        default:
          description: >-
            A specific error occurred - see the status code and details for more
            information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

    post:
      description: |
        Creates a shipping-notice.

        When creating a new shipping-notice a `zalando_advice_id` will be generated synchronously
        which is the Zalando specific ID to identify a shipping notice during its lifecycle.

        The shipping notice resource uuid will also be generated during creation which is a uniquely identification for the resource.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id

        Postconditions:
        - the shipping-notice state is set to "initial"

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Shipping Notice
      requestBody:
        required: true
        description: |
          shipping-notice data to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutShippingNoticeRequest'
      responses:
        201:
          description: |
            Resource has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponseWithItems'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}':
    get:
      description: |
        Returns shipping-notice resource for a given shipping-notice ID.
        Used by a merchant and by ZFS Service operations to track the status of a shipping-notice currently in progress.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Shipping Notice
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      responses:
        200:
          description: |
            Returns a shipping-notice resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingNoticeById'
          headers:
            ETag:
              schema:
                type: string
                format: uuid
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

    put:
      description: |
        Updates an existing shipping-notice
        Used by merchants to update general shipping notice

        Note:
        As a temporary measure for backwards compatibility, this endpoint also supports creating new shipping notices with a given ID by the author.
        However, this behavior will be deprecated once the new POST endpoint for creation is fully rolled out.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id
        - shipping-notice resource is in status `initial`

        Postconditions:
        - the shipping-notice state is set to "initial"

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Shipping Notice
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          description: |
            The UUID (v4) uniquely identifying the resource.
      requestBody:
        required: true
        description: |
          shipping-notice and dispatch-items data to be updated. In case of an update the given data overwrites existing data entirely
          meaning that omitting optional fields in the update will possibly nullify existing data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutShippingNoticeRequest'
      responses:
        201:
          description: |
            Resource has been created. (Deprecated: Please transition to the new creation method using the POST /shipping-notices endpoint.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponseWithItems'
        204:
          description: |
            Resource has been updated.
          headers:
            ETag:
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponse'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}/announced-item-sets':
    get:
      description: |
        Returns a paginated query result containing a list of announced item sets for a given shipping-notice ID ordered by creation time in descending order.
        Used by ZFS Service operations to track the validation status of items. Can also be used by the merchant to access its item sets.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Item Set
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      responses:
        200:
          description: |
            Returns the list of announced item set references.
          headers:
            ETag:
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnouncedItemSetsResponse'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

    post:
      description: |
        Creates a new announced-item-set for a given shipping-notice ID. An announced-item-set resource is immutable.
        Used by merchants to specify either each product item and its planned quantity to be shipped to a Zalando warehouse, or to provide only the total quantity of items. 

        An announced-item-set is validated synchronously. 
        If individual items are provided, each item in the set is validated to ensure it is valid as per the ShippableItem definition. See definition of ShippableItem for details.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id
        - shipping-notice resource is in status `initial`

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Item Set
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      requestBody:
        required: true
        description: |
          Announced item set to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemSetUploadRequest'
      responses:
        201:
          description: |
            Resource has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponseWithItems'
        400:
          description: |
            - If body data does not match resource definition.
            - If shipping notice is not "initial" state
            - If shipping-notice ID is already assigned to a different merchant.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'
          headers:
            Last-Modified:
              schema:
                type: string
                format: date-time
            ETag:
              schema:
                type: string
                format: uuid
            Location:
              schema:
                type: string
                format: uri
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}/announced-item-sets/{shippable-item-set-id}':
    get:
      description: |
        Returns announced-item-set resource for a given shipping-notice ID and announced-item-set ID.
        Used by ZFS Service operations to track the validation status of items. Can also be used by the merchant to access its item sets.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Item Set
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid

          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
        - name: shippable-item-set-id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 14780c22-8e7a-41b1-6450-2d6fc2874e75
          description: |
            The UUID (v4) uniquely identifying the sub resource. Generated by the API when creating a new resource.
      responses:
        200:
          description: |
            Returns an announced-item-set resource.
          headers:
            ETag:
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippableItemSet'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}/announcement-confirmations':
    post:
      description: |
        Creates an announcement-confirmation for a given shipping-notice ID, which is a
        status transition resource without (body) data to trigger a shipping-notice state change
        from "initial" to "ready_for_delivery_date".
        An announcement-confirmation resource is immutable.
        This endpoint is to be used by merchants to confirm that the shipping-notice and last announced-item-set
        are ready to continue with the workflow to request a delivery date.
        Also at most one announcement-confirmation resource can be created per shipping-notice resource.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id
        - shipping-notice resource is in status `initial`
        - the shipping-notice resource must have the following information:

          zalando_merchant_id,
          zalando_advice_id,
          requested_zalando_location_id,
          carrier_name,
          pallets_count,
          colli_count,
          hanging_goods_count,
          earliest_delivery_date,
          contact_email

        - there must be at least one announced-item-set resource and the newest one must have validation state 'succeeded'
        - no announcement confirmation exists yet for the given shipping-notice-id

        Postconditions:
        - the shipping-notice state is implicitly set to `ready_for_delivery_date`

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Booking
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: d48acb0d-7481-45de-b7c1-814a5c998f15
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnouncementConfirmationRequest'
      responses:
        201:
          description: |
            Resource has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponse'
          headers:
            Last-Modified:
              schema:
                type: string
                format: date-time
            ETag:
              schema:
                type: string
                format: uuid
            Location:
              schema:
                type: string
                format: uri
        400:
          description: |
            - If body data does not match resource definition
            - If actor tried to create a second  announcement confirmation for the same shipping-notice
            - If shipping notice state is not 'initial'
            - if implicit validation of the shipping-notice or announced-item-set failed (see preconditions above)
            - Resource ID is already assigned to a different merchant.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}/dispatch-item-sets':
    get:
      description: |
        Returns a paginated query result containing a list of dispatch-item-sets for a given shipping-notice ID ordered by creation date in descending order.
        Used by ZFS Service operations to track the validation status of items. Can also be used by the merchant to access its item sets.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Item Set
      parameters:
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      responses:
        200:
          description: |
            Returns the list of dispatch-item-sets.
          headers:
            ETag:
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchItemSetsResponse'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

    post:
      description: |
        Creates a new dispatch-item-set for a given shipping-notice ID. A dispatch-item-set resource is immutable.
        Used by merchants to define which product items and quantities are dispatched to a Zalando warehouse.

        A dispatch-item-set is validated synchronously by verifying that any item of the set is valid. See definition of ShippableItem for details.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id
        - shipping-notice resource is in status `ready_for_dispatch`

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Item Set
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      requestBody:
        required: true
        description: |
          Dispatch item set to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemSetUploadRequest'
      responses:
        201:
          description: |
            Resource has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponseWithItems'
          headers:
            Last-Modified:
              schema:
                type: string
                format: date-time
            ETag:
              schema:
                type: string
                format: uuid
            Location:
              schema:
                type: string
                format: uri
        400:
          description: |
            - If body data does not match resource definition.
            - If no delivery date confirmation available.
            - If shipping-notice ID is already assigned to a different merchant.
            - If shipping notice is not "ready_for_dispatch" state
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/shipping-notices/{shipping-notice-id}/dispatch-confirmations':
    post:
      description: |
        Creates a dispatch-confirmation for a given shipping-notice ID, which is a
        status transition resource without (body) data to trigger a shipping-notice state change
        from "ready_for_dispatch" to "ready_for_receive".
        A dispatch-confirmation resource is immutable.

        This endpoint is to be used by merchants to confirm that:

        - either the last dispatch-item-set (if any exists because it is optional)
        - or the last announced-item-set

        are ready to continue with the workflow to request an inbound tour.

        A `shipping-notice` can only have one `dispatch-confirmation`.
        Creating another `dispatch-confirmation` will lead to a conflict.
        It is not possible to upload more `dispatch-item-set`s after a `dispatch-confirmation` was created.

        Preconditions:
        - requesting actor is authorized to access the shipping-notice-id
        - shipping-notice resource is in status `ready_for_dispatch`
        - there must be a delivery-date-confirmation
        - optionally there can be a dispatch-item-set
        - no dispatch-confirmation exists yet for the given shipping-notice-id

        Postconditions:
        - an inbound-tour resource is created
        - the shipping-notice state is implicitily set to `ready_for_receive`

      security:
        - oauth2: [ zfs-advice-service.shipping-notice.write ]
      tags:
        - Booking
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: 'If-Match'
          in: header
          schema:
            $ref: '#/components/headers/If-Match'
        - name: shipping-notice-id
          in: path
          required: true
          example: 94780c22-8e7a-41b1-a450-3d6fc6874e74
          schema:
            type: string
            format: uuid
          description: |
            The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
      responses:
        201:
          description: |
            Resource has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceMetaDataResponse'
          headers:
            Last-Modified:
              schema:
                type: string
                format: date-time
            ETag:
              schema:
                type: string
                format: uuid
            Location:
              schema:
                type: string
                format: uri
        400:
          description: |
            - If shipping notice state is not 'ready_for_dispatch' or 'ready_for_receive'
            - if implicit validation of the shipping-notice, announced-item-set or dispatch-item-set failed (see preconditions above)
            - Resource ID is already assigned to a different merchant.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/tours':
    get:
      description: Returns information about a list of tours belonging to a given Zalando Advice ID.
      security:
        - oauth2: [ zfs-advice-service.tour.read ]
      tags:
        - Tour
      parameters:
        - name: 'X-Flow-ID'
          in: header
          description: >-
            A custom header that is passed with any further requests, which can
            be used for monitoring and diagnostics.
          schema:
            $ref: '#/components/headers/X-Flow-ID'
        - name: zalando_advice_id
          in: query
          required: true
          description: The numeric Zalando-specific ID to identify a shipping notice.
          schema:
            type: string
            example: '99200000'
      responses:
        200:
          description: Returns a query result containing a list of tour resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperLoopTourListResponse'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'

  '/zfs/inbound/recommendations':
    get:
      description: Returns the inbound recommendations for the merchant having the given advice_id
      security:
        - oauth2: [ zfs-advice-service.shipping-notice.read ]
      tags:
        - Recommendation
      parameters:
        - name: advice_id
          in: query
          description: A numeric Zalando-specific ID to identify a shipping notice during its lifecycle to be processed by Zalando systems.
          required: true
          example: "99331409"
          schema:
            type: string
        - name: date_from
          in: query
          required: false
          example: '2024-01-01'
          description: The start of the date interval that the recommendations data will be queried. This parameter defaults to today in case it is not supplied. Dates from the past are not allowed.
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          required: false
          example: '2024-01-01'
          description: The end of the date interval that the recommendations data will be queried. This parameter defaults to 5 weeks from today in case it is not supplied. Dates which are beyond 5 weeks in the future are not allowed.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Returns the recommendations for the merchant having the given advice_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundRecommendationsApiResponse'
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'
  '/article-customs-data':
    post:
      operationId: postArticleCustomsData
      description: |
        Creates article customs data for processing.
      security:
        - oauth2: [ partner-dispatch-service.customs-data.write ]
      tags:
        - Article Customs Data
      parameters:
        - name: X-Flow-ID
          in: header
          schema:
            type: string
        - name: Prefer
          in: header
          required: false
          schema:
            type: string
          description: |
            If set to "return=representation", the response will include the article customs data
            and mapping validation result. Otherwise, the default 204 No Content response is returned.
      requestBody:
        required: true
        description: |
          Article customs data to be processed.
        content:
          application/json:
            schema:
              type: object
              required:
                - article_customs_data
                - merchant_id
              properties:
                merchant_id:
                  type: string
                  format: uuid
                article_customs_data:
                  type: array
                  items:
                    $ref: '#/components/schemas/ArticleCustomsData'
      responses:
        '200':
          description: |
            Article customs data has been created successfully, with representation returned.
            Only returned when the Prefer header is set to "return=representation".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleCustomsDataResponse'
        '204':
          description: |
            Article customs data has been created successfully.
        default:
          description: |
            A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem'


components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://api-sandbox.merchants.zalando.com/auth/token"
          scopes:
            zfs/shipping-notice/read: Allows for the reading of shipping-notice resources and any subresources.
            zfs/shipping-notice/write: Allows for the creating or updating of shipping-notice resources and any subresources.
            zfs/tour/read: Allows to read tour data

  headers:
    X-Flow-ID:
      description: >
        A custom header that is passed with any further requests, which can be
        used for monitoring and diagnostics.
      schema:
        type: string
      example: "8416269b-e98e-43e2-889c-ad3b7b40d152"

    Last-Modified:
      schema:
        type: string
        format: date-time

    ETag:
      schema:
        type: string
        format: uuid

    If-Match:
      description: |
        The RFC7232 If-Match header field in a request requires the server to
        only operate on the resource that matches at least one of the provided
        entity-tags. This allows clients express a precondition that prevent
        the method from being applied if there have been any changes to the
        resource.
      schema:
        type: string

  schemas:
    ResourceMetaDataResponse:
      type: object
      properties:
        etag:
          type: string
          format: uuid
          example: 1fd98d8f-8528-4206-80cf-ec292fd0e039
        lastModified:
          type: string
          example: 2024-07-11
          format: date-time
        location:
          type: string
          example: https://api-staging.merchants.zalando.com/zfs/shipping-notices/94780c22-8e7a-41b1-a450-3d6fc6874e74
          nullable: true
          format: uri
        resourceId:
          nullable: true
          example: 77fe3704-b687-4ce7-8dd8-96c639fb1c5b
          type: string
          format: uuid

    ResourceMetaDataResponseWithItems:
      type: object
      properties:
        etag:
          type: string
          format: uuid
        lastModified:
          type: string
          format: date
        location:
          type: string
          example: https://api-staging.merchants.zalando.com/zfs/shipping-notices/94780c22-8e7a-41b1-a450-3d6fc6874e74/announced-item-sets/741a1792-8717-48e5-b07a-08f518121911
          format: uri
          nullable: true
        resourceId:
          type: string
          format: uuid
        itemSetId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShippableItem'
          nullable: true
        validationState:
          type: string
          x-extensible-enum: [ succeeded, failed ]
        isResourceCreated:
          type: boolean
          nullable: true
          description: indicates whether new resource has been created successfully or not

    ItemSetUploadRequest:
      type: object
      description: |
        a list of announced items defining the item identifier (ean) and quantity
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShippableItemCreation'

    AnnouncementConfirmationRequest:
      type: object
      properties:
        booking_recommendation_id:
          type: string
          format: uuid

    AnnouncedItemSetsResponse:
      type: object
      properties:
        announced_item_sets:
          type: array
          items:
            $ref: '#/components/schemas/ShippableItemSet'

    DispatchItemSetsResponse:
      type: object
      properties:
        dispatchitem_sets:
          type: array
          items:
            $ref: '#/components/schemas/ShippableItemSet'

    ShippableItem:
      allOf:
        - $ref: '#/components/schemas/ShippableItemCreation'
        - type: object
          description: |
            A shippable item defining the item identifier (ean) and quantity.
            The shippable item is validated when creating a shippable item set resource. The validation status is set to "valid"

            - if the ean is matching the expected EAN-13 pattern
            - if the ean correlates to a Zalando Simple SKU

          properties:
            sku:
              type: string
              format: sku
              maxLength: 50
              readOnly: true
              description: the Zalando Simple SKU found during validation for the given EAN
              example: TH341G023-K1100XL000
            validation_state:
              type: string
              readOnly: true
              description: |
                a state indicating if the item has passed validation (valid, invalid) - must not be set by the actor

                - valid: ean is matching the expected EAN-13 pattern and correlates to a Zalando Simple SKU
                - invalid: ean has invalid format and no related Zalando Simple SKU found
              x-extensible-enum: [ valid, invalid ]

    ShippableItemCreation:
      type: object
      required:
        - ean
        - quantity
      description: |
        a shippable item defining the item identifier (EAN) and quantity
      properties:
        ean:
          type: string
          format: ean
          pattern: ^[0-9]{13}$
          maxLength: 13
          description: a 13-digit EAN
          example: 0191476239145
        quantity:
          type: integer
          format: int64
          minimum: 1
          example: 10
          description: the amount of items to be shipped for the given EAN

    ShippableItemSet:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/SelfLink'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShippableItem'
        resource_id:
          type: string
          format: uuid
          description: The UUID (v4) uniquely identifying the sub resource. Generated by the API when creating a new resource.
        shipping_notice_id:
          type: string
          format: uuid
          description: The UUID (v4) uniquely identifying the resource. To be generated by the actor when creating a new resource.
        items_total:
          type: integer
          format: int64
          minimum: 0
          readOnly: true
          description: total item count processed by the validation
        items_valid:
          type: integer
          format: int64
          minimum: 0
          readOnly: true
          description: item count successfully validated
        validation_state:
          type: string
          readOnly: true
          description: the overall validation state for the entire item set - validation is only "succeeded" if all items are also validated successfully
          x-extensible-enum: [ succeeded, failed ]
        validation_description:
          type: string
          maxLength: 2000
          readOnly: true
          description: an optional human readable description in case the validation is "failed"
        created:
          type: string
          format: date-time
          readOnly: true
          description: the date/time (format see RFC 3339, section 5.6) when this resource has been created
          example: '2017-07-21T17:32:28.123Z'

    ShippingNotice:
      type: object
      properties:
        resource_id:
          type: string
          format: uuid
          description: A unique ID to identify a shipping notice.
          example: '1002dc78-1837-444c-2983-c00d32c47h25'
        zalando_merchant_id:
          type: string
          format: uuid
          description: the Zalando specific UUID representing a merchant - can not be changed once defined within resource
          example: 57dd7874-cd76-4cef-8efa-095948680518
        zalando_advice_id:
          type: string
          readOnly: true
          maxLength: 50
          description: the Zalando specific ID for a shipping notice (in Zalando terms it is called `advice_id` - currently restricted to 8 digits which may change in the future) - can not be changed by the actor
          example: '99200000'
        merchant_b2b_reference:
          type: string
          maxLength: 100
          description: a merchant specific optional reference id or information for the advise (for example a merchant location)
          example: SOME-B2B-REFERENCE
        comments:
          type: string
          maxLength: 1000
          description: an optional free text (restricted to 1000 characters) e.g. containing a message to ZFS operations with additional details
          example: 'some comments'
        requested_zalando_location_id:
          type: string
          format: uuid
          description: the warehouse location requested by the actor
          example: 1e57b2b6-907b-4676-8766-339a1d596e59
        carrier_name:
          type: string
          maxLength: 100
          description: an identifier for the carrier delivering the goods to the warehouse
          example: DHL
        pallets_count:
          type: integer
          format: int64
          minimum: 0
          example: 2
          description: expected pallets count for a shipping-notice
        colli_count:
          type: integer
          format: int64
          minimum: 0
          example: 1
          description: expected colli count for a shipping-notice
        hanging_goods_count:
          type: integer
          format: int64
          minimum: 0
          description: expected hanging goods count for a shipping-notice
        earliest_delivery_date:
          type: string
          format: date
          description: the earliest date (format see RFC 3339, section 5.6, definition "full-date") when the actor will be able to deliver the announced goods to the warehouse
          example: '2022-07-21'
        contact_email:
          type: string
          format: email
          description: this is an email address on merchant side which maybe used to get in contact in case there are problems during the shipping process.
          example: 'some_merchant@acme.com'
        state:
          type: string
          example: ready_for_dispatch
          readOnly: true
          description: |
            This is the workflow state for a shipping-note which can not be directly edited at all
            but is "initial" when creating a new shipping-notice resource and will the switched during
            the process. Status preconditions and changes are described in the respective endpoint descriptions
            in the API doc.
          x-extensible-enum:
            [
              initial,
              ready_for_delivery_date,
              waiting_for_delivery_date,
              ready_for_dispatch,
              ready_for_receive,
              processing_at_warehouse,
              closed,
              cancelled
            ]
        delivery_type:
          type: string
          example: palletized
          readOnly: true
          description: delivery type (palletized, loose_load, hanging, quarantine)
        last_modified_date:
          type: string
          example: 2024-07-11T14:12:09.013455Z
          format: date-time
          description: Timestamp indicating when the shipping notice was last modified.
        additional_contact_email:
          type: string
          format: email
          description: this is an additional email address on merchant side which maybe used to get in contact in case there are problems during the shipping process.
          example: 'some_merchant1@acme.com'
        ticket_id:
          type: string
          maxLength: 50
          example: AVS-1381729
          description: An identifier to a ticketing system to process the delivery date request - currently this is a JIRA ticket for SCM
        inbound_tour_id:
          type: string
          example: WE-20240711-4859-AV-GD
          description: The ID of the inbound tour
        inbound_tour_state:
          $ref: '#/components/schemas/ReceiveTourStatus'
        inbound_tour_last_modified_date:
          type: string
          format: date-time
          example: 2024-07-09T16:29:04.233244Z
          description: Timestamp indicating when the inbound tour was last modified.
        last_announced_item_set_resource_id:
          type: string
          format: uuid
          example: 97b17d9f-e8a1-45b0-a722-30423466933a
          description: the Zalando specific UUID representing the last announced item set resource ID - will change every time a new announced item set is uploaded to the shipping notice
        announced_item_sets:
          type: string
          format: uri
          readOnly: true
          description: a uri to the endpoint listing announced-item-set resources already created for this shipping-notice by the merchant
          example: https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a/announced-item-sets
        last_dispatch_item_set_resource_id:
          type: string
          format: uuid
          example: a7517d9f-e8a1-45b0-a722-30278466933a
          description: the Zalando specific UUID representing the last dispatch item set resource ID - will change every time a new dispatch item set is uploaded to the shipping notice
        dispatch_item_count:
          type: integer
          format: int64
          readOnly: true
          example: 1150
          description: the total item count of the latest dispatch-item-set item set (if any)
        received_item_quantity:
          type: integer
          format: int64
          example: 870
          description: The count of received items coming from Partner Inbound Tracker service
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
        self:
          $ref: '#/components/schemas/SelfLink'
        dispatch_item_sets:
          type: string
          format: uri
          readOnly: true
          description: a uri to the endpoint listing dispatch-item-set resources already created for this shipping-notice by the merchant
          example: https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a/dispatch-item-sets
        confirmed_delivery_date:
          type: string
          format: date
          description: the confirmed date (format see RFC 3339, section 5.6, definition "full-date") when the actor will be able to deliver the announced goods to the warehouse
          example: '2017-07-21'
        is_last_announced_item_set_valid:
          type: boolean
          readOnly: true
          example: true
          description: The validation state of the last uploaded announced item set is valid.
        is_last_dispatch_item_set_valid:
          type: boolean
          readOnly: true
          example: false
          description: The validation state of the last uploaded announced item set is valid.
        announced_item_count:
          type: integer
          format: int64
          example: 1500
          readOnly: true
          description: the total item count of the announced-item-set used for the delivery-date-request (if any)
        source_system:
          $ref: '#/components/schemas/SourceSystem'
        created_by_user:
          type: string
          description: the client created the resource
          example: "John Doe"
        last_modified_by_user:
          type: string
          description: the client modified the resource
          example: "John Doe"
        last_modified_by_system:
          type: string
          description: the client used for request
          example: ZDIRE
        last_dispatch_confirmation_resource_id:
          type: string
          format: uuid
          example: 27b17d9f-e8a1-45b0-a722-304234669334
          description: the Zalando specific UUID representing the last dispatch confirmation ID - will change every time a new dispatch confirmation is done

    PutShippingNoticeRequest:
      type: object
      required:
        - zalando_merchant_id
        - announced_items
      description: |
        shipping-notice resource to be sent with a "put" request.
      properties:
        zalando_merchant_id:
          type: string
          format: uuid
          description: the Zalando specific UUID representing a merchant - can not be changed once defined within resource
          example: 57dd7874-cd76-4cef-8efa-095948680518
        merchant_b2b_reference:
          type: string
          maxLength: 100
          description: a merchant specific optional reference id or information for the advise (for example a merchant location)
          example: SOME-B2B-REFERENCE
        comments:
          type: string
          maxLength: 1000
          description: an optional free text (restricted to 1000 characters) e.g. containing a message to ZFS operations with additional details
          example: 'some comments'
        requested_zalando_location_id:
          type: string
          format: uuid
          description: the warehouse location requested by the actor
          example: 1e57b2b6-907b-4676-8766-339a1d596e59
        carrier_name:
          type: string
          maxLength: 100
          description: an identifier for the carrier delivering the goods to the warehouse
          example: DHL
        pallets_count:
          type: integer
          format: int64
          minimum: 0
          example: 3
          description: expected pallets count for a shipping-notice
        colli_count:
          type: integer
          format: int64
          minimum: 0
          description: expected colli count for a shipping-notice
        hanging_goods_count:
          type: integer
          format: int64
          minimum: 0
          description: expected hanging goods count for a shipping-notice
        earliest_delivery_date:
          type: string
          format: date
          description: the earliest date (format see RFC 3339, section 5.6, definition "full-date") when the actor will be able to deliver the announced goods to the warehouse
          example: '2022-07-21'
        contact_email:
          type: string
          format: email
          description: this is an email address on merchant side which maybe used to get in contact in case there are problems during the shipping process.
          example: 'some_merchant@acme.com'
        additional_contact_email:
          type: string
          format: email
          description: this is an additional email address on merchant side which maybe used to get in contact in case there are problems during the shipping process.
          example: 'some_merchant1@acme.com'
        announced_items:
          $ref: '#/components/schemas/ItemSetUploadRequest'

    ShippingNoticeResponse:
      type: object
      description: |
        The result of a query for shipping-notice resources.
      properties:
        shipping_notices:
          type: array
          items:
            $ref: '#/components/schemas/ShippingNotice'
        total_count:
          type: integer
          example: 153
          format: int64
        to_be_dispatched_next_working_day_count:
          type: integer
          format: int64
          example: 23
        total_draft_count:
          type: integer
          format: int64
          example: 78
        total_actions_required_count:
          type: integer
          format: int64
          example: 4

    SelfLink:
      type: string
      format: uri
      readOnly: true
      description: a uri pointing to where this resource is located - uses https protocol
      example: https://api-sandbox.merchants.zalando.com/zfs/shipping-notices/e7eab8ae-38e1-427b-950d-466bea9df67a/dispatch-item-sets/e02da135-7423-4ab1-b19a-3ed2e0e309d2

    Booking:
      type: object
      description: A summary of information for a specific tour.
      required:
        - booking_type
        - requested_delivery_date
      properties:
        resource_id:
          type: string
          format: uuid
          description: A unique ID to identify a shipping notice booking.
          example: '2062dc78-1800-444c-9727-c00d32c47f25'
        shipping_notice_resource_id:
          type: string
          format: uuid
          description: A unique ID to identify a shipping notice.
          example: '1002dc78-1837-444c-2983-c00d32c47h25'
        ticket_id:
          type: string
          maxLength: 50
          description: An identifier to a ticketing system to process the delivery date request - currently this is a JIRA ticket for SCM
          example: AVS-1380751
        requested_delivery_date:
          type: string
          format: date
          description: the requested date when the actor would like to deliver the announced goods to the warehouse
          example: '2020-07-21'
        requested_zalando_location_id:
          type: string
          format: uuid
          description: the warehouse location requested by the actor
          example: '29809185-6a98-4691-a15b-e8d16839b6e8'
        confirmed_delivery_date:
          type: string
          format: date
          description: the confirmed date when the actor should dispatch goods to the confirmed warehouse
          example: '2020-07-21'
        confirmed_zalando_location_id:
          type: string
          format: uuid
          description: the confirmed warehouse where the partner will send goods to.
          example: '29809185-6a98-4691-a15b-e8d16839b6e8'
        confirmed_by:
          type: string
          example: "John Doe"
          description: the user who confirmed delivery date request or 'API' if booking was scheduled automatically
        confirmed_at:
          type: string
          format: date-time
          readOnly: true
          description: the date/time when this resource has been confirmed
          example: '2021-07-23T17:32:28.123Z'
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: the date/time when this resource has been created
          example: '2021-07-21T17:32:28.123Z'
        created_by:
          type: string
          readOnly: true
          example: "John Doe"
          description: The Actor/User who created this booking resource.
        booking_type:
          $ref: '#/components/schemas/BookingType'
        automatically_scheduled:
          type: boolean
          example: true
          description: Indicates whether this resource has been automatically scheduled.
        source_system:
          $ref: '#/components/schemas/SourceSystem'
        created_by_user:
          type: string
          readOnly: true
          description: The Actor/User who created this booking resource.
          example: "John Doe"
        confirmed_by_user:
          type: string
          readOnly: true
          description: The Actor/User who confirmed this booking resource.
          example: "John Doe"
        confirmed_by_system:
          type: string
          readOnly: true
          description: The Actor/User who confirmed this booking resource.
          example: ZDIRECT
        confirmed_booked_quantity:
          type: integer
          format: int64
          minimum: 1
          example: 550
          description: the total quantity of confirmed booking
        comments:
          type: string
          maxLength: 1000
          description: an optional text, e.g. containing a message to ZFS operations with additional details for same day slot requests.
          example: 'some comments'

    ReceiveTourStatus:
      type: string
      example: DUE_AT_WAREHOUSE
      x-extensible-enum:
        - DUE_AT_WAREHOUSE
        - RECEIVE_IN_PROGRESS
        - RECEIVED

    SourceSystem:
      type: string
      example: ZDIRECT
      x-extensible-enum:
        - PROTOZWO
        - ZDIRECT
        - API
        - PDS
        - HYPERLOOP
        - ZEOS_ONE
        - THIRD_PARTY_API

    ShippingNoticeState:
      type: string
      example: ready_for_dispatch
      x-extensible-enum:
        - initial
        - waiting_for_delivery_date
        - ready_for_dispatch
        - ready_for_receive
        - processing_at_warehouse
        - closed
        - cancelled

    BookingType:
      type: string
      example: rebooking
      x-extensible-enum:
        - booking
        - rebooking
        - same_day_slot

    ShippingNoticeById:
      allOf:
        - $ref: '#/components/schemas/ShippingNotice'
        - type: object
          properties:
            editable_fields:
              type: array
              description: A list of editable fields for the current state of the shipping notice
              format: string
              example: [ "merchant_b2b_reference", "additional_contact_email" ]

    HyperloopTourResponse:
      type: object
      description: A summary of information for a hyperloop tour.
      required:
        - zalando_advice_id
      properties:
        shipping_notice_id:
          type: string
          description: A unique ID to identify a shipping notice.
          format: uuid
        zalando_advice_id:
          type: string
          description: A numeric Zalando-specific ID to identify a shipping notice during its lifecycle to be processed by Zalando systems.
          example: '99200000'
        tour_number:
          type: string
          description: Identifier of a tour.
          example: '20171026-0001-BR-ERF'
          nullable: true
        to_location:
          type: string
          description: Destination location for the tour.
          nullable: true
        from_location:
          type: string
          description: Start location of the tour.
          nullable: true
        planned_arrival_time_at_dock:
          type: string
          description: Planned arrival time at the dock
          example: '2024-07-10T04:00:00.000Z'
          nullable: true
        planned_arrival_time_at_yard:
          type: string
          description: Planned arrival time at the dock
          example: '2024-07-10T04:00:00.000Z'
          nullable: true
        type:
          type: string
          description: Type of the tour
          example: 'NEW_GOODS'
          nullable: true
        planned_amount_of_loading_units:
          type: object
          description: Amount of planned loading units provided by the creator of the tour.
          properties:
            pallets:
              type: integer
              format: int32
              nullable: true
            colli:
              type: integer
              format: int32
              nullable: true
            hanging_garments:
              type: integer
              format: int32
              nullable: true
          nullable: true
        actual_amount_of_loading_units:
          type: object
          description: Actual amount of loading units provided by the creator of the tour.
          properties:
            pallets:
              type: integer
              format: int32
              nullable: true
            colli:
              type: integer
              format: int32
              nullable: true
            hanging_garments:
              type: integer
              format: int32
              nullable: true
          nullable: true
        current_status:
          type: string
          readOnly: true
          description: |
            Status of the tour. Possible values are:

            - `initialized` - the tour is created and is in its initial state
            - `canceled` - the tour was canceled/deleted
            - `arrived` - the truck has arrived at the destination warehouse
            - `unloading` - the tour is currently being unloaded
            - `rejected` - the tour was rejected, e.g. because a pallet is missing or is defect.
            - `unloaded` - the tour was completely unloaded from the truck

          example: unloaded
          nullable: true
          x-extensible-enum:
            [
              initialized,
              arrived,
              unloading,
              unloaded,
              canceled,
              rejected,
            ]

    HyperLoopTourListResponse:
      type: object
      properties:
        tours:
          type: array
          items:
            $ref: '#/components/schemas/HyperloopTourResponse'

    Issue:
      type: object
      description: Issues related to a shipping notice when actions are required.
      properties:
        resource_id:
          type: string
          format: uuid
          description: The UUID (v4) uniquely identifying the resource.
        shipping_notice_uuid:
          type: string
          format: uuid
          description: A unique ID to identify a shipping notice.
        merchant_id:
          type: string
          format: uuid
          description: The Zalando specific UUID representing a merchant.
        advice_id:
          type: string
          description: the Zalando specific ID for a shipping notice (in Zalando terms it is called `advice_id` - currently restricted to 8 digits which may change in the future) - can not be changed by the actor
        issue_type:
          type: string
          description: The type of the issue.
          x-extensible-enum:
            - dispatch_information_missing
            - truck_rejection
            - no_show
            - no_time_slot_booked
        confirmed_delivery_date:
          type: string
          format: date
          description: the confirmed date (format see RFC 3339, section 5.6, definition "full-date") when the actor will be able to deliver the announced goods to the warehouse
          example: '2017-07-21'
        tour_number:
          type: string
          format: string
          description: Identifier of a tour.
        created_at:
          type: string
          format: date-time
          description: Timestamp indicating when the issue was created.
        removed_at:
          type: string
          format: date-time
          description: Timestamp indicating when the issue was removed.
        is_active:
          type: boolean
          description: Indicates whether the issue is still active or not.
    InboundRecommendationsApiResponse:
      type: object
      properties:
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/ApiRecommendation'

    ApiRecommendation:
      type: object
      properties:
        date:
          type: string
          format: date
          example: '2024-01-01'
          description: The date of the recommendation.
        zalando_location_id:
          type: string
          format: uuid
          description: The id of the warehouse.
    ArticleCustomsData:
      type: object
      properties:
        article_id:
          type: object
          properties:
            id:
              type: string
              description: The article identifier
              example: '124567890123'
            type:
              type: string
              description: Article id type, could be a global standard like EAN_13 or a merchant specific identifier type
              example: 'EAN_13'
          required: [ id, type ]
        merchant_specified_identifier:
          type: object
          properties:
            type:
              type: string
              description: The type of the merchant specified identifier
              example: 'GTIN'
            values:
              type: array
              items:
                type: string
              description: The values of the merchant specified identifier
              example: [ '123456789', '987654321' ]
        customs_data:
          type: object
          properties:
            country_of_origin:
              type: string
              description: The country of origin of the article (ISO 3166-1 alpha-2 code)
              format: ISO 3166-1 alpha-2
              example: DE
            customs_value:
              type: number
              format: double
              description: The customs value of the article
              example: 39.99
            currency:
              type: string
              description: The currency of the customs value (ISO 4217 code)
              format: ISO 4217
              example: EUR
            gross_weight_grams:
              type: integer
              format: int32
              description: The gross weight of the article in grams
              example: 1000
            net_weight_grams:
              type: integer
              format: int32
              description: The net weight of the article in grams
              example: 900
            preferential_status:
              type: boolean
              description: Preferential status of the article
            position_document_references:
              type: array
              items:
                $ref: '#/components/schemas/Document'
            components:
              type: array
              description: List of components that make up the article
              items:
                $ref: '#/components/schemas/ArticleCustomsDataComponent'
      required: [ article_id ]
    ArticleCustomsDataComponent:
      type: object
      properties:
        weight_proportion:
          type: number
          format: double
          description: The weight proportion of the component relative to the whole article
          example: 0.1
        price_proportion:
          type: number
          format: double
          description: The price proportion of the component relative to the whole article
          example: 0.3
        country_of_origin:
          type: string
          description: The country of origin of the component (ISO 3166-1 alpha-2 code)
          format: ISO 3166-1 alpha-2
          example: KH
        material_construction:
          type: string
          description: The material construction of the component
          example: Knitted
        material_composition:
          type: string
          description: The material composition of the component
          example: 80%VISKOSE 20%POLYESTER
        measurement_value:
          type: string
          description: The measurement value of the component
          example: Size 36
        set_or_multipack_quantity:
          type: integer
          format: int32
          description: The quantity of items in a set or multipack
          example: 1
        classifications:
          type: array
          description: List of country-specific tariff classifications for the component
          items:
            $ref: '#/components/schemas/ArticleCustomsDataClassification'
        additional_customs_data:
          type: object
          description: Additional customs data as key-value pairs
          additionalProperties: {}
    ArticleCustomsDataClassification:
      type: object
      properties:
        country_code:
          type: string
          description: The country code (ISO 3166-1 alpha-2) for this classification
          format: ISO 3166-1 alpha-2
          example: CH
        import:
          $ref: '#/components/schemas/ArticleCustomsDataTariff'
        export:
          $ref: '#/components/schemas/ArticleCustomsDataTariff'
    ArticleCustomsDataTariff:
      type: object
      properties:
        tariff_number:
          type: string
          description: The tariff number for the component
          example: 6110.30.00
        tariff_description:
          type: string
          description: The tariff description for the component
          example: PULL-OVER MAILLE FEMME 80%VISCOSE 20%POLYESTER
        additional_codes:
          type: array
          description: Additional tariff codes
          items:
            type: string
          example: [ AB ]
        prohibitions_and_restrictions:
          type: array
          description: List of prohibitions and restrictions applicable to the component
          items:
            type: string
          example: [ Textiles ]
    ArticleCustomsDataResponse:
      type: object
      properties:
        validation_result:
          type: object
          properties:
            mapping:
              type: object
              properties:
                invalid_article_count:
                  type: integer
                valid_article_count:
                  type: integer
                validation_errors:
                  type: array
                  items:
                    $ref: '#/components/schemas/DispatchValidationError'
            customs:
              $ref: '#/components/schemas/CustomsValidationResult'
        merchant_id:
          type: string
          format: uuid
        article_customs_data:
          type: array
          items:
            $ref: '#/components/schemas/ArticleCustomsData'
    CustomsValidationResult:
      type: object
      properties:
        total_number_of_validated_articles:
          type: integer
        number_of_valid_articles:
          type: integer
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/CustomsValidationError'
    CustomsValidationError:
      type: object
      properties:
        article:
          $ref: '#/components/schemas/CustomsValidationErrorArticle'
        component:
          type: integer
        field:
          type: string
        failure_reasons:
          type: array
          items:
            type: string
    CustomsValidationErrorArticle:
      type: object
      properties:
        article_id:
          $ref: '#/components/schemas/CustomsValidationErrorArticleId'
        msis:
          type: array
          items:
            $ref: '#/components/schemas/CustomsValidationMsi'
    CustomsValidationErrorArticleId:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    CustomsValidationMsi:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
    Document:
      type: object
      properties:
        type:
          type: string
          description: The type of the document
          example: 'INVOICE'
        number:
          type: string
          description: The number of the document
          example: '0958222220404'
        date:
          type: string
          format: date
          description: The date of the transactional document
          example: '2024-01-01'
        currency:
          type: string
          description: The currency of the document
          format: ISO 4217
          example: EUR
    DispatchValidationError:
      type: object
      properties:
        failure_reason:
          type: string
          enum: ['article_mapping_issue']
          description: >
            The reason why the validation failed.
            article_mapping_issue: The article identifier is not recognized, most likely due to an onboarding issue.
        articles:
          type: array
          items:
            type: string
            description: A list of article identifiers that failed validation
            example: ['1234567890123', '9876543210987']
