x-tagGroups:
  - name: Introduction
    tags:
      - Concepts
      - Main Features
      - Flow Diagrams
      - Webhooks
      - Authentication
  - name: Endpoints
    tags:
      - Locker API
      - Parcel API
  - name: Webhooks
    tags:
      - Locker Events
      - Parcel Events
      - Collection Events
openapi: 3.1.0
info:
  title: GLS/NXT OOH Platform Integration REST API
  version: 1.1.0
  description: >
    The **GLS/NXT OOH Platform Integration API** is designed to optimize
    **first-mile and last-mile logistics operations** by providing comprehensive
    management of lockers, parcels, and carrier settings.


    ## 🚀 Key Capabilities


    - **📦 Locker Management**: Create, update, and retrieve locker information
    with detailed location and compartment data

    - **📋 Parcel Operations**: Handle delivery and return operations with
    real-time booking and status tracking

    - **📡 Real-time Updates**: Webhook-based event notifications for immediate
    status awareness


    ## 🔄 Event-Driven Architecture


    The API extends traditional REST capabilities with **event-based data
    exchange** built on top of webhooks and **traceable session management** for
    couriers and end-users locker interactions.


    ## 🛡️ Security & Reliability


    - **Robust authentication** and error handling mechanisms

    - **Secure and reliable** interactions with comprehensive validation

    - **Real-time status updates** via webhooks for enhanced operational
    efficiency


    ## 🎯 Business Value


    By leveraging these features, carriers can **streamline their APM logistics
    integration processes** and quickly provide a more **flexible and convenient
    service** for their customers.
  contact:
    name: GLS/NXT
    url: https://www.glsnxt.com/
    email: api-support@glsnxt.com
servers:
  - url: https://api.staging.glsnxt.com/ooh/carrier-connector/v1
    description: Staging
  - url: https://api.glsnxt.com/ooh/carrier-connector/v1
    description: Production
tags:
  - name: Concepts
    description: >-
      In this API, some terms are used in specific ways to facilitate
      understanding and usage. This section clarifies the meanings of these
      terms.


      - **Locker**: A locker represents a location equipped with electronically
      controlled storage compartments, used by carriers for optimized first-mile
      and last-mile logistics operations.

      - **Module**: Some lockers can be divided into multiple modules, typically
      done to increase the storage capacity of a locker.

      - **Compartment**: Each module features multiple compartments, which come
      in different sizes.

      - **Parcel**: A package that is delivered in and collected from a
      compartment.
  - name: Main Features
    description: >-
      The **GLS/NXT OOH Platform Integration API** enables carriers to
      seamlessly integrate with the OOH Platform, facilitating quick and
      scalable adoption of lockers in their operational workflows.


      ## 🚚 Operations Overview


      The API supports two main operations for parcel handling:


      ### 📦 Delivery Operations

      - **Purpose**: Deliver parcels to lockers for consignee pickup

      - **Use Case**: Ideal for **last-mile deliveries**

      - **Benefit**: Provides consignees with flexible and convenient delivery
      options


      ### 🔄 Return Operations  

      - **Purpose**: Enable customers to return parcels and ship new ones using
      lockers

      - **Use Case**: Supports **first-mile returns**

      - **Benefit**: Allows customers to drop off items at designated lockers


      ## 🏪 Locker Management


      Comprehensive capabilities for managing lockers:


      | Operation | Description |

      |-----------|-------------|

      | **Creation** | Set up new lockers with location, size, and feature
      details |

      | **Retrieval** | Fetch locker information including status and contained
      parcels |

      | **Updating** | Modify locker details for status, location, or
      configuration changes |


      ## 📋 Parcel Management


      The API provides three core parcel operations:


      - **📤 Parcel Data Upload**: Publish carrier parcel data to trigger locker
      bookings or pre-checks

      - **📖 Get Parcel Information**: Access real-time parcel data including
      status and event history  

      - **❌ Cancel Parcels**: Cancel undelivered parcels to free up locker
      capacity


      ## 🔐 Authentication & Security


      | Method | Purpose |

      |--------|---------|

      | **ApiKeyAuth** | General API access |


      ## ⚠️ Error Handling


      Standard HTTP status codes with detailed error messages:


      | Code | Status | Description |

      |------|--------|-------------|

      | `200` | **OK** | Request successful |

      | `400` | **Bad Request** | Malformed or invalid request |

      | `401` | **Unauthorized** | Authentication failed or missing |

      | `404` | **Not Found** | Requested resource not found |

      | `500` | **Internal Server Error** | Unexpected server error |
  - name: Flow Diagrams
    description: >-
      The main flow diagrams can be found here for implementation guidance: 


      # Parcel Booking Flow

      <script>window.addEventListener("message", function(e) {var i =
      e.data.split(":")[1];var h = e.data.split(":")[2];if (e.data.split(":")[0]
      == "swimlanes-io" && i && h) {document.getElementById("__sw-io-" +
      i).setAttribute("style","height:" + h + "px");}}, false);</script>

      <div id="__sw-io-tVXm8"><iframe style="border:none; width:100%;
      height:100%" scrolling="no"
      src="https://cdn.swimlanes.io/dist/embeded.html#tVXfb9s2EH7XX3HwXjatkhXPAzY9FHNtr3OTJUHjogWCwGbEk8VFIgWSjuMN+d93FCVbddNhGLAHCxLvu+9+fTxbYUtM4ZrpDEuYYSkeUe+DIFilEIZnMVxrjLICswe4VbUVSrLyLgyDKdNaoIboNby9uBleflp2JNHkekG+w7r5MkPOLAthff1+vpr+Np+er4NAKotpsCwQLP16JhCGojIJV22oMARjsQarwCchcmDgqSEj4D2CRoP6ETkISTAGpsZM5CKDUmUPqGNivFQtijlaIqU4XEmEnbBFP4E4COZPrKpLhK1hG+rMxwJlF5C8Mo3MIn8F91tLqYmypIg57oCzvQG2UZBrVVFaQm6A+3Y6+GmhO+dZYFmD4CityPeuNIdqY0lEblzdTYVcaMwobgxT1wYDNepc6YqqZhohrNiTqLYVGPEnhsAkh0dWCi7sHlTeUXK0TJQGzDYrgJm2P7CYUdUiT3ujvjoP2qm6AbezTmGUJHCoYUUglPzUNacQyF90H5/91HP/dbK4mM88RSO2UQxvlHqgxv0Xfb25ujpfXL5dt+IiENxqzKn7MsO7bwtra5MOh1xlJt6URj7ZOFOV+x5mPlZE+sGNbiQSsVoMFTW5+Tq+RfX2vhSm8MFd6O+CYL1eB38FAAN8pFEu9zUOUhi0CQ1eOYtv9QfBncWoCi8OB429TcFXuDigpifHHqukERvSB6FcWDqSrGpivlOFhJnCBugSqmgazvAHGWKu8Bf06na1Dwjz3DByUSFxEu+RkmNtC/ocj1quAsWmsP2TneAt5MC0O4KC56YxXxUSySeI45gC5sxEphZSon6GidnLDJpOgqLLAzvE+4J08T8Pduej+MFuaxotmm/+2RzRTqmpaWj6IjCFqKmdth02k/tufGejH15QAwG8GHqAF+RAsBM1nKI7Fof272fe3mXUKfNicrNc/U6373PzjWV26xQwmL6fT5bzmTezLENjpopjTx0HDU5VWdJmohY5R2o8dcg6tsnBzeV5uB2O47bh8Ex0bkl9xpIsHcMoGY2j5McoGS+Tn9PxKE2S75OEnq2kv3LLVl3KDeiZnned/tx6avdKt73dBqTs8m1Z7o/67Au0/T/86KeeHtZLF2d9XH2fcVMfvtiA/4rXb8OG9m8=#tVXm8"></iframe></div>



      # Parcel Cancel Flow

      <script>window.addEventListener("message", function(e) {var i =
      e.data.split(":")[1];var h = e.data.split(":")[2];if (e.data.split(":")[0]
      == "swimlanes-io" && i && h) {document.getElementById("__sw-io-" +
      i).setAttribute("style","height:" + h + "px");}}, false);</script>

      <div id="__sw-io-dY9Q"><iframe style="border:none; width:100%;
      height:100%" scrolling="no"
      src="https://cdn.swimlanes.io/dist/embeded.html#dY9BawJBDIXv8ytyFrerpQeZgyCLFbG0Qi30Ou5mNXRMlsxQWMT/7rjdpQjtKQnJe9/LjqJHC1unJXooHKdiTOFUCRWyOaxe3vPXz91wki22awujvOmmkJedIj+HIzUn5PhB1WVkDNW2N4O3jWGJaM1ioFTo6Ru1hSQGYd/CHuHHCKvU16L4e0QcBeIRwUv5hfpg+kS3cH1OC4+TyQ2EXN2xnx35MODrmD76z3bcB3CRhIECsKQNH5KkkRBo7/Fv8tN0BktV0Q5+BQ==#dY9Q"></iframe></div>



      # Courier Collection/Delivery Flow

      <script>window.addEventListener("message", function(e) {var i =
      e.data.split(":")[1];var h = e.data.split(":")[2];if (e.data.split(":")[0]
      == "swimlanes-io" && i && h) {document.getElementById("__sw-io-" +
      i).setAttribute("style","height:" + h + "px");}}, false);</script>

      <div id="__sw-io-zVXw"><iframe style="border:none; width:100%;
      height:100%" scrolling="no"
      src="https://cdn.swimlanes.io/dist/embeded.html#zVXdb9owEH/PX3HiMSqk2mMeJmUhW6PSgEK6dZomMMlRrLpxFptWCPG/9xwbiqZq7SY2jQc+Lue738dx1lwLDCGW65ZjCxesrgSvb01ECCw1l3UwRMEfsN14Xi01hl6x4gqWQj4Cfd5ijS0vQUtg9QaELO+ojt40SL8rYE0jOFK6bGEh9QrKQ93ueeVqg2ywZSasBuD7GTXyfdArprujL6QBr6mnKltEW2rB2lJWCPhjzRusHBR19nyY4DZSKb4QCI9cr+Rag7+nvmcJUVmiUiRAhcqHPoFAQm2TVMmos4k01A1F19gm3FNE32Otiae8o/4G91EmIaejbK3lPREomRCbgQf08jy+DOFakewHH6KmMfzw1pL1YtZ28f57+DSaBtlNEZJKLrsfTVISy5+MpwUEpHjg4AZOgmBrv1zzaud7nqtgirm6Ibw7P4fxpTM4R9WQwgb6RkhWEZRSrEmOAz5FChkLK6bZGah1uQKm9uYzK6AxQ3UCWQWUmRHnRRd2ozDw/pSeQ6ECfCDdyaz5tIjyIhnOf8Wxk/t5vAniA+OC0VCcDkc8Ho2SuEjH2exNkE7WeBLlcTKaTeMoy/5Z0yO2H9MsnV680hnryrrg/nNmQfwFE4bJKP2c5F//YwuORNjAkhTA6vT85zDHtpVtGI+vCFxxlWTF7EM+vkyy1206vRtvGpFTDufVZJS8Zr/hehjL/S4+3FRfcLGipf5c4LhCB+KFZLtL5/O5t6U93zus4F4IPaVbatE7Mw8cdHvtmFvn5wS3Pin8rbswtt27OWkhTLrn6XHhLmNH79+9XQeh4+YNBoMQtkum+qrhNV3cO4jUpi73d5QVzYpgq+6J0Vy+TN5mOc6hkfs6T5N85nZCMpwlN5M0N/If9HWH3OD/dmk3Sa7kEw==#zVXw"></iframe></div>
  - name: Webhooks
    description: >-
      Webhooks provide real-time updates on locker and parcel statuses by
      pushing notifications to specified URLs. This ensures Carriers stay
      informed about relevant events as they happen.


      Webhook endpoints are designed to push updates about lockers, parcels, and
      other events to URLs provided by the Carrier. These endpoints include:

      - **Locker Updates**: Enables carriers to receive real-time updates about
      locker status and details.

      - **Parcel Updates**: Allows carriers to receive notifications about
      changes in parcel status.

      - **Pickup Notifications**: Daily notifications about parcels that need to
      be picked up from lockers.


      **Key Features:**

      - **Real-time Updates**: Push notifications for immediate awareness of
      changes.

      - **Customizable URLs**: Configure URLs to receive specific event updates.
  - name: Authentication
    description: >
      Use the API Key provided by the GLS/NXT team to authorize requests. The
      API Key should be included in the `X-API-Key` header of each request.


      Example: `'X-API-Key: <your-api-key>'`


      > info

      > In the near future, OAuth 2.0 authentication mechanisms will replace API
      Key Authorization.
  - name: Locker API
    description: >
      The Locker API endpoints provide comprehensive management of lockers,
      including their creation, updating, and retrieval. These endpoints
      support:

      - **Locker Creation**: Set up new lockers with necessary details such as
      location, internal carrier IDs, and specific locker features.

      - **Locker Information Retrieval**: Access detailed information about
      lockers, including their status and location.

      - **Locker Updates**: Update existing locker details to reflect changes in
      status or configuration.


      **Key Features:**

      - **Flexible Locker Management**: Create and update lockers to keep
      information current and accurate.

      - **Detailed Location Data**: Access geographic and logistical details of
      each locker.

      - **Compartment Management**: Manage the availability and allocation of
      compartments within lockers.
  - name: Locker Events
    description: >
      This webhook endpoint is designed to push events about locker updates.

      - **New Locker**: An event will be pushed when a new Locker is created.

      - **Locker status**: An event is pushed when the locker status changes
      (enabled/disabled).
  - name: Parcel API
    description: >
      The Parcel API endpoints are focused on the management of the parcel
      bookings. It allows for Carrier to publish parcel data for respective
      locker booking creation, the retrieval of parcel information and
      cancellation of parcel bookings.

      - **Parcel Data Publishing**: Publish parcel data from the Carrier into
      the OOH Platform, enabling carriers to trigger locker bookings or
      pre-checks at the appropriate time.

      - **Parcel Information Retrieval**: Fetch details of parcels, including
      status, and event history.

      - **Parcel Cancellation**: Cancel parcel booking for parcels that are no
      longer to be delivered into the locker.


      **Key Features:**

      - **Real-time Parcel Bookings**: Push real-time parcel data to the OOH
      Platform to perform bookings at any time.

      - **Comprehensive Parcel Data**: Retrieve detailed information on parcel
      booking status and history.

      - **Cancellation Flexibility**: Cancel undelivered parcels to manage
      logistics effectively.
  - name: Parcel Events
    description: >
      This webhook endpoint is designed to push updates about parcels handling
      events.

      - **Parcel Updates**: Get notifications about changes in parcel status.
  - name: Collection Events
    description: >
      This webhook endpoint is designed to push events about lockers that
      require parcel collections.

      - **Sporadic Collection**: Events are pushed to notify the Carrier that
      lockers have parcels to be collected.
paths:
  /lockers:
    post:
      tags:
        - Locker API
      summary: Create a new locker
      description: >-
        Create a new locker with the specified details for the carrier,
        provider, location, and features.
      security:
        - ApiKeyAuth: []
      operationId: createLocker
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_input'
      responses:
        '201':
          description: Locker created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/locker_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '500':
          $ref: '#/components/responses/response_500'
    get:
      tags:
        - Locker API
      summary: Get a list of lockers
      description: >-
        Retrieve a list of lockers with optional filters such as location,
        status, carrier, and provider.
      security:
        - ApiKeyAuth: []
      operationId: listLockers
      parameters:
        - name: providerName
          in: query
          required: false
          description: Filter lockers by provider name.
          schema:
            type: string
            example: BLOQ
        - name: status
          in: query
          required: false
          description: Filter lockers by status.
          schema:
            $ref: '#/components/schemas/status'
            example: ACTIVE
        - name: city
          in: query
          required: false
          description: Filter lockers by city.
          schema:
            type: string
            example: Berlin
        - name: countryCode
          in: query
          required: false
          description: Filter lockers by country code (ISO 3166-1 alpha-2).
          schema:
            type: string
            example: DE
        - name: compartmentSize
          in: query
          required: false
          description: Filter lockers by the size of compartments available.
          schema:
            type: string
            enum:
              - SMALL
              - MEDIUM
              - LARGE
              - XLARGE
              - XXLARGE
            example: MEDIUM
      responses:
        '200':
          description: List of lockers retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/locker_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '500':
          $ref: '#/components/responses/response_500'
  /lockers/{uid}:
    patch:
      tags:
        - Locker API
      summary: Update a locker
      description: >-
        Update the details of an existing locker, including carrier details,
        provider details, location, and features.
      security:
        - ApiKeyAuth: []
      operationId: updateLocker
      parameters:
        - name: uid
          in: path
          required: true
          description: The OOH Platform UID for the locker.
          schema:
            type: string
            example: '426614174000'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_input'
      responses:
        '200':
          description: Locker updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/locker_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '404':
          $ref: '#/components/responses/response_404'
        '500':
          $ref: '#/components/responses/response_500'
  /lockers/providers:
    get:
      tags:
        - Locker API
      summary: >-
        Get a list of existing locker model and locker version pairs for
        provider
      description: >-
        Retrieve a list of existing locker model and locker version pairs for
        each provider.
      security:
        - ApiKeyAuth: []
      operationId: listLockerProviders
      responses:
        '200':
          description: >-
            List of existing locker model and locker version pairs for each
            provider retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - type: object
                      properties:
                        providerName:
                          type: string
                          description: The name of the locker provider.
                        lockerModel:
                          type: string
                          description: The model of the locker provided by the provider.
                        lockerVersion:
                          type: string
                          description: >-
                            The version of the locker model provided by the
                            provider.
                        providerUid:
                          type: string
                          description: >-
                            The unique identifier of the provider on the GLS/NXT
                            system.
              example:
                - providerName: KEBA
                  lockerModel: Model 1
                  lockerVersion: v2.1
                  providerUid: '1103459297'
                - providerName: KEBA
                  lockerModel: Model 1
                  lockerVersion: v2.2
                  providerUid: '1103459297'
                - providerName: KEBA
                  lockerModel: Model 2
                  lockerVersion: v1.0
                  providerUid: '1103459297'
                - providerName: MYFLEXBOX
                  lockerModel: Model 23
                  lockerVersion: v1.5
                  providerUid: '1203659298'
        '401':
          $ref: '#/components/responses/response_401'
        '500':
          $ref: '#/components/responses/response_500'
  /lockers/status:
    patch:
      tags:
        - Locker API
      summary: Update Locker Status
      description: Update the status of an existing locker.
      security:
        - ApiKeyAuth: []
      operationId: updateLockerStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_status'
      responses:
        '200':
          description: Locker status updated successfully.
          content: {}
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '404':
          $ref: '#/components/responses/response_404'
        '409':
          $ref: '#/components/responses/response_409'
        '500':
          $ref: '#/components/responses/response_500'
  /parcels/data:
    post:
      tags:
        - Parcel API
      summary: Publish parcel data
      description: >
        This endpoint allows the Carriers to publish parcel data into the OOH
        Platform. It should be used to push parcel data at the time when the
        locker booking is expected to take place or to pre-check if a parcel can
        be accepted in the locker.
      security:
        - ApiKeyAuth: []
      operationId: publishParcelData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/input_data'
      responses:
        '200':
          description: Parcel event published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/input_data_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '500':
          $ref: '#/components/responses/response_500'
  /parcels/data/by-tenant-locker-id:
    post:
      tags:
        - Parcel API
      summary: Publish parcel data with carrier locker id
      description: >
        This endpoint is an alternative to `/parcels/data` endpoint and could be
        used to publish parcel data using carrierLockerId instead of lockerUid.
      security:
        - ApiKeyAuth: []
      operationId: publishParcelDataByTenantId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/input_data_carrier_specific'
      responses:
        '200':
          description: Parcel event published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/input_data_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '500':
          $ref: '#/components/responses/response_500'
  /parcels:
    get:
      tags:
        - Parcel API
      summary: Get parcels
      description: >
        Retrieve a list of parcels associated with the carrier. This endpoint
        allows fetching detailed information about parcels, including their
        status and history.
      security:
        - ApiKeyAuth: []
      operationId: getParcels
      parameters:
        - name: ids
          in: query
          description: Comma-separated list of parcel IDs to retrieve
          required: true
          schema:
            type: string
            example: 12345131,G6789011,A1234511
      responses:
        '200':
          description: Parcels fetched successfully
          content:
            application/json:
              schema:
                type: array
                description: List of parcels
                items:
                  $ref: '#/components/schemas/parcel_response'
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '404':
          $ref: '#/components/responses/response_404'
        '500':
          $ref: '#/components/responses/response_500'
  /parcels/{parcelId}:
    patch:
      tags:
        - Parcel API
      summary: Cancel parcel
      description: >
        Cancel the booking of a specific parcel. Only parcels that haven’t been
        delivered can be cancelled. This endpoint allows carriers to manage
        cancellations effectively.
      security:
        - ApiKeyAuth: []
      operationId: cancelParcel
      parameters:
        - name: parcelId
          in: path
          description: The parcel ID to be cancelled
          required: true
          schema:
            type: string
            example: '1234567890'
      responses:
        '200':
          description: Parcel cancelled successfully
        '400':
          $ref: '#/components/responses/response_400'
        '401':
          $ref: '#/components/responses/response_401'
        '404':
          $ref: '#/components/responses/response_404'
        '500':
          $ref: '#/components/responses/response_500'
webhooks:
  LockerUpdates:
    post:
      tags:
        - Locker Events
      summary: Webhook for locker updates
      description: >
        Webhook to push locker updates to any URL provided by the carrier. This
        endpoint allows carriers to receive 

        real-time updates about lockers.
      operationId: webhookLockerUpdates
      requestBody:
        description: Information about locker updates.
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/locker_response'
                - type: object
                  properties:
                    eventTimestamp:
                      type: string
                      format: date-time
                      example: '2025-08-20T00:00:00Z'
                      description: The timestamp of the locker status update.
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  ParcelUpdates:
    post:
      tags:
        - Parcel Events
      summary: Webhook for parcel updates
      description: >
        Webhook to push parcel updates to any URL provided by the carrier. This
        endpoint allows carriers to receive 

        real-time updates about parcels.
      operationId: webhookParcelUpdates
      requestBody:
        description: Information about parcel updates
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/parcel_response'
                - type: object
                  properties:
                    eventTimestamp:
                      type: string
                      format: date-time
                      example: '2025-08-20T00:00:00Z'
                      description: The timestamp of the parcel update
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  CollectionNotification:
    post:
      tags:
        - Collection Events
      summary: Webhook for pickup notifications
      description: >
        Webhook to push collection notifications to any URL provided by the
        carrier. Notifications are sent once per day, 

        informing the carrier about parcels that need to be picked up from the
        lockers.
      operationId: webhookCollectionNotifications
      requestBody:
        description: Information about locker collections.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/collection_events'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
      description: API Authorization Key for API access
  schemas:
    status:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - MAINTENANCE
        - DECOMMISSIONED
      example: ACTIVE
    carrier:
      type: object
      description: The details of the locker on the Carrier's system.
      properties:
        lockerName:
          type: string
          description: The name assigned to the locker on the Carrier's system.
          example: Berlin Locker 01
        lockerId:
          type: string
          description: The unique identifier of the locker on the Carrier's system.
          example: XR1003
        activationDate:
          type: string
          format: date-time
          description: The date when the locker is to be activated for the carrier.
          example: '2025-08-20T00:00:00Z'
      required:
        - lockerName
        - lockerId
        - activationDate
    provider:
      type: object
      description: The details of the locker on the Provider's system.
      properties:
        name:
          type: string
          description: The name of the locker provider.
          example: KEBA
        lockerModel:
          type: string
          description: The model of the locker provided by the provider.
          example: Model 1
        lockerVersion:
          type: string
          description: The version of the locker model provided by the provider.
          example: v2.1
      required:
        - name
        - lockerModel
        - lockerVersion
    location:
      type: object
      description: Details about the geographical location of the locker.
      properties:
        street:
          type: string
          description: The street name where the locker is located.
          example: Main Street
        streetNumber:
          type: string
          description: The street number of the locker location.
          example: '1'
        postalCode:
          type: string
          description: The postal code of the locker location.
          example: '90210'
        city:
          type: string
          description: The city where the locker is located.
          example: Berlin
        lon:
          type: number
          format: double
          description: The longitude coordinate of the locker location.
          example: -118.2437
        lat:
          type: number
          format: double
          description: The latitude coordinate of the locker location.
          example: 34.0522
        countryCode:
          type: string
          description: The ISO 3166-1 alpha-2 country code for the locker location.
          example: DE
      required:
        - street
        - streetNumber
        - postalCode
        - city
        - lon
        - lat
        - countryCode
    features:
      type: object
      description: Features available in the locker.
      properties:
        hasScreen:
          type:
            - boolean
            - 'null'
          description: Indicates if the locker has a screen.
          example: true
        hasPinPad:
          type:
            - boolean
            - 'null'
          description: Indicates if the locker has a PIN pad.
          example: true
        hasPinBarcodeReader:
          type:
            - boolean
            - 'null'
          description: Indicates if the locker has a barcode reader.
          example: false
    metadata:
      type: object
      description: Metadata associated with the locker.
      properties:
        key:
          type:
            - string
            - 'null'
          description: The key of the metadata.
          example: maxWeightCapacity
        value:
          type:
            - string
            - 'null'
          description: The value of the metadata.
          example: 50kg
    compartment:
      type: object
      description: Details about the compartments available in the locker.
      properties:
        size:
          type: string
          enum:
            - SMALL
            - MEDIUM
            - LARGE
            - XLARGE
            - XXLARGE
          description: The size of the compartment.
          example: MEDIUM
        count:
          type: integer
          description: The number of compartments of this size available in the locker.
          example: 4
        height:
          type: integer
          description: The height of the compartment in millimeters.
          example: 400
        width:
          type: integer
          description: The width of the compartment in millimeters.
          example: 400
        length:
          type: integer
          description: The length of the compartment in millimeters.
          example: 600
    locker_response:
      type: object
      properties:
        uid:
          type: string
          description: The internal unique identifier assigned to the locker.
          example: '1002377838'
        carrier:
          allOf:
            - $ref: '#/components/schemas/carrier'
            - type: object
              properties:
                status:
                  $ref: '#/components/schemas/status'
        provider:
          allOf:
            - $ref: '#/components/schemas/provider'
            - type: object
              properties:
                lockerUid:
                  type: string
                  description: >-
                    The unique identifier of the locker on the Provider's
                    system.
                  example: PROVIDER_LOCKER_ABC123
        location:
          $ref: '#/components/schemas/location'
        features:
          $ref: '#/components/schemas/features'
        metadata:
          type: array
          description: Additional metadata associated with the locker.
          items:
            $ref: '#/components/schemas/metadata'
        compartmentTypes:
          type:
            - array
            - 'null'
          description: A list of different compartment types available in the locker.
          items:
            $ref: '#/components/schemas/compartment'
          example:
            - size: SMALL
              count: 10
              height: 200
              width: 400
              length: 600
            - size: MEDIUM
              count: 4
              height: 400
              width: 400
              length: 600
            - size: LARGE
              count: 2
              height: 800
              width: 400
              length: 600
    create_input:
      type: object
      properties:
        carrier:
          $ref: '#/components/schemas/carrier'
        provider:
          $ref: '#/components/schemas/provider'
        location:
          $ref: '#/components/schemas/location'
        metadata:
          type: array
          description: Additional metadata associated with the locker.
          items:
            $ref: '#/components/schemas/metadata'
        features:
          $ref: '#/components/schemas/features'
      required:
        - carrier
        - provider
        - location
    update_input:
      type: object
      properties:
        carrier:
          $ref: '#/components/schemas/carrier'
        location:
          $ref: '#/components/schemas/location'
        metadata:
          type: array
          description: Additional metadata associated with the locker.
          items:
            $ref: '#/components/schemas/metadata'
        features:
          $ref: '#/components/schemas/features'
    update_status:
      type: object
      properties:
        lockerUid:
          type: string
          example: '678438790243767'
          description: The unique identifier of the locker in the GLS/NXT Platform
        status:
          $ref: '#/components/schemas/status'
      required:
        - lockerUid
        - status
    booking_type:
      type: string
      description: The type of booking request.
      enum:
        - PRE_CHECK
        - BOOKING
      example: BOOKING
    shipment_type_input:
      type: string
      description: The possible types of last-mile shipments accepted.
      enum:
        - LAST_MILE
        - ALTERNATIVE_DELIVERY
      example: LAST_MILE
    consignee:
      type:
        - object
        - 'null'
      description: The details of the consignee.
      properties:
        name:
          type:
            - string
            - 'null'
          example: John Doe
        email:
          type:
            - string
            - 'null'
          format: email
          example: john.doe@google.com
    dimensions:
      type: object
      description: The dimensions of the parcel.
      properties:
        depth:
          type:
            - integer
            - 'null'
          description: Depth in mm
          example: 190
        height:
          type:
            - integer
            - 'null'
          description: Height in mm
          example: 100
        width:
          type:
            - integer
            - 'null'
          description: Width in mm
          example: 140
    allocation_type:
      type: string
      description: The allocation type of the shipment.
      enum:
        - HARD_RESERVATION
        - SOFT_RESERVATION
      example: HARD_RESERVATION
    input_data:
      type: object
      properties:
        eventType:
          $ref: '#/components/schemas/booking_type'
        lockerUid:
          type: string
          description: The unique identifier of the locker in the GLS/NXT Platform.
          example: locker_567890
        carrierParcelId:
          type: string
          description: The identifier of the parcel in the carrier's system.
          example: A123456789
        shipmentType:
          $ref: '#/components/schemas/shipment_type_input'
        consignee:
          $ref: '#/components/schemas/consignee'
        dimensions:
          $ref: '#/components/schemas/dimensions'
        weight:
          type: integer
          description: Weight in grams
          example: 400
        allocationType:
          $ref: '#/components/schemas/allocation_type'
      required:
        - eventType
        - carrierParcelId
        - lockerUid
        - dimensions
    input_data_response:
      type: object
      properties:
        status:
          type: string
          description: The status of the event processing.
          example: success
        message:
          type: string
          description: >-
            A message providing additional information about the event
            processing.
          example: Parcel event received and processed successfully
        timestamp:
          type: string
          format: date-time
          description: The timestamp when the event was processed.
          example: '2023-06-18T10:45:00Z'
    input_data_carrier_specific:
      type: object
      properties:
        eventType:
          $ref: '#/components/schemas/booking_type'
        carrierLockerId:
          type: string
          description: The unique identifier of the locker in the Carrier Platform.
          example: LOCKER123
        carrierParcelId:
          type: string
          description: The identifier of the parcel in the carrier's system.
          example: 12345KL6789M
        shipmentType:
          $ref: '#/components/schemas/shipment_type_input'
        consignee:
          $ref: '#/components/schemas/consignee'
        dimensions:
          $ref: '#/components/schemas/dimensions'
        weight:
          type: integer
          description: Weight in grams
          example: 300
        allocationType:
          $ref: '#/components/schemas/allocation_type'
      required:
        - eventType
        - carrierParcelId
        - carrierLockerId
        - dimensions
    shipment_type:
      type: string
      description: The type of shipment.
      enum:
        - LAST_MILE
        - ALTERNATIVE_DELIVERY
        - FIRST_MILE
        - RETURN
      example: LAST_MILE
    dimensions_status:
      type: string
      description: The status of the parcel dimensions.
      enum:
        - PARCEL_DIMENSIONS_EXCEED
        - PARCEL_DIMENSIONS_OK
        - PARCEL_DIMENSIONS_UNKNOWN
      example: PARCEL_DIMENSIONS_OK
    shipment_status:
      type: string
      description: The status of the shipment.
      enum:
        - BOOKING_PRE_CHECK
        - BOOKING_REQUESTED
        - BOOKING_CREATED
        - BOOKING_CANCELLED
        - BOOKING_REJECTED_INVALID_LOCKER
        - BOOKING_REJECTED_PROVIDER_ERROR
        - BOOKING_REJECTED_LOCKER_UNAVAILABLE
        - BOOKING_REJECTED_DIMENSIONS_EXCEED
        - BOOKING_REJECTED_INVALID_CONSIGNEE
        - COURIER_DELIVERED
        - COURIER_DELIVERY_EXPIRED
        - COURIER_DELIVERY_LABEL_SCANNED
        - COURIER_COLLECTED
        - COURIER_COLLECTED_EXPIRED
        - COURIER_COLLECTION_LABEL_SCANNED
        - COURIER_COLLECTION_LABEL_NOT_AVAILABLE
        - CONSIGNEE_COLLECTED
        - CONSIGNEE_DELIVERED
        - CONSIGNEE_DELIVERY_EXPIRED
        - CONSIGNEE_COLLECTION_EXPIRED
        - DELIVERY_PARCEL_TOO_BIG
        - DELIVERY_COMPARTMENT_BROKEN
        - DELIVERY_COMPARTMENT_OCCUPIED
        - DELIVERY_NOT_POSSIBLE
        - COLLECTION_PARCEL_NOT_AVAILABLE
        - COLLECTION_COMPARTMENT_BROKEN
        - COLLECTION_NOT_POSSIBLE
      example: BOOKING_PRE_CHECK
    code:
      type:
        - object
        - 'null'
      description: Access codes with valid until timestamp.
      properties:
        code:
          type: string
          example: anyValidCode123
        validUntil:
          type: string
          format: date-time
          example: '2025-01-27T12:00:00Z'
          description: >-
            Code validity in UTC timestamp [ISO
            8601](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
            format.
      required:
        - code
    access_codes:
      type:
        - object
        - 'null'
      description: Access codes for the parcel
      properties:
        consigneeCollection:
          type: string
          example: anyValidCode123
          deprecated: true
        consigneeCollectionCode:
          type: object
          $ref: '#/components/schemas/code'
          description: The access code for the consignee collection
    parcel_events:
      type: array
      items:
        type: object
        properties:
          timestamp:
            type: string
            format: date-time
            example: '2025-08-20T00:00:00Z'
          eventType:
            $ref: '#/components/schemas/shipment_status'
    signature:
      type: object
      description: >-
        A Base64-encoded image representing the consignee's signature, captured
        upon parcel collection
      properties:
        imageBase64:
          type: string
          example: imageBase64StringHere
        format:
          type: string
          example: ''
    parcel_response:
      type: object
      properties:
        shipmentUid:
          type: string
          example: anyParcelId123
          description: The unique identifier of the parcel shipment in the GLS/NXT Platform
        lockerUid:
          type: string
          example: anyLockerId123
          description: The unique identifier of the locker in the GLS/NXT Platform
        carrierParcelId:
          type: string
          example: anyCarrierParcelId123
          description: The identifier of the parcel in the carrier's system
        carrierLockerId:
          type:
            - string
            - 'null'
          example: Locker1
          description: The identifier of the locker in the carrier's system
        shipmentType:
          $ref: '#/components/schemas/shipment_type'
        dimensionsStatus:
          $ref: '#/components/schemas/dimensions_status'
        shipmentStatus:
          $ref: '#/components/schemas/shipment_status'
        accessCodes:
          $ref: '#/components/schemas/access_codes'
        consignee:
          $ref: '#/components/schemas/consignee'
        events:
          $ref: '#/components/schemas/parcel_events'
        allocationType:
          $ref: '#/components/schemas/allocation_type'
        shipmentSignature:
          $ref: '#/components/schemas/signature'
    collection_events:
      type: object
      properties:
        eventTimestamp:
          type: string
          format: date-time
          example: '2025-08-20T00:00:00Z'
          description: The timestamp of the collection event
        lockerUid:
          type: string
          description: The unique identifier of the locker in the GLS/NXT Platform
          example: '8979879823'
        carrierLockerId:
          type:
            - string
            - 'null'
          description: The unique identifier of the locker in the Carrier's system
          example: GHX1234
        courierAccessCode:
          type:
            - string
            - 'null'
          description: >-
            Access code for the courier to collect parcels from locker. Access
            code rotates daily.
          example: '342156'
        parcels:
          type: array
          items:
            type: object
            properties:
              carrierParcelId:
                type: string
                description: The identifier of the parcel in the carrier's system
                example: '1234212321'
  responses:
    '200':
      description: Return a 200 status to indicate that the data was received successfully.
    '401':
      description: Return a 401 status to indicate that the POST was unauthorized.
    '500':
      description: >-
        Return a 500 status to indicate that the POST was unsuccessfully
        processed.
    response_400:
      description: Bad request due to invalid input.
      content:
        application/json:
          schema:
            properties:
              errorCode:
                type: string
                description: A code representing the type of error.
                example: INVALID_REQUEST
              message:
                type: string
                description: A message describing the error.
                example: Bad request due to invalid input
    response_401:
      description: The requested resource requires authentication.
      content:
        application/json:
          schema:
            properties:
              errorCode:
                type: string
                description: A code representing the type of error.
                example: UNAUTHORIZED
              message:
                type: string
                description: A message describing the error.
                example: The requested resource requires authentication
    response_500:
      description: The server encountered an internal error.
      content:
        application/json:
          schema:
            properties:
              errorCode:
                type: string
                description: A code representing the type of error.
                example: SERVER_ERROR
              message:
                type: string
                description: A message describing the error.
                example: The server encountered an internal error
    response_404:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            properties:
              errorCode:
                type: string
                description: A code representing the type of error.
                example: NOT_FOUND
              message:
                type: string
                description: A message describing the error.
                example: The requested resource was not found
    response_409:
      description: The request conflicts with the current state of the target resource
      content:
        application/json:
          schema:
            properties:
              errorCode:
                type: string
                description: A code representing the type of error.
                example: CONFLICT
              message:
                type: string
                description: A message describing the error.
                example: The locker status cannot be updated due to a conflicting state
