API Người bán: kết nối SKU, đơn mua đăng ký trước và tồn kho tại kho Thâm Quyến với hệ thống của bạn

Những gì bạn có thể làm hiện nay

• Tạo hoặc cập nhật SKU hàng loạt (dựa trên seller_sku của bạn), mỗi màu sắc và kích cỡ có mã vạch sản phẩm riêng, đồng thời liên kết với mã phân loại sản phẩm trên Shopee / Coupang / momo.
• Tự động đối chiếu quy định nhập khẩu theo mã biểu thuế 11 chữ số, đánh dấu sản phẩm cần kiểm tra, cần giấy phép hoặc không được phép nhập khẩu.
• Đăng ký trước mã vận đơn và hàng bên trong từng thùng khi mua hàng; khi hàng đến kho Thâm Quyến, phiếu công việc dán mã WO-SK được tạo tự động, kho dán mã và quét lên kệ từng sản phẩm.
• Tra cứu tồn kho theo từng kho và sổ biến động tồn kho, đồng thời nhận ngay qua webhook các thông báo hàng đến kho, hoàn tất nhập kho, chênh lệch số lượng và thay đổi tồn kho.

Quy trình nhập kho

1. Tạo SKU: gửi mã vạch sản phẩm, quy cách, tên hàng khai báo và mã biểu thuế.
2. Đăng ký nhập kho trước: gửi mã vận đơn và số lượng dự kiến của từng SKU.
3. Hàng đến kho Thâm Quyến: sau khi quét mã vận đơn, phiếu công việc WO-SK được tạo và in tự động.
4. Dán mã và lên kệ: kho in mã vạch sản phẩm, dán lên từng sản phẩm và quét để đếm số lượng.
5. Hoàn tất nhập kho: số lượng thực nhận được đưa vào tồn kho kho Thâm Quyến, hàng hư hỏng được tính riêng, chênh lệch được thông báo cho hệ thống của bạn.

Tính năng đang lên kế hoạch

Đơn xuất kho hàng loạt, lô xuất hàng được tự động nhóm theo quy định khai báo, cùng với tồn kho đặt sẵn, phân loại và nhãn vận chuyển của sàn tại kho Đào Viên. Các tính năng này sẽ được công bố trên trang này khi ra mắt.

Các bước kích hoạt

1. Trong trung tâm thành viên, thêm người khai báo loại “Công ty” và nhập mã số thuế Đài Loan 8 chữ số.
2. Liên hệ bộ phận chăm sóc khách hàng HowBridge để đăng ký kích hoạt API Người bán; khóa sẽ được cấp sau khi được phê duyệt.
3. Khóa chỉ hiển thị một lần. Hãy lưu trong biến môi trường phía máy chủ, không đưa vào trình duyệt hoặc ứng dụng.
4. Nếu cần webhook, trước tiên hãy thiết lập và xác minh URL trong trang API của trung tâm thành viên, sau đó đăng ký nhận sự kiện người bán.

Base URL

Định dạng và ngôn ngữ

Yêu cầu và phản hồi đều là JSON. Thông báo lỗi mặc định bằng tiếng Trung phồn thể; gửi kèm Accept-Language: en để nhận tiếng Anh. Khi xử lý trong chương trình, luôn dùng error.code cố định bằng tiếng Anh.

Cấu trúc phản hồi

Thành công trả về {"success": true, "data": …, "meta": …}; thất bại trả về {"success": false, "error": {"code", "message", "errors", "context"}}, trong đó errors là chi tiết theo từng trường. Ngoại lệ duy nhất là khi không gửi khóa hoặc khóa không hợp lệ: HTTP 401, body là {"message": "Unauthenticated."}.

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

Giới hạn tần suất

Mỗi khóa được gọi 60 lần mỗi phút và 5,000 lần mỗi ngày (gói lưu lượng cao: 300 lần mỗi phút và 50,000 lần mỗi ngày); mỗi lần gọi endpoint hàng loạt tính là một lần. Nếu cần dữ liệu theo thời gian thực, hãy đăng ký webhook thay vì gọi thăm dò liên tục (polling).

Tính lũy đẳng (Idempotency-Key)

Yêu cầu ghi có thể kèm header Idempotency-Key (8–128 ký tự, gồm chữ, số và _-:.). Khi mạng bị hết thời gian chờ, gửi lại với cùng key và cùng nội dung sẽ nhận được phản hồi của lần đầu, kèm header Idempotent-Replayed: true; dùng cùng key với nội dung khác sẽ trả về 422. Bản ghi được lưu trong 24 giờ.

Phản hồi hàng loạt

Endpoint hàng loạt trả kết quả cho từng mục: tất cả thành công trả về 200, một phần thất bại trả về 207, tất cả thất bại trả về 422. Mỗi mục đều có index, status (created / updated / failed) và lý do thất bại.

Ký tự dùng cho mã định danh

seller_sku chỉ được dùng chữ, số và ._- (1–64 ký tự); mã vạch sản phẩm được dùng thêm / và + (3–64 ký tự). Không phân biệt chữ hoa và chữ thường.

Tạo hoặc cập nhật SKU hàng loạt

POST/api/v1/merchant/skus/batch

Tối đa 200 mục mỗi lần. Mỗi mục được xử lý độc lập, một mục thất bại không ảnh hưởng đến các mục khác.

Ví dụ về yêu cầu (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

Phản hồi 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

Xác định quy định nhập khẩu (regulation.status)

Tra cứu danh sách SKU

GET/api/v1/merchant/skus

Có thể lọc theo seller_sku, barcode, regulation_status, updated_since (ISO 8601), phân trang bằng page / per_page (tối đa 100).

Lấy một SKU

GET/api/v1/merchant/skus/{seller_sku}

Cập nhật liên kết sản phẩm trên sàn

PUT/api/v1/merchant/skus/{seller_sku}/channels

Thay thế toàn bộ liên kết hiện có bằng danh sách được gửi. Cùng một phân loại sản phẩm trên sàn không thể liên kết đồng thời với hai SKU.

Tải nhãn mã vạch sản phẩm

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

Trả về tệp PDF nhãn 40×30mm, qty là số nhãn (1–1000). Kho Thâm Quyến in cùng loại nhãn này khi dán mã; dùng chức năng này khi bạn muốn tự dán mã trước khi gửi hàng.

Tạo phiếu nhập kho

POST/api/v1/merchant/inbound-orders

Xác thực toàn bộ phiếu: chỉ cần có một lỗi thì phiếu sẽ không được tạo. Tại một thời điểm, mỗi mã vận đơn chỉ được thuộc một phiếu nhập kho đang xử lý; SKU trùng lặp trong cùng một kiện hàng sẽ được cộng gộp số lượng.

Ví dụ về yêu cầu (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

Trạng thái phiếu nhập kho

Trạng thái kiện hàng

Tra cứu phiếu nhập kho

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

Có thể lọc theo status, reference_no, updated_since. Mỗi kiện hàng trả về số lượng dự kiến, thực nhận, hư hỏng và chênh lệch.

Hủy phiếu nhập kho

POST/api/v1/merchant/inbound-orders/{id}/cancel

Chỉ có thể hủy khi chưa có kiện hàng nào đến kho; sau khi hủy, mã vận đơn có thể được đăng ký trước lại.

Tra cứu tồn kho

GET/api/v1/merchant/inventory?warehouse_code=SZ

Có thể lọc theo warehouse_code và seller_sku[] (tối đa 200 mã).

Phản hồi 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

Sổ biến động tồn kho

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

Bản ghi biến động chỉ thêm, không sửa. Dùng con trỏ after_id để lấy trang tiếp theo (tối đa 500 bản ghi mỗi lần), lưu lại meta.next_after_id trong phản hồi để tiếp tục lấy dữ liệu đối soát.

Cách thiết lập

1. Thiết lập URL webhook trong trang API của trung tâm thành viên (chỉ chấp nhận https) và hoàn tất xác minh quyền sở hữu: endpoint của bạn phải trả về HTTP 200 với body là {"challenge": "giá trị nhận được"}.
2. Gọi PUT /api/v1/merchant/webhook/events để đăng ký nhận sự kiện người bán. Sau đó, việc đổi URL trong trung tâm thành viên sẽ không xóa đăng ký sự kiện người bán.

curl -X PUT https://0523.tw/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

Danh sách sự kiện

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

Xác minh chữ ký

Mỗi lần đẩy đều kèm X-Lucky-Event, X-Lucky-Delivery-Id và X-Lucky-Signature: t=dấu_thời_gian,v1=chữ_ký. Dùng webhook secret của bạn tính HMAC-SHA256 trên “dấu thời gian + . + body gốc”, so sánh với v1, và từ chối dấu thời gian cũ hơn 5 phút. Khi cùng một sự kiện được gửi lại, delivery_id không đổi, có thể dùng để loại bỏ trùng lặp.

Phản hồi không phải 2xx sẽ được thử lại sau 1 phút, 5 phút, 30 phút, 2 giờ và 6 giờ; nếu thất bại liên tiếp 20 lần, webhook sẽ tự động bị vô hiệu hóa và cần thiết lập lại trong trung tâm thành viên.

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

Tài khoản LINE chính thức @0523tw

Email kỹ thuật howyunqisoftware@gmail.com

Phiên bản v1 Giai đoạn 1 (2026-09-17): SKU sản phẩm, đăng ký nhập kho trước, dán mã và lên kệ tại kho Thâm Quyến, tra cứu tồn kho, webhook.