GLS/NXT OOH Platform Integration REST API

Parcel API

Server

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.

Publish parcel data

POST

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

/parcels/data

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.

Publish parcel data › Request Body

If you send `consignee`, send both `name` and `email` as strings, and no other fields. The platform rejects a consignee with a missing, null or unknown field.

input_data

eventType

booking_type · enum · required

The type of booking request.

Enum values:

PRE_CHECK

BOOKING

lockerUid

string · required

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

carrierParcelId

string · required

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

dimensions · required

The dimensions of the parcel. A missing field counts as unknown, and the platform uses 10 mm for it.

shipmentType

shipment_type_input · enum

The possible types of last-mile shipments accepted. Defaults to LAST_MILE when not present.

Enum values:

LAST_MILE

ALTERNATIVE_DELIVERY

consignee

consignee

The details of the consignee.

weight

integer

Weight in grams

allocationType

allocation_type · enum

The allocation type of the shipment.

Enum values:

HARD_RESERVATION

SOFT_RESERVATION

requiresAccessibleCompartment

boolean

Indicates whether the parcel requires an accessible compartment. Defaults to false when not present or null.

Default: false

secondaryShipmentId

string

A secondary identifier for the shipment, separate from carrierParcelId.

codAmount

integer · int64

Cash-on-delivery amount to collect, expressed in minor units (e.g. cents).

codCurrency

string

ISO 4217 currency code for codAmount.

lockStatus

string · enum

The lock state to apply to the parcel on booking. LOCKED blocks the consignee from collecting the parcel; UNLOCKED releases it for collection.

Enum values:

LOCKED

UNLOCKED

Publish parcel data › Responses

Parcel event published successfully

input_data_response

status

string · required

The status of the event processing.

message

string · required

A message providing additional information about the event processing.

timestamp

string · date-time · required

The timestamp when the event was processed.

POST/parcels/data

curl https://api.staging.glsnxt.com/ooh/carrier-connector/v1/parcels/data \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "eventType": "BOOKING",
  "lockerUid": "locker_567890",
  "carrierParcelId": "A123456789",
  "shipmentType": "LAST_MILE",
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "dimensions": {
    "depth": 190,
    "height": 100,
    "width": 140
  },
  "weight": 400,
  "allocationType": "HARD_RESERVATION",
  "requiresAccessibleCompartment": false,
  "secondaryShipmentId": "EXP-CODE-0001",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "lockStatus": "LOCKED"
}'

Example Request Body

{
  "eventType": "BOOKING",
  "lockerUid": "locker_567890",
  "carrierParcelId": "A123456789",
  "shipmentType": "LAST_MILE",
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "dimensions": {
    "depth": 190,
    "height": 100,
    "width": 140
  },
  "weight": 400,
  "allocationType": "HARD_RESERVATION",
  "requiresAccessibleCompartment": false,
  "secondaryShipmentId": "EXP-CODE-0001",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "lockStatus": "LOCKED"
}

json

Example Responses

{
  "status": "success",
  "message": "Parcel event received and processed successfully.",
  "timestamp": "2023-06-18T10:45:00Z"
}

json

application/json

Publish parcel data with carrier locker id

POST

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

/parcels/data/by-tenant-locker-id

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

Publish parcel data with carrier locker id › Request Body

If you send `consignee`, send both `name` and `email` as strings, and no other fields. The platform rejects a consignee with a missing, null or unknown field.

input_data_carrier_specific

eventType

booking_type · enum · required

The type of booking request.

Enum values:

PRE_CHECK

BOOKING

carrierLockerId

string · required

The unique identifier of the locker in the Carrier Platform.

carrierParcelId

string · required

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

dimensions · required

The dimensions of the parcel. A missing field counts as unknown, and the platform uses 10 mm for it.

shipmentType

shipment_type_input · enum

The possible types of last-mile shipments accepted. Defaults to LAST_MILE when not present.

Enum values:

LAST_MILE

ALTERNATIVE_DELIVERY

consignee

consignee

The details of the consignee.

weight

integer

Weight in grams

allocationType

allocation_type · enum

The allocation type of the shipment.

Enum values:

HARD_RESERVATION

SOFT_RESERVATION

requiresAccessibleCompartment

boolean

Indicates whether the parcel requires an accessible compartment. Defaults to false when not present or null.

Default: false

secondaryShipmentId

string

A secondary identifier for the shipment, separate from carrierParcelId.

codAmount

integer · int64

Cash-on-delivery amount to collect, expressed in minor units (e.g. cents).

codCurrency

string

ISO 4217 currency code for codAmount.

lockStatus

string · enum

The lock state to apply to the parcel on booking. LOCKED blocks the consignee from collecting the parcel; UNLOCKED releases it for collection.

Enum values:

LOCKED

UNLOCKED

Publish parcel data with carrier locker id › Responses

Parcel event published successfully

input_data_response

status

string · required

The status of the event processing.

message

string · required

A message providing additional information about the event processing.

timestamp

string · date-time · required

The timestamp when the event was processed.

POST/parcels/data/by-tenant-locker-id

curl https://api.staging.glsnxt.com/ooh/carrier-connector/v1/parcels/data/by-tenant-locker-id \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "eventType": "BOOKING",
  "carrierLockerId": "LOCKER123",
  "carrierParcelId": "12345KL6789M",
  "shipmentType": "LAST_MILE",
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "dimensions": {
    "depth": 190,
    "height": 100,
    "width": 140
  },
  "weight": 300,
  "allocationType": "HARD_RESERVATION",
  "requiresAccessibleCompartment": false,
  "secondaryShipmentId": "EXP-CODE-0001",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "lockStatus": "LOCKED"
}'

Example Request Body

{
  "eventType": "BOOKING",
  "carrierLockerId": "LOCKER123",
  "carrierParcelId": "12345KL6789M",
  "shipmentType": "LAST_MILE",
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "dimensions": {
    "depth": 190,
    "height": 100,
    "width": 140
  },
  "weight": 300,
  "allocationType": "HARD_RESERVATION",
  "requiresAccessibleCompartment": false,
  "secondaryShipmentId": "EXP-CODE-0001",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "lockStatus": "LOCKED"
}

json

Example Responses

{
  "status": "success",
  "message": "Parcel event received and processed successfully.",
  "timestamp": "2023-06-18T10:45:00Z"
}

json

application/json

Get parcels

GET

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

/parcels

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

Get parcels › query Parameters

ids

string · required

Comma-separated list of parcel IDs to retrieve

Get parcels › Responses

Parcels fetched successfully. The list is empty when the carrier has no parcel with these IDs.

parcel_response[]

List of parcels

parcel_response

shipmentUid

string · required

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

lockerUid

string · required

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

carrierParcelId

string · required

The identifier of the parcel in the carrier's system

dimensionsStatus

dimensions_status · enum · required

The status of the parcel dimensions. The parcel API sends PARCEL_DIMENSIONS_EXCEEDED for a parcel that is too big; webhooks send PARCEL_DIMENSIONS_EXCEED.

Enum values:

PARCEL_DIMENSIONS_EXCEED

PARCEL_DIMENSIONS_EXCEEDED

PARCEL_DIMENSIONS_OK

PARCEL_DIMENSIONS_UNKNOWN

shipmentStatus

shipment_status · enum · required

The status of the shipment. LOCKED, UNLOCKED and CONSIGNEE_PAID are milestones in a parcel's events; they are never the parcel's shipmentStatus.

Enum values:

BOOKING_PRE_CHECK

BOOKING_REQUESTED

BOOKING_CREATED

BOOKING_CANCELLED

BOOKING_CANCELLATION_FAILED

BOOKING_EXPIRED

BOOKING_REJECTED_INVALID_LOCKER

BOOKING_REJECTED_PROVIDER_ERROR

isFinal

boolean · required

consignee

consignee · required

The details of the consignee.

requiresAccessibleCompartment

boolean · required

carrierLockerId

string | null

The identifier of the locker in the carrier's system

The type of shipment. null when the platform received no shipment type for the parcel.

accessCodes

access_codes

Access codes for the parcel

object[]

The allocation type of the shipment. null when the platform received no allocation type for the parcel.

providerName

string | null

The name of the locker network provider

providerLockerId

string | null

The identifier of the locker in the provider's system

shipmentSignature

signature

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

labelType

string | null · enum

Label mode for the shipment. LABELLESS means no printed label is used and LABELED means a printed label is used.

Enum values:

LABELLESS

LABELED

referenceCode

string | null

Reference code scanned by driver during pickup of the labelless parcel. This field is only relevant for LABELLESS shipments.

secondaryShipmentId

string | null

A secondary identifier for the shipment, separate from carrierParcelId.

paymentStatus

string | null · enum

The current cash-on-delivery payment status for the shipment, when applicable. Absent when the shipment carries no CoD payment.

Enum values:

EXPECTED

PAID

FAILED

codAmount

integer | null · int64

Cash-on-delivery amount to collect, expressed in minor units (e.g. cents). Absent when the shipment carries no CoD payment.

codCurrency

string | null

ISO 4217 currency code for codAmount. Absent when the shipment carries no CoD payment.

paymentType

string | null · enum

The payment method used for a cash-on-delivery parcel, as reported by the locker provider. Absent when the shipment carries no CoD payment.

Enum values:

CARD

FLIK

lockStatus

string | null · enum

The current provider lock state of the parcel, when known. LOCKED means the consignee cannot collect the parcel (e.g. a cash-on-delivery payment is still pending); UNLOCKED means it can be collected. Absent when the parcel carries no lock state.

Enum values:

LOCKED

UNLOCKED

GET/parcels

curl 'https://api.staging.glsnxt.com/ooh/carrier-connector/v1/parcels?ids=<string>' \
  --header 'X-API-Key: <api-key>'

Example Responses

[
  {
    "shipmentUid": "anyParcelId123",
    "lockerUid": "anyLockerId123",
    "carrierParcelId": "anyCarrierParcelId123",
    "carrierLockerId": "Locker1",
    "shipmentType": "LAST_MILE",
    "dimensionsStatus": "PARCEL_DIMENSIONS_OK",
    "shipmentStatus": "CONSIGNEE_COLLECTED",
    "isFinal": true,
    "accessCodes": {
      "consigneeCollection": "anyValidCode123",
      "consigneeCollectionCode": {
        "code": "anyValidCode123",
        "validUntil": "2025-01-27T12:00:00Z"
      }
    },
    "consignee": {
      "name": "John Doe",
      "email": "john.doe@google.com"
    },
    "events": [
      {
        "timestamp": "2025-08-20T00:00:00Z",
        "eventType": "CONSIGNEE_COLLECTED"
      }
    ],
    "allocationType": "HARD_RESERVATION",
    "providerName": "LOCKY_PT",
    "providerLockerId": "1178",
    "shipmentSignature": {
      "imageBase64": "imageBase64StringHere",
      "format": ""
    },
    "requiresAccessibleCompartment": true,
    "labelType": "LABELLESS",
    "referenceCode": "LBL000000018",
    "secondaryShipmentId": "EXP-CODE-0001",
    "paymentStatus": "PAID",
    "codAmount": 2450,
    "codCurrency": "EUR",
    "paymentType": "CARD",
    "lockStatus": "LOCKED",
    "signature": {
      "imageBase64": "imageBase64StringHere",
      "format": ""
    }
  }
]

json

application/json

Get parcels (v2)

GET

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

/v2/parcels

Retrieve a paginated list of parcels associated with the carrier, filterable by locker and/or parcel IDs.

At least one of lockerId, carrierLockerId or ids must be provided.
When more than one filter is given, the result is the intersection of all provided filters.
By default this endpoint returns parcels regardless of status — both active bookings and completed/final parcels linked to the locker. Pass isFinal to narrow the result to open (false) or finalized (true) parcels.
The platform does not page deeper than 10000 parcels. When (page - 1) * pageSize is more than 10000, the response is 422. Use more filters instead.

Get parcels (v2) › query Parameters

lockerId

string

The platform locker UID to filter by. At least one of lockerId, carrierLockerId or ids is required.

carrierLockerId

string

The carrier's own locker identifier to filter by. At least one of lockerId, carrierLockerId or ids is required.

ids

string

Comma-separated list of parcel IDs to filter by. At least one of lockerId, carrierLockerId or ids is required.

isFinal

boolean

Optional finality filter. When omitted, no status filter is applied (all statuses). true returns only finalized parcels, false returns only open ones. Must be lowercase true or false.

page

integer · int32 · min: 1

The page number to retrieve (1-based).

Default: 1

pageSize

integer · int32 · min: 1 · max: 100

The number of items per page. Maximum 100.

Default: 30

Get parcels (v2) › Responses

Parcels fetched successfully

A paginated list of parcels.

parcel_page

parcel_response[] · required

The list of parcels for the current page.

pageNumber

integer · int32 · required

The current page number (1-based).

pageSize

integer · int32 · required

The number of items per page.

isLast

boolean · required

Whether this is the last page.

GET/v2/parcels

curl https://api.staging.glsnxt.com/ooh/carrier-connector/v1/v2/parcels \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "content": [
    {
      "shipmentUid": "anyParcelId123",
      "lockerUid": "anyLockerId123",
      "carrierParcelId": "anyCarrierParcelId123",
      "carrierLockerId": "Locker1",
      "shipmentType": "LAST_MILE",
      "dimensionsStatus": "PARCEL_DIMENSIONS_OK",
      "shipmentStatus": "CONSIGNEE_COLLECTED",
      "isFinal": true,
      "accessCodes": {
        "consigneeCollection": "anyValidCode123",
        "consigneeCollectionCode": {
          "code": "anyValidCode123",
          "validUntil": "2025-01-27T12:00:00Z"
        }
      },
      "consignee": {
        "name": "John Doe",
        "email": "john.doe@google.com"
      },
      "events": [
        {
          "timestamp": "2025-08-20T00:00:00Z",
          "eventType": "CONSIGNEE_COLLECTED"
        }
      ],
      "allocationType": "HARD_RESERVATION",
      "providerName": "LOCKY_PT",
      "providerLockerId": "1178",
      "shipmentSignature": {
        "imageBase64": "imageBase64StringHere",
        "format": ""
      },
      "requiresAccessibleCompartment": true,
      "labelType": "LABELLESS",
      "referenceCode": "LBL000000018",
      "secondaryShipmentId": "EXP-CODE-0001",
      "paymentStatus": "PAID",
      "codAmount": 2450,
      "codCurrency": "EUR",
      "paymentType": "CARD",
      "lockStatus": "LOCKED",
      "signature": {
        "imageBase64": "imageBase64StringHere",
        "format": ""
      }
    }
  ],
  "pageNumber": 1,
  "pageSize": 30,
  "isLast": true
}

json

application/json

Cancel parcel

PATCH

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

/parcels/{parcelId}

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.

When the locker provider rejects the cancellation, the response has the provider's HTTP status code and an sma_error body.

Cancel parcel › path Parameters

parcelId

string · required

The parcel ID to be cancelled

Cancel parcel › Responses

Parcel cancelled successfully

No data returned

Lock or unlock a parcel

PATCH

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

/parcels/{parcelId}/lock

Lock or unlock a parcel in its locker compartment. Locking prevents the consignee from collecting the parcel — for example while a cash-on-delivery payment is still pending — and unlocking releases it for collection. The carrier is identified by the API key.

Parcel locking must be enabled for the carrier; otherwise the response is 422. When the locker provider rejects the request, the response has the provider's HTTP status code and an sma_error body.

Lock or unlock a parcel › path Parameters

parcelId

string · required

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

Lock or unlock a parcel › Request Body

parcel_lock_request

status

string · enum · required

The lock state to apply. LOCKED blocks the consignee from collecting the parcel; UNLOCKED releases it for collection.

Enum values:

LOCKED

UNLOCKED

reason

string · enum

Why the parcel is being locked. Optional. On LOCKED it defaults to CASH_ON_DELIVERY when omitted. On UNLOCKED it is ignored — the parcel's original lock reason determines how it is released.

Enum values:

CASH_ON_DELIVERY

POLICE_HOLD

OTHER

Lock or unlock a parcel › Responses

Lock state updated successfully.

No data returned

Network API