Skip to content

GLS/NXT OOH Platform Integration REST API (1.1.0)

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.

Download OpenAPI description
openapi-carrier-integration-api.json
openapi-carrier-integration-api.yaml
Overview
URL

https://www.glsnxt.com/

GLS/NXT

[email protected]

Languages
Servers
Mock server

https://docs.glsnxt.com/_mock/openapi-carrier-integration-api/

Staging

https://api.staging.glsnxt.com/ooh/carrier-connector/v1/

Production

https://api.glsnxt.com/ooh/carrier-connector/v1/

Concepts

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.

Main Features

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.

Flow Diagrams

The main flow diagrams can be found here for implementation guidance:

Webhooks

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.

Authentication

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.

Locker API

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.
Operations

Parcel API

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.
Operations

Publish parcel data

Request

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
Bodyapplication/jsonrequired
eventTypestring(booking_type)required

The type of booking request.

Enum"PRE_CHECK""BOOKING"
lockerUidstringrequired

The unique identifier of the locker in the GLS/NXT Platform.

Example: "locker_567890"
carrierParcelIdstringrequired

The identifier of the parcel in the carrier's system.

Example: "A123456789"
shipmentTypestring(shipment_type_input)

The possible types of last-mile shipments accepted.

Enum"LAST_MILE""ALTERNATIVE_DELIVERY"
consigneeobject or null(consignee)

The details of the consignee.

dimensionsobject(dimensions)required

The dimensions of the parcel.

dimensions.​depthinteger or null

Depth in mm

Example: 190
dimensions.​heightinteger or null

Height in mm

Example: 100
dimensions.​widthinteger or null

Width in mm

Example: 140
weightinteger

Weight in grams

Example: 400
allocationTypestring(allocation_type)

The allocation type of the shipment.

Enum"HARD_RESERVATION""SOFT_RESERVATION"
curl -i -X POST \
  https://docs.glsnxt.com/_mock/openapi-carrier-integration-api/parcels/data \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "eventType": "BOOKING",
    "lockerUid": "locker_567890",
    "carrierParcelId": "A123456789",
    "shipmentType": "LAST_MILE",
    "consignee": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "dimensions": {
      "depth": 190,
      "height": 100,
      "width": 140
    },
    "weight": 400,
    "allocationType": "HARD_RESERVATION"
  }'

Responses

Parcel event published successfully

Bodyapplication/json
statusstring

The status of the event processing.

Example: "success"
messagestring

A message providing additional information about the event processing.

Example: "Parcel event received and processed successfully"
timestampstring(date-time)

The timestamp when the event was processed.

Example: "2023-06-18T10:45:00Z"
Response
application/json
{
  "status": "success",
  "message": "Parcel event received and processed successfully",
  "timestamp": "2023-06-18T10:45:00Z"
}

Publish parcel data with carrier locker id

Request

This endpoint is an alternative to /parcels/data endpoint and could be used to publish parcel data using carrierLockerId instead of lockerUid.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
eventTypestring(booking_type)required

The type of booking request.

Enum"PRE_CHECK""BOOKING"
carrierLockerIdstringrequired

The unique identifier of the locker in the Carrier Platform.

Example: "LOCKER123"
carrierParcelIdstringrequired

The identifier of the parcel in the carrier's system.

Example: "12345KL6789M"
shipmentTypestring(shipment_type_input)

The possible types of last-mile shipments accepted.

Enum"LAST_MILE""ALTERNATIVE_DELIVERY"
consigneeobject or null(consignee)

The details of the consignee.

dimensionsobject(dimensions)required

The dimensions of the parcel.

dimensions.​depthinteger or null

Depth in mm

Example: 190
dimensions.​heightinteger or null

Height in mm

Example: 100
dimensions.​widthinteger or null

Width in mm

Example: 140
weightinteger

Weight in grams

Example: 300
allocationTypestring(allocation_type)

The allocation type of the shipment.

Enum"HARD_RESERVATION""SOFT_RESERVATION"
curl -i -X POST \
  https://docs.glsnxt.com/_mock/openapi-carrier-integration-api/parcels/data/by-tenant-locker-id \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "eventType": "BOOKING",
    "carrierLockerId": "LOCKER123",
    "carrierParcelId": "12345KL6789M",
    "shipmentType": "LAST_MILE",
    "consignee": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "dimensions": {
      "depth": 190,
      "height": 100,
      "width": 140
    },
    "weight": 300,
    "allocationType": "HARD_RESERVATION"
  }'

Responses

Parcel event published successfully

Bodyapplication/json
statusstring

The status of the event processing.

Example: "success"
messagestring

A message providing additional information about the event processing.

Example: "Parcel event received and processed successfully"
timestampstring(date-time)

The timestamp when the event was processed.

Example: "2023-06-18T10:45:00Z"
Response
application/json
{
  "status": "success",
  "message": "Parcel event received and processed successfully",
  "timestamp": "2023-06-18T10:45:00Z"
}

Get parcels

Request

Retrieve a list of parcels associated with the carrier. This endpoint allows fetching detailed information about parcels, including their status and history.

Security
ApiKeyAuth
Query
idsstringrequired

Comma-separated list of parcel IDs to retrieve

Example: ids=12345131,G6789011,A1234511
curl -i -X GET \
  'https://docs.glsnxt.com/_mock/openapi-carrier-integration-api/parcels?ids=12345131%2CG6789011%2CA1234511' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Parcels fetched successfully

Bodyapplication/jsonArray [
shipmentUidstring

The unique identifier of the parcel shipment in the GLS/NXT Platform

Example: "anyParcelId123"
lockerUidstring

The unique identifier of the locker in the GLS/NXT Platform

Example: "anyLockerId123"
carrierParcelIdstring

The identifier of the parcel in the carrier's system

Example: "anyCarrierParcelId123"
carrierLockerIdstring or null

The identifier of the locker in the carrier's system

Example: "Locker1"
shipmentTypestring(shipment_type)

The type of shipment.

Enum"LAST_MILE""ALTERNATIVE_DELIVERY""FIRST_MILE""RETURN"
dimensionsStatusstring(dimensions_status)

The status of the parcel dimensions.

Enum"PARCEL_DIMENSIONS_EXCEED""PARCEL_DIMENSIONS_OK""PARCEL_DIMENSIONS_UNKNOWN"
shipmentStatusstring(shipment_status)

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"
accessCodesobject or null(access_codes)

Access codes for the parcel

consigneeobject or null(consignee)

The details of the consignee.

eventsArray of objects(parcel_events)
allocationTypestring(allocation_type)

The allocation type of the shipment.

Enum"HARD_RESERVATION""SOFT_RESERVATION"
shipmentSignatureobject(signature)

A Base64-encoded image representing the consignee's signature, captured upon parcel collection

]
Response
application/json
[
  {
    "shipmentUid": "anyParcelId123",
    "lockerUid": "anyLockerId123",
    "carrierParcelId": "anyCarrierParcelId123",
    "carrierLockerId": "Locker1",
    "shipmentType": "LAST_MILE",
    "dimensionsStatus": "PARCEL_DIMENSIONS_OK",
    "shipmentStatus": "BOOKING_PRE_CHECK",
    "accessCodes": { … },
    "consignee": { … },
    "events": [ … ],
    "allocationType": "HARD_RESERVATION",
    "shipmentSignature": { … }
  }
]

Locker Events

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).
Webhooks

Parcel Events

This webhook endpoint is designed to push updates about parcels handling events.

  • Parcel Updates: Get notifications about changes in parcel status.
Webhooks

Collection Events

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.
Webhooks