OMS Aggregator APIs v1.0
1. Token Generation
Overview: Generates an access token required for authenticating subsequent API requests. This endpoint utilizes the Client Credentials Grant Type (OAuth 2.0) for secure server-to-server communication.
- Method: POST
- BaseURL: https://api-copilot-stage-local.xstak.com
- Endpoint: /auth/token (or similar base URL for authentication)
- Authentication: None (This is the authentication endpoint itself)
1.1 Request Body Parameters
1.2 Success Response (200 OK)
Upon successful authentication, the response will contain the access token and its expiration time.
JSON
{
"access_token":
"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJLSUF2WnBVbDdYX1ZUWURxQUhvSU41O
GQtZ1N2Q3psMWVpS0Y0VFdVSUVvIn0.eyJleHAiOjE3NjU5NjgzMDAsImlhdCI6MTc2NTk2ODAw
MCwianRpIjoiNjFlYjVlMzctODZmYi00ODRjLTljZjgtMTY3NzI0OTE1N2NhIiwiaXNzIjoiaHR0cHM6Ly9
rZXljbG9hay1zdGFnZS1sb2NhbC54c3Rhay5jb20vYXV0aC9yZWFsbXMvMjI2YjVjNTM0NzZkYmVhZi
IsImF1ZCI6WyJjb3BpbG90IiwiYWNjb3VudCJdLCJzdWIiOiJkZTU0MWY2NC0xZDNjLTQ2ZjItYjBjYS0z
MzQyMjM2MDZiNzgiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGktdXNlci1wZWlVVWFJdXdlIiwiYWNyI
joiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLTIyNmI1YzUzNDc2ZGJlYWYi
LCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY2
9waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiY
WRkX3VzZXJzIl19LCJhcGktdXNlci1wZWlVVWFJdXdlIjp7InJvbGVzIjpbInVtYV9wcm90ZWN0aW9uIl
19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlu
a3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJlbWFpbF92ZXJpZmll
ZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxOTIuMTY4LjE1Ni4yNTIiLCJjbGllbnRJZCI6ImFwaS11c2VyLX
BlaVVVYUl1d2UiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtYXBpLXVzZXIt
cGVpdXVhaXV3ZSIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjE1Ni4yNTIiLCJlbWFpbCI6ImFwaS11
c2Vyc2hlaHJvb3ouYWhtYWRAcG9zdGV4Z2xvYmFsLmNvbSJ9.l-bOnG3LxQdPx00OJOCiVyEHUw1pfYeA0bt1JiiAphznzshRDGuBqzTDeGWx7FCUAerXynjPdEIFtbAlGOUfNpGehR
V3reU5m-uHQOz_BhVVSqFMqSjzi8tt-faX9x8AZoAAeEvbOyZ4c3MMIDsMvpeZeZHTvXqKpfZe1iTWY3DczRKd1pHYtdBQqGjcHpSn22Oo6PN1dWdv6dpK2M9xA8Bk0MgkFglZ9qdvvcijOXykDWdHea21Ey
pHEvWXh8EZIDEQETqFXdWfQgeb7yCfv30BvlRvY4Hy-mCMQ-MRBKN6e29afulp79H4fFzJfiFHhUUmALLShb88P6HqOA",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "shipments:write shipments:read"
}
Please use the updated API below to generate the access token:
curl --location 'https://api-copilot-stage-local.xstak.com/v1/admin/service-account/token' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "api-user-peiUUaIuwe",
"clientSecret": "PhiVyUF0HG7bLzUeOATb",
"grantType": "client_credentials",
"companyCode": "226b5c53476dbeaf"1.3 Usage Note Use the access_token in the Token header for all protected API calls2. Create Shipment API
Overview:
Creates a new domestic or international shipment in the OMS. It handles comprehensive details like multi-package items, COD, Arabic text, and complex pricing (tax/discount).
- Method: POST
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments
- Authentication: Token (Required)
2.1 Request Body: Required Fields
2.2 shipToInfo / shipFromInfo Object Fields
2.3 packagesInfo Array Item Fields
2.4 Success Response (200 OK)
JSON
{
"code": "200",
"status": "Success",
"message": "Shipment created successfully",
"data": {
"shipmentId": "68CDFD1BDC57C595"
}
}
2.5 Key Error Scenarios
3. Create Return Shipment API
Overview: Initiates a return process for a previously delivered shipment.
- Method: POST
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments/{shipment_id}/return
- Path Parameter: shipment_id (Unique ID of the original shipment)
- Authentication: Token (Required)
3.1 Request Body: Return Fields The request body is nearly identical to the Create Shipment API, with the following mandatory requirements:
- shipToInfo: Details of the destination (Warehouse/Facility receiving the return).
- shipFromInfo: Details of the origin (Customer returning the items).
- shipmentType: Must be set to "RETURN"
3.2 Success Response (200 OK)
JSON
{
"code": "200",
"status": "Success",
"message": "Return shipment created successfully",
"data": {
"shipmentId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
}
}3.3 Key Error Scenarios
4. Cancel Shipment API Overview: Cancels an existing shipment that has not yet been processed (e.g., dispatched or picked up).
- Method: POST
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments/{shipment_id}/cancel
- Path Parameter: shipment_id (Unique ID of the shipment to cancel)
- Request Body: None
- Authentication: Token (Required
4.1 Success Response (202 Accepted)
{
“code”: “202”,
“status”: “Success”,
“message”: “Shipment cancelled successfully”,
“data”: {}
}4.2 Key Error Scenarios
5. Track Shipment by ID API
Overview: Retrieves real-time tracking information, history, and the current status of a shipment.
- Method: GET
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments/{shipment_id}/track
- Path Parameter: shipment_id (Unique ID of the shipment to track)
- Authentication: Token (Required)
5.1 Success Response (200 OK)
JSON
{
"code": "200",
"status": "Success",
"message": "Tracking information fetched successfully",
"data": {
"shipmentStatus": "BOOKED"
}
}5.2 Key Error Scenarios
6. Get Couriers API Overview:
Retrieves a list of available courier IDs configured for the authenticated organization.
- Method: GET
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments/couriers
- Authentication: Token (Required)
6.1 Success Response (200 OK)
JSON
{
"code": "200",
"status": "Success",
"message": "Couriers fetched successfully",
"data": {
"couriers": [
"68e943ba7bd0238e3e98ca5a",
"68e9507cd2dc80652ee581cd"
]
}
7. Get AWB API
Overview:
Retrieves the Air Waybill (AWB) download URL for a specific shipment.
- Method: GET
- BaseURL: https://oe-unc-stage-local.xstak.com/oe/
- Endpoint: /aggtr/api/v1/shipments/{shipment_id}/awb
- Path Parameter: shipment_id (Unique ID of the shipment)
- Authentication: Token (Required)
7.1 Success Response (200 OK)
JSON
{
“code”: “200”,
“status”: “Success”,
Page 16 of 17
“message”: “AWB URL fetched successfully”,
“data”: {
“awbUrl”: “https://example.com/orders/.../download/SingleOrderFileAndDispatchNote”
}
}7.2 Key Error Scenarios
Common Error Response Structure All error responses across the APIs use a consistent JSON format:
JSON
{
"errorCode": "400",
"errorMessage": "Validation failed: name is required",
Page 17 of 17
"errorStatus": "Error",
"userMessage": "Validation failed: name is required"
}