API Đơn hàng

---

Tạo đơn hàng

Method	POST
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 Name	Data Type	Description
1	address_id	Long	Mã kho hàng (3.1)
2	consignee_name	String	Họ tên người nhận
3	consignee_phone	String	Số điện thoại người nhận
4	consignee_address	String	Địa chỉ người nhận 1
5	consignee_address_other	String	Địa chỉ người nhận 2
6	consignee_country	String	Mã quốc gia (fix: US)
7	consignee_city	String	Tỉnh / thành phố (3.2)
8	consignee_postal_code	String	5 chữ số (người dùng nhập)
9	consignee_state_code	String	State code (3.2)
10	order_number	String	Mã đơn hàng của đối tác
11	product_name	String	Nội dung hàng hóa
12	product_price	Decimal	Giá trị hàng hóa
13	length	Decimal	Chiều dài (cm)
14	width	Decimal	Chiều rộng (cm)
15	height	Decimal	Chiều cao (cm)
16	weight	Decimal	Trọng lượng (gram)
17	service_code	String	Dịch vụ chính (liên hệ)
18	service_add	String	Dịch vụ gia tăng
19	money_collection	Decimal	Số tiền thu hộ
20	order_code_upstream_partner	String	Mã đối tác của đối tác
21	package_option	String	Pin 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
22	unit_type	String	Đơ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)
23	label_sender	String	Field 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
24	mode	String	Truyề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_GROUND và US_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_UNIUNI và US_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:

Service	Giá trị cho phép	Mô tả
EPK, LBE	818, 820	818 = Marked, 820 = Unmarked
LBE6	8181, 8182, 8201, 8202	Mã đầ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:

Service	Trọng lượng tối đa	Length + 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": [],
  "zone": "002"
}

Giải thích

STT	Tên trường	Kiểu dữ liệu	Mô tả
1	error	boolean	Trạng thái lỗi
2	ref	String	Mã tham chiếu giao dịch
3	message	String	Thông báo
4	data	String	Mã đơn hàng của BELL
5	warnings	Array	Danh 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)
6	zone	String/null	Zone của tuyến vận chuyển. null nếu không xác định được zone

Zone

Response tạo đơn trả thêm trường zone ở cấp cao nhất. Trường này có kiểu String/null; giá trị được giữ nguyên dưới dạng chuỗi (ví dụ: "002"). Nếu không xác định được zone, giá trị là null. Trường zone không được trả trong response lỗi.

Mỗi phần tử trong warnings:

Field	Mô tả
field	Tên trường bị chuyển đổi
label	Tên hiển thị của trường
original	Giá trị gốc trước khi chuyển đổi
sanitized	Giá trị sau khi chuyển sang ASCII
message	Mô 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).

Method	POST
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ểm	Simple (mặc định)	Advanced
Số kiện hàng	1 kiện (truyền thẳng length, width, height, weight)	Nhiều kiện (mảng packages)
Khai báo hàng hóa	product_name + product_price	Mả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 địa	Bắt buộc cho dịch vụ quốc tế (UPS WW, FedEx IP)
Extra fields	Không	Hỗ trợ trade_terms, tax_type, tax_number

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

No.	Field Name	Data Type	Description
1	mode	String	Bắt buộc với service nâng cao. Giá trị: "advanced"
2	consignee_company	String	Tên công ty người nhận. Bắt buộc với service advanced, tối đa 100 ký tự
3	consignee_email	String	Email người nhận. Không bắt buộc, tối đa 50 ký tự
4	packages	Array	Mảng các kiện hàng. Bắt buộc, tối thiểu 1 kiện
5	packages[].weight	Decimal	Trọng lượng kiện (theo unit_type, mặc định gram)
6	packages[].length	Decimal	Chiều dài (theo unit_type, mặc định cm)
7	packages[].width	Decimal	Chiều rộng (theo unit_type, mặc định cm)
8	packages[].height	Decimal	Chiều cao (theo unit_type, mặc định cm)
9	packages[].goods	Array	Mảng hàng hóa trong kiện này. Bắt buộc, tối thiểu 1 mục
10	packages[].goods[].name_en	String	Tên hàng hóa (tiếng Anh). Bắt buộc, tối đa 100 ký tự
11	packages[].goods[].name_vi	String	Tên hàng hóa (tiếng Việt). Không bắt buộc
12	packages[].goods[].brand	String	Thương hiệu. Không bắt buộc
13	packages[].goods[].packaging_type	String	Loại đóng gói. Không bắt buộc
14	packages[].goods[].origin	String	Mã quốc gia xuất xứ (ISO-2). Bắt buộc, 2 ký tự
15	packages[].goods[].price	Decimal	Giá trị hàng hóa (USD). Bắt buộc, tối thiểu 0.01
16	packages[].goods[].quantity	Integer	Số lượng. Bắt buộc, tối thiểu 1
17	packages[].goods[].unit	String	Đơn vị tính (vd: pcs, kg, set). Không bắt buộc
18	packages[].goods[].hs_code	String	Mã HS Code hải quan. Không bắt buộc
19	packages[].goods[].material	String	Chất liệu. Không bắt buộc
20	extra_fields	Object	Thông tin thuế/thương mại bổ sung. Không bắt buộc
21	extra_fields.trade_terms	String	Điều khoản thương mại: DDU, DDP, CIP, C&F. Với FEDEX_ICP/FEDEX_ICP2 chỉ được DDP
22	extra_fields.tax_type	String	Loại thuế: IOSS, EORI, VAT
23	extra_fields.tax_number	String	Mã số thuế tương ứng (tối đa 100 ký tự)
24	extra_fields.signature_required	Boolean	Yê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_ICP và FEDEX_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_type	Cân nặng → gram	Kí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
}

---

Chỉnh sửa địa chỉ đơn lỗi và gửi lại

Dùng cho đơn đang ở trạng thái Error (status = 11) do nhà vận chuyển từ chối vì thông tin địa chỉ người nhận. API lưu địa chỉ mới và đưa đơn vào luồng gửi lại, giữ nguyên mã đơn BELL — không tạo đơn mới.

Request là bất đồng bộ: BELL trả về 202 ngay sau khi lưu địa chỉ và xếp hàng, rồi mới gọi sang nhà vận chuyển. Kết quả cuối cùng lấy bằng cách tra cứu đơn (xem Theo dõi kết quả).

Method	POST
URL	/api/order/edit-order

Quy trình khuyến nghị

1. Gọi /api/order/get-order-info/{order_number} để đọc status và processing_error — biết chính xác trường nào cần sửa.
2. Gọi /api/order/edit-order với các field địa chỉ cần thay đổi.
3. Nhận 202 = yêu cầu đã được xếp hàng. Tra lại /api/order/get-order-info/{order_number} để lấy kết quả cuối.
4. Nếu bị lỗi, đọc code trong response lỗi để xử lý (xem bảng mã kết quả).

Body request

{
  "order_code": "BELL240625120345123",
  "consignee_country": "US",
  "consignee_state_code": "CA",
  "consignee_city": "San Francisco",
  "consignee_postal_code": "94105",
  "consignee_address": "123 Main Street",
  "consignee_address_other": "Suite 200"
}

Giải thích

No.	Field Name	Data Type	Description
1	order_code	String	Bắt buộc. Mã vận đơn BELL (order_code), tối đa 100 ký tự. Không dùng mã đối tác hoặc mã nhà vận chuyển
2	consignee_country	String	Mã quốc gia (ISO-2), tối đa 2 ký tự
3	consignee_state_code	String	State code, tối đa 50 ký tự. Bắt buộc với US và các dịch vụ advanced
4	consignee_city	String	Tỉnh / thành phố, tối đa 50 ký tự
5	consignee_postal_code	String	Mã bưu chính, tối đa 20 ký tự. Theo đúng quy tắc quốc gia / UniUni ở Validation Rules
6	consignee_address	String	Địa chỉ người nhận 1, tối đa 200 ký tự
7	consignee_address_other	String	Địa chỉ người nhận 2, tối đa 200 ký tự. Cho phép null để xoá

Quy tắc chỉnh sửa

• Phải truyền ít nhất một field địa chỉ. Chỉ truyền order_code sẽ bị từ chối VALIDATION_FAILED.
• Field địa chỉ không truyền thì giữ nguyên giá trị đang lưu. Truyền lại đúng giá trị cũ vẫn được coi là yêu cầu gửi lại đơn.
• Chỉ 6 field địa chỉ trên là được phép. Mọi key khác (address_id, service_code, status, consignee_name, consignee_phone, packages, goods, extra_fields, các field tiền...) đều bị từ chối, kể cả khi truyền null.
• Kho gửi, mã đơn BELL, dịch vụ, kiện hàng và hàng hoá không thay đổi. Muốn sửa các thông tin này phải huỷ đơn và tạo lại.
• Địa chỉ mới được validate theo đúng ràng buộc của dịch vụ đang gắn với đơn. consignee_country được tự chuẩn hoá sang chữ in hoa và UK → GB.
• Với các dịch vụ yêu cầu ASCII (US_UNIUNI_D, US_UPS_GROUND, LBE6), địa chỉ gửi lên được tự chuyển sang ASCII và response trả về mảng warnings tương ứng.

Điều kiện đơn hợp lệ

Đơn phải thoả tất cả điều kiện sau, nếu không sẽ nhận 409:

• Thuộc đúng customer đang gọi API (sai chủ sở hữu trả 404, không phân biệt với đơn không tồn tại).
• Đang ở trạng thái Error (status = 11), chưa bị xoá.
• Chưa có mã đơn phía nhà vận chuyển và chưa có tracking.
• Không có lượt gửi lại nào đang xử lý.

cảnh báo

Không import, sửa hay huỷ đơn từ giao diện trong lúc một lượt gửi lại đang chạy. Mỗi đơn chỉ xử lý một lượt tại một thời điểm.

Response thành công (202)

Envelope ngắn, giống API tạo đơn:

{
  "error": false,
  "ref": null,
  "message": "Cập nhật đơn thành công",
  "data": "BELL240625120345123",
  "warnings": []
}

Giải thích

No.	Field Name	Data Type	Description
1	error	boolean	false = BELL đã nhận và ghi nhận yêu cầu
2	ref	String	Luôn null ở response thành công
3	message	String	Cập nhật đơn thành công
4	data	String	Mã vận đơn BELL (không đổi so với trước khi sửa)
5	warnings	Array	Cảnh báo không chặn, ví dụ ASCII auto-sanitize. Cùng cấu trúc với API tạo đơn

202 không có nghĩa là nhà vận chuyển đã nhận đơn

202 chỉ khẳng định: địa chỉ mới đã được lưu và đơn đã được xếp vào luồng gửi lại. Việc gọi sang nhà vận chuyển diễn ra sau khi response đã trả về. Kết quả cuối cùng phải tra cứu riêng — xem mục Theo dõi kết quả.

Luồng xử lý

Đồng bộ (trước khi trả response):

1. Kiểm tra quyền sở hữu và điều kiện đơn.
2. Validate địa chỉ mới theo ràng buộc của dịch vụ đang gắn với đơn.
3. Xác thực địa chỉ qua nhà cung cấp xác thực (có thể mất tới ~25 giây).
4. Tính cước tạm cho địa chỉ mới — chỉ đọc bảng giá, chưa ghi gì vào công nợ.
5. Lưu địa chỉ mới + payload gửi nhà vận chuyển. Đơn chuyển từ Error (11) sang Init (1).
6. Trả 202.

Bất đồng bộ (sau khi response đã trả về):

7. BELL gọi nhà vận chuyển tạo lô hàng, ghi nhận kết quả.
8. Nếu được tiếp nhận: cập nhật cước, tải nhãn, đơn về Label (3).
9. Nếu bị từ chối: đơn quay lại Error (11), processing_error được cập nhật với lý do mới.

Theo dõi kết quả

Gọi /api/order/get-order-info/{order_number} và đọc status:

status	Ý nghĩa
Init	Đang gửi sang nhà vận chuyển. Chờ và tra lại
Label	Gửi lại thành công. tracking_code và tracking_label_url đã có giá trị
Error	Nhà vận chuyển từ chối. Đọc processing_error để biết lý do, sửa tiếp rồi gọi lại API

mẹo

Thường mất vài giây tới vài chục giây. Nên chờ 5–10 giây rồi mới tra lần đầu, và giới hạn số lần poll. Nếu đơn ở Init quá lâu (trên vài phút), liên hệ hỗ trợ kèm mã đơn thay vì gọi lại API — gọi lại sẽ bị chặn 409.

Bảng mã kết quả

Thành công luôn là 202 với envelope ngắn ở trên. Mọi mã dưới đây đều là lỗi xảy ra trước khi địa chỉ được lưu. Envelope lỗi có thêm field code — luôn xử lý theo code, không dựa vào message.

HTTP	code	Ý nghĩa và hành động phía đối tác
404	ORDER_NOT_FOUND	Không tìm thấy đơn hoặc đơn không thuộc customer. data = null
409	ORDER_BUSY	Đơn đang được xử lý bởi một tiến trình khác. Thử lại sau
409	ORDER_NOT_EDITABLE	Đơn không ở trạng thái Error, hoặc đã có mã đơn / tracking từ nhà vận chuyển
409	RECOVERY_NOT_RETRYABLE	Không còn lượt khôi phục nào hợp lệ cho đơn này
409	PROVIDER_RESULT_UNKNOWN	Đã có một lượt gửi lại đang xử lý hoặc chưa rõ kết quả. Không gọi lại — chờ hoặc liên hệ hỗ trợ kèm ref
409	BILLING_LOCKED	Invoice đã chốt hoặc công nợ cần kiểm tra. Liên hệ hỗ trợ
409	ADDRESS_RECOMMENDATION_AVAILABLE	Địa chỉ có đề xuất chỉnh sửa. Xem suggestions, xác nhận rồi gọi lại
422	VALIDATION_FAILED	Payload hoặc địa chỉ không hợp lệ. Xem errors
422	ADDRESS_VALIDATION_FAILED	Địa chỉ không xác thực được
422	PRICING_UNAVAILABLE	Không tính được cước cho địa chỉ mới
422	UNSUPPORTED_PROVIDER	Cấu hình nhà vận chuyển của đơn không hỗ trợ luồng này
503	PROVIDER_UNAVAILABLE	Không chuẩn bị được yêu cầu gửi nhà vận chuyển. Chưa gửi gì đi, có thể thử lại
503	ADDRESS_VALIDATION_UNAVAILABLE	Dịch vụ xác thực địa chỉ tạm thời không khả dụng. Thử lại sau
503	LOCAL_PERSISTENCE_FAILED	BELL chưa xử lý được yêu cầu. Nếu response có ref khác null, không gọi lại — tra cứu trạng thái đơn trước

Ví dụ field không được phép sửa (422)

{
  "error": true,
  "ref": null,
  "code": "VALIDATION_FAILED",
  "message": "This field cannot be edited.",
  "data": null,
  "errors": {
    "consignee_name": ["This field cannot be edited."]
  },
  "warnings": []
}

Ví dụ địa chỉ có đề xuất (409)

{
  "error": true,
  "ref": null,
  "code": "ADDRESS_RECOMMENDATION_AVAILABLE",
  "message": "Địa chỉ có đề xuất cần xác nhận trước khi tiếp tục.",
  "data": null,
  "suggestions": {
    "consignee_city": "San Francisco",
    "consignee_postal_code": "94105-1804"
  },
  "warnings": []
}

suggestions dùng tên field theo chuẩn đối tác và không được tự áp dụng — đối tác xác nhận rồi gọi lại API với giá trị mong muốn.

Cước phí và thanh toán

• Bước tính cước trong preflight chỉ đọc bảng giá và hạn mức ví. Không tạo giao dịch, không giữ tiền, không ghi cước.
• Cước chỉ được cập nhật sau khi nhà vận chuyển tiếp nhận đơn, tức là sau khi response 202 đã trả về. Nhận 202 chưa có nghĩa là cước đã thay đổi.
• Tra cước mới qua /api/price/get-price/{order_number} sau khi đơn về Label. Trước đó giá trị trả về vẫn là cước của địa chỉ cũ.
• Nếu nhà vận chuyển từ chối, cước giữ nguyên như trước khi sửa.
• Luồng này không tạo đơn mới, kiện hàng mới, hàng hoá mới hay giao dịch thanh toán mới.

Timeout và retry

Không tự động gọi lại

API không còn chờ nhà vận chuyển, nhưng vẫn có bước xác thực địa chỉ đồng bộ có thể mất tới ~25 giây. Đặt timeout HTTP tối thiểu 60 giây.

Nếu request timeout hoặc lỗi mạng phía đối tác, không gọi lại ngay — địa chỉ có thể đã được lưu và đơn đã vào luồng gửi lại. Tra /api/order/get-order-info/{order_number} để xem status thực tế trước khi làm bất kỳ thao tác nào.

Tình huống	Có gọi lại được không
202 thành công	Không. Đơn đã vào luồng gửi lại — hãy theo dõi kết quả
VALIDATION_FAILED, ADDRESS_VALIDATION_FAILED	Được, sau khi sửa dữ liệu
ADDRESS_RECOMMENDATION_AVAILABLE	Được, sau khi xác nhận đề xuất
ORDER_BUSY, PROVIDER_UNAVAILABLE, ADDRESS_VALIDATION_UNAVAILABLE	Được, chờ ít phút rồi thử lại
PROVIDER_RESULT_UNKNOWN, LOCAL_PERSISTENCE_FAILED có ref	Không. Tra cứu trạng thái đơn, liên hệ hỗ trợ kèm ref
Timeout / không nhận được response	Không. Tra get-order-info trước
Đơn về Error với processing_error mới	Được, sửa địa chỉ theo lý do rồi gọi lại

---

Hủy đơn hàng

Method	POST
URL	/api/order/cancel-order

Payload request

No.	Field Name	Data Type	Description
1	order_number	String	Mã vận đơn của BELL

Response

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

---

In nhãn vận đơn

Method	GET
URL	/api/order/print-order/{order_number}

Path parameter

No.	Field Name	Data Type	Description
1	order_number	String	Mã 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
      }
    ],
    "processing_error": null
  }
}

Giải thích

No.	Field Name	Data Type	Description
1	error	boolean	Trạng thái lỗi
2	ref	String	Mã tham chiếu
3	message	String	Thông báo
4	data.orderNumber	String	Mã đơn hàng truy vấn
5	data.tracking	String	Tracking number chính của đơn
6	data.labelFormat	String	Định dạng file nhãn: PDF, GIF, PNG, JPG (hoặc rỗng nếu chưa có nhãn)
7	data.labelSize	String	Kích thước nhãn (mặc định 4x6)
8	data.label	String	Nội dung nhãn Base64 (hiện luôn rỗng — dùng labelUrl thay thế)
9	data.labelUrl	String	URL file nhãn vận đơn để tải/xem trực tuyến
10	data.receiptUrls	Array	Danh sách URL file biên lai (waybill receipt). Có thể rỗng []
11	data.trackings	Array	Danh sách tracking theo từng kiện (multi-package). Rỗng [] nếu đơn 1 kiện hoặc chưa có tracking
12	data.processing_error	String	Lý do đơn bị lỗi (status = 11 Error) đã được diễn giải sang tiếng Việt. null nếu đơn không ở trạng thái lỗi

thông tin

receiptUrls và trackings 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

Method	GET
URL	/api/order/get-order-info/{order_number}

Path parameter

No.	Field Name	Data Type	Description
1	order_number	String	Mã đơ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",
    "zone": "002",
    "status": "Label",
    "service": "EPK",
    "reason": null,
    "processing_error": 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 Name	Data Type	Description
1	status	String	success hoặc error
2	message	String	Thông báo kết quả
3	data.order_code	String	Mã vận đơn BELL
4	data.order_code_partner	String	Mã đơn hàng của đối tác
5	data.zone	String/null	Zone của tuyến vận chuyển. null nếu không xác định được zone
6	data.status	String	Trạng thái đơn hàng (xem bảng bên dưới)
7	data.service	String	Mã dịch vụ
8	data.reason	String	Lý do (ví dụ: lý do hủy đơn). Null nếu không có
9	data.processing_error	String	Lý do đơn bị lỗi (status = Error), đã được BELL diễn giải sang tiếng Việt. null nếu đơn không ở trạng thái lỗi hoặc không xác định được nguyên nhân
10	data.tracking_code	String	Tracking number của carrier
11	data.tracking_label_url	String	URL file nhãn vận đơn
12	data.carrier	String	Tên carrier vận chuyển
13	data.ship_date	String	Ngày gửi hàng
14	data.consignee_name	String	Tên người nhận
15	data.consignee_phone	String	Số điện thoại người nhận
16	data.consignee_company	String	Công ty người nhận
17	data.consignee_country	String	Mã quốc gia (ISO-2)
18	data.consignee_state	String	Bang / tỉnh
19	data.consignee_city	String	Thành phố
20	data.consignee_postal_code	String	Mã bưu chính
21	data.consignee_address	String	Địa chỉ người nhận
22	data.consignee_address2	String	Địa chỉ người nhận 2
23	data.created_date	String	Thời gian tạo đơn

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

Giá trị	Mô tả
Init	Mớ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
Exception	Có vấn đề phát sinh
Void	Đã hủy
Request Cancel	Yêu cầu hủy
Unknown	Không xác định
Draft	Bả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

Nhận hành trình tự động

Để BELL chủ động gửi cập nhật tới hệ thống của Quý khách, xem Webhook hành trình đơn. API GET bên dưới dùng để tra cứu, đồng bộ lịch sử ban đầu hoặc đối chiếu khi cần.

Method	GET
URL	/api/order/tracking/{order_number}

Path request

No.	Field Name	Data Type	Description
1	order_number	String	Mã 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 Name	Data Type	Description
1	error	boolean	Trạng thái lỗi (false = thành công)
2	ref	String	Mã tham chiếu yêu cầu (có thể null)
3	message	String	Thông báo kết quả xử lý
4	data	Array	Danh sách sự kiện tracking
5	data[].trackingNumber	String	Mã vận đơn / tracking number
6	data[].code	String	Mã sự kiện hoặc mã tham chiếu nội bộ
7	data[].city	String	Thành phố phát sinh sự kiện
8	data[].stateCode	String	Mã bang / tỉnh
9	data[].zipCode	String	Mã bưu chính
10	data[].countryCode	String	Mã quốc gia (ISO-2)
11	data[].eventDate	String	Thời gian xảy ra sự kiện (ISO 8601, UTC)
12	data[].eventStatus	String	Trạng thái / nội dung sự kiện tracking
13	data[].note	String	Ghi chú/mô tả trạng thái

---

Báo giá vận chuyển

Method	POST
URL	/api/price/get-price

Yêu cầu header Authorization: Bearer <token> theo hướng dẫn xác thực. API báo giá một dịch vụ, một kiện hàng trước khi tạo đơn. Không cần order_number, không tạo đơn hoặc nhãn, không kiểm tra ví/công nợ và không phát sinh thanh toán.

Thay đổi contract

Đối tác phải truyền một service_code được hỗ trợ và một address_id dương, tồn tại trong hệ thống. Không dùng kho 0 để tự chọn kho.

API không còn trả danh sách toàn bộ dịch vụ hoặc tự chọn giá rẻ nhất. data chỉ chứa một báo giá, không còn field carrier. Đối tác cần cập nhật payload và logic đọc response nếu đang tích hợp contract cũ.

Body request

{
  "address_id": 57,
  "service_code": "US_UNIUNI_D",
  "consignee_country": "US",
  "consignee_state_code": "CA",
  "consignee_city": "Los Angeles",
  "consignee_postal_code": "90001",
  "consignee_address": "123 Example Street",
  "unit_type": "cm-g",
  "weight": 300,
  "length": 20,
  "width": 10,
  "height": 5
}

Kho và địa chỉ trong ví dụ chỉ minh họa; cần chọn kho thực tế phù hợp với dịch vụ đã được mở cho tài khoản.

Field	Kiểu dữ liệu	Bắt buộc	Quy tắc
address_id	Integer	Có	Số nguyên ≥ 1, kho phải tồn tại và được hỗ trợ bởi dịch vụ. Xem bảng bên dưới
service_code	String	Có	Chỉ nhận EPK, LBE6, US_UNIUNI_D, US_UPS_GROUND
consignee_country	String	Có	Cả bốn dịch vụ hiện chỉ hỗ trợ US; hệ thống chuẩn hóa mã quốc gia sang chữ hoa
consignee_state_code	String	Có	Mã bang, tối đa 50 ký tự
consignee_city	String	Có	Thành phố, tối đa 50 ký tự
consignee_postal_code	String	Có	Tối đa 20 ký tự; 5 chữ số hoặc ZIP+4, ví dụ 90001 hoặc 90001-1234. Với US_UNIUNI_D, 5 chữ số đầu phải thuộc vùng phục vụ UniUni
consignee_address	String	Có	Địa chỉ người nhận, tối đa 200 ký tự
consignee_address_other	String/null	Không	Địa chỉ bổ sung, tối đa 200 ký tự
consignee_company	String/null	Không	Tên công ty, tối đa 100 ký tự
consignee_email	String/null	Không	Email hợp lệ, tối đa 50 ký tự
weight	Number	Có	Cân thực; số hữu hạn ≥ 0.01, theo unit_type
length, width, height	Number	Có	Mỗi chiều là số hữu hạn ≥ 0.01, không vượt 150 cm sau quy đổi
unit_type	String/null	Không	mm-g, cm-g, cm-kg, in-lb; mặc định cm-g khi bỏ qua hoặc gửi null
package_option	String/null	Không	Mã pin lithium; chỉ áp dụng cho EPK và LBE6 trong API báo giá
mode	String/null	Không	Bỏ qua, null hoặc simple; không hỗ trợ advanced

Dịch vụ và kho gửi

Dịch vụ	address_id được hỗ trợ
EPK	Không có danh sách giới hạn riêng; kho phải tồn tại và có cấu hình quốc gia gửi
LBE6	73, 75, 80, 101, 113
US_UNIUNI_D	57, 58, 100
US_UPS_GROUND	73, 75, 80, 101, 113, 967

Lấy ID kho từ data[].shop_id của GET /api/order/list-shop (xem Danh sách kho hàng). Kho vẫn phải tồn tại trong môi trường đang gọi. Tài khoản phải được BELL gán bảng giá bán đang hoạt động cho đúng dịch vụ; bảng giá public chưa được gán không cấp quyền báo giá.

Phạm vi dữ liệu

• Chỉ gửi một kiện bằng weight, length, width, height ở cấp cao nhất. mode=advanced, is_advanced=true hoặc packages có dữ liệu đều trả 422. Nên bỏ hoàn toàn packages và is_advanced khỏi payload báo giá.
• US_UNIUNI_ID và các mã ngoài bốn dịch vụ trên không được hỗ trợ.
• Không yêu cầu hoặc sử dụng consignee_name, consignee_phone; nếu đối tác cũ vẫn gửi thì hai field này bị bỏ qua. Quy tắc tạo đơn hàng không thay đổi.
• Các field tạo đơn như order_number, goods, product_price, label_sender, service_add không tham gia tính báo giá.
• Với LBE6, US_UNIUNI_D, US_UPS_GROUND, hệ thống tự chuẩn hóa company, state, city và các dòng địa chỉ sang ASCII trước validation.

Đơn vị và hàng có pin

unit_type	Kích thước	Cân nặng
mm-g	mm	gram
cm-g	cm	gram
cm-kg	cm	kg
in-lb	inch	pound

Hệ thống quy đổi về cm và gram: 1 mm = 0.1 cm, 1 kg = 1000 gram, 1 inch = 2.54 cm, 1 pound = 453.59237 gram. Không làm tròn cân hoặc kích thước trung gian.

Nếu hàng có pin, gửi package_option dạng chuỗi theo dịch vụ:

Dịch vụ	package_option hợp lệ
EPK	818, 820
LBE6	8181, 8182, 8201, 8202

• US_UNIUNI_D và US_UPS_GROUND không hỗ trợ tùy chọn pin trong API này.
• Khi có package_option: cân thực sau quy đổi phải ≤ 11 lbs và length + 2 × width + 2 × height phải < 108 inch.
• Với LBE6, mã bắt đầu bằng 818 được gửi tới UBI dưới dạng Battery Only, mã bắt đầu bằng 820 là Inside Equipment. Đối tác chỉ gửi package_option, không gửi batteryPacking riêng.
• Không có pin thì bỏ qua hoặc gửi null. API không tính thêm riêng phí pin, chữ ký, bảo hiểm hoặc dịch vụ gia tăng.

Cách xác định báo giá

• EPK: cân tính cước là giá trị lớn hơn giữa cân thực và cân thể tích (length_cm × width_cm × height_cm / hệ số quy đổi của dịch vụ × 1000, đơn vị gram). API lấy giá của bậc cân phù hợp trong bảng giá bán, không nhân thêm cân và không gọi UBI.
• LBE6 / US_UNIUNI_D / US_UPS_GROUND: dùng cân thực để tra cấu hình bảng giá, lấy dự phí từ UBI cho đúng kho và số đo kiện rồi áp dụng tỷ lệ điều chỉnh giá bán đã cấu hình.
• Tiền được làm tròn tới hai chữ số thập phân ở bước cuối. API không chuyển đổi ngoại tệ; amount theo tiền tệ cấu hình của dịch vụ. Response không có field currency; liên hệ BELL để xác nhận tiền tệ khi tích hợp.
• Báo giá UBI là dự phí, không phải phí quyết toán cuối của nhà vận chuyển. Muốn tra cước của đơn đã tạo, dùng API tra cứu cước phí đơn hàng.
• Không có giá phù hợp thì trả lỗi; không tự chọn bậc gần nhất, giá rẻ nhất hoặc trả thành công giả với giá 0. Giá thực sự bằng 0 trong cấu hình vẫn hợp lệ.

Response thành công

{
  "error": false,
  "ref": null,
  "message": "Thành công",
  "data": [
    {
      "serviceCode": "US_UNIUNI_D",
      "serviceName": "Tên dịch vụ theo cấu hình",
      "amount": 2.87,
      "addressId": 57,
      "postcode": "92843"
    }
  ]
}

Field	Kiểu dữ liệu	Mô tả
error	Boolean	false khi báo giá thành công
ref	null	Không có mã tham chiếu trong response báo giá
message	String	Thông báo kết quả
data	Array	Đúng một báo giá, chỉ gồm năm field bên dưới
data[].serviceCode	String	Mã dịch vụ được yêu cầu
data[].serviceName	String/null	Tên dịch vụ theo cấu hình
data[].amount	Number	Giá bán sau làm tròn, không phải chuỗi; không đảm bảo giữ đuôi .00
data[].addressId	Integer	ID kho gửi đã chọn
data[].postcode	String	Mã bưu chính của kho gửi, không phải consignee_postal_code; chuỗi rỗng nếu kho chưa có mã bưu chính

Tên dịch vụ, giá và mã bưu chính trong ví dụ chỉ minh họa. Response không trả carrier, giá mua hoặc dữ liệu thô từ nhà vận chuyển.

Mã lỗi báo giá

HTTP	code	Nguyên nhân / cách xử lý
401	Không có code chuẩn của báo giá	Token thiếu, sai hoặc hết hạn; kiểm tra lại xác thực
422	VALIDATION_FAILED	Payload, kho, mode, địa chỉ, số đo hoặc tùy chọn pin không hợp lệ; sửa các field trong errors
422	UNSUPPORTED_PRICE_SERVICE	Mã dịch vụ ngoài bốn mã được hỗ trợ; sửa service_code
403	SERVICE_NOT_ENABLED	Tài khoản chưa được gán bảng giá bán đang hoạt động cho dịch vụ; liên hệ BELL
404	PRICE_NOT_FOUND	Không có vùng giá hoặc bậc cân phù hợp
503	PRICE_CONFIGURATION_INVALID	Cấu hình báo giá thiếu, trùng hoặc không hợp lệ; liên hệ BELL
502	PROVIDER_RATE_UNAVAILABLE	Không lấy được dự phí hợp lệ từ UBI; có thể thử lại sau

Ví dụ lỗi validation (422)

{
  "error": true,
  "ref": null,
  "message": "Báo giá chỉ hỗ trợ simple mode, một kiện.",
  "data": [],
  "code": "VALIDATION_FAILED",
  "errors": {
    "mode": ["Báo giá chỉ hỗ trợ simple mode, một kiện."]
  }
}

Ví dụ chưa được mở dịch vụ (403)

{
  "error": true,
  "ref": null,
  "message": "Customer chưa được mở dịch vụ báo giá này.",
  "data": [],
  "code": "SERVICE_NOT_ENABLED"
}

Lỗi báo giá trả data: []; lỗi validation có thêm errors theo field. Riêng lỗi token bị chặn trước bước báo giá trả định dạng xác thực {"status":"error","message":"..."}, không theo envelope trên.

---

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

API này tra cước đã ghi nhận của đơn hàng, khác với API báo giá trước khi tạo đơn. Contract của endpoint GET không thay đổi.

Method	GET
URL	/api/price/get-price/{order_number}

Path request

No.	Field Name	Data Type	Description
1	order_number	String	Mã 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 Name	Data Type	Description
1	error	boolean	Trạng thái lỗi (false = thành công)
2	message	String	Thông báo kết quả xử lý
3	data	Array	Danh sách chi tiết cước phí
4	data[].order_code	String	Mã vận đơn
5	data[].amount	Decimal	Số tiền cước
6	data[].type	String	Loạ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.