Cập Nhật Quan Trọng Về Dữ Liệu từ NhanhVN
Áp dụng từ: Ngày 15 tháng 5 năm 2026
NhanhVN vừa ra mắt API v3 với cấu trúc dữ liệu được thiết kế lại toàn diện. Để đảm bảo hệ thống dữ liệu của bạn tiếp tục hoạt động ổn định và nhận được các tính năng mới nhất, chúng tôi đã hỗ trợ kết nối với NhanhVN v3 và bắt đầu lộ trình ngừng hỗ trợ v2.
Dưới đây là tóm tắt những thay đổi quan trọng bạn cần biết:
1. Hỗ trợ NhanhVN API v3
Hệ thống đã được cập nhật để kết nối với NhanhVN API v3. Dữ liệu từ v3 được tổ chức lại theo hướng gom nhóm các thông tin liên quan vào cùng một cột dạng JSON, thay vì trải rộng thành nhiều cột riêng lẻ như trước. Điều này giúp cấu trúc bảng gọn hơn và dễ mở rộng hơn trong tương lai.
Hệ thống đã tự động tạo bộ bảng mới cho v3. Dữ liệu v3 sẽ được lưu vào dataset riêng biệt (ví dụ: nhanhvn_v3.*) tách biệt hoàn toàn với dataset v2 hiện tại.
2. Thời hạn ngừng hỗ trợ NhanhVN v2 (Trước ngày 30 tháng 11, 2026)
Theo thông báo chính thức từ NhanhVN, API v2 sẽ ngừng hoàn toàn vào ngày 30/11/2026 và không còn nhận cập nhật tính năng mới kể từ bây giờ.
Bạn nên bắt đầu chuyển đổi pipeline dữ liệu sang v3 càng sớm càng tốt. Hãy kiểm tra lại các báo cáo, biểu đồ đang sử dụng bảng nhanhvn.* và lên kế hoạch chuyển sang bảng nhanhvn_v3.* tương ứng trước hạn chót.
Các bảng v3 không tương thích ngược với v2. Cấu trúc cột đã thay đổi đáng kể — nhiều cột phẳng (flat columns) đã được gộp vào cột JSON, một số bảng bị đổi tên hoặc thay thế hoàn toàn. Bạn không thể đơn giản trỏ báo cáo cũ sang dataset mới mà không cần điều chỉnh.
3. Tóm tắt những thay đổi cấu trúc dữ liệu chính
Bảng mới trong v3
| Bảng | Mô tả |
|---|---|
order_history | Lịch sử chuyển trạng thái đơn hàng |
bill_draft_product | Thay thế bill_imex_requirement — cấu trúc không tương thích |
Bảng bị xóa trong v3
| Bảng | Thay thế bằng |
|---|---|
bill_imex_requirement | bill_draft_product — không có đường di chuyển dữ liệu trực tiếp |
Những thay đổi phổ biến trên nhiều bảng
| Bảng | Thay đổi chính |
|---|---|
bill | ~20 cột phẳng gộp vào JSON: customer, sale, payment, related, v.v. |
order | ~30 cột phẳng gộp vào JSON: shipping_address, carrier, payment, channel, v.v. |
product | Giá, kích thước, hình ảnh, đơn vị gộp vào JSON: prices, shipping, images, units |
bill_imex | Cột nhà cung cấp, sản phẩm, kho gộp vào JSON; nhiều kiểu dữ liệu đổi từ FLOAT → INTEGER |
transaction | Cột đối tác, tài khoản gộp vào JSON: contact, items, depot |
customer | level, group: STRING → REPEATED STRING (mảng) |
Chi tiết đầy đủ về từng bảng xem tại tài liệu kỹ thuật NhanhVN v3 changelog.
4. Cách bắt đầu sử dụng v3
Để chuyển sang v3, bạn cần thực hiện 2 bước:
- Tạo source mới: Vào Data Sources → Add new source → chọn Nhanh.vn. API Version mặc định sẽ là v3.
- Tạo connection mới: Vào Connections → Add new connection → chọn source v3 vừa tạo. Thiết lập tương tự connection v2 hiện tại.
Source và connection v2 cũ vẫn hoạt động bình thường cho đến 30/11/2026 — hai phiên bản có thể chạy song song trong giai đoạn chuyển tiếp.
Xem hướng dẫn chi tiết tại tài liệu Nhanh.vn.