Händler-API: SKUs, Einkaufsvoranmeldungen und Bestand im Lager Shenzhen an Ihr System anbinden

Was Sie heute tun können

• SKUs gesammelt anlegen oder aktualisieren (maßgeblich ist Ihre seller_sku), mit einem eigenen Produktbarcode für jede Farbe und Größe, verknüpft mit den Variantennummern auf Shopee / Coupang / momo.
• Einfuhrbestimmungen automatisch anhand der 11-stelligen taiwanischen Zolltarifnummer prüfen und Produkte kennzeichnen, die eine Prüfung oder Genehmigung benötigen oder nicht eingeführt werden dürfen.
• Beim Einkauf Sendungsnummern und den Inhalt jedes Kartons voranmelden; bei Eingang im Lager Shenzhen wird automatisch ein WO-SK-Etikettierauftrag angelegt, und das Lager etikettiert jedes Stück einzeln, scannt es und lagert es ein.
• Bestand pro Lager und Bestandsbuchungen abfragen und per Webhook in Echtzeit über Eingang im Lager, abgeschlossenen Wareneingang, Mengenabweichungen und Bestandsänderungen informiert werden.

Ablauf des Wareneingangs

1. SKUs anlegen: Produktbarcode, Varianten, Anmeldebezeichnung und Zolltarifnummer übermitteln.
2. Wareneingang voranmelden: Sendungsnummern und die angemeldete Menge jeder SKU übermitteln.
3. Eingang im Lager Shenzhen: Nach dem Scannen der Sendungsnummer wird automatisch ein WO-SK-Auftrag angelegt und gedruckt.
4. Etikettieren und einlagern: Das Lager druckt die Produktbarcodes, etikettiert jedes Stück und zählt es per Scan.
5. Wareneingang abgeschlossen: Die tatsächlich erhaltene Menge geht in den Bestand des Lagers Shenzhen ein, beschädigte Ware wird separat erfasst, und Abweichungen werden an Ihr System gemeldet.

Geplante Funktionen

Sammel-Versandaufträge, automatisch nach Anmeldevorschriften gruppierte Versandchargen sowie vorgelagerter Bestand, Sortierung und Plattform-Versandetiketten im Lager Taoyuan. Diese Funktionen werden bei Veröffentlichung auf dieser Seite angekündigt.

Schritte zur Freischaltung

1. Legen Sie im Mitgliederbereich einen Anmelder vom Typ „Unternehmen“ an und geben Sie die 8-stellige Steuernummer ein.
2. Wenden Sie sich an den HowBridge-Kundenservice, um die Händler-API freischalten zu lassen. Nach erfolgreicher Prüfung wird ein Schlüssel ausgegeben.
3. Der Schlüssel wird nur einmal angezeigt. Speichern Sie ihn in einer serverseitigen Umgebungsvariable und niemals im Browser oder in einer App.
4. Wenn Sie Webhooks nutzen möchten, richten Sie zuerst auf der API-Seite im Mitgliederbereich die URL ein und verifizieren Sie sie; abonnieren Sie anschließend die Händlerereignisse.

Base URL

Format und Sprache

Anfragen und Antworten sind JSON. Fehlermeldungen sind standardmäßig in traditionellem Chinesisch; mit Accept-Language: en erhalten Sie sie auf Englisch. Für die Programmlogik verwenden Sie immer den festen englischen error.code.

Antwortstruktur

Bei Erfolg wird {"success": true, "data": …, "meta": …} zurückgegeben, bei Fehlern {"success": false, "error": {"code", "message", "errors", "context"}}, wobei errors die Details pro Feld enthält. Einzige Ausnahme ist ein fehlender oder ungültiger Schlüssel: HTTP 401 mit dem Body {"message": "Unauthenticated."}.

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

Ratenbegrenzung

Pro Schlüssel 60 Anfragen pro Minute und 5.000 pro Tag (im High-Volume-Tarif 300 pro Minute und 50.000 pro Tag); eine Sammelanfrage zählt als eine Anfrage. Für Echtzeitdaten abonnieren Sie Webhooks, statt regelmäßig abzufragen (Polling).

Idempotenz (Idempotency-Key)

Schreibende Anfragen können den Header Idempotency-Key mitsenden (8–128 Zeichen: Buchstaben, Ziffern und _-:.). Wird nach einem Netzwerk-Timeout mit demselben Key und demselben Inhalt erneut gesendet, erhalten Sie die ursprüngliche Antwort mit dem Header Idempotent-Replayed: true; derselbe Key mit anderem Inhalt ergibt 422. Einträge werden 24 Stunden aufbewahrt.

Sammelantworten

Sammel-Endpunkte melden das Ergebnis jedes Eintrags: 200, wenn alle erfolgreich sind, 207 bei teilweisem Fehlschlag und 422, wenn alle fehlschlagen. Jeder Eintrag enthält index, status (created / updated / failed) und die Fehlergründe.

Zulässige Zeichen in Kennungen

seller_sku darf nur Buchstaben, Ziffern und ._- enthalten (1–64 Zeichen); Produktbarcodes dürfen zusätzlich / und + enthalten (3–64 Zeichen). Groß- und Kleinschreibung wird nicht unterschieden.

SKUs gesammelt anlegen oder aktualisieren

POST/api/v1/merchant/skus/batch

Bis zu 200 Einträge pro Anfrage. Jeder Eintrag wird unabhängig verarbeitet; ein Fehler wirkt sich nicht auf die übrigen Einträge aus.

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

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

Bewertung der Einfuhrbestimmungen (regulation.status)

SKUs abfragen

GET/api/v1/merchant/skus

Filterbar nach seller_sku, barcode, regulation_status und updated_since (ISO 8601); Paginierung über page / per_page (max. 100).

Einzelne SKU

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

Plattform-Produktzuordnungen aktualisieren

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

Die übermittelte Liste ersetzt alle bisherigen Zuordnungen vollständig; dieselbe Plattformvariante kann nicht gleichzeitig mit zwei SKUs verknüpft sein.

Barcode-Etiketten herunterladen

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

Gibt ein PDF mit Etiketten im Format 40×30mm zurück; qty ist die Anzahl der Etiketten (1–1000). Das Lager Shenzhen druckt beim Etikettieren dasselbe Etikett; dieser Endpunkt ist für den Fall gedacht, dass Sie vor dem Versand selbst etikettieren möchten.

Wareneingangsauftrag anlegen

POST/api/v1/merchant/inbound-orders

Validierung als Ganzes: Bei einem einzigen Fehler wird nichts angelegt. Eine Sendungsnummer kann jeweils nur zu einem laufenden Wareneingangsauftrag gehören; doppelte SKUs im selben Paket werden mengenmäßig zusammengeführt.

Anforderungsbeispiel (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 des Wareneingangsauftrags

Paketstatus

Wareneingangsaufträge abfragen

GET/api/v1/merchant/inbound-orders

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

Filterbar nach status, reference_no und updated_since. Für jedes Paket werden vorangemeldete, erhaltene und beschädigte Mengen sowie die Abweichung zurückgegeben.

Wareneingangsauftrag stornieren

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

Nur möglich, solange noch kein Paket im Lager eingetroffen ist; nach der Stornierung können die Sendungsnummern erneut vorangemeldet werden.

Bestand abfragen

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

Filterbar nach warehouse_code und seller_sku[] (max. 200).

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

Bestandsbuchungen

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

Bewegungsdatensätze, die nur ergänzt und nie geändert werden. Blättern Sie mit dem Cursor after_id vorwärts (max. 500 Datensätze pro Anfrage) und merken Sie sich meta.next_after_id aus der Antwort, um den Abgleich fortzusetzen.

Einrichtung

1. Richten Sie auf der API-Seite im Mitgliederbereich die Webhook-URL ein (nur https) und schließen Sie die Inhaberschaftsprüfung ab: Ihr Endpunkt muss mit HTTP 200 und dem Body {"challenge": "empfangener Wert"} antworten.
2. Rufen Sie PUT /api/v1/merchant/webhook/events auf, um Händlerereignisse zu abonnieren. Eine spätere Änderung der URL im Mitgliederbereich hebt die Abonnements der Händlerereignisse nicht auf.

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

Ereignisliste

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

Signatur prüfen

Jede Zustellung enthält X-Lucky-Event, X-Lucky-Delivery-Id und X-Lucky-Signature: t=Zeitstempel,v1=Signatur. Berechnen Sie mit Ihrem Webhook-Secret einen HMAC-SHA256 über „Zeitstempel + . + Roh-Body“, vergleichen Sie ihn mit v1 und lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind. Bei Wiederholungen desselben Ereignisses bleibt die delivery_id gleich und kann zur Deduplizierung genutzt werden.

Bei einer Antwort außerhalb von 2xx wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden erneut zugestellt; nach 20 aufeinanderfolgenden Fehlschlägen wird der Webhook automatisch deaktiviert und muss im Mitgliederbereich neu eingerichtet werden.

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

Offizielles LINE-Konto @0523tw

E-Mail für technische Fragen howyunqisoftware@gmail.com

Version v1 Phase 1 (2026-09-17): Produkt-SKUs, Wareneingangs-Voranmeldung, Etikettierung und Einlagerung im Lager Shenzhen, Bestandsabfrage, Webhooks.