Locker Provider API

Download schema

Operations that a locker provider calls: validation before a locker accepts a parcel or opens a compartment, and label printing. Carriers do not call these operations.

For locker providers

Base URL: https://api.glsnxt.com/ooh/provider-connector (staging: https://api.staging.glsnxt.com/ooh/provider-connector). Authenticate with your provider API key in the X-API-Key header. Each operation is enabled for each provider separately. A key that cannot use an operation gets 401.

For a validation, the platform does not decide the answer itself. It asks the carrier that owns the parcel and returns the result. When the answer is not a success status, the locker must not accept the parcel and must not open the compartment.

Validate a first-mile deposit

POST

https://api.staging.glsnxt.com/ooh/provider-connector

/api/validate/first-mile

The locker calls this operation before it accepts a parcel that a sender wants to drop off. The platform asks the carrier if the parcel is known and can be deposited.

200 means the locker can accept the parcel. 422 means the locker must refuse the parcel. For any other status, the check did not complete and the locker must not accept the parcel. The call changes no state, so it is safe to send it again.

Validate a first-mile deposit › Request Body

provider_validation_request

lockerId

string · required

The ID of the locker in the provider's system.

provider_validation_identification · required

The value the sender or courier entered or scanned at the locker.

provider_validation_network · required

The locker network the locker belongs to.

Validate a first-mile deposit › Responses

The parcel can be deposited.

provider_first_mile_validation_response

isEligible

boolean · required

Always true in this response.

isLabelless

boolean · required

true when the parcel has no label and the locker must handle it as a labelless parcel.

reservationId

string · required

The carrier's reference for this deposit.

parcelNumber

string · required

barcode

string · required

provider_validation_contact · required

provider_first_mile_dimensions · required

The size and weight of the parcel. A value is absent when it is not known.

POST/api/validate/first-mile

curl https://api.staging.glsnxt.com/ooh/provider-connector/api/validate/first-mile \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "lockerId": "LOCKER-SI-001",
  "identification": {
    "identificationType": "ParcelNumber",
    "value": "12345678901"
  },
  "network": {
    "operator": "GLS",
    "region": "SI"
  }
}'

Example Request Body

{
  "lockerId": "LOCKER-SI-001",
  "identification": {
    "identificationType": "ParcelNumber",
    "value": "12345678901"
  },
  "network": {
    "operator": "GLS",
    "region": "SI"
  }
}

json

Example Responses

{
  "isEligible": true,
  "isLabelless": false,
  "reservationId": "68754444",
  "parcelNumber": "120230340",
  "barcode": "001202303404",
  "consignee": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+38640123456"
  },
  "sender": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+38640123456"
  },
  "dimensions": {
    "widthInCm": 12,
    "heightInCm": 11,
    "depthInCm": 10,
    "weightInKg": 0.6
  }
}

json

application/json

Validate a last-mile deposit

POST

https://api.staging.glsnxt.com/ooh/provider-connector

/api/validate/last-mile

The locker calls this operation before it accepts a parcel that a courier wants to deliver. The platform asks the carrier if the parcel is known and can be deposited.

Validate a last-mile deposit › Request Body

provider_validation_request

lockerId

string · required

The ID of the locker in the provider's system.

provider_validation_identification · required

The value the sender or courier entered or scanned at the locker.

provider_validation_network · required

The locker network the locker belongs to.

Validate a last-mile deposit › Responses

The parcel can be deposited.

provider_last_mile_validation_response

isEligible

boolean · required

Always true in this response.

object · required

parcelNumber

string · required

barcode

string · required

object · required

The size of the parcel. A value is absent when it is not known.

recipientName

string

Absent when it is not known.

recipientEmail

string

Absent when it is not known.

recipientPhone

string

Absent when it is not known.

object

Present only for a cash-on-delivery parcel. It reports the payment the recipient must make. It does not create the cash-on-delivery amount on the platform.

POST/api/validate/last-mile

curl https://api.staging.glsnxt.com/ooh/provider-connector/api/validate/last-mile \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "lockerId": "LOCKER-SI-001",
  "identification": {
    "identificationType": "ParcelNumber",
    "value": "12345678901"
  },
  "network": {
    "operator": "GLS",
    "region": "SI"
  }
}'

Example Request Body

{
  "lockerId": "LOCKER-SI-001",
  "identification": {
    "identificationType": "ParcelNumber",
    "value": "12345678901"
  },
  "network": {
    "operator": "GLS",
    "region": "SI"
  }
}

json

Example Responses

{
  "isEligible": true,
  "reservation": {
    "reservationId": "68754444",
    "expiresAtUtc": "2026-07-23T23:59:59.999999Z"
  },
  "parcelNumber": "120230340",
  "barcode": "001202303404",
  "recipient": {
    "pin": "123456"
  },
  "recipientName": "Jane Doe",
  "recipientEmail": "[email protected]",
  "recipientPhone": "+38640123456",
  "dimensions": {
    "widthCm": 12,
    "heightCm": 11,
    "depthCm": 10
  },
  "cod": {
    "isPaymentRequiredToUnlock": true,
    "paymentDetails": {
      "amount": 24.9,
      "currency": "EUR",
      "reference": "8107554962"
    }
  }
}

json

application/json

Validate a labelless reference code

POST

https://api.staging.glsnxt.com/ooh/provider-connector

/api/validate/reference-code

The locker calls this operation after the driver scans a mini label, and before it opens the compartment that holds a labelless parcel. The platform checks if this carrier already used the reference code.

Only 202 permits the locker to open the compartment. On 409, the locker must show an error and ask the driver for another label. For any other status, the check did not complete and the compartment must stay closed. This includes 500 and a timeout.

Every response has an empty body. The call changes no state, so it is safe to send it again.

Validate a labelless reference code › Request Body

provider_reference_code_validation_request

carrierName

string · required

The platform name of the carrier the locker serves, as in the locker configuration. A reference code is unique for each carrier, so another carrier can use the same code.

referenceCode

string · required

The code on the mini label, exactly as scanned. The platform compares the full text, so remove any scanner prefix, suffix or white space before you send it.

Validate a labelless reference code › Responses

This carrier did not use the reference code before. The locker can open the compartment.

No data returned

Get a label PDF

POST

https://api.staging.glsnxt.com/ooh/provider-connector

/api/labels

The locker calls this operation to print a label for a parcel. The platform renders the QR code content into a label PDF of the requested size.

The call changes no state, so it is safe to send it again.

Get a label PDF › Request Body

provider_label_request

labelSize

string · enum · required

The label size in inches.

Enum values:

4x3

4x6

qrCodeContent

string · required

The QR code content exactly as the locker received it for the parcel. The platform prints it on the label without changes.

Get a label PDF › Responses

The label PDF.

string · binary

Locker Events