Skip to main content

Package Handoffs Management

4 API calls in this section.

List Package Handoffs​

Warehousing / Package Handoffs Management
GET/warehousing/handoffs?tenant_id={{tenant_id}}&warehouse_id=&delivery_id=&driver_id=&warehouse_staff_id=&status=&search=&page=1&limit=10

Retrieves package handoffs based on specified filter criteria. Supports pagination and filtering by warehouse, delivery ID, driver ID, warehouse staff ID, and status. Authentication: - Requires valid authentication token - User must have 'view:tenant' or 'manage:operations:tenant' permission Query Parameters: - tenant_id (required): UUID of the tenant - warehouse_id (optional): Filter by warehouse ID - delivery_id (optional): Filter by delivery ID - driver_id (optional): Filter by driver ID - warehouse_staff_id (optional): Filter by warehouse staff ID - status (optional): Filter by handoff status (pending, in_progress, completed) - search (optional): Search term to filter by status - page (optional): Page number for pagination (default: 1) - limit (optional): Number of items per page (default: 10) Response: - Returns a paginated list of package handoffs - Includes related entities such as warehouse, picking order, and warehouse staff information - Includes a status_matrix summary for the current non-status filters - Provides pagination information (total count, current page, limit)

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/warehousing/handoffs?tenant_id={{tenant_id}}&warehouse_id=&delivery_id=&driver_id=&warehouse_staff_id=&status=&search=&page=1&limit=10" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json"

Query parameters

tenant_idOptional
query string

{{tenant_id}}

UUID of the tenant (required)

warehouse_idOptional
query string

Filter by warehouse ID (optional)

delivery_idOptional
query string

Filter by delivery ID (optional)

driver_idOptional
query string

Filter by driver ID (optional)

warehouse_staff_idOptional
query string

Filter by warehouse staff ID (optional)

statusOptional
query string

Filter by handoff status: pending, in_progress, completed (optional)

searchOptional
query string

Search term to filter by status (optional)

pageOptional
query string

1

Page number for pagination (optional, default: 1)

limitOptional
query string

10

Number of items per page (optional, default: 10)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Handoffs retrieved successfully",4  "handoffs": [5    {6      "id": "12345678-1234-1234-1234-123456789012",7      "tenant_id": "tenant-uuid",8      "warehouse_id": "warehouse-uuid",9      "delivery_id": "delivery-uuid",10      "picking_order_id": "picking-order-uuid",11      "warehouse_staff_id": "staff-uuid",12      "driver_id": "driver-uuid",13      "status": "completed",14      "signature_url": "https://example.com/signatures/sig123.png",15      "notes": "Handoff completed without issues",16      "initiated_at": "2023-05-15T14:30:00Z",17      "completed_at": "2023-05-15T14:45:00Z",18      "warehouse": {19        "id": "warehouse-uuid",20        "name": "Main Warehouse",21        "code": "WH001"22      },23      "picking_order": {24        "id": "picking-order-uuid",25        "reference_number": "PO-12345"26      },27      "warehouse_staff": {28        "id": "staff-uuid",29        "user_id": {30          "id": "user-uuid",31          "full_name": "John Smith"32        }33      }34    }35  ],36  "status_matrix": {37    "pending": 4,38    "in_progress": 2,39    "completed": 8,40    "total": 1441  },42  "page": 1,43  "limit": 10,44  "total": 145}
Error - Tenant Not Found404
Response body
json
1{2  "success": false,3  "message": "Tenant not found"4}
Error - Insufficient Permissions403
Response body
json
1{2  "success": false,3  "message": "Insufficient permissions"4}
Error - Server Error500
Response body
json
1{2  "success": false,3  "message": "Internal server error"4}

Create Package Handoff​

Warehousing / Package Handoffs Management
POST/warehousing/handoffs?tenant_id={{tenant_id}}

Records a package handoff from warehouse staff to delivery driver. Validates the existence of related entities and creates the handoff record with pending status. Authentication: - Requires valid authentication token - User must have 'manage:operations:tenant' permission Query Parameters: - tenant_id (required): UUID of the tenant Business Rules: - Required fields: warehouse_id, delivery_id, picking_order_id, warehouse_staff_id - All referenced entities must exist and belong to the specified tenant - The picking order must be in 'completed' status - The delivery must have a driver assignment in a pre-pickup state: assigned, accepted, or en_route_to_pickup - If the delivery is already picked_up or beyond, the handoff must not be created because the warehouse handoff window is already closed - A handoff record cannot be created if one already exists for that delivery - driver_id is resolved from the delivery assignment when the handoff is created - Status is always set to 'pending' when creating handoffs - Use the update endpoint to change status to completed when requirements are met

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/warehousing/handoffs?tenant_id={{tenant_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "warehouse_id": "warehouse-uuid",7  "delivery_id": "delivery-uuid",8  "picking_order_id": "picking-order-uuid",9  "warehouse_staff_id": "staff-uuid",10  "driver_id": "driver-uuid",11  "signature_url": "https://example.com/signatures/sig123.png",12  "notes": "Package ready for handoff"13}'
Request body
json
1{2  "warehouse_id": "warehouse-uuid",3  "delivery_id": "delivery-uuid",4  "picking_order_id": "picking-order-uuid",5  "warehouse_staff_id": "staff-uuid",6  "driver_id": "driver-uuid",7  "signature_url": "https://example.com/signatures/sig123.png",8  "notes": "Package ready for handoff"9}

Query parameters

tenant_idOptional
query string

{{tenant_id}}

UUID of the tenant (required)

Request body fields

warehouse_idExample
string

Example field from the request body.

delivery_idExample
string

Example field from the request body.

picking_order_idExample
string

Example field from the request body.

warehouse_staff_idExample
string

Example field from the request body.

driver_idExample
string

Example field from the request body.

signature_urlExample
string

Example field from the request body.

notesExample
string

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response201
Response body
json
1{2  "success": true,3  "message": "Handoff created successfully",4  "handoff": {5    "id": "12345678-1234-1234-1234-123456789012",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "delivery_id": "delivery-uuid",9    "picking_order_id": "picking-order-uuid",10    "warehouse_staff_id": "staff-uuid",11    "driver_id": "driver-uuid",12    "status": "pending",13    "signature_url": null,14    "notes": "Package ready for handoff",15    "initiated_at": "2023-05-15T14:30:00Z",16    "completed_at": null17  }18}
Error - Missing Required Field400
Response body
json
1{2  "success": false,3  "message": "Field required: warehouse_id"4}
Error - Warehouse Not Found404
Response body
json
1{2  "success": false,3  "message": "Warehouse not found"4}
Error - Delivery Not Found404
Response body
json
1{2  "success": false,3  "message": "Delivery not found"4}
Error - Picking Order Not Found404
Response body
json
1{2  "success": false,3  "message": "Picking order not found"4}
Error - Picking Order Not Completed400
Response body
json
1{2  "success": false,3  "message": "Picking order not completed"4}
Error - Handoff Already Exists400
Response body
json
1{2  "success": false,3  "message": "Handoff already exists for delivery"4}
Error - Insufficient Permissions403
Response body
json
1{2  "success": false,3  "message": "Insufficient permissions"4}
Error - Invalid Request Body400
Response body
json
1{2  "success": false,3  "message": "Invalid request body"4}

Get Package Handoff​

Warehousing / Package Handoffs Management
GET/warehousing/handoffs/:id?tenant_id={{tenant_id}}

Retrieves detailed information about a specific package handoff including related entities such as warehouse, picking order, warehouse staff, driver, and delivery information. Authentication: - Requires valid authentication token - User must have 'view:tenant' or 'manage:operations:tenant' permission Path Parameters: - id: UUID of the package handoff (required) Query Parameters: - tenant_id: UUID of the tenant (required if not in auth context) Response: - Returns detailed information about the specified handoff - Includes related entities information (warehouse, picking order, staff, driver) - Includes delivery details such as delivery code, pickup/drop-off locations, and customer information

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/warehousing/handoffs/:id?tenant_id={{tenant_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json"

Path parameters

idRequired
path string

handoff-uuid

UUID of the package handoff (required)

Query parameters

tenant_idOptional
query string

{{tenant_id}}

UUID of the tenant (required if not in auth)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Handoff retrieved successfully",4  "handoff": {5    "id": "12345678-1234-1234-1234-123456789012",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "delivery_id": "delivery-uuid",9    "picking_order_id": "picking-order-uuid",10    "warehouse_staff_id": "staff-uuid",11    "driver_id": "driver-uuid",12    "status": "completed",13    "signature_url": "https://example.com/signatures/sig123.png",14    "notes": "Handoff completed without issues",15    "initiated_at": "2023-05-15T14:30:00Z",16    "completed_at": "2023-05-15T14:45:00Z",17    "warehouse": {18      "id": "warehouse-uuid",19      "name": "Main Warehouse",20      "code": "WH001"21    },22    "picking_order": {23      "id": "picking-order-uuid",24      "reference_number": "PO-12345"25    },26    "warehouse_staff": {27      "id": "staff-uuid",28      "user_id": {29        "id": "user-uuid",30        "full_name": "John Smith"31      }32    },33    "driver": {34      "id": "driver-uuid",35      "user_id": {36        "id": "user-uuid",37        "full_name": "Jane Doe"38      }39    },40    "delivery": {41      "id": "delivery-uuid",42      "delivery_code": "DLV-000123",43      "status": "assigned",44      "pickup": {45        "id": "pickup-location-uuid",46        "full_address": "123 Warehouse Street, City, State 12345"47      },48      "drop_off": {49        "id": "dropoff-location-uuid",50        "full_address": "456 Customer Avenue, City, State 67890"51      },52      "customer": {53        "id": "customer-uuid",54        "full_name": "John Customer"55      }56    }57  }58}
Error - Handoff Not Found404
Response body
json
1{2  "success": false,3  "message": "Handoff not found"4}
Error - Tenant Not Found404
Response body
json
1{2  "success": false,3  "message": "Tenant not found"4}
Error - Insufficient Permissions403
Response body
json
1{2  "success": false,3  "message": "Insufficient permissions"4}

Update Package Handoff​

Warehousing / Package Handoffs Management
PUT/warehousing/handoffs/:id?tenant_id={{tenant_id}}

Updates an existing package handoff with new information such as status, driver assignment, signature, or notes. Special validation rules apply when marking handoffs as completed. Authentication: - Requires valid authentication token - User must have 'manage:operations:tenant' permission Path Parameters: - id: UUID of the package handoff to update (required) Query Parameters: - tenant_id: UUID of the tenant (required if not in auth context) Business Rules: - At least one field must be provided for update - Valid status values are: pending, in_progress, completed - If driver_id is provided, the driver must exist and belong to the tenant - Special rules for 'completed' status: - delivery_id must be present in the handoff record - The delivery must have a driver assignment in a pre-pickup state: assigned, accepted, or en_route_to_pickup - If the delivery is already picked_up or beyond, the handoff can no longer be completed through this warehouse step - signature_url is mandatory for completion - driver_id will be automatically set from the delivery assignment - If status is changed to 'completed', the completed_at timestamp is set automatically

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request PUT "$ONDI_BASE_URL/warehousing/handoffs/:id?tenant_id={{tenant_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "status": "completed",7  "driver_id": "driver-uuid",8  "signature_url": "https://example.com/signatures/sig123.png",9  "notes": "Updated notes for the handoff"10}'
Request body
json
1{2  "status": "completed",3  "driver_id": "driver-uuid",4  "signature_url": "https://example.com/signatures/sig123.png",5  "notes": "Updated notes for the handoff"6}

Path parameters

idRequired
path string

handoff-uuid

UUID of the package handoff to update (required)

Query parameters

tenant_idOptional
query string

{{tenant_id}}

UUID of the tenant (required if not in auth)

Request body fields

statusExample
string

Example field from the request body.

driver_idExample
string

Example field from the request body.

signature_urlExample
string

Example field from the request body.

notesExample
string

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Handoff updated successfully",4  "handoff": {5    "id": "12345678-1234-1234-1234-123456789012",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "delivery_id": "delivery-uuid",9    "picking_order_id": "picking-order-uuid",10    "warehouse_staff_id": "staff-uuid",11    "driver_id": "driver-uuid",12    "status": "completed",13    "signature_url": "https://example.com/signatures/sig123.png",14    "notes": "Updated notes for the handoff",15    "initiated_at": "2023-05-15T14:30:00Z",16    "completed_at": "2023-05-15T15:30:00Z"17  }18}
Error - Handoff Not Found404
Response body
json
1{2  "success": false,3  "message": "Handoff not found"4}
Error - Driver Not Found404
Response body
json
1{2  "success": false,3  "message": "Driver not found"4}
Error - Invalid Status400
Response body
json
1{2  "success": false,3  "message": "Invalid status"4}
Error - No Fields to Update400
Response body
json
1{2  "success": false,3  "message": "No fields to update"4}
Error - Tenant Not Found404
Response body
json
1{2  "success": false,3  "message": "Tenant not found"4}
Error - Insufficient Permissions403
Response body
json
1{2  "success": false,3  "message": "Insufficient permissions"4}
Error - Delivery ID Required for Completion400
Response body
json
1{2  "success": false,3  "message": "Delivery ID required for completion"4}
Error - Delivery Not Assigned to Driver400
Response body
json
1{2  "success": false,3  "message": "Delivery not assigned to driver"4}
Error - Signature URL Required for Completion400
Response body
json
1{2  "success": false,3  "message": "Signature URL required for completion"4}
Error - Invalid Request Body400
Response body
json
1{2  "success": false,3  "message": "Invalid request body"4}