Taobao/1688 주문 생성 및 관리 방법

이 가이드를 사용하는 경우

사용자가 Elimapi를 통해 Taobao/1688에서 제품을 대신 구매할 수 있게 해야 할 때 사용합니다 — 주문 미리보기, 생성, 추적부터 구매 지갑 결제까지.

참고: 이 기능은 현재 베트남 시장만 지원합니다. 다른 시장은 추후 추가될 예정입니다.

전체 참조(상태, endpoint, 파라미터, 오류 코드): 주문 API

사전 조건

• API 인증 정보(JWT 또는 API 키) — API 요청 인증 참조
• 제품 ID 및 SKU ID — 제품 검색에서 확인
• 중국 내 유효한 배송 주소

전체 흐름

Preview → Tạo đơn (payment_status=unpaid) → Xác nhận thanh toán ví → payment_status=paid

각 주문에는 두 가지 독립적인 상태가 있습니다: status(플랫폼)와 payment_status(Elim 지갑). UI에 항상 둘 다 표시하고 — 하나로 합치지 마십시오.

1단계 — 주문 미리보기

미리보기를 호출하여 예상 총액을 확인하고 상품 상태를 점검하세요. 이 단계에서는 주문이 생성되지 않으며 금액이 차감되지 않습니다.

POST /v1/orders/preview

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

unavailable_items 확인 필수: 이 배열이 비어 있지 않으면 주문을 생성할 수 없습니다 — 먼저 사용자에게 오류 항목(품절, 잘못된 SKU, 판매 중단) 처리를 요청하세요.

배송 주소는 중국 내 유효한 주소여야 합니다.

2단계 — 주문 생성

미리보기 단계에서 검증된 데이터(동일한 body)를 그대로 사용하여 실제 주문을 생성합니다:

POST /v1/orders

생성에 성공하면 사용자를 주문 상세 페이지로 리다이렉트하세요(/orders/ORD...) — 주문은 이미 플랫폼에 제출되었으므로 사용자를 장바구니에 머물게 하지 마십시오.

응답 처리:

[!WARNING] 응답이 status: "unknown"을 반환하면 “주문이 생성되지 않았을 수 있습니다 — 지원팀에 문의하세요.”라는 경고를 표시하고 결제 흐름을 계속하지 마십시오.

3단계 — 주문 조회

주문 목록(페이지네이션, JWT로 사용자 식별):

GET /v1/orders?page=1&size=20&platform=taobao&status=paid

필터 파라미터: page, size, platform(taobao/alibaba), status, created_from, created_to.

목록의 line_items는 생성 시점의 스냅샷입니다. 최신 데이터가 필요하면 주문 상세를 호출하세요.

주문 상세:

GET /v1/orders/:id

두 플랫폼 간의 응답 차이점에 유의하세요:

상세 호출 전에 목록 응답의 platform 필드를 캐시하여 올바른 컴포넌트를 렌더링하세요.

4단계 — 주문 취소(필요 시)

POST /v1/orders/:id/cancel

조건: status가 creating 또는 pending_payment일 때만 취소할 수 있습니다. 다른 상태에서는 취소 버튼을 비활성화하세요. 취소 후 GET /v1/orders/:id를 다시 호출하여 최신 상태를 확인하세요.

주문에 플랫폼 주문 ID가 아직 없으면 시스템은 { success: true, message: 'Internal order cancelled, no external order to cancel' }을 반환합니다 — Elim에서는 취소되었지만 Taobao/1688에서는 작업이 수행되지 않았습니다.

5단계 — 주문 결제

Elim은 대행 구매 에이전트 역할을 합니다: 사용자는 구매 지갑(CNY 단위)으로 Elim에 결제하고, Elim이 플랫폼과 정산합니다.

1. 지갑 잔액 확인: GET /v1/purchasing/wallet → { balance, frozen_balance, available }
2. 결제 확인: POST /v1/purchasing/orders/:id/confirm → 시스템이 지갑을 확인하고 금액을 차감한 후 payment_status = paid로 업데이트합니다.
3. 응답의 balance_after를 사용하여 다시 호출하지 않고 지갑 잔액을 업데이트하세요.
4. 지갑 잔액이 부족하면 시스템이 { error: "insufficient_balance", deficit, current_balance, required }와 함께 400을 반환합니다 — 부족한 CNY 금액을 알리고 충전 방법을 안내하는 모달을 표시하세요.

결과 확인

• 미리보기가 예상과 일치하는 총액과 빈 unavailable_items를 반환합니다.
• 주문 생성이 ORD... 형식의 data.id와 status = pending_payment를 반환합니다.
• 결제 확인이 balance_after와 함께 payment_status = paid를 반환합니다.
• 주문 상세에 올바른 status와 payment_status가 표시됩니다.

일반적인 오류 처리

관련 링크

• 참조: 주문 API — 전체 상태, 파라미터, 오류 코드
• 인증: API 요청 인증