Nhanh.vn¶
Kích hoạt theo yêu cầu
Logidata kéo dữ liệu Nhanh.vn hằng ngày bằng chính hạ tầng này — đơn hàng, khách hàng và sản phẩm đều đang chảy vào kho dữ liệu của khách hàng thật. Báo Logidata khi bạn cần, nền tảng được bật cho tài khoản của bạn.
Base URL:
Đường dẫn, tham số và response giống hệt Nhanh.vn Open
API. Gốc là https://pos.open.nhanh.vn.
Một kết nối = một gian hàng (businessId) trên Nhanh.vn.
Điều Logidata làm hộ bạn¶
Nhanh.vn không dùng header xác thực như phần lớn API hiện đại. Mỗi request là
một POST form phải mang đủ bốn trường: version, appId, businessId,
accessToken, và toàn bộ tham số nghiệp vụ bị nhét vào một chuỗi JSON trong
trường data.
| Việc | Gọi thẳng Nhanh.vn | Qua Logidata |
|---|---|---|
Đăng ký app trên Nhanh và xin appId/secretKey |
Bạn tự làm | Không |
Gửi kèm appId + businessId + accessToken mỗi request |
Bạn tự làm | Không |
Làm mới accessToken trước khi hết hạn |
Bạn tự làm | Không |
Đóng gói tham số vào chuỗi JSON data |
Bạn tự làm | Logidata nhận query string thường và tự đóng gói |
Bạn gọi bằng đúng hai header như mọi nền tảng khác, với query string bình thường — Logidata dịch sang đúng dạng form mà Nhanh yêu cầu.
Nhóm dữ liệu¶
Allowlist chỉ đọc, gồm các endpoint Logidata đã dùng thật trong pipeline production:
| Nhóm | Đường dẫn gốc | Dùng để |
|---|---|---|
| Đơn hàng | /api/order/index |
Đơn theo khoảng thời gian tạo hoặc thời gian cập nhật, kèm sản phẩm trong đơn |
| Khách hàng | /api/customer/search |
Danh sách khách, thông tin liên hệ, lịch sử mua |
| Sản phẩm | /api/product/search |
Danh mục sản phẩm, mã, giá, tồn kho |
Ràng buộc cần biết¶
Lọc theo ngày cập nhật, không chỉ ngày tạo. /api/order/index nhận cả
fromDate/toDate (ngày tạo) lẫn updatedDateTimeFrom/updatedDateTimeTo
(ngày cập nhật). Đơn Nhanh đổi trạng thái và giá trị sau khi tạo, nên
pipeline đối soát nên chạy theo ngày cập nhật rồi ghi đè theo id; chạy theo
ngày tạo sẽ bỏ sót mọi thay đổi muộn.
Phân trang bắt buộc. Response trả data.totalPages; bạn phải lặp qua từng
page cho tới hết. Mỗi trang là một request tính vào hạn mức — hãy ước
lượng trước khi backfill lịch sử dài.
Đơn trả về dưới dạng object, không phải mảng. data.orders là một map khoá
theo mã đơn. Đây là quy ước của Nhanh và Logidata giữ nguyên văn, không tự
đổi thành mảng.
Xác thực và mã lỗi¶
Giống hệt mọi nền tảng khác: X-API-Key + X-Account-Id (xem Xác
thực), cùng bộ mã lỗi. X-Account-Id ở
đây trỏ tới một gian hàng Nhanh.vn.