API Pedagang: sambungkan SKU, pemberitahuan awal pembelian dan stok gudang Shenzhen ke sistem anda

Perkara yang boleh dilakukan sekarang

• Cipta atau kemas kini SKU secara pukal (berdasarkan seller_sku anda), dengan kod bar produk tersendiri bagi setiap warna dan saiz, dan pautkan kepada nombor varian produk Shopee / Coupang / momo.
• Semak keperluan import secara automatik berdasarkan kod tarif Taiwan 11 digit, dan tandakan produk yang memerlukan pemeriksaan, permit atau tidak boleh diimport.
• Beri pemberitahuan awal nombor penjejakan dan kandungan setiap kotak semasa membuat pembelian; apabila barang tiba di gudang Shenzhen, pesanan kerja pelabelan WO-SK dibuka secara automatik dan gudang melabel serta mengimbas setiap unit ke rak.
• Semak stok mengikut gudang dan lejar stok, serta terima pemberitahuan webhook secara masa nyata untuk ketibaan di gudang, penerimaan selesai, perbezaan kuantiti dan perubahan stok.

Aliran penerimaan stok

1. Cipta SKU: hantar kod bar produk, varian, nama pengisytiharan dan kod tarif.
2. Pemberitahuan awal penerimaan: hantar nombor penjejakan dan kuantiti dijangka bagi setiap SKU.
3. Ketibaan di gudang Shenzhen: selepas nombor penjejakan diimbas, pesanan kerja WO-SK dibuka dan dicetak secara automatik.
4. Pelabelan dan penyusunan ke rak: gudang mencetak kod bar produk, melabel setiap unit dan mengimbasnya untuk dikira.
5. Penerimaan selesai: kuantiti sebenar yang diterima masuk ke stok gudang Shenzhen, unit rosak dikira berasingan, dan perbezaan dimaklumkan kepada sistem anda.

Ciri yang dirancang

Pesanan penghantaran keluar secara pukal, kelompok penghantaran yang dikumpulkan secara automatik mengikut peraturan pengisytiharan, serta stok hadapan, pengisihan dan label penghantaran platform di gudang Taoyuan. Ciri ini akan diumumkan di halaman ini apabila dilancarkan.

Langkah pengaktifan

1. Di pusat ahli, tambah pengisytihar jenis “syarikat” dan isikan nombor cukai perniagaan 8 digit.
2. Hubungi khidmat pelanggan HowBridge untuk memohon pengaktifan API Pedagang; kunci akan dikeluarkan selepas permohonan diluluskan.
3. Kunci hanya dipaparkan sekali. Simpan kunci dalam pemboleh ubah persekitaran di sisi pelayan, dan jangan letakkan dalam pelayar atau aplikasi.
4. Jika memerlukan webhook, tetapkan dan sahkan URL di halaman API pusat ahli terlebih dahulu, kemudian langgan acara pedagang.

Base URL

Format dan bahasa

Permintaan dan respons menggunakan JSON. Mesej ralat secara lalai dalam bahasa Cina Tradisional; hantar Accept-Language: en untuk menerimanya dalam bahasa Inggeris. Logik program hendaklah sentiasa menggunakan error.code yang tetap dalam bahasa Inggeris.

Struktur respons

Jika berjaya, respons ialah {"success": true, "data": …, "meta": …}; jika gagal, {"success": false, "error": {"code", "message", "errors", "context"}}, dengan errors mengandungi butiran bagi setiap medan. Satu-satunya pengecualian ialah apabila kunci tidak dihantar atau tidak sah: HTTP 401, dengan body {"message": "Unauthenticated."}.

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

Had kadar

Setiap kunci dihadkan kepada 60 permintaan seminit dan 5,000 permintaan sehari (pelan penggunaan tinggi: 300 seminit dan 50,000 sehari); satu permintaan pukal dikira sebagai satu permintaan. Untuk data masa nyata, langgan webhook dan jangan membuat tinjauan berulang (polling).

Idempotensi (Idempotency-Key)

Permintaan tulis boleh menyertakan pengepala Idempotency-Key (8–128 aksara: huruf, digit dan _-:.). Selepas tamat masa rangkaian, hantar semula dengan kunci dan kandungan yang sama untuk menerima respons pertama, bersama pengepala Idempotent-Replayed: true; kunci yang sama dengan kandungan berbeza akan mengembalikan 422. Rekod disimpan selama 24 jam.

Respons pukal

Titik akhir pukal melaporkan hasil bagi setiap item: 200 jika semua berjaya, 207 jika sebahagian gagal, dan 422 jika semua gagal. Setiap item mempunyai index, status (created / updated / failed) dan sebab kegagalan.

Aksara pengecam

seller_sku hanya boleh menggunakan huruf, digit dan ._- (1–64 aksara); kod bar produk juga boleh menggunakan / dan + (3–64 aksara). Huruf besar dan huruf kecil dianggap sama.

Cipta atau kemas kini SKU secara pukal

POST/api/v1/merchant/skus/batch

Maksimum 200 item bagi setiap permintaan. Setiap item diproses secara berasingan, jadi kegagalan satu item tidak menjejaskan item lain.

Contoh permintaan (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" } ]
    }
  ]
}'

Maklum balas 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 } }
}

Penentuan keperluan import (regulation.status)

Senaraikan SKU

GET/api/v1/merchant/skus

Tapis mengikut seller_sku, barcode, regulation_status atau updated_since (ISO 8601); gunakan page / per_page (maksimum 100) untuk penomboran halaman.

Dapatkan satu SKU

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

Kemas kini pautan produk platform

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

Senarai yang dihantar akan menggantikan semua pautan sedia ada; varian platform yang sama tidak boleh dipautkan kepada dua SKU pada masa yang sama.

Muat turun label kod bar produk

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

Mengembalikan PDF label 40×30mm; qty ialah bilangan label (1–1000). Gudang Shenzhen mencetak label yang sama semasa pelabelan; titik akhir ini disediakan jika anda mahu melabel sendiri sebelum penghantaran.

Cipta pesanan penerimaan

POST/api/v1/merchant/inbound-orders

Disahkan secara keseluruhan: jika terdapat sebarang ralat, tiada apa-apa yang dicipta. Satu nombor penjejakan hanya boleh berada dalam satu pesanan penerimaan yang sedang aktif pada satu masa; SKU berulang dalam bungkusan yang sama akan digabungkan kuantitinya.

Contoh permintaan (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 }
      ]
    }
  ]
}'

Status pesanan penerimaan

Status bungkusan

Senaraikan pesanan penerimaan

GET/api/v1/merchant/inbound-orders

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

Tapis mengikut status, reference_no atau updated_since. Setiap bungkusan mengembalikan kuantiti dijangka, diterima dan rosak, serta perbezaannya.

Batalkan pesanan penerimaan

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

Pembatalan hanya dibenarkan selagi belum ada bungkusan yang tiba di gudang; selepas dibatalkan, nombor penjejakan boleh diberi pemberitahuan awal semula.

Semak inventori

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

Tapis mengikut warehouse_code dan seller_sku[] (maksimum 200).

Maklum balas 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 }
}

Lejar stok

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

Rekod pergerakan yang hanya ditambah dan tidak pernah diubah. Gunakan kursor after_id untuk menyelak halaman ke hadapan (maksimum 500 rekod setiap kali), dan simpan meta.next_after_id daripada respons untuk meneruskan penyesuaian akaun.

Cara penetapan

1. Di halaman API pusat ahli, tetapkan URL webhook (hanya https) dan lengkapkan pengesahan pemilikan: titik akhir anda mesti membalas HTTP 200 dengan body {"challenge": "nilai yang diterima"}.
2. Panggil PUT /api/v1/merchant/webhook/events untuk melanggan acara pedagang. Menukar URL di pusat ahli kemudian tidak akan membuang langganan acara pedagang.

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"]}'

Senarai acara

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"
  }
}

Sahkan tandatangan

Setiap penghantaran menyertakan X-Lucky-Event, X-Lucky-Delivery-Id dan X-Lucky-Signature: t=cap_masa,v1=tandatangan. Kira HMAC-SHA256 dengan webhook secret anda ke atas “cap masa + . + body mentah”, bandingkan dengan v1, dan tolak cap masa yang lebih lama daripada 5 minit. Apabila acara yang sama dicuba semula, delivery_id tidak berubah dan boleh digunakan untuk menyingkirkan pendua.

Respons bukan 2xx akan dicuba semula selepas 1 minit, 5 minit, 30 minit, 2 jam dan 6 jam; selepas 20 kegagalan berturut-turut, webhook dinyahaktifkan secara automatik dan perlu ditetapkan semula di pusat ahli.

// 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);

Akaun rasmi LINE @0523tw

E-mel teknikal howyunqisoftware@gmail.com

Versi v1 Fasa 1 (2026-09-17): SKU produk, pemberitahuan awal penerimaan, pelabelan dan penyusunan ke rak di gudang Shenzhen, pertanyaan inventori, webhook.