# GLS/NXT OOH Platform Integration REST API

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.


Version: 1.1.0

## Servers

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

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

## Security

### ApiKeyAuth

API Authorization Key for API access

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[GLS/NXT OOH Platform Integration REST API](https://docs.glsnxt.com/_spec/openapi-carrier-integration-api.yaml)

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


### Create a new locker

 - [POST /lockers](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-api/createlocker.md): Create a new locker with the specified details for the carrier, provider, location, and features.

### Get a list of lockers

 - [GET /lockers](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-api/listlockers.md): Retrieve a list of lockers with optional filters such as location, status, carrier, and provider.

### Update a locker

 - [PATCH /lockers/{uid}](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-api/updatelocker.md): Update the details of an existing locker, including carrier details, provider details, location, and features.

### Get a list of existing locker model and locker version pairs for provider

 - [GET /lockers/providers](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-api/listlockerproviders.md): Retrieve a list of existing locker model and locker version pairs for each provider.

### Update Locker Status

 - [PATCH /lockers/status](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-api/updatelockerstatus.md): Update the status of an existing locker.

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


### Publish parcel data

 - [POST /parcels/data](https://docs.glsnxt.com/openapi-carrier-integration-api/parcel-api/publishparceldata.md): 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 with carrier locker id

 - [POST /parcels/data/by-tenant-locker-id](https://docs.glsnxt.com/openapi-carrier-integration-api/parcel-api/publishparceldatabytenantid.md): This endpoint is an alternative to  endpoint and could be used to publish parcel data using carrierLockerId instead of lockerUid.


### Get parcels

 - [GET /parcels](https://docs.glsnxt.com/openapi-carrier-integration-api/parcel-api/getparcels.md): Retrieve a list of parcels associated with the carrier. This endpoint allows fetching detailed information about parcels, including their status and history.


### Cancel parcel

 - [PATCH /parcels/{parcelId}](https://docs.glsnxt.com/openapi-carrier-integration-api/parcel-api/cancelparcel.md): 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.


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


### Webhook for locker updates

 - [POST LockerUpdates](https://docs.glsnxt.com/openapi-carrier-integration-api/locker-events/webhooklockerupdates.md): Webhook to push locker updates to any URL provided by the carrier. This endpoint allows carriers to receive 
real-time updates about lockers.


## Parcel Events

This webhook endpoint is designed to push updates about parcels handling events.
- **Parcel Updates**: Get notifications about changes in parcel status.


### Webhook for parcel updates

 - [POST ParcelUpdates](https://docs.glsnxt.com/openapi-carrier-integration-api/parcel-events/webhookparcelupdates.md): Webhook to push parcel updates to any URL provided by the carrier. This endpoint allows carriers to receive 
real-time updates about parcels.


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


### Webhook for pickup notifications

 - [POST CollectionNotification](https://docs.glsnxt.com/openapi-carrier-integration-api/collection-events/webhookcollectionnotifications.md): 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.