머천트 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 개통을 신청하세요. 심사가 승인되면 API 키가 발급됩니다.
3. API 키는 한 번만 표시됩니다. 서버 측 환경 변수에 보관하고, 브라우저나 앱에는 넣지 마세요.
4. webhook이 필요하면 먼저 회원 센터의 API 페이지에서 URL을 설정하고 검증한 뒤, 머천트 이벤트를 구독하세요.

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Base URL

형식 및 언어

요청과 응답은 모두 JSON입니다. 오류 메시지는 기본적으로 번체 중국어이며, Accept-Language: en을 보내면 영어로 반환됩니다. 프로그램에서 분기할 때는 항상 영어로 고정된 error.code를 사용하세요.

응답 구조

성공 시 {"success": true, "data": …, "meta": …}, 실패 시 {"success": false, "error": {"code", "message", "errors", "context"}}를 반환하며, errors는 필드별 상세 내역입니다. 유일한 예외는 API 키가 없거나 유효하지 않은 경우로, HTTP 401과 함께 body는 {"message": "Unauthenticated."}입니다.

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

요청 한도

API 키당 분당 60회, 일일 5,000회입니다(대용량 요금제는 분당 300회, 일일 50,000회). 일괄 엔드포인트는 한 번 호출을 1회로 계산합니다. 실시간 데이터가 필요하면 폴링하지 말고 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

40×30mm 라벨 PDF를 반환하며, 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. 회원 센터 API 페이지에서 webhook URL을 설정하고(https만 허용) 소유권 검증을 완료하세요. 엔드포인트는 HTTP 200과 함께 body로 {"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=서명이 포함됩니다. webhook secret으로 “타임스탬프 + . + 원본 body”에 대해 HMAC-SHA256을 계산하여 v1과 비교하고, 5분이 지난 타임스탬프는 거부하세요. 같은 이벤트를 재시도할 때 delivery_id는 바뀌지 않으므로 중복 제거에 사용할 수 있습니다.

2xx 이외의 응답은 1분, 5분, 30분, 2시간, 6시간 후에 재시도합니다. 20회 연속 실패하면 자동으로 비활성화되며, 회원 센터에서 다시 설정해야 합니다.

// 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.