중국–한국 물류 연동 가이드

01 · 운영자 시작하기

1. 작업 공간 이름을 입력하여 테스트 공간을 만듭니다. 운영자 키를 파일로 저장하세요. 브라우저를 닫은 뒤에는 키로 다시 연결합니다.
2. 운임·계약에서 해운/항공 기본 운임, 0.5kg 또는 1kg 추가 구간, 부피 환산값, 중대형 기준과 수수료를 설정합니다. 요금표를 CSV로 내려받을 수 있습니다.
3. API 연동에서 파트너 키를 발급하여 고객사의 서버 담당자에게 안전한 경로로 전달합니다. 운영자 키는 전달하지 마세요.

각 키의 유효기간은 30일입니다. 키 복구·운영자 갱신 기능은 이 파일럿에 포함되지 않습니다. 분실 또는 만료 시 새 테스트 공간이 필요합니다. 파트너 키는 운영자가 폐기·재발급할 수 있습니다.

02 · 주문 접수와 Excel

배송 신청에서 판매자 ID, 외부 주문번호, 노선, 가상 수취인, 신고 구분, 상품과 포장을 입력합니다. 같은 판매자 ID + 외부 주문번호는 중복 등록할 수 없습니다.

1. Excel 접수 → 양식 다운로드. Orders 시트의 영문 열 이름을 유지합니다.
2. 상품 하나당 한 행을 입력합니다. 같은 주문의 공통 정보는 모든 행에서 동일해야 합니다. 전화번호·우편번호는 텍스트로 저장하세요.
3. .xlsx 파일을 선택하고 오류 행을 수정한 후 접수합니다. 최대 2MB, 500행, 100주문, 주문당 50상품입니다. 수식 셀은 허용하지 않습니다.
4. 결과를 확인하고 CSV 결과를 저장합니다. 동일 파일 재접수는 기존 주문을 반환합니다. 이미 접수한 주문 내용을 바꿔 재업로드하면 충돌하므로 별도 주문으로 검증하세요.

03 · 창고와 한국 배송 이력

submitted → received → measured → ready → departed → customs → handoff → delivered

주문 상세에서 순서대로 상태를 등록하고 작업 메모를 남깁니다. 계량 단계에서 실측 중량·크기를 입력하면 당시 운임으로 견적이 고정됩니다. 인계 시에는 규칙에 맞는 운송사와 테스트 송장번호가 필요합니다.

• 문제 발생 시 exception으로 기록하고 해결 후 직전 상태로 복귀합니다. 취소는 출발 이전에만 가능합니다.
• 배송 완료·취소는 최종 상태입니다. 시스템이 자동 조회하는 실제 운송장이나 통관 결과는 없습니다.
• 인계 시 샘플 비용을 한 번 기록합니다. 대사 명세의 월은 UTC 기준이며 최대 5,000행을 조회·다운로드합니다. 합계는 표시된 행 기준입니다.

04 · API quick start (English)

Base URL: https://YOUR-SITE. JSON over HTTPS. API keys belong on your server. The public UI creates a sandbox; all /api/v1 routes require a Bearer key. Download OpenAPI above for request and response schemas.

# Create a synthetic workspace (no authentication)
curl -X POST 'https://YOUR-SITE/api/sandbox' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Integration test"}'

# Set API_KEY securely on your own server, using the returned key.
curl 'https://YOUR-SITE/api/v1/shipments?limit=20' \
  -H "Authorization: Bearer $API_KEY"

Create an order

Save this synthetic payload as order.json:

{
  "external_order_id": "DEMO-001",
  "seller_id": "test-seller",
  "service": "sea",
  "port": "incheon",
  "recipient": {
    "name": "Synthetic recipient",
    "phone": "01000000000",
    "postcode": "00000",
    "address": "Synthetic test address"
  },
  "clearance_type": "personal",
  "declaration_currency": "USD",
  "items": [
    {
      "name_en": "Cotton shirt",
      "sku": "TEST-SKU",
      "quantity": 1,
      "unit_value": 10
    }
  ],
  "parcel": {
    "weight_kg": 1,
    "length_cm": 10,
    "width_cm": 10,
    "height_cm": 10
  }
}

curl -X POST 'https://YOUR-SITE/api/v1/shipments' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: partner-demo-2026-001' \
  --data-binary @order.json

201 creates a shipment; 200 with replayed:true returns the existing shipment for the same normalized payload and idempotency key. A changed payload or duplicate seller/order reference returns 409. Never generate a new key on network retries. A workspace partner key can access every seller in that workspace: do not share it with individual sellers.

Warehouse update & synchronization

POST /api/v1/shipments/{id}/events
Authorization: Bearer <operator-key>
Content-Type: application/json

{"version":1,"status":"received","note":"Synthetic warehouse receipt"}

GET /api/v1/events?after=0
Authorization: Bearer <partner-key>

Use the latest shipment version. A stale update returns 409 VERSION_CONFLICT; fetch the current shipment and decide whether the update is still appropriate. Read the event feed in sequence, deduplicate by event id, and persist next_cursor only after processing. Poll every 30 seconds when has_more is false; drain immediately when true. Sequence gaps are normal. Version 1 provides a pull feed, not push webhooks.

Limits, errors & access

• JSON body ≤ 1 MiB; batches ≤ 100 orders; items ≤ 50 per order. Batch response is HTTP 207: inspect every result. Batches are not all-or-nothing.
• Operator: rates, manual states, keys, reads and order creation. Partner: reads, quotes and order creation; no warehouse/rate/key changes. Keys are stored as SHA-256 hashes.
• 401: invalid/expired/revoked key. 403: operator required or cross-origin denied. 400: validation. 409: conflict. 422: rate disabled. 503: retry with exponential backoff and jitter, keeping the idempotency key.
• Errors include error.code and request_id; validation errors include details. Responses are no-store. Browser cross-origin integration is disabled; use server-to-server calls.
• Sandbox data remains in the database after the browser closes and after key expiry. Automatic retention/deletion, production accounts and recovery are not implemented in this pilot.