Đồng bộ đơn hàng sàn

Nhập / cập nhật đơn hàng từ sàn vào Hubport theo khoảng thời gian hoặc theo từng đơn

Đơn hàng sàn được Hubport tự động nhập khi sàn gửi thông báo, kèm một lượt đồng bộ định kỳ khoảng 10–15 phút làm lưới an toàn. Các endpoint dưới đây để đồng bộ chủ động (ví dụ nhập lại đơn cũ, kiểm tra một đơn).

Đơn sàn được tạo thành đơn bán Hubport (gán store và kho receipt_warehouse của kênh), dòng hàng nhận diện theo liên kết SKU. Trạng thái, thanh toán, mã vận đơn được cập nhật theo sàn ở các lần đồng bộ sau.

Quyền: setting.sale cho mọi endpoint trong trang này.

Đồng bộ theo khoảng thời gian

Sàn	Endpoint
Shopee	`POST /v1/ecomshopee/syncorders/:channelid`
Lazada	`POST /v1/ecomlazada/syncorders/:channelid`
TikTok Shop	`POST /v1/ecomtiktokshop/syncorders/:channelid`

Request Body (tuỳ chọn)

Trường	Kiểu	Bắt buộc	Mô tả
`time_from`	int	Không	Mốc bắt đầu (Unix timestamp, giây). Mặc định: mốc đã đồng bộ gần nhất trừ 10 phút; lần đầu: 3 ngày trước
`time_to`	int	Không	Mốc kết thúc (Unix timestamp). Mặc định: hiện tại
`time_field`	string	Không	`update_time` (mặc định) hoặc `create_time`
`page_size`	int	Không	Số đơn mỗi trang khi gọi sàn (tối đa 100)

Khoảng thời gian tối đa 90 ngày (mốc bắt đầu cũ hơn sẽ bị cắt về 90 ngày trước time_to).

Response (HTTP 200)

Trường	Kiểu	Mô tả
`channel_id`	int	ID kênh
`time_from`, `time_to`	int	Khoảng thời gian thực tế đã đồng bộ
`total`	int	Số đơn sàn trong khoảng
`pages`	int	Số trang đã gọi sàn (Lazada, TikTok Shop)
`created`	int	Số đơn Hubport mới tạo
`updated`	int	Số đơn được cập nhật
`unchanged`	int	Số đơn không đổi
`skipped`	int	Số đơn bỏ qua (xem `items[].error`)
`error`	int	Số đơn lỗi
`items`	array	Kết quả từng đơn (xem bên dưới)
`api_calls`	int	Số lần gọi API sàn

Kết quả từng đơn (items[]):

Trường	Mô tả
`order_sn` (Shopee) / `channel_order_id` (Lazada, TikTok Shop)	Mã đơn trên sàn
`action`	`created`, `updated`, `unchanged`, `skipped`, `error`
`order_id`	ID đơn bán Hubport (0 nếu chưa tạo)
`error`	Lý do bỏ qua / lỗi, ví dụ `cancelled_before_import` (đơn huỷ trước khi nhập), `stale_update_time` (dữ liệu cũ hơn bản đã áp), `locked` (đơn đang được xử lý ở luồng khác), `error_synced_order_monthly_limit_exceeded` (hết hạn mức đơn sàn/tháng của gói), `fbl_or_digital_not_supported` (Lazada: đơn kho Lazada / hàng số)
`channel_status`	Lazada: trạng thái đơn trên sàn
`exception`	TikTok Shop: yêu cầu huỷ / trả hàng đang mở (`CANCEL_REQUESTED`, `RETURN_REQUESTED`...)

{
  "channel_id": 31,
  "time_from": 1759996400,
  "time_to": 1760000000,
  "total": 2,
  "created": 1,
  "updated": 1,
  "unchanged": 0,
  "skipped": 0,
  "error": 0,
  "items": [
    { "order_sn": "251013ABCDEF01", "action": "created", "order_id": 88010 },
    { "order_sn": "251012ABCDEF99", "action": "updated", "order_id": 87990 }
  ],
  "api_calls": 3
}

Đồng bộ một đơn

Sàn	Endpoint
Shopee	`POST /v1/ecomshopee/syncorder/:channelid/:ordersn`
Lazada	`POST /v1/ecomlazada/syncorder/:channelid/:orderid`
TikTok Shop	`POST /v1/ecomtiktokshop/syncorder/:channelid/:orderid`

Lấy chi tiết đơn từ sàn rồi tạo / cập nhật đơn Hubport. Response là một phần tử kết quả như items[] ở trên (HTTP 422 nếu action = error).

Danh sách ánh xạ đơn

Sàn	Endpoint
Shopee	`GET /v1/ecomshopee/orders/:channelid`
Lazada	`GET /v1/ecomlazada/orders/:channelid`
TikTok Shop	`GET /v1/ecomtiktokshop/orders/:channelid`

Query: limit (mặc định 100, tối đa 500). Trả các ánh xạ mới nhất giữa đơn sàn và đơn Hubport: { total, items }.

Trường	Kiểu	Mô tả
`id`	int	ID ánh xạ
`company_id`	int	ID công ty
`channel_id`	int	ID kênh
`channel_order_id`	string	Mã đơn trên sàn
`order_id`	int	ID đơn bán Hubport (0 nếu chưa tạo)
`channel_status`	string	Trạng thái đơn trên sàn
`channel_update_time`	int	Thời điểm cập nhật đơn trên sàn đã áp (Unix timestamp)
`tracking_code`	string	Mã vận đơn
`package_number`	string	Mã kiện / gói hàng trên sàn
`sync_status`	int	`1` (OK), `3` (Lỗi), `5` (Chờ — ví dụ hết hạn mức đơn tháng)
`sync_error`	string	Lỗi đồng bộ gần nhất
`date_created`, `date_modified`, `date_last_synced`	int	Unix timestamp

Error Codes

Mã lỗi	Mô tả
`error_time_range_invalid`	`time_from` không nhỏ hơn `time_to` (HTTP 422)
`error_order_sn_invalid` / `error_order_id_invalid`	Mã đơn không hợp lệ (HTTP 422)
`error_remote_order_not_found`	Không tìm thấy đơn trên sàn (HTTP 422)
`error_not_found`	Kênh không tồn tại, sai loại sàn hoặc không thuộc công ty của bạn (HTTP 404)
`error_channel_disabled`	Kênh đang tắt (HTTP 422)
`error_feature_requires_plan`	Gói chưa có tính năng kết nối sàn (HTTP 402)
`error_shopee_api` / `error_lazada_api` / `error_tiktokshop_api`	Lỗi do sàn trả về (HTTP 422)
`error_role_not_available`	Không có quyền `setting.sale` (HTTP 403)

Đồng bộ đơn hàng sàn

Đồng bộ theo khoảng thời gianCopy Anchor Link

Request Body (tuỳ chọn)Copy Anchor Link

Response (HTTP 200)Copy Anchor Link

Đồng bộ một đơnCopy Anchor Link

Danh sách ánh xạ đơnCopy Anchor Link