API v1 Documentation

Overview
Authentication
Order Management Module
Parcel Management Module
Complete Business Flow Examples
- Scenario 1: Create Order and Parcel Simultaneously
- Scenario 2: Create Order and Parcel Separately
Notes
Technical Support

Overview

API v1 is a RESTful HTTP interface for managing orders and parcels. Please contact customer service to obtain an API Secret Key.

Basic Information:

Base Path: /api/v1
Authentication: Bearer API Secret Key (via Authorization header)
Request Format: application/json
Response Format: application/json
Character Encoding: UTF-8

Standard Response Format:

json

{
  "code": 0,           // 0 indicates success, non-zero indicates failure
  "message": "string", // Response message
  "data": {}          // Response data
}

Common Error Codes:

0 - Success
500 - Internal server error
3001 - Resource not found or access denied
3002 - Operation condition not met
3003 - Resource state does not allow this operation
3006 - Resource creation failed

Authentication

All endpoints (except health check) require a Bearer Token in the request header:

http

Authorization: Bearer your_api_secret_key_here

Authentication Error Response Example:

json

{
  "code": 1002,
  "message": "API Key missing, please add Authorization: Bearer xxxxxxxxxxxxx in request header",
  "data": null
}

Possible Authentication Errors:

API Key missing
API Key invalid or disabled
API Key expired
Associated user does not exist

Request Example:

bash

curl -X POST https://agentsben.com/api/v1/orders/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key_here" \
  -d '{"items": [...]}'

Order Management Module

1. Create Order

Add product information to cart and create order (two steps in one).

Endpoint: POST /api/v1/orders/create

Note: When auto_create_parcel is true, a parcel will be created synchronously. This way orders will be automatically packed when they arrive at the warehouse. Currently, auto-shipping is not supported. You need to call the pay parcel API to trigger payment completion. The parcel will be sent via international express after payment.

Request Parameters:

Parameter	Type	Required	Description
items	Array	Yes	Product list
items[].title	String	Yes	Product title
items[].detail_url	String	Yes	Product detail URL
items[].price	Number	Yes	Product price (greater than or equal to 0)
items[].quantity	Number	Yes	Product quantity (greater than or equal to 1)
items[].currency_unit	String	No	Currency unit, supports: USD/EUR/HKD/JPY/CNY, default CNY
items[].pic_url	String	No	Product image URL
items[].express_fee	Number	No	Express fee, default 0
items[].colour	String	No	Color/Specification
items[].size	String	No	Size/Model
items[].order_notes	String	No	Order notes
auto_create_parcel	Boolean	No	Whether to create parcel synchronously, default false
delivery_address	Object	Conditional	Delivery address (required when auto_create_parcel is true)
delivery_address.recipient_name	String	Conditional	Recipient name
delivery_address.phone	String	Conditional	Contact phone (6-20 digits)
delivery_address.address	String	Conditional	Detailed address
delivery_address.post_code	String	Conditional	Postal code (3-20 characters)
delivery_address.recipient_email	String	No	Recipient email
parcel_note	String	No	Parcel notes

Request Example:

json

{
  "items": [
    {
      "title": "Apple iPhone 15 Pro",
      "detail_url": "https://example.com/item/12345",
      "price": 999.99,
      "quantity": 1,
      "currency_unit": "USD",
      "pic_url": "https://example.com/image.jpg",
      "express_fee": 10.00,
      "colour": "Space Black",
      "size": "256GB",
      "order_notes": "Please ship as soon as possible"
    }
  ],
  "auto_create_parcel": true,
  "delivery_address": {
    "recipient_name": "John Doe",
    "phone": "+1234567890",
    "address": "123 Main St, New York, NY",
    "post_code": "10001",
    "recipient_email": "[email protected]"
  },
  "parcel_note": "Fragile, please pack carefully"
}

Response Example (Success):

json

{
  "code": 0,
  "message": "Order and parcel created successfully",
  "data": {
    "order": {
      "order_id": "ORD20231122001",
      "od_item_ids": ["ODITEM001", "ODITEM002"],
      "status": "WaitingForPayment",
      "currency_unit": "CNY",
      "amount_fee": 7199.93,
      "amount_fee_cny": 7199.93,
      "paypal_account": "[email protected]"
    },
    "parcel": {
      "parcel_id": "PKG20231122001",
      "parcel_status": "WaitingForPayment",
      "od_item_ids": ["ODITEM001", "ODITEM002"],
      "address_info": {
        "recipient_name": "John Doe",
        "phone": "+1234567890",
        "address": "123 Main St, New York, NY",
        "post_code": "10001"
      },
      "created_at": "2023-11-22T10:30:00.000Z"
    }
  }
}

Response Example (Order Only):

json

{
  "code": 0,
  "message": "Order created successfully",
  "data": {
    "order": {
      "order_id": "ORD20231122001",
      "od_item_ids": ["ODITEM001"],
      "status": "WaitingForPayment",
      "currency_unit": "CNY",
      "amount_fee": 7199.93,
      "amount_fee_cny": 7199.93,
      "paypal_account": "[email protected]"
    },
    "parcel": null
  }
}

Error Response Example:

json

{
  "code": 1001,
  "message": "Parameter error: items cannot be empty",
  "data": null
}

2. Get Order Details

Query detailed information of a single order item.

Endpoint: POST /api/v1/orders/detail

Request Parameters:

Parameter	Type	Required	Description
od_item_id	String	Yes	Order item ID

Request Example:

json

{
  "od_item_id": "ODITEM001"
}

Response Example:

json

{
  "code": 0,
  "message": "Get order details successfully",
  "data": {
    "od_item_id": "ODITEM001",
    "order_id": "ORD20231122001",
    "title": "Apple iPhone 15 Pro",
    "detail_url": "https://example.com/item/12345",
    "sku_img_url": "https://example.com/image.jpg",
    "sku_props": [
      {"label": "Space Black"},
      {"label": "256GB"}
    ],
    "price": 999.99,
    "express_fee": 10.00,
    "service_fee": 50.00,
    "quantity": 1,
    "status": "WaitingForPayment",
    "paid": 0,
    "paid_amount": 0,
    "order_notes": "Please ship as soon as possible",
    "total_amount": 1059.99,
    "created_at": "2023-11-22T10:30:00.000Z",
    "status_changelog": [
      {
        "od_item_id": "ODITEM001",
        "from_status": null,
        "to_status": "WaitingForPayment",
        "created_at": "2023-11-22T10:30:00.000Z"
      }
    ]
  }
}

Error Response:

json

{
  "code": 3001,
  "message": "Order item does not exist or access denied",
  "data": null
}

3. Pay Order

Pay for order items (using account balance).

Endpoint: POST /api/v1/orders/pay_order_items

Request Parameters:

Parameter	Type	Required	Description
od_item_ids	Array	Yes	Order item ID list

Request Example:

json

{
  "od_item_ids": ["ODITEM001", "ODITEM002"]
}

Response Example (Success):

json

{
  "code": 0,
  "message": "success",
  "data": null
}

Error Response Example:

json

{
  "code": 1,
  "message": "Insufficient balance",
  "data": null
}

4. Request Order Refund

Request refund for order (only supports paid orders).

Endpoint: POST /api/v1/orders/request_refund

Request Parameters:

Parameter	Type	Required	Description
od_item_ids	Array	Yes	Order item ID list

Request Example:

json

{
  "od_item_ids": ["ODITEM001", "ODITEM002"]
}

Response Example (Success):

json

{
  "code": 0,
  "message": "Refund request submitted successfully",
  "data": {
    "od_item_ids": ["ODITEM001", "ODITEM002"],
    "status": "RefundRequested"
  }
}

Error Response Example:

json

{
  "code": 3002,
  "message": "Some order items do not meet refund conditions (unpaid or current status does not allow refund)",
  "data": {
    "cannot_refund_items": [
      {
        "od_item_id": "ODITEM001",
        "status": "WaitingForPayment",
        "paid": 0
      }
    ]
  }
}

5. Delete Order

Delete unpaid order items (paid orders cannot be deleted).

Endpoint: POST /api/v1/orders/delete

Request Parameters:

Parameter	Type	Required	Description
od_item_ids	Array	Yes	Order item ID list (can be empty array)

Request Example:

json

{
  "od_item_ids": ["ODITEM001", "ODITEM002"]
}

Response Example (Success):

json

{
  "code": 0,
  "message": "Deleted successfully",
  "data": {
    "deleted_count": 2,
    "od_item_ids": ["ODITEM001", "ODITEM002"]
  }
}

Error Response Example:

json

{
  "code": 3003,
  "message": "Paid order items cannot be deleted",
  "data": {
    "paid_items": [
      {
        "od_item_id": "ODITEM001",
        "title": "Apple iPhone 15 Pro",
        "paid_balance_confirm_id": "BC001"
      }
    ]
  }
}

Parcel Management Module

6. Create Parcel

Create parcel from existing order items (using default configuration: Route 2, including tax, no insurance).

Endpoint: POST /api/v1/parcel/create

Request Parameters:

Parameter	Type	Required	Description
od_item_ids	Array	Yes	Order item ID list
delivery_address	Object	Yes	Delivery address information
delivery_address.recipient_name	String	Yes	Recipient name
delivery_address.phone	String	Yes	Contact phone
delivery_address.address	String	Yes	Detailed address
delivery_address.post_code	String	Yes	Postal code
delivery_address.recipient_email	String	No	Recipient email
parcel_note	String	No	Parcel notes

Request Example:

json

{
  "od_item_ids": ["ODITEM001", "ODITEM002"],
  "delivery_address": {
    "recipient_name": "John Doe",
    "phone": "+1234567890",
    "address": "123 Main St, New York, NY",
    "post_code": "10001",
    "recipient_email": "[email protected]"
  },
  "parcel_note": "Fragile, please pack carefully"
}

Response Example (Success):

json

{
  "code": 0,
  "message": "success",
  "data": {
    "parcel_id": "PKG20231122001",
    "parcel_status": "WaitingForPayment",
    "od_item_ids": ["ODITEM001", "ODITEM002"],
    "address_info": {
      "recipient_name": "John Doe",
      "phone": "+1234567890",
      "address": "123 Main St, New York, NY",
      "post_code": "10001",
      "recipient_email": "[email protected]"
    },
    "created_at": "2023-11-22T10:30:00.000Z"
  }
}

Error Response Example:

json

{
  "code": 1,
  "message": "Empty order items selected.",
  "data": null
}

7. Get Parcel Details

Query detailed parcel information, including fee information.

Endpoint: POST /api/v1/parcel/detail

Request Parameters:

Parameter	Type	Required	Description
parcel_id	String	Yes	Parcel ID

Request Example:

json

{
  "parcel_id": "PKG20231122001"
}

Response Example:

json

{
  "code": 0,
  "message": "success",
  "data": {
    "parcel": {
      "parcel_id": "PKG20231122001",
      "email": "[email protected]",
      "parcel_status": "WaitingForPayment",
      "delivery_address": {
        "recipient_name": "John Doe",
        "phone": "+1234567890",
        "address": "123 Main St, New York, NY",
        "post_code": "10001"
      },
      "od_item_ids": ["ODITEM001", "ODITEM002"],
      "parcel_note": "Fragile, please pack carefully",
      "total_weight": 1.5,
      "estimated_freight": 150.00,
      "tax_fee": 50.00,
      "insurance_fee": 0,
      "total_fee": 200.00,
      "created_at": "2023-11-22T10:30:00.000Z",
      "updated_at": "2023-11-22T10:30:00.000Z"
    }
  }
}

Error Response:

json

{
  "code": 1,
  "message": "Parcel not found.",
  "data": null
}

8. Delete Parcel

Delete unpaid parcel (paid parcels cannot be deleted).

Endpoint: POST /api/v1/parcel/delete

Request Parameters:

Parameter	Type	Required	Description
parcel_id	String	Yes	Parcel ID

Request Example:

json

{
  "parcel_id": "PKG20231122001"
}

Response Example (Success):

json

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "Parcel deleted successfully."
  }
}

Error Response Example:

json

{
  "code": 1,
  "message": "Parcel has been paid and cannot be deleted",
  "data": null
}

9. Pay Parcel

Pay parcel shipping fee (using account balance).

Endpoint: POST /api/v1/parcel/pay

Request Parameters:

Parameter	Type	Required	Description
parcel_id	String	Yes	Parcel ID

Request Example:

json

{
  "parcel_id": "PKG20231122001"
}

Response Example (Success):

json

{
  "code": 0,
  "message": "success",
  "data": null
}

Error Response Example:

json

{
  "code": 1,
  "message": "Insufficient balance",
  "data": null
}

Complete Business Flow Examples

Scenario 1: Create Order and Parcel Simultaneously

bash

# Step 1: Create order and parcel synchronously
curl -X POST https://agentsben.com/api/v1/orders/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "items": [
      {
        "title": "Product Name",
        "detail_url": "https://example.com/item/123",
        "price": 100.00,
        "quantity": 2,
        "currency_unit": "CNY"
      }
    ],
    "auto_create_parcel": true,
    "delivery_address": {
      "recipient_name": "John Doe",
      "phone": "+1234567890",
      "address": "123 Main St, New York",
      "post_code": "10001"
    }
  }'

# Step 2: Pay for order
curl -X POST https://agentsben.com/api/v1/orders/pay_order_items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "od_item_ids": ["ODITEM001"]
  }'

# Step 3: Pay for parcel
curl -X POST https://agentsben.com/api/v1/parcel/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "parcel_id": "PKG20231122001"
  }'

Scenario 2: Create Order and Parcel Separately

bash

# Step 1: Create order only
curl -X POST https://agentsben.com/api/v1/orders/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "items": [
      {
        "title": "Product Name",
        "detail_url": "https://example.com/item/123",
        "price": 100.00,
        "quantity": 2
      }
    ]
  }'

# Step 2: Query order details
curl -X POST https://agentsben.com/api/v1/orders/detail \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "od_item_id": "ODITEM001"
  }'

# Step 3: Pay for order
curl -X POST https://agentsben.com/api/v1/orders/pay_order_items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "od_item_ids": ["ODITEM001"]
  }'

# Step 4: Create parcel
curl -X POST https://agentsben.com/api/v1/parcel/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "od_item_ids": ["ODITEM001"],
    "delivery_address": {
      "recipient_name": "John Doe",
      "phone": "+1234567890",
      "address": "123 Main St, New York",
      "post_code": "10001"
    }
  }'

# Step 5: Pay for parcel
curl -X POST https://agentsben.com/api/v1/parcel/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret_key" \
  -d '{
    "parcel_id": "PKG20231122001"
  }'

Notes

1. API Key Management

API Key format: Authorization: Bearer xxxxxxxxxxxxx
API Key status: active (activated) or inactive (disabled)
Disabled or expired API Keys cannot be used
Please keep your API Key secure and do not share it with others

2. Rate Limiting

All endpoints have rate limit protection
Concurrent request limit: The same request cannot be initiated repeatedly while being processed
Retry wait time: 10 seconds
If you receive a rate limit error, please wait for the specified time before retrying

3. Currency Support

Supported currency units:

CNY - Chinese Yuan (default)
USD - US Dollar
EUR - Euro
HKD - Hong Kong Dollar
JPY - Japanese Yen

4. Order Status Description

WaitingForPayment - Waiting for payment
Paid - Paid
Purchased - Purchased
Shipped - Shipped
RefundRequested - Refund requested
Refunded - Refunded
Cancelled - Cancelled

5. Parcel Status Description

WaitingForPayment - Waiting for payment
Paid - Paid
InTransit - In transit
Delivered - Delivered

6. Other Notes

Service fee is automatically calculated when creating orders
Parcels use default configuration: Route 2, including tax, no insurance
Paid orders and parcels cannot be deleted
Only paid orders can request refunds
All amounts are in the smallest unit of the corresponding currency (e.g., yuan, dollar)

Technical Support

For any questions, please contact our support team.

API v1 Documentation ​

Table of Contents ​

Overview ​

Authentication ​

Order Management Module ​

1. Create Order ​

2. Get Order Details ​

3. Pay Order ​

4. Request Order Refund ​

5. Delete Order ​

Parcel Management Module ​

6. Create Parcel ​

7. Get Parcel Details ​

8. Delete Parcel ​

9. Pay Parcel ​

Complete Business Flow Examples ​

Scenario 1: Create Order and Parcel Simultaneously ​

Scenario 2: Create Order and Parcel Separately ​

Notes ​

1. API Key Management ​

2. Rate Limiting ​

3. Currency Support ​

4. Order Status Description ​

5. Parcel Status Description ​

6. Other Notes ​

Technical Support ​

API v1 Documentation

Table of Contents

Overview

Authentication

Order Management Module

1. Create Order

2. Get Order Details

3. Pay Order

4. Request Order Refund

5. Delete Order

Parcel Management Module

6. Create Parcel

7. Get Parcel Details

8. Delete Parcel

9. Pay Parcel

Complete Business Flow Examples

Scenario 1: Create Order and Parcel Simultaneously

Scenario 2: Create Order and Parcel Separately

Notes

1. API Key Management

2. Rate Limiting

3. Currency Support

4. Order Status Description

5. Parcel Status Description

6. Other Notes

Technical Support