Express

4 API calls in this section.

Active Express API endpoints for package management

Package Entry

Express Shipping / Express

POST/express/package-entry

API: Package Entry

Endpoint

POST /express/package-entry

Purpose

External endpoint for package entry. This API is called when a package is received at the facility. It either creates a new package record or updates an existing one.

• No Bearer token required

Business Logic

1. Validate customer exists using provided customer_id

2. Check if package already exists using order_id

3. If package exists: Update weight, shipping price, tracking code, cargo information, and mark as received

4. If package doesn't exist: Create new unclaimed package with status=received, quantity=1, currency=USD

5. Calculate shipping price based on weight

6. Return package and customer details with claimed/unclaimed status

Response Field Notes

• is_claimed: true if customer has already claimed this order with invoice, false if package arrived before customer claim

• store_name: Populated with store name if package was claimed by customer first, empty if unclaimed

• package_type: Populated with package type if package was claimed by customer first, empty if unclaimed (filled only after customer claim)

• order_id: The unique order identifier from the e-commerce platform (StarEx order_id parameter)

• tracking_number: Our internal Galina tracking number for this package

Error Responses

400 - Missing Required Fields

404 - Customer Not Found

500 - Internal Server Error

500 - Service Unavailable

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json
X-API-KeyRequired	string	API key authentication (required) header (required) API key authentication (required) header (required) Example: {{api_key}}

Body parameters

Parameter	Type	Description
weightOptional	number	(integer, optional): Package weight in grams from weighing system (integer, optional): Package weight in grams from weighing system
customer_idOptional	string	(string, optional): Customer ID to lookup the galina customer (string, optional): Customer ID to lookup the galina customer
order_idOptional	string	(string, optional): Order ID that becomes our order_number (string, optional): Order ID that becomes our order_number
cargo_tracking_codeOptional	string	(string, optional): Cargo tracking code provided by shipping partner (separate from order_id) (string, optional): Cargo tracking code provided by shipping partner (separate from order_id)
cargo_infoOptional	array<string>	(array of strings, optional): Additional cargo information such as item codes, AWB numbers, etc. (array of strings, optional): Additional cargo information such as item codes, AWB numbers, etc.
label_dataOptional	object	(object, optional): Arbitrary JSON object for label payload/metadata (object, optional): Arbitrary JSON object for label payload/metadata

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/express/package-entry" \2  --header "Content-Type: application/json" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --data-raw '{5  "weight": 1500,6  "customer_id": "GL222111",7  "order_id": "TREND-ORD-98765",8  "cargo_tracking_code": "AZO593623623",9  "cargo_info": [10    "1521235ATT35",11    "124125515"12  ],13  "label_data": {}14}'

Response examples

200 · Success Response - Claimed Package200 · Success Response - Unclaimed Package400 · Error - Missing Required Fields404 · Error - Customer Not Found500 · Error - Internal Server Error400 · 400 - Missing Required Fields404 · 404 - Customer Not Found500 · 500 - Service Unavailable

200OK

Response body

json

1{2  "success": true,3  "data": {4    "package": {5      "tracking_number": "GL1706371234567",6      "order_id": "TREND-ORD-98765",7      "quantity": 1,8      "price": 25.5,9      "currency": "USD",10      "store_name": "Trendyol",11      "hs_code": "0000.00.00",12      "package_type": "general_goods",13      "status": "received",14      "is_claimed": true15    },16    "customer": {17      "first_name": "Ahmed",18      "last_name": "Al-Rahman",19      "phone_number": "+964987654321",20      "address": "123 Main Street, Erbil, Iraq",21      "id_pin": "GL222111"22    },23    "label": ""24  },25  "message": "Package received successfully"26}

Package Update

Express Shipping / Express

POST/express/package-update

API: Package Update

Endpoint

POST /express/package-update

Purpose

Update existing express package fields by order_id (same fields accepted by package entry). Recomputes international fee and, if linked delivery exists, recomputes domestic fee and updates the delivery.

Error Responses

• 400: order_id is required

• 404: Package not found

• 500: Internal server error

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json
X-API-KeyRequired	string	API key authentication (required) header (required) API key authentication (required) header (required) Example: {{api_key}}

Body parameters

Parameter	Type	Description
order_idRequired	string	(string, required): Order ID to locate the package (string, required): Order ID to locate the package
weightOptional	number	(integer, optional): Updated weight in grams (integer, optional): Updated weight in grams
cargo_tracking_codeOptional	string	(string | string[], optional): External tracking code(s) (string | string[], optional): External tracking code(s)
cargo_infoOptional	array<string>	(string[], optional): Tags like fragile, electronics (string[], optional): Tags like fragile, electronics

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/express/package-update" \2  --header "Content-Type: application/json" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --data-raw '{5  "order_id": "{{order_id}}",6  "weight": 3200,7  "cargo_tracking_code": "STAREX-TRACK-123",8  "cargo_info": [9    "fragile",10    "electronics"11  ]12}'

Replace {{placeholders}} with your own values before sending.

Response examples

200 · Success Response200 · Success Response (200)

200OK

Response body

json

1{2  "success": true,3  "data": {4    "order_id": "TREND-ORD-98765",5    "weight": 3200,6    "cargo_tracking_code": "STAREX-TRACK-123",7    "cargo_info": [8      "fragile",9      "electronics"10    ]11  }12}

Webhook Status Update

Express Shipping / Express

POST/express/webhook-status-update

API: Webhook Status Update

Endpoint

POST /express/webhookStatusUpdate

Purpose

External webhook for package status updates. Called whenever package status changes during transit.

• No Bearer token required

External statuses are mapped to internal statuses

• pending → pending

• claimedByCustomer → claimed

• executedByShipper → in_transit

• inTransitInternational → in_transit_international

• inWarehouseDomestic → in_warehouse

• inProgressDomestic → out_for_delivery

• delivered → delivered

• canceled → cancelled

• accepted_at_facility → in_transit

• package_being_packaged → in_transit

• in_transit_outside_iraq → in_transit_international

• arrived_in_iraq → in_warehouse

Business Logic

1. Locate package using the provided order_id

2. Map external status to internal status representation

3. Update package status and maintain status history

4. Webhook always returns success response for reliability

Success Response (Update Failed)

Note

This endpoint always returns success status even if package is not found or update fails. This is intentional webhook design to prevent unnecessary retries. The processed field indicates whether the update was successfully applied.

Possible Error Codes

• MISSING_REQUIRED_FIELDS: Missing order_id, status, timestamp, or details

• INTERNAL_SERVER_ERROR: JSON parsing or severe system error

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json
X-API-KeyRequired	string	API key authentication (required) header (required) API key authentication (required) header (required) Example: {{api_key}}

Body parameters

Parameter	Type	Description
order_idRequired	string	(string, required): Order ID to identify the package (string, required): Order ID to identify the package
statusRequired	string	(string, required): New status value from external system (string, required): New status value from external system
timestampRequired	string	(string, required): ISO 8601 timestamp when status change occurred (string, required): ISO 8601 timestamp when status change occurred
detailsRequired	string	(string, required): Human-readable details about the status change (string, required): Human-readable details about the status change

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/express/webhook-status-update" \2  --header "Content-Type: application/json" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --data-raw '{5  "order_id": "TREND-ORD-98765",6  "status": "in_transit_outside_iraq",7  "timestamp": "2025-01-27T12:00:00Z",8  "details": "Package en route to Iraq"9}'

Response examples

200 · Success Response - Status Updated200 · Success Response - Package Not Found500 · Error - Missing Required Fields200 · Success Response (Package Not Found)200 · Success Response (Update Failed)500 · Error Response (500 - Only for severe errors)

200OK

Response body

json

1{2  "success": true,3  "data": {4    "order_id": "TREND-ORD-98765",5    "status": "in_transit_outside_iraq",6    "processed": true,7    "timestamp": "2025-01-27T12:00:00Z"8  },9  "message": "Status update processed successfully"10}

Update Order

Express Shipping / Express

POST/express/update-order/TREND-ORD-98765

API: Update Order

Current implementation limitation

The router in functions/express/index.ts matches only POST /express/update-order, while apis/order.ts extracts order_id from the last URL segment. The documented /express/update-order/:order_id request does not reach that handler and returns 404. Treat this as an intended contract with a routing defect, and resolve the backend mismatch before using the success examples as a runnable test.

Endpoint

POST /express/update-order/:order_id

Purpose

Update order details after measurement or status changes. Only weight, size, and status fields are allowed.

Field Restrictions

• Only weight, size, and status fields are accepted

• Any other fields will result in a validation error

• Status updates are handled via the database RPC function for proper history tracking

Business Logic

1. Extract order_id from URL path

2. Validate only allowed fields are provided

3. Update weight and size directly in database

4. Update status via update_package_status RPC function

5. Return summary of updated fields

Error Responses

400 - Missing Order ID

400 - Invalid Fields

404 - Order Not Found

500 - Update Failed

Path parameters

Parameter	Type	Description
order_idRequired	string	(string, required): Order ID in the URL path (string, required): Order ID in the URL path

Headers

Parameter	Type	Description
Content-Type	string	Example: application/json
X-API-KeyRequired	string	API key authentication (required) header (required) API key authentication (required) header (required) Example: {{api_key}}

Body parameters

Parameter	Type	Description
weightOptional	number	(integer, optional): Updated package weight in grams (integer, optional): Updated package weight in grams
sizeOptional	object	(object, optional): Updated package dimensions (object, optional): Updated package dimensions
size.lengthOptional	number	(number, optional): Length in centimeters (number, optional): Length in centimeters
size.widthOptional	number	(number, optional): Width in centimeters (number, optional): Width in centimeters
size.heightOptional	number	(number, optional): Height in centimeters (number, optional): Height in centimeters
statusOptional	string	(string, optional): Updated package status (uses update_package_status RPC) (string, optional): Updated package status (uses update_package_status RPC)

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/express/update-order/TREND-ORD-98765" \2  --header "Content-Type: application/json" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --data-raw '{5  "weight": 3000,6  "size": {7    "length": 35,8    "width": 25,9    "height": 1510  },11  "status": "executedByShipper"12}'

Response examples

200 · Success Response400 · Error - Invalid Fields404 · Error - Order Not Found400 · 400 - Missing Order ID500 · 500 - Update Failed

200OK

Response body

json

1{2  "success": true,3  "message": "Order updated successfully",4  "data": {5    "order_id": "TREND-ORD-98765",6    "updatedFields": {7      "weight": 3000,8      "size": {9        "length": 35,10        "width": 25,11        "height": 1512      },13      "status": "executedByShipper"14    },15    "timestamp": "2025-01-27T12:00:00Z"16  }17}