Aggregator APIs Postman Collection
javascript
{
"info": {
"_postman_id": "f05f5d58-7c33-4c15-ae0f-9d52f56b7e71",
"name": "Shipment Management APIs",
"description": "Complete collection for Shipment Management APIs including create, return, cancel, track, get couriers, and get AWB endpoints. See API_DOCUMENTATION_SHIPMENT_MANAGEMENT.md for detailed documentation.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "19110390"
},
"item": [
{
"name": "Create Shipment",
"request": {
"method": "POST",
"header": [
{
"key": "Token",
"value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKallMbzhWRnZNZlhBcmpHbzA0X2NMNEtKRjFpT2dvLWhzanVhaENKZFJZIn0.eyJleHAiOjE3NjkwOTk2NjQsImlhdCI6MTc2OTA5OTM2NCwianRpIjoiY2I5YTZjOTMtOWY4OS00MWU2LWE1MDctNjBiM2RhMTQxOWM0IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1saXZlLnhzdGFrLmNvbS9hdXRoL3JlYWxtcy83Nzc2OTllYzdkYzNiZDdjIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjRlZjRiM2U5LTYxY2MtNDI3NS1hZTFiLWRiODg4YzQwZmIxYyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNvcGlsb3QiLCJzZXNzaW9uX3N0YXRlIjoiM2MwNmU5YjQtYzk0Ny00YTk1LWFkYWYtNzI5MDE2NmI5NDlmIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJsb2dpc3RpY3MtYWRtaW4iLCJkZWZhdWx0LXJvbGVzLTc3NzY5OWVjN2RjM2JkN2MiLCJvZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ4c3Rhay1jb3BpbG90LWFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiYWRkX3VzZXJzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIzYzA2ZTliNC1jOTQ3LTRhOTUtYWRhZi03MjkwMTY2Yjk0OWYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJPbW5pZnVsICAiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzaGVocm9vei5haG1hZEBwb3N0ZXhnbG9iYWwuY29tIiwiZ2l2ZW5fbmFtZSI6Ik9tbmlmdWwiLCJmYW1pbHlfbmFtZSI6IiAiLCJlbWFpbCI6InNoZWhyb296LmFobWFkQHBvc3RleGdsb2JhbC5jb20ifQ.KoDyy0DqMOfH42Hz0uGydmXEXc7V35fyi8A0eWd6bqAeGKam5DrGidamG-yb4QB_A5WgPn7T5IKUHAyJhIKVS3Rk5mVLcMLMnGfKtxLhCwgw3ExmXXSu-uXd1ysxUXo87EvnglZQ9sjLoEk2aUJEwT7QSzm-KVMaxqF4pQCVRYB0eh9E1ViL_0GftIRxWrE5NmbCVn4T6I1S-Yi9eunTCB3Tk22Q2d5gYW8K-fimietwmZ0O8A5RkoocRlJ2dsgL11d2U5dNYH4LuCOllgemjWrvaciwdY0oQYTfJ6PacdMwON4pb7AJRWYk4dThjpLSqr3td3LAWIjpKCAPkGtwhw",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"shipToInfo\": {\n \"name\": \"عبدالله سالم\",\n \"email\": \"haris.islam@xstak.com\",\n \"phone\": \"+966501234558\",\n \"country\": \"Saudi Arabia\",\n \"postalCode\": \"54000\",\n \"address\": \"جدة حي الصفاء شارع عبدالله بن سهل, Al Wazeeriyah\",\n \"city\": \"Medina\",\n \"shippingArea\": \"Al Wazeeriyah\",\n \"longitude\": \"46.6753\",\n \"latitude\": \"24.7136\"\n },\n \"shipFromInfo\": {\n \"name\": \"OI-warehouse\",\n \"email\": \"shehrooz.ahmad@postexglobal.com\",\n \"phone\": \"+96692320433738\",\n \"country\": \"Saudi Arabia\",\n \"postalCode\": \"5033\",\n \"address\": \"warehouse\",\n \"city\": \"Medina\",\n \"shippingArea\": \"\",\n \"longitude\": \"55.2708\",\n \"latitude\": \"25.2048\"\n },\n \"packagesInfo\": [\n {\n \"name\": \"Black Men Chappal GL-1523\",\n \"sku\": \"abcd100\",\n \"quantity\": 1,\n \"hsCode\": \"ABC100\",\n \"unitPrice\": \"2000.0\",\n \"totalPrice\": \"2000.0\",\n \"originalPrice\": \"2000.0\",\n \"weight\": {\n \"unit\": \"kg\",\n \"value\": 1.5\n },\n \"discount\": {\n \"discountPercentage\": \"10%\",\n \"discountAmount\": \"200.0\"\n },\n \"tax\": {\n \"taxPercentage\": \"15%\",\n \"taxAmount\": \"300.0\"\n },\n \"productImage\": \"https://cdn.shopify.com/s/files/1/0568/3308/1529/products/E04919-MG0-1.jpg\"\n }\n ],\n \"dimension\": {\n \"height\": 10.5,\n \"width\": 20.0,\n \"length\": 30.0,\n \"unit\": \"cm\"\n },\n \"shipmentAmount\": \"123\",\n \"shipmentCodAmount\": \"123\",\n \"shipmentCurrency\": \"SAR\",\n \"shipmentNumber\": \"SHIP-1234567\",\n \"paymentMethod\": \"Cash On Delivery\",\n \"courierId\": \"\",\n \"serviceType\": \"standard\",\n \"remarks\": \"Handle with care\",\n \"numberOFBoxes\": \"2\",\n \"shipmentType\": \"SHIPMENT\",\n \"customerNationalAddress\": \"DMWA6963\",\n \"customerNationalId\": \"\",\n \"customerNationalIdType\": \"ID\",\n \"otherInfo\": {\n \"giftAmount\": \"100.0\",\n \"content_type\": \"electronics\",\n \"specialInstructions\": \"Fragile items\"\n }\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.oms.postex.sa/oe/aggtr/api/v1/shipments",
"protocol": "https",
"host": [
"api",
"oms",
"postex",
"sa"
],
"path": [
"oe",
"aggtr",
"api",
"v1",
"shipments"
]
},
"description": "# Create Shipment\n\nThis endpoint creates a new shipment in the Order Management System (OMS). It accepts comprehensive shipment details including sender/recipient information, package details, dimensions, and delivery preferences.\n\n## Overview\n\nUse this API to create shipments for order fulfillment. The endpoint supports:\n\n- Domestic and international shipments\n \n- Multiple package items in a single shipment\n \n- Cash on Delivery (COD) and other payment methods\n \n- Arabic text in customer names and addresses\n \n- Flexible courier and service type selection\n \n- Tax and discount calculations per item\n \n\n## Request Structure\n\n### **REQUIRED FIELDS**\n\n#### shipToInfo (Recipient Details)\n\n- `name` - Recipient's full name (supports Arabic characters, e.g., \"عبدالله سالم\")\n \n- `email` - Recipient's email address\n \n- `phone` - Recipient's phone number (with country code, e.g., \"+966501234558\")\n \n- `country` - Destination country\n \n- `address` - Full delivery address (supports Arabic text)\n \n- `city` - Destination city\n \n\n#### shipFromInfo (Sender/Warehouse Details)\n\n- `name` - Sender or warehouse name\n \n- `email` - Sender's email address\n \n- `phone` - Sender's phone number (with country code)\n \n- `country` - Origin country\n \n- `address` - Full pickup/warehouse address\n \n- `city` - Origin city\n \n\n#### packagesInfo (Array of Package Items)\n\nEach item in the array must include:\n\n- `name` - Product name/description\n \n- `quantity` - Number of units\n \n- `unitPrice` - Price per unit (as string, e.g., \"2000.0\")\n \n- `totalPrice` - Total price for this item (as string)\n \n- `originalPrice` - Original price before discounts (as string)\n \n- `weight` - Object containing:\n \n - `unit` - Weight unit (e.g., \"kg\")\n \n - `value` - Weight value (numeric)\n \n\n#### dimension (Package Dimensions)\n\n- `height` - Package height (numeric)\n \n- `width` - Package width (numeric)\n \n- `length` - Package length (numeric)\n \n- `unit` - Dimension unit (e.g., \"cm\")\n \n\n#### Other Required Fields\n\n- `shipmentNumber` - Unique shipment identifier\n \n- `paymentMethod` - Payment method (e.g., \"Cash On Delivery\")\n \n- `courierId` - ID of the courier service\n \n- `serviceType` - Service level (e.g., \"standard\")\n \n\n### **OPTIONAL FIELDS**\n\n- `postalCode` - Postal/ZIP code for sender and recipient\n \n- `shippingArea` - Specific area within the city\n \n- `longitude` / `latitude` - Geographic coordinates\n \n- `sku` - Stock Keeping Unit for products\n \n- `discount` - Discount details (percentage and amount)\n \n- `tax` - Tax details (percentage and amount)\n \n- `productImage` - URL to product image\n \n- `remarks` - Special handling instructions\n \n- `numberOFBoxes` - Number of boxes in shipment\n \n- `shipmentType` - Type of shipment (default: \"SHIPMENT\")\n \n- `customerNationalAddress` - National address format\n \n- `customerNationalId` - National ID number\n \n- `customerNationalIdType` - Type of ID document\n \n- `otherInfo` - Additional information object containing:\n \n - `giftAmount` - Gift value\n \n - `content_type` - Content category\n \n - `specialInstructions` - Additional handling notes\n \n\n---\n\n## Response Formats\n\n### **Success Response (200 OK)**\n\nWhen a shipment is successfully created, the API returns:\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"Shipment created successfully\",\n \"data\": {\n \"shipmentId\": \"68CDFD1BDC57C595\"\n }\n}\n\n ```\n\n**Response Fields:**\n\n- `code` - HTTP status code as string\n \n- `status` - Operation status (\"Success\")\n \n- `message` - Human-readable success message\n \n- `data.shipmentId` - Unique identifier for the created shipment (use this for tracking and updates)\n \n\n---\n\n## Error Scenarios\n\nThe API may return the following error responses:\n\n### **400 Bad Request - Validation Error**\n\nReturned when required fields are missing or invalid data is provided.\n\n``` json\n{\n \"errorCode\": \"400\",\n \"errorMessage\": \"Validation failed: name is required\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Validation failed: name is required\"\n}\n\n ```\n\n**Common validation errors:**\n\n- Missing required fields (name, email, phone, address, etc.)\n \n- Invalid email format\n \n- Invalid phone number format\n \n- Missing or invalid weight/dimension values\n \n- Invalid price formats\n \n\n---\n\n### **406 Not Acceptable - Shipment Number Already Exists**\n\nReturned when attempting to create a shipment with a duplicate shipment number.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Shipment number already exist\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"This shipment number already exists. Please use a different shipment number.\"\n}\n\n ```\n\n**Resolution:** Generate a new unique shipment number and retry the request.\n\n---\n\n### **406 Not Acceptable - Invalid Request**\n\nReturned when the request structure is malformed or contains invalid data combinations.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Invalid request\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid request\"\n}\n\n ```\n\n**Common causes:**\n\n- Invalid courier ID\n \n- Unsupported service type\n \n- Invalid country or city names\n \n- Malformed JSON structure\n \n\n---\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### **403 Forbidden - Insufficient Permissions**\n\nReturned when the authenticated user does not have permission to create shipments.\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Insufficient permissions to create shipments\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have the required permissions to create shipments. Please contact your administrator.\"\n}\n\n ```\n\n**Resolution:** Contact your system administrator to request the necessary permissions for shipment creation.\n\n---\n\n## Best Practices\n\n1. **Unique Shipment Numbers:** Always generate unique shipment numbers to avoid 406 errors\n \n2. **Validate Before Sending:** Validate all required fields client-side before making the API call\n \n3. **Token Management:** Implement token refresh logic to handle expired tokens gracefully\n \n4. **Error Handling:** Implement proper error handling for all error scenarios listed above"
},
"response": []
},
{
"name": "Create Return Shipment",
"request": {
"method": "POST",
"header": [
{
"key": "token",
"value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKallMbzhWRnZNZlhBcmpHbzA0X2NMNEtKRjFpT2dvLWhzanVhaENKZFJZIn0.eyJleHAiOjE3NjkwOTk2NjQsImlhdCI6MTc2OTA5OTM2NCwianRpIjoiY2I5YTZjOTMtOWY4OS00MWU2LWE1MDctNjBiM2RhMTQxOWM0IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1saXZlLnhzdGFrLmNvbS9hdXRoL3JlYWxtcy83Nzc2OTllYzdkYzNiZDdjIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjRlZjRiM2U5LTYxY2MtNDI3NS1hZTFiLWRiODg4YzQwZmIxYyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNvcGlsb3QiLCJzZXNzaW9uX3N0YXRlIjoiM2MwNmU5YjQtYzk0Ny00YTk1LWFkYWYtNzI5MDE2NmI5NDlmIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJsb2dpc3RpY3MtYWRtaW4iLCJkZWZhdWx0LXJvbGVzLTc3NzY5OWVjN2RjM2JkN2MiLCJvZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ4c3Rhay1jb3BpbG90LWFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiYWRkX3VzZXJzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIzYzA2ZTliNC1jOTQ3LTRhOTUtYWRhZi03MjkwMTY2Yjk0OWYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJPbW5pZnVsICAiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzaGVocm9vei5haG1hZEBwb3N0ZXhnbG9iYWwuY29tIiwiZ2l2ZW5fbmFtZSI6Ik9tbmlmdWwiLCJmYW1pbHlfbmFtZSI6IiAiLCJlbWFpbCI6InNoZWhyb296LmFobWFkQHBvc3RleGdsb2JhbC5jb20ifQ.KoDyy0DqMOfH42Hz0uGydmXEXc7V35fyi8A0eWd6bqAeGKam5DrGidamG-yb4QB_A5WgPn7T5IKUHAyJhIKVS3Rk5mVLcMLMnGfKtxLhCwgw3ExmXXSu-uXd1ysxUXo87EvnglZQ9sjLoEk2aUJEwT7QSzm-KVMaxqF4pQCVRYB0eh9E1ViL_0GftIRxWrE5NmbCVn4T6I1S-Yi9eunTCB3Tk22Q2d5gYW8K-fimietwmZ0O8A5RkoocRlJ2dsgL11d2U5dNYH4LuCOllgemjWrvaciwdY0oQYTfJ6PacdMwON4pb7AJRWYk4dThjpLSqr3td3LAWIjpKCAPkGtwhw",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"shipToInfo\": {\n \"name\": \"XStak Warehouse\",\n \"email\": \"warehouse@xstak.com\",\n \"phone\": \"+966501234558\",\n \"country\": \"Saudi Arabia\",\n \"address\": \"W13 , Street 24, Al Quoz industrial Area 4\",\n \"city\": \"Jeddah\"\n },\n \"shipFromInfo\": {\n \"name\": \"عبدالله سالم\",\n \"email\": \"haris.islam@xstak.com\",\n \"phone\": \"+966501234558\",\n \"country\": \"Saudi Arabia\",\n \"address\": \"جدة حي الصفاء شارع عبدالله بن سهل, Al Wazeeriyah\",\n \"city\": \"Riyadh\"\n },\n \"packagesInfo\": [\n {\n \"name\": \"Product Name\",\n \"quantity\": 1,\n \"unitPrice\": \"2000.0\",\n \"totalPrice\": \"2000.0\",\n \"originalPrice\": \"2000.0\",\n \"weight\": {\n \"unit\": \"kg\",\n \"value\": 1.0\n }\n }\n ],\n \"dimension\": {\n \"height\": 10.0,\n \"width\": 20.0,\n \"length\": 30.0,\n \"unit\": \"cm\"\n },\n \"shipmentNumber\": \"RETURN-123456\",\n \"paymentMethod\": \"Cash On Delivery\",\n \"shipmentType\": \"RETURN\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.oms.postex.sa/oe/aggtr/api/v1/shipments/{{shipment_id}}/return",
"protocol": "https",
"host": [
"api",
"oms",
"postex",
"sa"
],
"path": [
"oe",
"aggtr",
"api",
"v1",
"shipments",
"{{shipment_id}}",
"return"
]
},
"description": "# Create Return Shipment\n\n## Overview\n\nThis endpoint creates a return shipment in the Order Management System (OMS). It allows you to initiate a return process by specifying the origin (customer), destination (warehouse), package details, and shipment information.\n\n## Endpoint\n\n```\nPOST {{base_url}}/oms/api/v1/shipments/{{shipment_id}}/return\n\n ```\n\n### Path Parameters\n\n- `shipment_id` - The unique identifier of the original shipment for which the return is being created\n \n\n## Authentication\n\nThis endpoint requires token authentication:\n\n```\ntoken: {{jwt_token}}\n\n ```\n\n## Request Body Structure\n\n### shipToInfo (Object)\n\nDestination details - typically the warehouse or facility receiving the returned items:\n\n- `name` (string) - Name of the receiving warehouse/facility\n \n- `email` (string) - Contact email address\n \n- `phone` (string) - Contact phone number (with country code)\n \n- `country` (string) - Country name\n \n- `address` (string) - Complete street address\n \n- `city` (string) - City name\n \n\n### shipFromInfo (Object)\n\nOrigin details - typically the customer returning the items:\n\n- `name` (string) - Customer's name\n \n- `email` (string) - Customer's email address\n \n- `phone` (string) - Customer's phone number (with country code)\n \n- `country` (string) - Country name\n \n- `address` (string) - Complete street address\n \n- `city` (string) - City name\n \n\n### packagesInfo (Array)\n\nArray of items being returned. Each item contains:\n\n- `name` (string) - Product name\n \n- `quantity` (number) - Number of units being returned\n \n- `unitPrice` (string) - Price per unit\n \n- `totalPrice` (string) - Total price for the quantity\n \n- `originalPrice` (string) - Original price of the item\n \n- `weight` (object) - Weight information\n \n - `unit` (string) - Weight unit (e.g., \"kg\")\n \n - `value` (number) - Weight value\n \n\n### dimension (Object)\n\nPackage dimensions for the return shipment:\n\n- `height` (number) - Package height\n \n- `width` (number) - Package width\n \n- `length` (number) - Package length\n \n- `unit` (string) - Measurement unit (e.g., \"cm\")\n \n\n### Additional Fields\n\n- `shipmentNumber` (string) - Unique identifier for the return shipment\n \n- `paymentMethod` (string) - Payment method for the return (e.g., \"Cash On Delivery\")\n \n- `shipmentType` (string) - Must be set to \"RETURN\" for return shipments\n \n\n## Response Formats\n\n### Success Response (200 OK)\n\nWhen the return shipment is successfully created:\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"Return shipment created successfully\",\n \"data\": {\n \"shipmentId\": \"A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6\"\n }\n}\n\n ```\n\n## Error Scenarios\n\n### 406 Not Acceptable - Original Shipment Not Found\n\nWhen the provided shipment ID does not exist in the system:\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Order not found\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Shipment not found for the provided shipment ID.\"\n}\n\n ```\n\n### 406 Not Acceptable - Original Shipment Not in Delivered State\n\nWhen attempting to create a return for a shipment that hasn't been delivered yet:\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Shipment is not in delivered state\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Original Shipment must be in delivered state to create a return shipment.\"\n}\n\n ```\n\n### 400 Bad Request - Validation Error\n\nWhen the request payload fails validation (missing required fields, invalid data types, etc.):\n\n``` json\n{\n \"errorCode\": \"400\",\n \"errorMessage\": \"Validation failed\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Validation failed\"\n}\n\n ```\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### 403 Forbidden - Insufficient Permissions\n\nWhen the authenticated user does not have the necessary permissions to create return shipments:\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Forbidden\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have sufficient permissions to create return shipments.\"\n}\n\n ```\n\n## Notes\n\n- The original shipment must be in \"delivered\" state before a return can be initiated\n \n- All address fields should be complete and accurate for successful shipment processing\n \n- The `shipmentType` field must be set to \"RETURN\" to properly identify this as a return shipment\n \n- Package dimensions and weight are required for logistics processing"
},
"response": []
},
{
"name": "Cancel Shipment",
"request": {
"method": "POST",
"header": [
{
"key": "token",
"value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKallMbzhWRnZNZlhBcmpHbzA0X2NMNEtKRjFpT2dvLWhzanVhaENKZFJZIn0.eyJleHAiOjE3NjkwOTk2NjQsImlhdCI6MTc2OTA5OTM2NCwianRpIjoiY2I5YTZjOTMtOWY4OS00MWU2LWE1MDctNjBiM2RhMTQxOWM0IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1saXZlLnhzdGFrLmNvbS9hdXRoL3JlYWxtcy83Nzc2OTllYzdkYzNiZDdjIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjRlZjRiM2U5LTYxY2MtNDI3NS1hZTFiLWRiODg4YzQwZmIxYyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNvcGlsb3QiLCJzZXNzaW9uX3N0YXRlIjoiM2MwNmU5YjQtYzk0Ny00YTk1LWFkYWYtNzI5MDE2NmI5NDlmIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJsb2dpc3RpY3MtYWRtaW4iLCJkZWZhdWx0LXJvbGVzLTc3NzY5OWVjN2RjM2JkN2MiLCJvZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ4c3Rhay1jb3BpbG90LWFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiYWRkX3VzZXJzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIzYzA2ZTliNC1jOTQ3LTRhOTUtYWRhZi03MjkwMTY2Yjk0OWYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJPbW5pZnVsICAiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzaGVocm9vei5haG1hZEBwb3N0ZXhnbG9iYWwuY29tIiwiZ2l2ZW5fbmFtZSI6Ik9tbmlmdWwiLCJmYW1pbHlfbmFtZSI6IiAiLCJlbWFpbCI6InNoZWhyb296LmFobWFkQHBvc3RleGdsb2JhbC5jb20ifQ.KoDyy0DqMOfH42Hz0uGydmXEXc7V35fyi8A0eWd6bqAeGKam5DrGidamG-yb4QB_A5WgPn7T5IKUHAyJhIKVS3Rk5mVLcMLMnGfKtxLhCwgw3ExmXXSu-uXd1ysxUXo87EvnglZQ9sjLoEk2aUJEwT7QSzm-KVMaxqF4pQCVRYB0eh9E1ViL_0GftIRxWrE5NmbCVn4T6I1S-Yi9eunTCB3Tk22Q2d5gYW8K-fimietwmZ0O8A5RkoocRlJ2dsgL11d2U5dNYH4LuCOllgemjWrvaciwdY0oQYTfJ6PacdMwON4pb7AJRWYk4dThjpLSqr3td3LAWIjpKCAPkGtwhw",
"type": "text"
}
],
"url": {
"raw": "https://api.oms.postex.sa/oe/aggtr/api/v1/shipments/{{shipment_id}}/cancel",
"protocol": "https",
"host": [
"api",
"oms",
"postex",
"sa"
],
"path": [
"oe",
"aggtr",
"api",
"v1",
"shipments",
"{{shipment_id}}",
"cancel"
]
},
"description": "# Cancel Shipment\n\n## Overview\n\nThis endpoint allows you to cancel an existing shipment in the Order Management System (OMS). Once a shipment is successfully cancelled, it will no longer be processed for delivery.\n\n## Endpoint Details\n\n- **Method:** `POST`\n \n- **URL Pattern:** `/oms/api/v1/shipments/{shipment_id}/cancel`\n \n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `shipment_id` | string | Yes | The unique identifier of the shipment to be cancelled |\n\n## Headers\n\n| Header | Value | Required | Description |\n| --- | --- | --- | --- |\n| `token` | {jwt_token} | Yes | JWT authentication token for API access |\n\n## Request Body\n\nThis endpoint does not require a request body.\n\n## Response Scenarios\n\n### Success Response (202 Accepted)\n\nThe shipment has been successfully cancelled.\n\n``` json\n{\n \"code\": \"202\",\n \"status\": \"Success\",\n \"message\": \"Shipment cancelled successfully\",\n \"data\": {}\n}\n\n ```\n\n### Error Responses\n\n#### 406 Not Acceptable - Shipment Not Found\n\nThe shipment with the provided ID does not exist in the system.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Shipment not found\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Shipment not found for the provided shipment ID.\"\n}\n\n ```\n\n#### 406 Not Acceptable - Unable to Cancel Shipment\n\nThe shipment cannot be cancelled in its current state (e.g., already dispatched or delivered).\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Unable to cancel shipment\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Unable to cancel shipment\"\n}\n\n ```\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### 403 Forbidden - Insufficient Permissions\n\nReturned when the authenticated user does not have permission to access the requested shipment.\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Insufficient permissions to access this shipment\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have permission to view tracking information for this shipment.\"\n}\n\n ```\n\n## Important Notes\n\n- **Timing:** Shipments can typically only be cancelled before they have been dispatched or picked up by the carrier\n \n- **Irreversible Action:** Once a shipment is cancelled, this action cannot be undone through the API\n \n- **Status Check:** It's recommended to check the shipment status before attempting cancellation"
},
"response": []
},
{
"name": "Track Shipment",
"request": {
"method": "GET",
"header": [
{
"key": "token",
"value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKallMbzhWRnZNZlhBcmpHbzA0X2NMNEtKRjFpT2dvLWhzanVhaENKZFJZIn0.eyJleHAiOjE3NjkwOTk2NjQsImlhdCI6MTc2OTA5OTM2NCwianRpIjoiY2I5YTZjOTMtOWY4OS00MWU2LWE1MDctNjBiM2RhMTQxOWM0IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1saXZlLnhzdGFrLmNvbS9hdXRoL3JlYWxtcy83Nzc2OTllYzdkYzNiZDdjIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjRlZjRiM2U5LTYxY2MtNDI3NS1hZTFiLWRiODg4YzQwZmIxYyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNvcGlsb3QiLCJzZXNzaW9uX3N0YXRlIjoiM2MwNmU5YjQtYzk0Ny00YTk1LWFkYWYtNzI5MDE2NmI5NDlmIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJsb2dpc3RpY3MtYWRtaW4iLCJkZWZhdWx0LXJvbGVzLTc3NzY5OWVjN2RjM2JkN2MiLCJvZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ4c3Rhay1jb3BpbG90LWFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiYWRkX3VzZXJzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIzYzA2ZTliNC1jOTQ3LTRhOTUtYWRhZi03MjkwMTY2Yjk0OWYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJPbW5pZnVsICAiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzaGVocm9vei5haG1hZEBwb3N0ZXhnbG9iYWwuY29tIiwiZ2l2ZW5fbmFtZSI6Ik9tbmlmdWwiLCJmYW1pbHlfbmFtZSI6IiAiLCJlbWFpbCI6InNoZWhyb296LmFobWFkQHBvc3RleGdsb2JhbC5jb20ifQ.KoDyy0DqMOfH42Hz0uGydmXEXc7V35fyi8A0eWd6bqAeGKam5DrGidamG-yb4QB_A5WgPn7T5IKUHAyJhIKVS3Rk5mVLcMLMnGfKtxLhCwgw3ExmXXSu-uXd1ysxUXo87EvnglZQ9sjLoEk2aUJEwT7QSzm-KVMaxqF4pQCVRYB0eh9E1ViL_0GftIRxWrE5NmbCVn4T6I1S-Yi9eunTCB3Tk22Q2d5gYW8K-fimietwmZ0O8A5RkoocRlJ2dsgL11d2U5dNYH4LuCOllgemjWrvaciwdY0oQYTfJ6PacdMwON4pb7AJRWYk4dThjpLSqr3td3LAWIjpKCAPkGtwhw",
"type": "text"
}
],
"url": {
"raw": "https://api.oms.postex.sa/oe/aggtr/api/v1/shipments/{{shipment_id}}/track",
"protocol": "https",
"host": [
"api",
"oms",
"postex",
"sa"
],
"path": [
"oe",
"aggtr",
"api",
"v1",
"shipments",
"{{shipment_id}}",
"track"
]
},
"description": "# Track Shipment by ID\n\n## Overview\n\nThis endpoint retrieves real-time tracking information for a specific shipment using its unique identifier. It provides comprehensive tracking details including current status, location history, and delivery updates.\n\n## URL Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `shipment_id` | string | Yes | The unique identifier of the shipment to track. This ID is typically provided when a shipment is created or can be retrieved from order details. |\n\n## Headers\n\n| Header | Type | Required | Description |\n| --- | --- | --- | --- |\n| `token` | string | Yes | token for authentication. Format`{{jwt_token}}`. The JWT token must be valid and have appropriate permissions to access shipment tracking information. |\n\n## Expected Response\n\n### Success Response (200 OK)\n\nThe endpoint returns a JSON object containing detailed tracking information:\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"Tracking information fetched successfully\",\n \"data\": {\n \"trackingInfo\": {\n \"shipmentId\": \"68CDFD1BDC57C595\",\n \"shipmentHistory\": [\n {\n \"status\": \"booked\",\n \"date\": \"2025-11-26T12:46:15.525\",\n \"remarks\": \"\"\n },\n {\n \"status\": \"in_transit\",\n \"date\": \"2025-11-27T10:30:00.000\",\n \"remarks\": \"Package picked up from warehouse\"\n }\n ]\n },\n \"shipmentStatus\": \"BOOKED\"\n }\n}\n\n ```\n\n**Response Fields:**\n\n- `code`: HTTP status code as a string\n \n- `status`: Overall status of the API call (Success/Error)\n \n- `message`: Descriptive message about the operation\n \n- `data.trackingInfo.shipmentId`: Unique identifier for the shipment\n \n- `data.trackingInfo.shipmentHistory`: Array of tracking events with status, date, and remarks\n \n- `data.shipmentStatus`: Current status of the shipment\n \n\n**Common Shipment Statuses:**\n\n- `booked`: Shipment has been created and booked\n \n- `in_transit`: Package is on its way to the destination\n \n- `out_for_delivery`: Package is out for final delivery\n \n- `delivered`: Package has been successfully delivered\n \n\n## Error Scenarios\n\n### 406 Not Acceptable - Shipment Not Found\n\nReturned when the provided shipment ID does not exist in the system.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Shipment not found\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Shipment not found for the provided shipment ID.\"\n}\n\n ```\n\n### 406 Not Acceptable - Tracking Info Not Found\n\nReturned when the shipment exists but no tracking information is available.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"No shipment info found\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"No shipment info found\"\n}\n\n ```\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### 403 Forbidden - Insufficient Permissions\n\nReturned when the authenticated user does not have permission to access the requested shipment.\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Insufficient permissions to access this shipment\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have permission to view tracking information for this shipment.\"\n}\n\n ```\n\n**Common causes:**\n\n- User attempting to access shipment from a different organization\n \n- User role lacks shipment tracking permissions\n \n- Shipment belongs to a restricted account\n \n\n## Error Response Structure\n\nAll error responses follow a consistent structure:\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `errorCode` | string | HTTP status code as a string |\n| `errorMessage` | string | Technical error message for debugging |\n| `errorStatus` | string | Always \"Error\" for error responses |\n| `userMessage` | string | User-friendly error message suitable for display |\n\n## Usage Notes\n\n- The `shipment_id` parameter is case-sensitive\n \n- Tracking history is returned in chronological order (oldest to newest)\n \n- Date fields follow ISO 8601 format\n \n- The `remarks` field may be empty for certain status updates"
},
"response": []
},
{
"name": "Get Couriers",
"request": {
"method": "GET",
"header": [
{
"key": "token",
"value": "{{jwt_token}}",
"type": "text"
}
],
"url": {
"raw": "{{base_url}}/aggtr/api/v1/shipments/couriers",
"host": [
"{{base_url}}"
],
"path": [
"aggtr",
"api",
"v1",
"shipments",
"couriers"
]
},
"description": "# Get Couriers\n\n## Overview\n\nThis endpoint retrieves a list of available courier IDs for the authenticated brand/organization. The courier IDs can be used for shipment operations and tracking.\n\n## Authentication\n\nRequires a valid JWT Bearer token in the Authorization header.\n\n## Success Response\n\n### 200 OK - With Couriers\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"Couriers fetched successfully\",\n \"data\": {\n \"couriers\": [\n \"68e943ba7bd0238e3e98ca5a\",\n \"68e9507cd2dc80652ee581cd\",\n \"68e9507e93f8c2514ccd0c70\",\n \"68e9507f93f8c2514ccd0c8b\",\n \"68e95083d2dc80652ee5821d\"\n ]\n }\n}\n\n ```\n\n### 200 OK - Empty List\n\nWhen no couriers are available for the brand/organization:\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"Couriers fetched successfully\",\n \"data\": {\n \"couriers\": []\n }\n}\n\n ```\n\n## Error Scenarios\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### 403 Forbidden - Insufficient Permissions\n\nReturned when the authenticated user does not have sufficient permissions to view courier information.\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Insufficient permissions to access courier information\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have permission to view courier information for this organization\"\n}\n\n ```\n\n### 406 Not Acceptable - Invalid Request\n\nReturned when the request format or parameters are invalid.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Invalid request\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid request\"\n}\n\n ```"
},
"response": []
},
{
"name": "Get AWB",
"request": {
"method": "GET",
"header": [
{
"key": "token",
"value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKallMbzhWRnZNZlhBcmpHbzA0X2NMNEtKRjFpT2dvLWhzanVhaENKZFJZIn0.eyJleHAiOjE3NjkwOTk2NjQsImlhdCI6MTc2OTA5OTM2NCwianRpIjoiY2I5YTZjOTMtOWY4OS00MWU2LWE1MDctNjBiM2RhMTQxOWM0IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1saXZlLnhzdGFrLmNvbS9hdXRoL3JlYWxtcy83Nzc2OTllYzdkYzNiZDdjIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjRlZjRiM2U5LTYxY2MtNDI3NS1hZTFiLWRiODg4YzQwZmIxYyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNvcGlsb3QiLCJzZXNzaW9uX3N0YXRlIjoiM2MwNmU5YjQtYzk0Ny00YTk1LWFkYWYtNzI5MDE2NmI5NDlmIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJsb2dpc3RpY3MtYWRtaW4iLCJkZWZhdWx0LXJvbGVzLTc3NzY5OWVjN2RjM2JkN2MiLCJvZSIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ4c3Rhay1jb3BpbG90LWFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29waWxvdCI6eyJyb2xlcyI6WyJ2aWV3X2Rhc2hib2FyZCIsInZpZXdfdXNlcnMiLCJlZGl0X3VzZXJzIiwiYWRkX3VzZXJzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIzYzA2ZTliNC1jOTQ3LTRhOTUtYWRhZi03MjkwMTY2Yjk0OWYiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIm5hbWUiOiJPbW5pZnVsICAiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzaGVocm9vei5haG1hZEBwb3N0ZXhnbG9iYWwuY29tIiwiZ2l2ZW5fbmFtZSI6Ik9tbmlmdWwiLCJmYW1pbHlfbmFtZSI6IiAiLCJlbWFpbCI6InNoZWhyb296LmFobWFkQHBvc3RleGdsb2JhbC5jb20ifQ.KoDyy0DqMOfH42Hz0uGydmXEXc7V35fyi8A0eWd6bqAeGKam5DrGidamG-yb4QB_A5WgPn7T5IKUHAyJhIKVS3Rk5mVLcMLMnGfKtxLhCwgw3ExmXXSu-uXd1ysxUXo87EvnglZQ9sjLoEk2aUJEwT7QSzm-KVMaxqF4pQCVRYB0eh9E1ViL_0GftIRxWrE5NmbCVn4T6I1S-Yi9eunTCB3Tk22Q2d5gYW8K-fimietwmZ0O8A5RkoocRlJ2dsgL11d2U5dNYH4LuCOllgemjWrvaciwdY0oQYTfJ6PacdMwON4pb7AJRWYk4dThjpLSqr3td3LAWIjpKCAPkGtwhw",
"type": "text"
}
],
"url": {
"raw": "https://api.oms.postex.sa/oe/aggtr/api/v1/shipments/{{shipment_id}}/awb",
"protocol": "https",
"host": [
"api",
"oms",
"postex",
"sa"
],
"path": [
"oe",
"aggtr",
"api",
"v1",
"shipments",
"{{shipment_id}}",
"awb"
]
},
"description": "# Get AWB\n\n## Overview\n\nThis endpoint retrieves the Air Waybill (AWB) URL for a specific shipment. The AWB is a shipping document that contains shipment details and can be downloaded/printed for courier and logistics purposes.\n\n## Path Parameters\n\n- `shipment_id` (required) - The unique identifier of the shipment\n \n\n## Headers\n\n- `token: {{jwt_token}}` (required) - JWT authentication token\n \n\n## Success Response (200 OK)\n\n``` json\n{\n \"code\": \"200\",\n \"status\": \"Success\",\n \"message\": \"AWB URL fetched successfully\",\n \"data\": {\n \"awbUrl\": \"https://example.com/orders/OB-123456/download/SingleOrderFileAndDispatchNote?file_source=courier\"\n }\n}\n\n ```\n\n## Error Scenarios\n\n### 406 Not Acceptable - Shipment Not Found\n\nReturned when the provided shipment ID does not exist in the system.\n\n``` json\n{\n \"errorCode\": \"406\",\n \"errorMessage\": \"Shipment not found\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Shipment not found for the provided shipment ID.\"\n}\n\n ```\n\n### **401 Unauthorized - Invalid or Missing Token**\n\nReturned when the token is missing, malformed, or expired.\n\n``` json\n{\n \"errorCode\": \"401\",\n \"errorMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"Invalid or missing authorization token. Token must be a valid JWT.\"\n}\n\n ```\n\n---\n\n### 403 Forbidden - Insufficient Permissions\n\nReturned when the authenticated user does not have sufficient permissions to access AWB documents for the requested shipment.\n\n``` json\n{\n \"errorCode\": \"403\",\n \"errorMessage\": \"Insufficient permissions to access AWB\",\n \"errorStatus\": \"Error\",\n \"userMessage\": \"You do not have the required permissions to access the AWB for this shipment.\"\n}\n\n ```"
},
"response": []
},
{
"name": "get token API",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"clientId\": \"api-user-qnMXaHZiAQ\",\n \"clientSecret\": \"iidTMQ-KrF7Qu3dJWhad\",\n \"grantType\": \"client_credentials\",\n \"companyCode\": \"777699ec7dc3bd7c\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.copilot-live.xstak.com/v1/admin/service-account/token",
"protocol": "https",
"host": [
"api",
"copilot-live",
"xstak",
"com"
],
"path": [
"v1",
"admin",
"service-account",
"token"
]
},
"description": "# Token Generation\n\n## Overview\n\nThis endpoint generates an access token for authentication. Use this token to authenticate subsequent API requests to the system.\n\n## Authentication Method\n\nThis endpoint uses the **Client Credentials Grant Type** OAuth 2.0 flow, which is designed for server-to-server authentication where no user interaction is required.\n\n## Request Body Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `clientId` | string | Yes | Your unique client identifier provided during service account setup |\n| `clientSecret` | string | Yes | Your confidential client secret key - keep this secure and never expose it in client-side code |\n| `grant type` | string | Yes | Must be set to `\"client_credentials\"` for this authentication flow |\n| `companyCode` | string | Yes | Your unique company identifier code assigned to your organization |"
},
"response": []
}
],
"variable": [
{
"key": "base_url",
"value": "https://your-api-base-url.com",
"type": "string"
},
{
"key": "jwt_token",
"value": "your-jwt-token-here",
"type": "string"
},
{
"key": "shipment_id",
"value": "68CDFD1BDC57C595",
"type": "string"
}
]
}