Chuyển tới nội dung chính

API Đơn hàng


Tạo đơn hàng

MethodPOST
URL/api/order/create-order

Body request

{
"address_id": 2,
"consignee_name": "sarenda mcguire",
"consignee_phone": "",
"consignee_address": "6105 W Elmwood Dr",
"consignee_address_other": "",
"consignee_country": "US",
"consignee_city": "Wildomar",
"consignee_postal_code": "57718",
"consignee_state_code": "SD",
"order_number": "DEV123456789",
"product_name": "Metal",
"product_price": 5.5,
"length": 1.93,
"width": 108,
"height": 1.9,
"weight": 1.1,
"service_code": "EPK",
"service_add": "",
"money_collection": 0,
"order_code_upstream_partner": "partner_of_partner",
"package_option": "818",
"unit_type": "cm-g",
"label_sender": "WRIGLEYS Cool Air",
"mode": null
}

Giải thích

No.Field NameData TypeDescription
1address_idLongMã kho hàng (3.1)
2consignee_nameStringHọ tên người nhận
3consignee_phoneStringSố điện thoại người nhận
4consignee_addressStringĐịa chỉ người nhận 1
5consignee_address_otherStringĐịa chỉ người nhận 2
6consignee_countryStringMã quốc gia (fix: US)
7consignee_cityStringTỉnh / thành phố (3.2)
8consignee_postal_codeString5 chữ số (người dùng nhập)
9consignee_state_codeStringState code (3.2)
10order_numberStringMã đơn hàng của đối tác
11product_nameStringNội dung hàng hóa
12product_priceDecimalGiá trị hàng hóa
13lengthDecimalChiều dài (cm)
14widthDecimalChiều rộng (cm)
15heightDecimalChiều cao (cm)
16weightDecimalTrọng lượng (gram)
17service_codeStringDịch vụ chính (liên hệ)
18service_addStringDịch vụ gia tăng
19money_collectionDecimalSố tiền thu hộ
20order_code_upstream_partnerStringMã đối tác của đối tác
21package_optionStringPin lithium: 818 (Marked), 820 (Unmarked). Với dịch vụ LBE6 dùng mã đầy đủ: 8181, 8182, 8201, 8202. Bỏ trống nếu không có PIN
22unit_typeStringĐơn vị của các chiều và cân nặng. Mặc định không điền là cm-g (mm-g,cm-g,cm-kg,in-lb)
23label_senderStringField này bổ sung tên đại lý người gửi, nếu không set thì lấy mặc định trong label_sender trong customer đã set
24modeStringTruyền "advanced" để dùng Advanced Mode (xem mục bên dưới). Bỏ trống hoặc null cho Simple Mode

Validation Rules

thông tin

service_code cần liên hệ để lấy danh sách dịch vụ khả dụng. Danh sách service phải tồn tại trong hệ thống BELL.

address_id

  • Bắt buộc, kiểu số nguyên.
  • Mỗi service chỉ chấp nhận một số address_id cụ thể (liên hệ để được cung cấp).

order_number

  • Bắt buộc, tối đa 50 ký tự.
  • Phải unique theo từng customer (không trùng mã đơn đã tạo trước đó).
  • Với service US_UPS_GROUNDUS_UNIUNI_D: chỉ cho phép ký tự a-z A-Z 0-9 _ ( ) - , # space.

consignee_name

  • Bắt buộc, tối đa 100 ký tự.
  • Với service US_UPS_GROUND: phải bao gồm họ và tên đầy đủ (ít nhất 2 từ cách nhau bởi khoảng trắng).

consignee_phone

  • Không bắt buộc.
  • Nếu có, phải đúng 10 chữ số (ví dụ: 0123456789).

consignee_email

  • Không bắt buộc.
  • Nếu có, phải đúng format email, tối đa 50 ký tự.

consignee_country

  • Bắt buộc, mã quốc gia 2 ký tự (ISO-2).

consignee_state_code

  • Bắt buộc khi consignee_country = US.
  • Không bắt buộc với các quốc gia khác.
  • Tối đa 50 ký tự.

consignee_postal_code

  • Bắt buộc, tối đa 20 ký tự.
  • Format theo quốc gia:
    • US: 5 chữ số hoặc 5+4 (ví dụ: 57718 hoặc 57718-1234).
    • GB/UK: format Royal Mail (ví dụ: SW1A 1AA).
  • Với service US_UNIUNIUS_UNIUNI_D: postal code phải nằm trong danh sách vùng phục vụ của UniUni.

consignee_address

  • Bắt buộc, tối đa 200 ký tự.

consignee_address_other

  • Không bắt buộc, tối đa 200 ký tự.

unit_type

  • Không bắt buộc. Mặc định: cm-g.
  • Giá trị cho phép: mm-g, cm-g, cm-kg, in-lb.

length / width / height

  • Bắt buộc, giá trị số > 0.
  • Giới hạn tối đa: 150 cm (quy đổi theo unit_type).

weight

  • Bắt buộc, giá trị số > 0.

product_name

  • Không bắt buộc, tối đa 100 ký tự.

product_price

  • Không bắt buộc, giá trị số ≥ 0.

service_add

  • Không bắt buộc, tối đa 100 ký tự.

label_sender

  • Không bắt buộc, tối đa 50 ký tự.
  • Nếu không set, lấy mặc định từ cài đặt label_sender của customer.

package_option (Lithium Battery)

  • Không bắt buộc.
  • Chỉ được sử dụng với service: EPK, LBE, LBE6.
  • Giá trị theo service:
ServiceGiá trị cho phépMô tả
EPK, LBE818, 820818 = Marked, 820 = Unmarked
LBE68181, 8182, 8201, 8202Mã đầy đủ: 818x = Marked, 820x = Unmarked
  • Khi có package_option, các kiện hàng (packages) phải thỏa mãn giới hạn:
ServiceTrọng lượng tối đaLength + 2×Width + 2×Height
EPK≤ 11 lbs< 108 inch
LBE≤ 11 lbs< 108 inch
LBE6≤ 11 lbs< 108 inch
thông tin

Nếu hàng hoá có PIN package_option cần nhập mã phù hợp theo service.

và cần dán mark https://express.bellvn.com/UN-3091.jpg hoặc https://express.bellvn.com/UN-3481.jpg

Response

{
"error": false,
"ref": null,
"message": "Tạo đơn thành công",
"data": "DEV123456789",
"warnings": []
}

Giải thích

STTTên trườngKiểu dữ liệuMô tả
1errorbooleanTrạng thái lỗi
2refStringMã tham chiếu giao dịch
3messageStringThông báo
4dataStringMã đơn hàng của BELL
5warningsArrayDanh sách cảnh báo khi hệ thống tự động chuyển ký tự sang ASCII (dịch vụ US_UNIUNI_D, US_UPS_GROUND, LBE6)

Mỗi phần tử trong warnings:

FieldMô tả
fieldTên trường bị chuyển đổi
labelTên hiển thị của trường
originalGiá trị gốc trước khi chuyển đổi
sanitizedGiá trị sau khi chuyển sang ASCII
messageMô tả hành động tự động

Tạo đơn hàng nâng cao (Advanced Mode)

Dành cho các dịch vụ quốc tế yêu cầu khai báo chi tiết hàng hóa và hỗ trợ nhiều kiện hàng (multi-package).

MethodPOST
URL/api/order/create-order
Lưu ý

Các service sau bắt buộc phải sử dụng mode advanced:

  • UPS_WW_SAVER2, UPS_WW_SAVER
  • UPS_WW_EXPEDITED2, UPS_WW_EXPEDITED
  • UPS_WW_EXPRESS2, UPS_WW_EXPRESS
  • FEDEX_IPE2, FEDEX_IPE, FEDEX_IP2, FEDEX_IP
  • FEDEX_IE2, FEDEX_IE, FEDEX_ICP2, FEDEX_ICP
  • FEDEX_IP_SBP, FEDEX_IP_SBP2

Nếu sử dụng các service trên mà không truyền mode: "advanced" hoặc thiếu thông tin goods, hệ thống sẽ trả lỗi validation.

ASCII Auto-Sanitize

Với các dịch vụ US_UNIUNI_D, US_UPS_GROUND, LBE6: hệ thống tự động chuyển các ký tự tiếng Việt có dấu sang ASCII (ví dụ: á → a, đ → d) cho các trường tên/địa chỉ. Response sẽ kèm mảng warnings liệt kê các trường đã được tự động chuyển đổi.

Body request

{
"mode": "advanced",
"address_id": 0,
"service_code": "UPS_WW_EXPRESS",
"order_number": "PARTNER-ADV-001",
"order_code_upstream_partner": "UPSTREAM-001",
"consignee_name": "John Doe",
"consignee_company": "ACME Corp",
"consignee_phone": "2125550001",
"consignee_email": "john@example.com",
"consignee_country": "US",
"consignee_state_code": "NY",
"consignee_city": "New York",
"consignee_postal_code": "10001",
"consignee_address": "123 Main Street",
"consignee_address_other": "Suite 100",
"unit_type": "cm-g",
"package_option": null,
"label_sender": "MY STORE",
"service_add": "",
"packages": [
{
"weight": 1000,
"length": 30,
"width": 20,
"height": 15,
"goods": [
{
"name_en": "Electronic Device",
"name_vi": "Thiết bị điện tử",
"brand": "BrandName",
"packaging_type": "Box",
"origin": "CN",
"price": 150.00,
"quantity": 2,
"unit": "pcs",
"hs_code": "8471.30",
"material": "Plastic"
}
]
},
{
"weight": 500,
"length": 25,
"width": 18,
"height": 10,
"goods": [
{
"name_en": "Accessories",
"name_vi": "Phụ kiện",
"brand": null,
"packaging_type": null,
"origin": "VN",
"price": 25.50,
"quantity": 5,
"unit": "pcs",
"hs_code": null,
"material": null
}
]
}
],
"extra_fields": {
"trade_terms": "DDP",
"tax_type": "IOSS",
"tax_number": "IOSS-123456789",
"signature_required": true
}
}

So sánh Simple vs Advanced

Đặc điểmSimple (mặc định)Advanced
Số kiện hàng1 kiện (truyền thẳng length, width, height, weight)Nhiều kiện (mảng packages)
Khai báo hàng hóaproduct_name + product_priceMảng goods chi tiết (tên, xuất xứ, HS code, ...)
Dịch vụ hỗ trợTất cả dịch vụ nội địaBắt buộc cho dịch vụ quốc tế (UPS WW, FedEx IP)
Extra fieldsKhôngHỗ trợ trade_terms, tax_type, tax_number

Giải thích các field bổ sung

No.Field NameData TypeDescription
1modeStringBắt buộc với service nâng cao. Giá trị: "advanced"
2consignee_companyStringTên công ty người nhận. Bắt buộc với service advanced, tối đa 100 ký tự
3consignee_emailStringEmail người nhận. Không bắt buộc, tối đa 50 ký tự
4packagesArrayMảng các kiện hàng. Bắt buộc, tối thiểu 1 kiện
5packages[].weightDecimalTrọng lượng kiện (theo unit_type, mặc định gram)
6packages[].lengthDecimalChiều dài (theo unit_type, mặc định cm)
7packages[].widthDecimalChiều rộng (theo unit_type, mặc định cm)
8packages[].heightDecimalChiều cao (theo unit_type, mặc định cm)
9packages[].goodsArrayMảng hàng hóa trong kiện này. Bắt buộc, tối thiểu 1 mục
10packages[].goods[].name_enStringTên hàng hóa (tiếng Anh). Bắt buộc, tối đa 100 ký tự
11packages[].goods[].name_viStringTên hàng hóa (tiếng Việt). Không bắt buộc
12packages[].goods[].brandStringThương hiệu. Không bắt buộc
13packages[].goods[].packaging_typeStringLoại đóng gói. Không bắt buộc
14packages[].goods[].originStringMã quốc gia xuất xứ (ISO-2). Bắt buộc, 2 ký tự
15packages[].goods[].priceDecimalGiá trị hàng hóa (USD). Bắt buộc, tối thiểu 0.01
16packages[].goods[].quantityIntegerSố lượng. Bắt buộc, tối thiểu 1
17packages[].goods[].unitStringĐơn vị tính (vd: pcs, kg, set). Không bắt buộc
18packages[].goods[].hs_codeStringMã HS Code hải quan. Không bắt buộc
19packages[].goods[].materialStringChất liệu. Không bắt buộc
20extra_fieldsObjectThông tin thuế/thương mại bổ sung. Không bắt buộc
21extra_fields.trade_termsStringĐiều khoản thương mại: DDU, DDP, CIP, C&F. Với FEDEX_ICP/FEDEX_ICP2 chỉ được DDP
22extra_fields.tax_typeStringLoại thuế: IOSS, EORI, VAT
23extra_fields.tax_numberStringMã số thuế tương ứng (tối đa 100 ký tự)
24extra_fields.signature_requiredBooleanYêu cầu chữ ký khi giao hàng. Chỉ hỗ trợ dịch vụ JingDong, chỉ dùng trong Advanced Mode

Validation cho Advanced Mode

packages

  • Bắt buộc, mảng tối thiểu 1 phần tử.
  • Mỗi kiện phải có đầy đủ: weight, length, width, height.
  • Giá trị phải > 0. Kích thước tối đa 150cm (quy đổi theo unit_type).

goods (với service bắt buộc advanced)

  • Bắt buộc, mảng tối thiểu 1 phần tử.
  • Mỗi mục hàng hóa phải có:
    • name_en: bắt buộc, tối đa 100 ký tự
    • origin: bắt buộc, 2 ký tự (mã quốc gia ISO-2)
    • price: bắt buộc, số > 0 (tối thiểu 0.01)
    • quantity: bắt buộc, số nguyên ≥ 1

extra_fields

  • Không bắt buộc.
  • Nếu truyền, các giá trị bên trong đều là string hoặc boolean.

extra_fields.trade_terms

  • Giá trị cho phép: DDU, DDP, CIP, C&F.
  • Với dịch vụ FEDEX_ICPFEDEX_ICP2: chỉ chấp nhận DDP.

extra_fields.tax_type

  • Giá trị cho phép: IOSS, EORI, VAT.

extra_fields.signature_required

  • Kiểu boolean. Chỉ hỗ trợ dịch vụ JingDong.
  • Chỉ có thể dùng trong Advanced Mode — bị từ chối (prohibited) nếu truyền ở Simple Mode.

Quy đổi đơn vị

Hệ thống lưu trữ nội bộ theo mm-g. Khi truyền unit_type khác, hệ thống tự quy đổi:

unit_typeCân nặng → gramKích thước → mm
mm-g×1×1
cm-g×1×10
cm-kg×1000×10
in-lb×453.59×25.4

Response

Giống response tạo đơn thường:

{
"error": false,
"ref": null,
"message": "Tạo đơn thành công",
"data": "BELL240625120345123"
}

Ví dụ lỗi validation

{
"error": true,
"ref": null,
"message": "Service này yêu cầu mode \"advanced\" với đầy đủ thông tin goods.",
"errors": {
"goods.0.origin": ["origin là bắt buộc"],
"goods.0.price": ["price là bắt buộc"]
},
"data": null
}

Hủy đơn hàng

MethodPOST
URL/api/order/cancel-order

Payload request

No.Field NameData TypeDescription
1order_numberStringMã vận đơn của BELL

Response

{
"error": false,
"ref": null,
"message": "Thành công",
"data": null
}

In nhãn vận đơn

MethodGET
URL/api/order/print-order/{order_number}

Path parameter

No.Field NameData TypeDescription
1order_numberStringMã vận đơn BELL hoặc mã đơn đối tác (order_code_partner)

Response

{
"error": false,
"ref": null,
"message": "Thành công",
"data": {
"orderNumber": "BELL1202103548",
"tracking": "42080521921449037400250000264",
"labelFormat": "PDF",
"labelSize": "4x6",
"label": "",
"labelUrl": "https://storage.bellvn.com/labels/BELL1202103548.pdf",
"receiptUrls": [
"https://storage.bellvn.com/receipts/BELL1202103548_1.pdf"
],
"trackings": [
{
"tracking_code": "42080521921449037400250000264",
"package_no": 1
}
]
}
}

Giải thích

No.Field NameData TypeDescription
1errorbooleanTrạng thái lỗi
2refStringMã tham chiếu
3messageStringThông báo
4data.orderNumberStringMã đơn hàng truy vấn
5data.trackingStringTracking number chính của đơn
6data.labelFormatStringĐịnh dạng file nhãn: PDF, GIF, PNG, JPG (hoặc rỗng nếu chưa có nhãn)
7data.labelSizeStringKích thước nhãn (mặc định 4x6)
8data.labelStringNội dung nhãn Base64 (hiện luôn rỗng — dùng labelUrl thay thế)
9data.labelUrlStringURL file nhãn vận đơn để tải/xem trực tuyến
10data.receiptUrlsArrayDanh sách URL file biên lai (waybill receipt). Có thể rỗng []
11data.trackingsArrayDanh sách tracking theo từng kiện (multi-package). Rỗng [] nếu đơn 1 kiện hoặc chưa có tracking
thông tin

receiptUrlstrackings chỉ có giá trị với các đơn hàng dịch vụ JingDong (đơn nhiều kiện hoặc có biên lai riêng). Với các dịch vụ khác, hai trường này trả về mảng rỗng.


Tra cứu thông tin đơn hàng

MethodGET
URL/api/order/get-order-info/{id}

Path parameter

No.Field NameData TypeDescription
1idStringMã đơn hàng BELL (order_code), mã đối tác (order_code_partner), hoặc ID nội bộ (id)

Response

{
"status": "success",
"message": "Get order info successfully",
"data": {
"order_code": "BELL240625120345123",
"order_code_partner": "DEV123456789",
"status": "Label",
"service": "EPK",
"reason": null,
"tracking_code": "42080521921449037400250000264",
"tracking_label_url": "https://storage.bellvn.com/labels/BELL240625120345123.pdf",
"carrier": "USPS",
"ship_date": "2024-06-25",
"consignee_name": "sarenda mcguire",
"consignee_phone": "0123456789",
"consignee_company": null,
"consignee_country": "US",
"consignee_state": "SD",
"consignee_city": "Wildomar",
"consignee_postal_code": "57718",
"consignee_address": "6105 W Elmwood Dr",
"consignee_address2": null,
"created_date": "2024-06-25 12:03:45"
}
}

Giải thích response

No.Field NameData TypeDescription
1statusStringsuccess hoặc error
2messageStringThông báo kết quả
3data.order_codeStringMã vận đơn BELL
4data.order_code_partnerStringMã đơn hàng của đối tác
5data.statusStringTrạng thái đơn hàng (xem bảng bên dưới)
6data.serviceStringMã dịch vụ
7data.reasonStringLý do (ví dụ: lý do hủy đơn). Null nếu không có
8data.tracking_codeStringTracking number của carrier
9data.tracking_label_urlStringURL file nhãn vận đơn
10data.carrierStringTên carrier vận chuyển
11data.ship_dateStringNgày gửi hàng
12data.consignee_nameStringTên người nhận
13data.consignee_phoneStringSố điện thoại người nhận
14data.consignee_companyStringCông ty người nhận
15data.consignee_countryStringMã quốc gia (ISO-2)
16data.consignee_stateStringBang / tỉnh
17data.consignee_cityStringThành phố
18data.consignee_postal_codeStringMã bưu chính
19data.consignee_addressStringĐịa chỉ người nhận
20data.consignee_address2StringĐịa chỉ người nhận 2
21data.created_dateStringThời gian tạo đơn

Bảng trạng thái đơn hàng

Giá trịMô tả
InitMới tạo
LabelĐã có nhãn
In TransitĐang vận chuyển
Out For DeliveryĐang giao hàng
DeliveredĐã giao thành công
ExceptionCó vấn đề phát sinh
VoidĐã hủy
Request CancelYêu cầu hủy
UnknownKhông xác định
DraftBản nháp

Lỗi thường gặp

{
"status": "error",
"message": "Order not found"
}
{
"status": "error",
"message": "Order not belong to Customer"
}

Track shipment

MethodGET
URL/api/order/tracking/{order_number}

Path request

No.Field NameData TypeDescription
1order_numberStringMã vận đơn của BELL

Response

{
"error": false,
"ref": null,
"message": "Thành công",
"data": [
{
"trackingNumber": "BELL2512171654532484",
"code": "12345678900",
"city": "City 0",
"stateCode": "State 0",
"zipCode": "Zip 0",
"countryCode": "Country 0",
"eventDate": "2025-12-18T03:57:04.896549Z",
"eventStatus": "LabelCreated 0",
"note": "Label Created"
},
{
"trackingNumber": "BELL2512171654532484",
"code": "12345678901",
"city": "City 1",
"stateCode": "State 1",
"zipCode": "Zip 1",
"countryCode": "Country 1",
"eventDate": "2025-12-18T03:57:04.896558Z",
"eventStatus": "LabelCreated 1",
"note": "Label Created"
}
]
}

Giải thích

No.Field NameData TypeDescription
1errorbooleanTrạng thái lỗi (false = thành công)
2refStringMã tham chiếu yêu cầu (có thể null)
3messageStringThông báo kết quả xử lý
4dataArrayDanh sách sự kiện tracking
5data[].trackingNumberStringMã vận đơn / tracking number
6data[].codeStringMã sự kiện hoặc mã tham chiếu nội bộ
7data[].cityStringThành phố phát sinh sự kiện
8data[].stateCodeStringMã bang / tỉnh
9data[].zipCodeStringMã bưu chính
10data[].countryCodeStringMã quốc gia (ISO-2)
11data[].eventDateStringThời gian xảy ra sự kiện (ISO 8601, UTC)
12data[].eventStatusStringTrạng thái / nội dung sự kiện tracking
13data[].noteStringGhi chú/mô tả trạng thái

Tra cứu cước phí đơn hàng

MethodGET
URL/api/price/get-price/{order_number}

Path request

No.Field NameData TypeDescription
1order_numberStringMã vận đơn của BELL

Response

{
"error": false,
"message": "Success",
"data": [
{
"order_code": "BELL2512171654532484",
"amount": 15.50,
"type": "MAIN"
}
]
}

Giải thích

No.Field NameData TypeDescription
1errorbooleanTrạng thái lỗi (false = thành công)
2messageStringThông báo kết quả xử lý
3dataArrayDanh sách chi tiết cước phí
4data[].order_codeStringMã vận đơn
5data[].amountDecimalSố tiền cước
6data[].typeStringLoại phí (MAIN: cước chính, hoặc phụ phí khác)
thông tin

API chỉ trả về cước phí của các đơn hàng thuộc invoice đang active. Nếu đơn chưa được tính cước hoặc chưa có invoice, sẽ trả về lỗi.