API Marchands : connectez vos SKU, vos préannonces d'achat et votre stock de Shenzhen à votre système

Ce que vous pouvez faire dès maintenant

• Créer ou mettre à jour des SKU en masse (identifiés par votre seller_sku), avec un code-barres produit distinct pour chaque couleur et chaque taille, et les lier aux références de variantes Shopee / Coupang / momo.
• Vérifier automatiquement les exigences à l'importation à partir du code tarifaire à 11 chiffres et signaler les produits soumis à inspection, à autorisation ou interdits à l'importation.
• Préannoncer les numéros de suivi et le contenu de chaque carton lors de l'achat ; à l'arrivée à l'entrepôt de Shenzhen, un ordre d'étiquetage WO-SK est créé automatiquement et l'entrepôt étiquette, scanne et met en stock chaque pièce.
• Consulter le stock par entrepôt et le journal des mouvements de stock, et recevoir en temps réel par webhook les arrivées, les réceptions terminées, les écarts de quantité et les variations de stock.

Processus de réception

1. Créer les SKU : envoyez les codes-barres produit, les variantes, les désignations déclarées et les codes tarifaires.
2. Préannoncer la réception : envoyez les numéros de suivi et la quantité annoncée pour chaque SKU.
3. Arrivée à l'entrepôt de Shenzhen : le scan du numéro de suivi crée et imprime automatiquement un ordre de travail WO-SK.
4. Étiquetage et mise en stock : l'entrepôt imprime les codes-barres produit, étiquette chaque pièce et la scanne pour le comptage.
5. Réception terminée : les quantités reçues entrent dans le stock de Shenzhen, les articles endommagés sont comptés à part et les écarts sont notifiés à votre système.

Fonctionnalités prévues

Commandes d'expédition en masse, lots d'expédition regroupés automatiquement selon les règles de déclaration, ainsi que stock prépositionné, tri et étiquettes d'expédition des places de marché à l'entrepôt de Taoyuan. Leur mise en service sera annoncée sur cette page.

Étapes d'activation

1. Dans l'espace membre, ajoutez un déclarant de type « entreprise » avec son numéro fiscal taïwanais à 8 chiffres.
2. Contactez le service client HowBridge pour demander l'activation de l'API Marchands ; une clé vous est délivrée après validation.
3. La clé ne s'affiche qu'une seule fois. Conservez-la dans une variable d'environnement côté serveur, jamais dans un navigateur ni dans une app.
4. Pour utiliser les webhooks, configurez et vérifiez d'abord votre URL sur la page API de l'espace membre, puis abonnez-vous aux événements marchands.

Base URL

Format et langue

Les requêtes et les réponses sont au format JSON. Les messages d'erreur sont en chinois traditionnel par défaut ; envoyez Accept-Language: en pour les recevoir en anglais. Dans votre code, basez toujours votre logique sur error.code, dont la valeur est toujours en anglais.

Structure des réponses

En cas de succès : {"success": true, "data": …, "meta": …} ; en cas d'échec : {"success": false, "error": {"code", "message", "errors", "context"}}, où errors détaille les erreurs champ par champ. Seule exception : une clé absente ou invalide renvoie HTTP 401 avec le corps {"message": "Unauthenticated."}.

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

Limites de débit

60 requêtes par minute et 5 000 par jour par clé (300 par minute et 50 000 par jour avec l'offre haut volume) ; une requête groupée compte pour une seule. Pour des données en temps réel, abonnez-vous aux webhooks au lieu d'interroger l'API en boucle.

Idempotence (Idempotency-Key)

Les requêtes d'écriture acceptent l'en-tête Idempotency-Key (8 à 128 caractères : lettres, chiffres et _-:.). Après un délai d'attente réseau dépassé, renvoyer la requête avec la même clé d'idempotence et le même contenu renvoie la réponse initiale, avec l'en-tête Idempotent-Replayed: true ; la même clé avec un contenu différent renvoie 422. Les enregistrements sont conservés 24 heures.

Réponses groupées

Les endpoints groupés renvoient un résultat pour chaque élément : 200 si tout réussit, 207 en cas d'échec partiel, 422 si tout échoue. Chaque élément comporte index, status (created / updated / failed) et le motif d'échec.

Caractères des identifiants

seller_sku n'accepte que des lettres, des chiffres et ._- (1 à 64 caractères) ; les codes-barres produit acceptent en plus / et + (3 à 64 caractères). La casse n'est pas prise en compte.

Créer ou mettre à jour des SKU en masse

POST/api/v1/merchant/skus/batch

Jusqu'à 200 éléments par requête. Chaque élément est traité indépendamment : l'échec de l'un n'affecte pas les autres.

Exemple de requête (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" } ]
    }
  ]
}'

Réponse 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 } }
}

Vérification des exigences à l'importation (regulation.status)

Lister les SKU

GET/api/v1/merchant/skus

Filtrez par seller_sku, barcode, regulation_status ou updated_since (ISO 8601) ; paginez avec page / per_page (100 maximum).

Consulter un SKU

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

Mettre à jour les correspondances avec les places de marché

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

La liste envoyée remplace intégralement les correspondances existantes ; une même variante de place de marché ne peut pas être liée à deux SKU.

Télécharger les étiquettes code-barres

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

Renvoie un PDF d'étiquettes 40×30 mm ; qty correspond au nombre d'étiquettes (1 à 1000). L'entrepôt de Shenzhen imprime la même étiquette lors de l'étiquetage ; cet endpoint vous sert si vous souhaitez étiqueter vous-même avant l'expédition.

Créer un ordre de réception

POST/api/v1/merchant/inbound-orders

Validation globale : en cas d'erreur, rien n'est créé. Un numéro de suivi ne peut appartenir qu'à un seul ordre de réception en cours ; les SKU en double dans un même colis sont fusionnés et leurs quantités additionnées.

Exemple de requête (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 }
      ]
    }
  ]
}'

Statuts de l'ordre de réception

Statuts des colis

Lister les ordres de réception

GET/api/v1/merchant/inbound-orders

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

Filtrez par status, reference_no ou updated_since. Chaque colis renvoie les quantités annoncées, reçues et endommagées, ainsi que l'écart.

Annuler un ordre de réception

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

L'annulation n'est possible que tant qu'aucun colis n'est arrivé ; après annulation, les numéros de suivi peuvent être préannoncés à nouveau.

Consulter le stock

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

Filtrez par warehouse_code et seller_sku[] (200 maximum).

Réponse 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 }
}

Journal des mouvements de stock

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

Enregistrements de mouvements en ajout seul, jamais modifiés. Paginez vers l'avant avec le curseur after_id (500 enregistrements maximum par requête) et conservez le meta.next_after_id de la réponse pour reprendre le rapprochement.

Configuration

1. Configurez l'URL du webhook sur la page API de l'espace membre (https uniquement) et effectuez la vérification de propriété : votre endpoint doit répondre HTTP 200 avec le corps {"challenge": "valeur reçue"}.
2. Appelez PUT /api/v1/merchant/webhook/events pour vous abonner aux événements marchands. Modifier ensuite l'URL dans l'espace membre ne supprime pas ces abonnements.

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

Liste des événements

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

Vérifier la signature

Chaque envoi comporte X-Lucky-Event, X-Lucky-Delivery-Id et X-Lucky-Signature: t=horodatage,v1=signature. Calculez un HMAC-SHA256 avec votre secret webhook sur « horodatage + . + corps brut », comparez-le à v1 et rejetez les horodatages de plus de 5 minutes. Lors des nouvelles tentatives d'un même événement, delivery_id reste identique et peut servir à dédoublonner.

Toute réponse autre que 2xx entraîne une nouvelle tentative après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures ; après 20 échecs consécutifs, le webhook est désactivé automatiquement et doit être reconfiguré dans l'espace membre.

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

Compte officiel LINE @0523tw

E-mail technique howyunqisoftware@gmail.com

Version v1, phase 1 (2026-09-17) : SKU produits, préannonces de réception, étiquetage et mise en stock à Shenzhen, consultation du stock, webhooks.