주문 API 참조

개요

이 페이지는 주문 모듈의 상태, 엔드포인트, 매개변수, 오류 코드를 정리합니다. 전체 워크플로는 Taobao/1688 주문 및 결제 가이드를 참고하세요. webhook으로 주문 업데이트를 수신하는 방법은 별도 참조 페이지가 있습니다.

적용 범위: 여러 시장을 지원합니다. 결제는 VND, USD 또는 RMB(CNY) 로 통일됩니다 — 구매 지갑은 이 세 가지 통화 중 하나로 충전하며, API의 잔액과 주문 금액은 공통 단위(*_cny)로 정규화됩니다.

Elim은 주문 이행과 결제를 담당하는 기술 플랫폼 입니다 — 소매 판매를 하지 않으며 최종 고객을 직접 상대하지 않습니다. 여러분의 시스템은 구매 지갑 을 통해 Elim에 결제하고, Elim이 다시 플랫폼의 판매자에게 결제합니다. 따라서 모든 주문에는 서로 독립적인 두 개의 상태 가 있습니다 — 플랫폼 상태(status)와 Elim과의 결제 상태(payment_status) — 여기에 플랫폼 측 결제 결과 표시(platform_payment_status)가 더해집니다.

모든 엔드포인트는 JWT 인증(Authorization: Bearer <token>) 또는 API Key(x-api-key)가 필요합니다. API 요청 인증을 참고하세요.

플랫폼 상태 (status)

Taobao / 1688 측의 주문 처리 진행 상황입니다.

creating → pending_payment → paid → shipped → completed
                                            ↘ cancelled

Elim 결제 상태 (payment_status)

사용자와 Elim 사이의 결제 진행 상황입니다. status와 독립적 입니다.

unpaid → requested → approved → paid → refunded
   ↑         ↓
   └──── rejected

requested 상태에서 사용자는 자신의 요청을 철회하여 unpaid로 되돌릴 수 있습니다(cancel-payment-request 참고). approved 이후에는 환불로만 되돌릴 수 있습니다.

플랫폼 결제 결과 (platform_payment_status)

Elim이 플랫폼에 결제를 시도한 후에만 값이 존재합니다.

인터페이스에는 항상 status와 payment_status를 함께 표시하세요. platform_payment_status는 주로 문제 발생 시 진단용입니다.

주문 엔드포인트

접두사 /v1/orders. Rate limit은 초 단위 윈도우 기준입니다.

미리보기 및 주문 생성 — 본문

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "town": "天河南街道"
  },
  "line_items": [
    { "product_ref": "734467086498", "sku_ref": "5578084256927", "quantity": 2, "price": 15.5 }
  ],
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "idempotency_key": "checkout-2026-08-25-001",
  "remark": "판매자를 위한 메모",
  "promotion_id": "PROMO123"
}

line_items[]

각 요소는 product_ref + sku_ref 쌍으로 품목을 식별하며, 상품 검색 / 상세에서 직접 가져옵니다.

mp_id + mp_skuid(marketplace ID) 쌍도 하위 호환을 위해 계속 허용됩니다.

receiver_address

미리보기 응답

{
  "success": true,
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "currency": "CNY",
  "total_product_amount": 31.0,
  "total_post_fee": 8.0,
  "total_amount": 39.0,
  "shops": [
    {
      "seller_id": "b2b-2201234567",
      "seller_name": "广州某某贸易有限公司",
      "post_fee": 8.0,
      "shop_amount": 31.0,
      "items": [
        { "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "unit_price": 15.5, "total_price": 31.0 }
      ]
    }
  ],
  "unavailable_items": []
}

주문 생성 응답

{
  "status": "pending_payment",
  "data": {
    "id": "ORD0000000123",
    "order_list": [
      {
        "success": true,
        "amount": 39.0,
        "post_fee": 8.0,
        "lines": [
          { "sub_id": "E2101234567890", "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "amount": 31.0 }
        ]
      }
    ]
  }
}

새 주문은 항상 payment_status = unpaid 상태입니다.

주문 목록 — 필터 매개변수

GET /v1/orders

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

{
  "total": 1, "page": 1, "size": 20,
  "items": [
    {
      "id": "ORD0000000123",
      "platform": "alibaba",
      "status": "paid",
      "payment_status": "paid",
      "total_amount_cny": 39.0,
      "total_amount": 39.0,
      "products": [
        { "id": "734467086498", "name": "某某商品", "price": 15.5, "quantity": 2, "img_urls": ["https://..."] }
      ],
      "created_at": "2026-04-09T10:30:00.000Z"
    }
  ]
}

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

주문 상세 — 플랫폼별 차이

GET /v1/orders/:id — 응답 전에 플랫폼에서 상태를 자동 동기화합니다.

platform 필드는 목록 응답에 이미 있습니다 — 상세를 호출하기 전에 표시 방식을 정하기 위해 저장해 두세요.

package_id는 Taobao 주문 상세 응답에서 얻는 정수 이며, ORD... ID가 아닙니다.

주문 취소 — 조건

POST /v1/orders/:id/cancel — status가 creating 또는 pending_payment일 때만 가능.

주문에 아직 플랫폼 주문 코드가 없는 경우: { "success": true, "message": "Internal order cancelled, no external order to cancel" }.

구매 지갑 엔드포인트

접두사 /v1/purchasing.

GET /v1/purchasing/wallet

{
  "balance": 1670.30,
  "frozen_balance": 286.50,
  "available_balance": 1383.80,
  "total_deposited": 5000.00,
  "total_spent": 3329.70,
  "updated_at": "2026-06-19T00:00:00.000Z"
}

GET /v1/purchasing/wallet/transactions

매개변수: page, size, type, date_from, date_to. 응답: { total, page, size, items }.

GET /v1/purchasing/exchange-rates

통화쌍(VND→CNY, USD→CNY)별 활성 환율 배열: source_currency, target_currency, rate(시장 환율), markup_percent, effective_rate(마크업 적용 후 Elim이 적용하는 환율).

주문 결제 엔드포인트

접두사 /v1/purchasing/orders/:id. :id는 ORD... 형식.

POST …/request-payment

{
  "success": true,
  "order_id": "ORD0000000123",
  "frozen_amount": 286.50,
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00
}

지갑 잔액 부족 오류 — 400:

{
  "error": "insufficient_balance",
  "current_balance": 120.00,
  "available_balance": 90.00,
  "required": 286.50,
  "deficit": 196.50
}

POST …/confirm

{
  "order_id": "ORD0000000123",
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00,
  "total_amount_cny": 286.50,
  "payment_status": "paid",
  "wallet_balance_after": 1383.80
}

wallet_balance_after를 사용하면 GET /v1/purchasing/wallet를 다시 호출하지 않고도 표시 잔액을 갱신할 수 있습니다.

Elim이 수행하는 상태 전이

사용자는 이 작업들을 호출하지 않습니다. payment_status가 어떻게 바뀌고 언제 payment.updated를 받는지 설명하기 위해 나열합니다.

webhook으로 주문 업데이트 수신

webhook을 등록하면 주문의 status 또는 payment_status가 변경될 때마다 Elim이 여러분의 시스템을 호출합니다 — 상태를 계속 폴링할 필요가 없어집니다. 주문 모듈과 관련된 두 이벤트:

Payload에는 주문 스냅샷이 담깁니다: data.order.id, status, payment_status, platform_payment_status, total_amount_cny, updated_at. 처리 후 HTTP 2xx를 반환하세요.

등록 엔드포인트, 전체 payload 구조, 헤더, HMAC 서명 검증 및 재시도 정책: Webhook 참조 를 확인하세요.

오류 코드

오류 응답은 { statusCode, message, error } 형태를 따릅니다. message는 때때로 베트남어이며 그대로 표시할 수 있습니다.

ID 규칙

• 내부 주문 ID: ORD + 10자리 숫자, 예: ORD0000000123. 모든 엔드포인트에 사용.
• 플랫폼 주문 코드(order_id): Taobao/1688이 발급하며, 주문 생성 성공 후에만 존재.
• package_id: 정수, Taobao 배송 추적에 사용.

관련 링크

• Taobao/1688 주문 및 결제 가이드 — 단계별 워크플로
• Webhook 참조 — order.updated / payment.updated 업데이트 수신
• API 요청 인증
• 전체 API 참조