주문 API 가이드

주문 API를 통해 타오바오와 1688(알리바바)에서 대리구매 주문을 생성하고 관리할 수 있습니다. 각 주문은 두 가지 독립적인 상태를 유지합니다: 타오바오/1688에서 반환하는 플랫폼 상태(status)와 구매 지갑 시스템이 관리하는 Elim 결제 상태(payment_status).

모든 엔드포인트는 Authorization: Bearer <token> 헤더 또는 API Key(X-API-KEY)를 통한 JWT 인증이 필요합니다.

인증 가이드: Authentication

주문 상태

API를 사용하기 전에 최종 사용자에게 표시할 때 혼동을 피하기 위해 주문의 두 가지 상태 차원을 이해하세요.

플랫폼 상태(status)

타오바오 또는 1688에서의 주문 처리 진행 상황을 반영합니다.

Elim 결제 상태(payment_status)

주문이 Elim에 결제되었는지 여부를 반영합니다. 이 상태는 status와 독립적 — 문제가 발생한 경우 주문이 status=shipped이지만 payment_status=unpaid일 수 있습니다.

주문 미리보기

자세히 보기: 주문 미리보기

실제 주문을 생성하기 전에 미리보기 엔드포인트를 호출하여 예상 총액을 확인하고 상품 가용성을 검사하세요. 이 단계는 주문을 생성하거나 금액을 차감하지 않습니다 — 결제 전 사용자가 확인할 수 있도록 정보만 반환합니다.

속도 제한: 20회 / 60초

POST /v1/orders/preview

요청 본문:

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区"
  },
  "line_items": [
    {
      "mp_id": "734467086498",
      "id": "5578084256927",
      "quantity": 2,
      "price": 15.5
    }
  ]
}

line_items 필드 설명

unavailable_items 처리

응답은 주문할 수 없는 상품(품절, 잘못된 SKU, 판매 중단)을 포함하는 unavailable_items 배열을 반환합니다. 이 배열이 비어있지 않으면 주문 생성을 허용하지 마세요 — 먼저 사용자가 문제 있는 상품을 처리하도록 요청하세요.

{
  "unavailable_items": [{ "mp_id": "123456", "id": "sku_789", "reason": "out_of_stock" }]
}

선택적 파라미터

주문 생성

자세히 보기: 주문 생성

플랫폼에서 실제 주문을 생성합니다. 요청 본문은 미리보기와 동일 — 불일치를 피하기 위해 미리보기 단계에서 이미 검증된 데이터를 사용하세요.

속도 제한: 10회 / 60초

POST /v1/orders

성공적으로 생성된 후, 사용자를 주문 상세 페이지(/orders/ORD...)로 리디렉션하세요. 주문이 플랫폼에 이미 제출되었으므로 사용자를 장바구니 페이지에 머물게 하지 마세요.

응답 처리

ID 규칙: Elim ID는 항상 ORD + 10자리 숫자 형식입니다(예: ORD0000000123). 성공적으로 생성된 주문은 플랫폼의 order_id도 가집니다.

주문 목록

자세히 보기: 주문 목록

현재 사용자(JWT로 식별)의 주문 목록을 반환합니다. 결과는 페이지 처리됩니다.

속도 제한: 30회 / 60초

GET /v1/orders

필터 파라미터

응답: { total, page, size, items: OrderListItem[] }

주문 상세

자세히 보기: 주문 상세

주문의 완전하고 최신 정보를 반환합니다.

속도 제한: 30회 / 60초

GET /v1/orders/:id

ORD... 형식의 ID를 전달하세요.

타오바오와 1688 응답 차이

두 플랫폼은 서로 다른 데이터 구조를 반환합니다 — 별도로 처리해야 합니다:

platform 필드는 목록 응답에서 제공됩니다 — 상세 조회 전 어떤 컴포넌트를 렌더링할지 알기 위해 목록 뷰에서 캐시하세요.

주문 취소

자세히 보기: 주문 취소

취소 가능한 상태의 주문을 취소합니다. 시스템이 성공적으로 취소한 후, GET /v1/orders/:id를 다시 호출하여 최신 상태를 확인하세요.

속도 제한: 10회 / 60초

POST /v1/orders/:id/cancel

조건: status가 creating 또는 pending_payment일 때만 취소할 수 있습니다. 다른 상태에서는 취소 버튼을 비활성화하세요.

물류 추적

자세히 보기: 물류 상세

중국 내 배송 추적 정보를 반환합니다. 타오바오 전용 — 1688 주문은 이미 주문 상세 응답에 logistics.logistics_info[]가 포함되어 있습니다.

속도 제한: 20회 / 60초

GET /v1/orders/:packageId/logistic-detail

packageId는 정수이며, 타오바오 주문 상세 응답에서 가져옵니다 — ORD... 형식의 ID가 아닙니다.

주문 결제

Elim은 대리구매 에이전트 역할을 합니다: 사용자는 구매 지갑(CNY 단위)을 통해 Elim에 결제하고, Elim은 시스템 외부에서 플랫폼에 결제합니다. 전체 흐름:

미리보기 → 주문 생성(payment_status=unpaid) → 지갑 결제 확인 → payment_status=paid

지갑 잔액 확인

GET /v1/purchasing/wallet

응답: { balance, frozen_balance, available } — available = balance - frozen_balance.

결제 확인

POST /v1/purchasing/orders/:id/confirm

시스템이 지갑 확인 → 차감 → payment_status = paid 업데이트합니다.

성공 응답(200):

{
  "order_id": "ORD0000000001",
  "goods_amount_cny": 299.0,
  "shipping_fee_cny": 15.0,
  "service_fee_cny": 15.7,
  "total_amount_cny": 329.7,
  "paid_at": "2026-04-13T10:00:00.000Z",
  "balance_after": 1670.3
}

balance_after를 사용하여 GET /v1/purchasing/wallet을 다시 호출하지 않고 로컬 상태의 지갑 잔액을 업데이트하세요.

잔액 부족 처리

지갑 잔액이 부족한 경우, 시스템은 다음 본문과 함께 400을 반환합니다:

{
  "error": "insufficient_balance",
  "deficit": 50.3,
  "current_balance": 279.4,
  "required": 329.7
}

얼마나 더 CNY가 필요한지 알려주는 모달을 표시하고 충전 방법을 안내하세요. 충전 과정은 시스템 외부에서 진행됩니다(은행 이체) — 관리자가 확인 후 수동으로 충전합니다.

서비스 수수료

서비스 수수료 공식: max(주문_총액 × 수수료_비율, 최소_수수료). 비율과 최소값은 관리자가 설정합니다.

지갑 거래 내역

GET /v1/purchasing/wallet/transactions

환율

GET /v1/purchasing/exchange-rates

Elim이 설정한 현재 환율 VND → CNY 및 USD → CNY를 반환합니다. 사용자가 충전하기 전에 이 환율을 표시하세요.

오류 처리

모든 오류 응답은 { statusCode, message, error } 형식을 따릅니다. 메시지가 베트남어인 경우 사용자에게 직접 표시할 수 있습니다.