Pickup API

Pickup task management endpoints.

Endpoints Overview

Endpoint	Method	Description
/api/v1/carrier/pickup/submit	POST	Submit pickup task
/api/v1/pickup/list	POST	Get pickup task list
/api/v1/pickup/re-send	POST	Re-send webhook notification
/api/v1/pickup/re-create	POST	Re-create pickup order
/api/v1/pickup/authorize/refresh	POST	Refresh authorization

---

Submit Pickup Task

Submit a new pickup task to carrier.

Request

Endpoint: POST /api/v1/carrier/pickup/submit

Headers:

• Content-Type: application/json
• Authorization: appToken {token}

Request Body:

{
  "request_id": "pickup_001",
  "service_code": "DHL_PICKUP",
  "authorize_id": "auth_123",
  "sender_address": {
    "postal_code": "10001",
    "country_code": "US",
    "province": "NY",
    "city": "New York",
    "address_1": "123 Main St"
  },
  "loading_address": {
    "postal_code": "10001",
    "country_code": "US",
    "province": "NY",
    "city": "New York",
    "address_1": "456 Warehouse Blvd"
  },
  "consignee_address": {
    "postal_code": "90001",
    "country_code": "US",
    "province": "CA",
    "city": "Los Angeles",
    "address_1": "789 Delivery Ave"
  },
  "reference_order_number": "ORDER_12345",
  "loading_time": {
    "start_date": "2025-03-10",
    "start_time": "09:00",
    "end_date": "2025-03-10",
    "end_time": "18:00"
  },
  "delivery_time": {
    "start_date": "2025-03-12",
    "start_time": "09:00",
    "end_date": "2025-03-12",
    "end_time": "18:00"
  },
  "item_lines": [
    {
      "weight": 10,
      "length": 30,
      "width": 20,
      "height": 15,
      "declare_name": "Electronics",
      "weight_class": "kg",
      "length_class": "cm"
    }
  ],
  "webhook_url": "https://your-domain.com/webhook",
  "sign_string": "signature_string",
  "meta_data": {
    "order_type": "B2B"
  }
}

Field Description

Field	Type	Required	Description
request_id	string	Yes	Unique request ID
service_code	string	Yes	Carrier service code
authorize_id	string	Yes	Authorization ID
sender_address	object	Yes	Sender address
loading_address	object	Yes	Pickup address
consignee_address	object	Yes	Consignee address
reference_order_number	string	Yes	Reference order number
loading_time	object	Yes	Expected pickup time window
delivery_time	object	Yes	Expected delivery time window
item_lines	object[]	Yes	Package items
webhook_url	string	Yes	Webhook notification URL
sign_string	string	Yes	Signature string
meta_data	object	No	Additional metadata

Time Window Fields

Field	Type	Required	Description
start_date	string	Yes	Start date (YYYY-MM-DD)
start_time	string	Yes	Start time (HH:MM)
end_date	string	Yes	End date (YYYY-MM-DD)
end_time	string	Yes	End time (HH:MM)

---

Pickup Task List

Get paginated list of pickup tasks.

Request

Endpoint: POST /api/v1/pickup/list

{
  "pageNumber": 1,
  "pageSize": 20,
  "process": "pending"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 50,
    "currPage": 1,
    "data": [
      {
        "id": 1,
        "request_id": "pickup_001",
        "reference_order_number": "ORDER_12345",
        "process": "create",
        "state": true,
        "loading_time": {...},
        "delivery_time": {...}
      }
    ]
  }
}

---

Re-send Notification

Re-trigger webhook notification for a pickup task.

Request

Endpoint: POST /api/v1/pickup/re-send

{
  "taskId": 123
}

---

Re-create Pickup Order

Re-initiate pickup order creation.

Request

Endpoint: POST /api/v1/pickup/re-create

{
  "taskId": 123
}

---

Refresh Authorization

Refresh carrier authorization for a pickup task.

Request

Endpoint: POST /api/v1/pickup/authorize/refresh

{
  "taskId": 123
}

---

Error Codes

Code	Description
please configure hot api key first	API key not configured
please do not repeat submit the same order	Duplicate order
request_id must be unique	Request ID already exists
the task id is required	Task ID missing
the task id is not exist	Task not found
the task is not in the pickup state	Task cannot be recreated
the task is in the processing	Task already being processed