API Logictic & Vận chuyển

TÀI LIỆU ĐẶC TẢ KỸ THUẬT

KẾT NỐI API BLUECOM

(Chuẩn tích hợp nghiệp vụ Logistics — Đơn hàng / Vận đơn / Thanh toán COD)

Cổng kết nối chính thức:

https://api.bluecom.vn

Hà Nội, ngày 04 tháng 09 năm 2026

Phiên bản: 1.0 — Tài liệu nội bộ / đối tác tích hợp

1. Mục đích của tài liệu

Tài liệu này đặc tả các chi tiết kỹ thuật để đối tác/khách hàng kết nối với hệ thống Bluecom thông qua cổng Bluecom Open API Gateway (api.bluecom.vn) nhằm thực hiện các nghiệp vụ:

●      Tạo và chỉnh sửa đơn hàng

●      Huỷ đơn hàng

●      Tracking đơn hàng

●      Webhook trạng thái của đơn hàng

●      Lấy danh mục địa chỉ

Mã của Product: 1001/ODOO/123456

Bộ mã chi nhánh (ma_dvi):

2. Thông tin kết nối chung

Base URL (Bluecom Open API Gateway): https://api.bluecom.vn

●      Định dạng dữ liệu: JSON

●      Phương thức: POST (áp dụng cho toàn bộ các hàm bên dưới trừ khi có ghi chú khác)

●      Xác thực mặc định: Bearer Token — lấy token qua hàm 3.1 (Get Token), sau đó thêm vào header Authorization của các hàm tiếp theo theo cú pháp: Authorization: Bearer <token>

●      Một số hàm sử dụng Basic Authentication riêng — được ghi chú cụ thể tại từng mục.

Toàn bộ đường dẫn (endpoint path), tên tham số, kiểu dữ liệu và mã trạng thái giữ nguyên theo chuẩn kỹ thuật gốc; khách hàng chỉ cần trỏ về cổng api.bluecom.vn thay vì kết nối trực tiếp tới hệ thống nội bộ.

3. Danh mục hàm API

3.1 Lấy Token xác thực (Get Token)

URL: https://api.bluecom.vn/api/Token

Tham số đầu vào:

Phương thức: POST

{

  "ma_dvi":"1001",//(*) Mã đơn vị VIT hà nội

  "ma":"ODOO",//(*)mã đăng nhập ODOO

  "mat_khau":"123456",//(*) mật khẩu đăng nhập

  "kh_bt_ql":1//(*) loại tài khoản (1- Khách hàng, 2- Bưu tá, 3- Quản lý)

}

Tham số đầu ra:

Là chuỗi Token: token này sẽ được add vào header của các phương thức sử dụng phía sau. Cách thức: ở mục Headers thêm tham số Authorization với value là: Bearer + chuỗi token vừa tạo ở trên.

3.2 Tạo và chỉnh sửa đơn hàng (Bill)

URL: https://api.bluecom.vn/api/BillOdoo

Tham số đầu vào:

Phương thức: POST

{

  "ma_dvi": "1001",(*)

  "nsd": "ODOO",(*) ODOO (Product)

  "pas": "123456",(*)

  "nx": "N",(*)// Thao tác N- nhập mới hoặc sửa thông tin, X- Xóa

  "so_id": "0",(*)// số id (=0 là nhập bill mới, !=0 là cập nhật thông tin bill đó)

  "ngay_ht": 20210403,// ngày nhập định dạng yyyyMMdd

  "loai_bp": "1",// loại sản phẩm: CPN, hàng ...

  "so_hieu": "",// số bill

  "ma_kh": "ODOO",//mã người gửi (khách hàng) TESTAPI (Sandbox)/ODOO (Product)

  "dchi_gui": "",// địa chỉ người gửi

  "ten_ng_nh": "",// tên người nhận

  "dt_ng_nh": "",// điện thoại người nhận

  "dchi": "",// địa chỉ nhận

  "tinh_nhan": "HNI",//tỉnh/thành

  "quan_huyen_nhan": "", //quận/huyện

  "phuong_xa_nhan": "", // xã/phường

  "so_kien": "1",// tổng số kiện

  "kluong": 0,// trọng lượng

  "kluong_qd": 0,// trọng lượng quy đổi nếu có, mặc định bằng trọng lượng

  "huyen": 0,// 0 - thư đi trung tâm tỉnh/tp, 1- thư đi huyện xã

  "dvu": "",// các dịch vụ phát sinh nếu có: HT- hỏa tốc, BP- báo phát...

  "ma_nt": "",// mã nguyên tệ, vnd- việt nam đồng, usd - usd

  "cuoc_chinh": 0,// cước chính

  "cuoc_dv": 0,// cước dịch vụ

  "tien_cod": 0,// tiền cod

  "cuoc_cod": 0,// cước thu cod

  "ppnl": 0,// phụ phí nhiên liệu

  "tong_cuoc": 0,// tổng cước chưa vat

  "vat": 0,// tiền vat

  "dthu_qd": 0,// tổng tiền

  "pt_tt": "C",// phương thức thanh toán, P- đầu nhận thanh toán, T -tiền mặt, C- công nợ

  "gio_nhan": "",// giờ nhập

  "ghi_chu": "",// ghi chú kèm theo nếu có

  "so_id_kh": "230",// số id bưu phẩm khách đẩy sang

  "kgia": 123,// giá khách đẩy sang

  "quan_huyen_gui": 123,// quận huyện người gửi

  "ten_nguoi_gui": 123,// tên người gửi

  "dt_gui": 123,// điện thoại người gửi

  "tinh_gui": "tinh_gui",

  "phuong_xa_gui": "phuong_xa_gui",

  "tt_phat": 1,// 0- không phát, 1- có phát

  "tt_gom": 1,// 0 - không gom, 1- có gom

  "xml_sp": "<DocumentElement><sp><ma_hang>A1</ma_hang><ten_hang>quần áo</ten_hang><so_luong>2</so_luong><don_gia>1000000</don_gia></sp></DocumentElement>"

}

Ví dụ:

{

  "ma_dvi": "207",

  "nsd": "ODOO",// TESTAPI (Sandbox)/ODOO (Product)

  "pas": "123456",

  "nx": "N",

  "so_id": "0",

  "ngay_ht": 20210403,

  "loai_bp": "1",

  "so_hieu": "",

  "ma_kh": "ODOO",// TESTAPI (Sandbox)/ODOO (Product)

  "dchi_gui": "",

  "ten_ng_nh": "",

  "dt_ng_nh": "",

  "dchi": "",

  "tinh_nhan": "HNI",

  "quan_huyen_nhan": "",

  "phuong_xa_nhan": "",

  "so_kien": "1",

  "kluong": 0,

  "kluong_qd": 0,

  "huyen": 0,

  "dvu": "",

  "ma_nt": "",

  "cuoc_chinh": 0,

  "cuoc_dv": 0,

  "tien_cod": 0,

  "cuoc_cod": 0,

  "ppnl": 0,

  "tong_cuoc": 0,

  "vat": 0,

  "dthu_qd": 0,

  "pt_tt": "C",

  "gio_nhan": "",

  "ghi_chu": "",

  "so_id_kh": "230",

  "kgia": 123,

  "quan_huyen_gui": "123",

  "ten_nguoi_gui": "123",

  "dt_gui": "123",

  "tinh_gui": "tinh_gui",

  "phuong_xa_gui": "phuong_xa_gui",

  "tt_phat": 1,

  "tt_gom": 2,

  "xml_sp": "<DocumentElement><sp><ma_hang>A1</ma_hang><ten_hang>quần áo</ten_hang><so_luong>2</so_luong><don_gia>1000000</don_gia></sp></DocumentElement>"

}

Tham số đầu ra:

{

  "status": "Success",//thành công, còn lại là thất bại

  "msg": "Số bill, so_id"// nếu thành công thì sẽ là số bill của bill vừa thao tác. Nếu thất bại thì sẽ là thông báo lỗi

}

3.3 Huỷ đơn hàng (Bill)

URL: https://api.bluecom.vn/api/BillHuy

Tham số đầu vào:

Phương thức: POST

{

  "ma_dvi": "1001",

  "ma_kh": "ODOO", // ODOO (Product)

  "so_bill": "20210928390383788300"// là số bill của bill muốn huỷ

}

Tham số đầu ra:

{

  "status": "1",//1- thành công, còn lại là thất bại

  "msg": "HH101765"// nếu thành công thì sẽ là số bill của bill vừa thao tác. Nếu thất bại thì sẽ là thông báo lỗi

}

3.4 Tra cứu vận đơn (Tracking)

URL: https://api.bluecom.vn/api/tracking

Tham số đầu vào:

Phương thức: POST

{

  "ma_dvi": "1001",

  "so_hieu": "CL-HCMN-0068214"

}

Tham số đầu ra:

{

  "status": "1",//1- thành công, còn lại là thất bại

  "msg": []//nếu thành công thì sẽ là dữ liệu của các bill. Nếu thất bại thì sẽ là thông báo lỗi

}

Cấu trúc dữ liệu trả về được mô tả chi tiết tại Phụ lục A (Bảng 1, Bảng 2).

3.5 Webhook trạng thái đơn hàng

Hệ thống Bluecom sẽ chủ động gửi (push) dữ liệu trạng thái đơn hàng tới URL webhook do đối tác đăng ký, theo cấu trúc:

{

  "Note": "",

  "Status": "GiaoThanhCong",

  "BillCode": "HNLO0984238857",

  "ReasonCode": "",

  "ExecutionTime": "2025-02-24 11:31:32.660578",

  "PartnerOrderCode": "HNLO0984238857",

  "ReAttemptTime": ""

}

Danh mục trạng thái (Status) đầy đủ được mô tả tại Phụ lục B.

3.6 Lấy danh mục địa chỉ

URL: https://api.bluecom.vn/api/Listwards

Tham số đầu vào:

Phương thức: POST

{

  "ma_tinh":"",

  "ma_huyen":""

}

Xác thực (Basic Authentication):

Authorize: Basic

username: odoo

password: odoo

Tham số đầu ra:

{

  "status": "Success",//thành công, còn lại là thất bại

  "msg": []//nếu thành công thì sẽ là dữ liệu của các địa danh. Nếu thất bại thì sẽ là thông báo lỗi

}

3.7 Xác nhận thanh toán COD

URL: https://api.bluecom.vn/api/thanhtoan

Tham số đầu vào:

Phương thức: POST

{

  "ma_dvi": "",

  "nsd": "",

  "pas": "",

  "xml_sp": "<DocumentElement><BuuPham><ma_dvi>1001</ma_dvi><so_id>20240104444709549207</so_id><ten_kh>NAMDUOC</ten_kh><ma_nt>VND</ma_nt><phi>0</phi><cod>3250000</cod><phi_phat>0</phi_phat><ttoan>3250000</ttoan><stt>1</stt></BuuPham><BuuPham></DocumentElement>",

  "so_id_tt_g": "",

  "ngay_ht": "",

  "pt": "",

  "ma_nt": "",

  "tongtt": 0,

  "ngay_d": 0,

  "ngay_c": 0,

  "nhom": 0,

  "ma_dt": "",

  "ten_tt": "",

  "dvi_tt": ""

}

Tham số đầu ra:

{

  "status": "1",//1- thành công, còn lại là thất bại

  "msg": []//nếu thành công thì sẽ là dữ liệu của các bill. Nếu thất bại thì sẽ là thông báo lỗi

}

3.8 Khai báo khách hàng hoặc tài xế

URL: https://api.bluecom.vn/api/Odoo

Tham số đầu vào:

Phương thức: POST (maDvi và ma là bắt buộc)

{

  "maDvi": "1001",

  "ma": "KH001",

  "ten": "Công ty TNHH ABC",

  "bangCuoc": "CUOCHUNG",//bỏ

  "pass": "123456",

  "loai": "1" //1-chủ hàng; 2-tài xế

}

Tham số đầu ra:

{

  "Status": "Thành công",

  "Error": ""

}

3.9 Khai báo nhân viên kinh doanh

URL: https://api.bluecom.vn/api/BillOdoo

Tham số đầu vào:

Phương thức: POST (maDvi và ma là bắt buộc)

{

  "maDvi": "1001",

  "ma": "NV001",

  "ten": "Nguyễn Văn A",

  "pas": "abc123",

  "phong": "Kinh doanh",

  "gd": 1, //bỏ

  "kt": 0, //bỏ

  "ht": 1, //bỏ

  "bt": 0, //bỏ

  "bc": 0, //bỏ

  "maKh": 0, //bỏ

  "bc3": "",//bỏ

  "tgian": "2024-01-01",//bỏ

  "lastLogin": "2024-01-02",//bỏ

  "khoa": "0", //Khóa tài khoản 0:ko; 1:có //bỏ

  "nloi": 0, //số lần đăng nhập lỗi //bỏ

  "nsd": "admin",//bỏ

  "ngayBdau": 20240101, //ngày bắt đầu //bỏ

  "ngayTdung": 20250101, //Ngày tuyển dụng //bỏ

  "trangThai": 1, //bỏ

  "ngaySinh": "1990-01-01"

}

Tham số đầu ra:

{

  "Status": "Thành công",

  "Error": ""

}

3.10 Cập nhật người phụ trách (ten_npt) cho khách hàng

URL: https://api.bluecom.vn/api/BillOdoo

Tham số đầu vào:

Phương thức: POST (tenNpt và ma là bắt buộc)

{

  //thiếu ma_dvi

  "ma": "KH001",

  "tenNpt": "" //cần nhập mã người phụ trách

}

Tham số đầu ra (ví dụ khi thiếu tham số):

{

  "Status": "Thất bại",

  "Error": "Thiếu tham số bắt buộc: ma, ten_npt"

}

3.11 Khai báo sản phẩm

URL: https://api.bluecom.vn/api/BillOdoo

Tham số đầu vào:

Phương thức: POST (maDvi và ma là bắt buộc)

{

  "maDvi": "1001",

  "ma": "SP001",

  "ten": "Sản phẩm A",

  "dviTinh": "chai",

  "soTp": 3, //số thập phân

  "loai": 2, //1-tài liệu; 2 : hàng hóa

  "dv": "X" //bỏ

}

Tham số đầu ra:

{

  "Status": "Thành công",

  "Error": ""

}

Phụ lục A — Cấu trúc dữ liệu Tracking

Bảng 1

Bảng 2

Phụ lục B — Danh mục trạng thái Webhook (Status)

●      TaoDon

●      DangGomHang

●      GomThanhCong

●      GomKhongThanhCong

●      HuyDon

●      NhapKho

●      DangGiaoHang

●      GiaoThanhCong

●      GiaoKhongThanhCong

●      NhapLaiKho

●      DangHoan

●      HoanThanhCong

●      HoanKhongThanhCong

●      DaThanhToanCOD