API для продавцов: подключите SKU, заявки на приёмку закупок и остатки склада в Шэньчжэне к своей системе

Что уже доступно

• Массово создавать и обновлять SKU (ключ — ваш seller_sku) с отдельным штрихкодом товара для каждого цвета и размера и привязывать их к вариантам товаров на Shopee / Coupang / momo.
• Автоматически проверять требования к ввозу по 11-значному коду таможенного тарифа и отмечать товары, которым нужна обязательная проверка или разрешение либо ввоз которых запрещён.
• При закупке заранее сообщать трек-номера и содержимое каждой коробки; при поступлении на склад в Шэньчжэне автоматически создаётся наряд на маркировку WO-SK, и склад поштучно маркирует, сканирует и размещает товар.
• Запрашивать остатки по складам и журнал движения остатков, а также получать через webhook в реальном времени события о поступлении, завершении приёмки, расхождениях в количестве и изменении остатков.

Процесс приёмки

1. Создание SKU: передайте штрихкоды товаров, варианты, наименования для декларации и коды тарифа.
2. Заявка на приёмку: передайте трек-номера и ожидаемое количество по каждому SKU.
3. Поступление на склад в Шэньчжэне: после сканирования трек-номера автоматически создаётся и печатается наряд WO-SK.
4. Маркировка и размещение: склад печатает штрихкоды товаров, поштучно наклеивает их и сканирует для подсчёта.
5. Приёмка завершена: фактически принятое количество зачисляется в остатки склада в Шэньчжэне, повреждённые единицы учитываются отдельно, а расхождения отправляются в вашу систему.

Планируемые функции

Массовые заказы на отгрузку, партии отгрузки с автоматической группировкой по правилам декларирования, а также заранее размещённые запасы, сортировка и транспортные этикетки маркетплейсов на складе в Таоюане. О запуске будет объявлено на этой странице.

Как подключиться

1. В личном кабинете добавьте декларанта типа «компания» и укажите 8-значный налоговый номер Тайваня.
2. Свяжитесь со службой поддержки HowBridge, чтобы подключить API для продавцов; ключ выдаётся после одобрения.
3. Ключ показывается только один раз. Храните его в переменной окружения на сервере и никогда не размещайте в браузере или приложении.
4. Если нужны webhook, сначала настройте и подтвердите URL на странице API в личном кабинете, затем подпишитесь на события продавца.

Base URL

Формат и язык

Запросы и ответы передаются в формате JSON. Сообщения об ошибках по умолчанию возвращаются на традиционном китайском; с заголовком Accept-Language: en — на английском. В логике программы всегда опирайтесь на error.code, который всегда на английском.

Структура ответа

При успехе возвращается {"success": true, "data": …, "meta": …}; при ошибке — {"success": false, "error": {"code", "message", "errors", "context"}}, где errors содержит сведения по каждому полю. Единственное исключение — отсутствующий или недействительный ключ: HTTP 401 с телом {"message": "Unauthenticated."}.

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

Лимиты запросов

60 запросов в минуту и 5000 в сутки на ключ (на тарифе для высокой нагрузки — 300 в минуту и 50 000 в сутки); пакетный запрос считается за один. Для получения данных в реальном времени подпишитесь на webhook вместо периодического опроса.

Идемпотентность (Idempotency-Key)

Запросы на запись принимают заголовок Idempotency-Key (8–128 символов: латинские буквы, цифры и _-:.). Если после сетевого тайм-аута повторить запрос с тем же ключом и тем же содержимым, вернётся первоначальный ответ с заголовком Idempotent-Replayed: true; тот же ключ с другим содержимым вернёт 422. Записи хранятся 24 часа.

Пакетные ответы

Пакетные эндпоинты возвращают результат по каждой записи: 200 — все успешно, 207 — часть с ошибками, 422 — все с ошибками. У каждой записи есть index, status (created / updated / failed) и причина ошибки.

Допустимые символы идентификаторов

seller_sku может содержать только латинские буквы, цифры и ._- (1–64 символа); штрихкод товара может также содержать / и + (3–64 символа). Регистр не учитывается.

Массовое создание и обновление SKU

POST/api/v1/merchant/skus/batch

До 200 записей за запрос. Каждая запись обрабатывается независимо, ошибка в одной не влияет на остальные.

Пример запроса (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" } ]
    }
  ]
}'

Ответ 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 } }
}

Проверка требований к ввозу (regulation.status)

Список SKU

GET/api/v1/merchant/skus

Фильтры: seller_sku, barcode, regulation_status, updated_since (ISO 8601); пагинация — page / per_page (не более 100).

Один SKU

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

Обновление привязок к маркетплейсам

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

Переданный список полностью заменяет существующие привязки; один и тот же вариант товара на маркетплейсе нельзя привязать к двум SKU.

Скачать этикетки со штрихкодом

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

Возвращает PDF с этикетками 40×30 мм; qty — количество этикеток (1–1000). Склад в Шэньчжэне при маркировке печатает такие же этикетки; этот метод нужен, если вы хотите промаркировать товар самостоятельно до отправки.

Создать заявку на приёмку

POST/api/v1/merchant/inbound-orders

Заявка проверяется целиком: при любой ошибке ничего не создаётся. Трек-номер может одновременно входить только в одну активную заявку на приёмку; повторяющиеся SKU в одной посылке объединяются с суммированием количества.

Пример запроса (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 }
      ]
    }
  ]
}'

Статусы заявки на приёмку

Статусы посылки

Список заявок на приёмку

GET/api/v1/merchant/inbound-orders

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

Фильтры: status, reference_no, updated_since. Для каждой посылки возвращаются заявленное, фактически принятое и повреждённое количество, а также расхождение.

Отменить заявку на приёмку

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

Отменить заявку можно, только пока ни одна посылка не поступила на склад; после отмены трек-номера можно снова указать в заявке.

Запрос остатков

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

Фильтры: warehouse_code и seller_sku[] (не более 200).

Ответ 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 }
}

Журнал движения остатков

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

Записи о движении только добавляются и никогда не изменяются. Листайте вперёд с курсором after_id (не более 500 записей за запрос) и сохраняйте meta.next_after_id из ответа, чтобы продолжить сверку.

Настройка

1. Укажите URL для webhook на странице API в личном кабинете (только https) и пройдите проверку владения: ваш эндпоинт должен ответить HTTP 200 с телом {"challenge": "полученное значение"}.
2. Вызовите PUT /api/v1/merchant/webhook/events, чтобы подписаться на события продавца. Последующая смена URL в личном кабинете не сбрасывает эти подписки.

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

Список событий

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-Lucky-Event, X-Lucky-Delivery-Id и X-Lucky-Signature: t=метка_времени,v1=подпись. Вычислите HMAC-SHA256 от «метка времени + . + исходное тело» с вашим webhook secret, сравните результат с v1 и отклоняйте метки времени старше 5 минут. При повторных отправках одного события delivery_id не меняется, поэтому его можно использовать для устранения дублей.

При ответе, отличном от 2xx, отправка повторяется через 1 минуту, 5 минут, 30 минут, 2 часа и 6 часов; после 20 неудачных попыток подряд webhook автоматически отключается, и его нужно заново настроить в личном кабинете.

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

Официальный аккаунт LINE @0523tw

Техническая почта howyunqisoftware@gmail.com

Версия v1, этап 1 (2026-09-17): SKU товаров, заявки на приёмку, маркировка и размещение на складе в Шэньчжэне, запрос остатков, webhook.