수동 구매 API

채널 하나, 판매자 하나, 구매 주문 하나

구매 주문 하나에 여러 상품이나 SKU를 포함할 수 있지만, 모든 항목은 동일한 채널과 동일한 판매자에 속해야 합니다.

고객이 서로 다른 판매자나 채널의 상품을 구매한다면 HIOBuy 주문 API를 호출하기 전에 애플리케이션에서 채널과 판매자별로 별도의 구매 주문으로 분리해야 합니다.

HIOBuy는 구매 주문을 자동 분할하지 않으며 이 흐름을 위한 일괄 주문 API도 제공하지 않습니다.

채널과 판매자 식별 방법

  • 주문 단위의 channel을 사용합니다. 채널별 단축 경로, 요청 본문, 상품 행의 채널이 일치해야 합니다. lines[] 또는 items[]에 다른 채널을 섞지 마세요.
  • 클라이언트에서 상품을 묶을 때 가능하면 상품 API의 실제 seller.id를 사용합니다. 1688은 sellerOpenId, Taobao 상품 상세는 shop_id에서 가져옵니다. 자동 생성된 대체 값 seller_1688_* / seller_taobao_*, 누락된 ID, 상품 제목 또는 상점 이름은 신뢰할 수 있는 판매자 증거가 아닙니다. Taobao 상점 ID와 렌더링 응답의 판매자 ID는 서로 다른 식별 체계이므로 비교하지 마세요.
  • 표준 생성 요청에 새로운 판매자 필수 필드는 추가되지 않습니다. self 모드에서는 공식 주문 생성 전에 Gateway가 원본 상품 상세로 1688의 판매자를 확인합니다. Taobao는 render_item_list[].seller_id와 함께 요청된 모든 상품과 SKU가 포함되어 있는지 확인합니다. 증거가 없거나 불명확하면 거부합니다.
  • Warehouse 구매 모드에서는 수동 주문을 포함하여 창고가 주문 생성, 구매 시작, 지갑 차감 또는 부분 성공 반환 전에 판매자를 검증해야 합니다. Gateway는 원본 요청의 채널 충돌을 확인하고 플랫폼을 중복 조회하지 않은 채 창고의 검증 오류를 전달합니다. 창고의 별도 인수 검증이 필요하며 Gateway 배포만으로 외부 창고의 구현을 확인할 수는 없습니다.
  • 수동 주문은 channel=manual을 사용하며 모든 항목의 source_platform도 같아야 합니다. seller_name은 표시용 선언일 뿐입니다. 창고는 각 상품의 실제 플랫폼 판매자를 확인하고 확인할 수 없으면 SELLER_ID_UNAVAILABLE을 반환해야 합니다. 호출자가 선언한 이름이나 ID로 이를 대신할 수 없습니다. 창고 계약의 인수 검증이 완료되기 전에는 수동 생성 기능을 켜지 마세요.

오류 및 처리 방법

다음 세 오류는 모두 HTTP 400, 분류 VALIDATION_ERROR를 사용합니다.

오류 코드처리 방법
MULTIPLE_CHANNELS_NOT_ALLOWED채널별로 분리하고 단축 경로, 본문, 상품 행의 채널을 일치시키세요.
MULTIPLE_SELLERS_NOT_ALLOWED각 채널 안에서 실제 판매자별로 나누어 별도 주문을 생성하세요.
SELLER_ID_UNAVAILABLE유효한 상품/SKU ID 또는 신뢰할 수 있는 창고 판매자 확인 기능을 확보하세요. 변경 없이 재시도하거나 이름으로 추측하지 마세요.

혼합 주문에 대해 API가 반환하는 영어 원문:

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

판매자 검증에서 거부되면 구매 주문이나 구매 작업을 생성하거나 지갑을 차감하거나 부분 성공을 만들어서는 안 됩니다. 기존 멱등성 규칙은 유지됩니다. 의도적으로 분리한 구매마다 별도 업무 참조 번호/키를 사용하고, 변경하지 않은 구매를 재시도할 때는 원래 키를 재사용하세요.

구매 주문과 창고 합배송

구매 주문은 개별 판매자에게서 진행하는 중국 내 구매입니다. 서로 다른 구매 주문의 상품은 별도 소포로 입고된 후 창고 및 배송 조건을 충족하면 하나의 국제 발송으로 합칠 수 있습니다. 합배송해도 원래 구매 주문 번호, 국내 배송비, 결제·취소·환불 상태는 합쳐지지 않습니다.

올바른 요청: 검증된 한 판매자의 여러 SKU

창고는 두 상품 URL이 플랫폼의 동일하고 안정적으로 식별된 판매자에게 속하는지 독립적으로 확인해야 합니다. 예시 URL은 판매자 증거나 운영 환경 인수 검증 결과가 아닙니다.

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

잘못된 예제: 실제 판매자가 다름

items[0].product_url이 판매자 A, items[1].product_url이 판매자 B에 속한다면 요청에 seller_name: "Seller A"가 있어도 창고는 MULTIPLE_SELLERS_NOT_ALLOWED를 반환해야 합니다. 소유 관계를 확인할 수 없다면 선언된 이름만으로 수락하지 말고 SELLER_ID_UNAVAILABLE을 반환하세요.

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

창고의 판매자 거부 결과는 기존 업무 번호/멱등성 계약에 따라 재현해야 하며 주문 생성이나 차감이 없어야 합니다. 이미 생성된 주문의 재요청, 상세 조회, 결제, 취소 동작은 유지됩니다.

POST /v1/orders/manual

요청 하나는 한 플랫폼과 한 판매자의 주문 하나를 생성합니다. 같은 판매자의 여러 상품을 담을 수 있습니다. jd, pinduoduo, poizon만 허용하며 seller_name은 필수입니다. 플랫폼이나 판매자가 다르면 다른 업무 주문 번호로 요청을 분리하세요.

Production API Key, order:create 권한, warehouse 모드와 유효한 창고 연결이 필요합니다. 마켓 OAuth는 필요하지 않습니다. Sandbox는 지원하지 않으며 창고의 수동 API 구현과 연동 확인 후 사용하세요.

요청

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16
{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "ko",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id는 앱의 수동 주문 내에서 고유하며 필수입니다. 같은 번호와 내용은 원래 주문을 반환하고 내용을 바꾸면 HTTP 409 IDEMPOTENCY_CONFLICT입니다. 새 구매에는 새 번호를 사용하세요. 생성·결제·취소에 Idempotency-Key가 필수입니다. order_sn은 HIOBuy가 생성하고 item_ref는 생략할 수 있습니다. sellers 배열과 상품별 판매자·플랫폼 지정은 허용하지 않습니다.

필드필수 값 또는 한도
channelmanual
external_order_id1–200
source_platformjd / pinduoduo / poizon
seller_name1–200
currency / monetary_unitCNY / CNY_minor
domestic_shipping_fee / items[].unit_priceinteger ≥ 0
items / items[].quantity1–100 / 1–9999

창고 요금

금액은 정수 CNY 펀 단위이며 3500은 CNY 35.00입니다. 상품액, 국내 운임, 기존 5% 구매 수수료와 총액은 창고가 계산합니다. 예시는 과금 기준·최소 요금·반올림을 정하지 않습니다. HIOBuy는 금액을 저장하며 5%를 다시 더하지 않습니다. 금액이나 상품 매핑이 누락되면 결제할 수 없습니다.

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

기존 주문 작업

생성은 지갑 차감이나 실제 구매를 시작하지 않습니다. 반환된 order_id와 channel=manual로 기존 결제·취소·상세·국내 추적 API를 사용하세요. pay_amount를 보내지 마세요. 저장된 금액과 창고 금액을 대조한 뒤 기존 지갑으로 결제하며 확정 후 구매합니다. 취소는 환불 완료를 뜻하지 않습니다.

{
  "channel": "manual",
  "order_id": "WH10001"
}
{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

재시도 및 제한

시간 초과나 결과 불명 시 원래 번호와 키를 유지하고 상세를 조회하세요. 새 키로 자동 재결제하지 마세요. 상세에는 payment_status, 상품 참조와 요금이 포함됩니다. 마켓 주문 목록 및 마켓 환불 API는 manual을 지원하지 않습니다. 상품 1–100행, 수량 1–9999, 판매자명 200자, 상품명·규격 500자, 비고 1000자, HTTP/HTTPS URL 2048자입니다. 문자열 금액과 소수는 거부합니다.

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support