API Merchant: hubungkan SKU, pendaftaran pembelian, dan stok gudang Shenzhen ke sistem Anda

Yang dapat dilakukan saat ini

• Buat atau perbarui SKU secara massal (berdasarkan seller_sku Anda), dengan barcode produk tersendiri untuk setiap warna dan ukuran, lalu tautkan ke nomor varian produk di Shopee / Coupang / momo.
• Cocokkan persyaratan impor secara otomatis berdasarkan kode tarif 11 digit, dan tandai produk yang memerlukan pemeriksaan, izin, atau tidak dapat diimpor.
• Daftarkan nomor resi dan isi setiap kardus lebih awal saat membeli; saat barang tiba di gudang Shenzhen, perintah kerja pelabelan WO-SK dibuat otomatis, lalu gudang melabeli, memindai, dan menempatkan setiap barang ke rak.
• Cek stok per gudang dan riwayat pergerakan stok, serta terima webhook secara real-time untuk kedatangan barang, penerimaan selesai, selisih jumlah, dan perubahan stok.

Alur barang masuk

1. Buat SKU: kirim barcode produk, varian, nama barang yang dideklarasikan, dan kode tarif.
2. Daftarkan barang masuk: kirim nomor resi dan jumlah yang diharapkan untuk setiap SKU.
3. Tiba di gudang Shenzhen: setelah nomor resi dipindai, perintah kerja WO-SK dibuat dan dicetak otomatis.
4. Pelabelan dan penempatan ke rak: gudang mencetak barcode produk, menempelkannya pada setiap barang, dan memindai untuk menghitung jumlah.
5. Penerimaan selesai: jumlah yang benar-benar diterima masuk ke stok gudang Shenzhen, barang rusak dihitung terpisah, dan selisihnya dikirim ke sistem Anda.

Fitur yang direncanakan

Order pengiriman massal, batch pengiriman yang dikelompokkan otomatis sesuai ketentuan deklarasi, serta stok siap kirim, penyortiran, dan label pengiriman marketplace di gudang Taoyuan. Fitur-fitur ini akan diumumkan di halaman ini saat dirilis.

Langkah aktivasi

1. Di pusat anggota, tambahkan pendeklarasi bertipe “perusahaan” dan isi nomor identitas pajak Taiwan 8 digit.
2. Hubungi layanan pelanggan HowBridge untuk mengajukan aktivasi API Merchant; kunci akan diterbitkan setelah disetujui.
3. Kunci hanya ditampilkan satu kali. Simpan di variabel lingkungan sisi server, jangan disertakan di browser atau aplikasi.
4. Jika memerlukan webhook, atur dan verifikasi URL terlebih dahulu di halaman API pusat anggota, lalu berlangganan event merchant.

Base URL

Format dan bahasa

Permintaan dan respons menggunakan JSON. Pesan error secara bawaan dalam bahasa Mandarin Tradisional; kirim Accept-Language: en untuk bahasa Inggris. Untuk logika program, selalu gunakan error.code yang tetap dalam bahasa Inggris.

Struktur respons

Jika berhasil mengembalikan {"success": true, "data": …, "meta": …}; jika gagal mengembalikan {"success": false, "error": {"code", "message", "errors", "context"}}, dengan errors berisi rincian per kolom. Satu-satunya pengecualian adalah jika kunci tidak dikirim atau tidak valid: HTTP 401 dengan body {"message": "Unauthenticated."}.

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

Batas laju

Setiap kunci dibatasi 60 permintaan per menit dan 5,000 per hari (paket volume tinggi: 300 per menit dan 50,000 per hari); satu panggilan endpoint massal dihitung satu kali. Untuk data real-time, berlanggananlah webhook alih-alih melakukan polling.

Idempotensi (Idempotency-Key)

Permintaan tulis dapat menyertakan header Idempotency-Key (8–128 karakter: huruf, angka, dan _-:.). Jika jaringan timeout, mengirim ulang dengan key dan isi yang sama akan mengembalikan respons pertama dengan header Idempotent-Replayed: true; key yang sama dengan isi berbeda mengembalikan 422. Catatan disimpan selama 24 jam.

Respons massal

Endpoint massal melaporkan hasil per item: 200 jika semua berhasil, 207 jika sebagian gagal, dan 422 jika semua gagal. Setiap item memiliki index, status (created / updated / failed), dan alasan kegagalan.

Karakter pengenal

seller_sku hanya boleh berisi huruf, angka, dan ._- (1–64 karakter); barcode produk juga boleh berisi / dan + (3–64 karakter). Huruf besar dan kecil dianggap sama.

Buat atau perbarui SKU secara massal

POST/api/v1/merchant/skus/batch

Maksimal 200 item per permintaan. Setiap item diproses secara terpisah, sehingga satu item yang gagal tidak memengaruhi item lainnya.

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

Tanggapan 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 persyaratan impor (regulation.status)

Daftar SKU

GET/api/v1/merchant/skus

Dapat difilter dengan seller_sku, barcode, regulation_status, updated_since (ISO 8601), dan dipaginasi dengan page / per_page (maksimal 100).

Ambil satu SKU

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

Perbarui tautan produk marketplace

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

Mengganti seluruh tautan yang ada dengan daftar yang dikirim. Varian marketplace yang sama tidak dapat ditautkan ke dua SKU sekaligus.

Unduh label barcode produk

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

Mengembalikan PDF label 40×30mm; qty adalah jumlah lembar (1–1000). Gudang Shenzhen mencetak label yang sama saat pelabelan; gunakan fitur ini jika Anda ingin melabeli barang sendiri sebelum dikirim.

Buat order barang masuk

POST/api/v1/merchant/inbound-orders

Divalidasi secara keseluruhan: jika ada satu error saja, order tidak akan dibuat. Satu nomor resi hanya dapat menjadi bagian dari satu order barang masuk yang sedang berjalan; SKU duplikat dalam satu paket akan digabungkan jumlahnya.

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 order barang masuk

Status paket

Daftar order barang masuk

GET/api/v1/merchant/inbound-orders

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

Dapat difilter dengan status, reference_no, updated_since. Setiap paket mengembalikan jumlah yang diharapkan, diterima, rusak, dan selisihnya.

Batalkan order barang masuk

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

Hanya dapat dibatalkan jika belum ada paket yang tiba di gudang; setelah dibatalkan, nomor resi dapat didaftarkan kembali.

Cek stok

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

Dapat difilter dengan warehouse_code dan seller_sku[] (maksimal 200).

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

Riwayat pergerakan stok

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

Catatan pergerakan yang hanya ditambah dan tidak pernah diubah. Gunakan kursor after_id untuk berpindah ke halaman berikutnya (maksimal 500 catatan per permintaan), lalu simpan meta.next_after_id dari respons untuk melanjutkan pengambilan data rekonsiliasi.

Cara pengaturan

1. Atur URL webhook di halaman API pusat anggota (hanya https) dan selesaikan verifikasi kepemilikan: endpoint Anda harus mengembalikan HTTP 200 dengan body {"challenge": "nilai yang diterima"}.
2. Panggil PUT /api/v1/merchant/webhook/events untuk berlangganan event merchant. Mengubah URL di pusat anggota setelahnya tidak akan menghapus langganan event merchant.

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

Daftar event

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

Verifikasi tanda tangan

Setiap pengiriman menyertakan X-Lucky-Event, X-Lucky-Delivery-Id, dan X-Lucky-Signature: t=stempel_waktu,v1=tanda_tangan. Hitung HMAC-SHA256 dengan webhook secret Anda atas “stempel waktu + . + body mentah”, bandingkan dengan v1, dan tolak stempel waktu yang lebih lama dari 5 menit. Saat event yang sama dikirim ulang, delivery_id tidak berubah sehingga dapat digunakan untuk menghapus duplikat.

Respons selain 2xx akan dicoba ulang setelah 1 menit, 5 menit, 30 menit, 2 jam, dan 6 jam; jika gagal 20 kali berturut-turut, webhook akan dinonaktifkan otomatis dan harus diatur ulang di pusat anggota.

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

Akun resmi LINE @0523tw

Email teknis howyunqisoftware@gmail.com

Versi v1 Tahap 1 (2026-09-17): SKU produk, pendaftaran barang masuk, pelabelan dan penempatan ke rak di gudang Shenzhen, cek stok, webhook.