공급업체 문의 생성

공급업체 대화에 쓰기 작업을 수행하는 엔드포인트는 두 개입니다. 하나는 대화를 시작하고, 다른 하나는 대화를 이어갑니다. 두 엔드포인트 모두 동일한 questions 배열을 받고 Idempotency-Key를 지원합니다.

문의 생성

POST /v1/supplier-inquiries — 스코프 supplier_inquiry:write.

요청 본문

필드	필수	설명
`product_url`	예	1688 또는 타오바오 상품의 절대 링크, 최대 2048자
`questions`	예	1~10개의 질문, 질문 유형 참고
`sku`	아니요	`{ "id": "...", "label": "..." }`, 각 200자 — 질문 범위를 특정 옵션으로 한정
`attachments`	아니요	최대 5개의 파일 참조, 첨부 파일 참고

POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "블랙 / XL" },
  "questions": [
    { "type": "packed_weight", "note": "소매 박스를 포함한 중량" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

응답

201 Created를 반환하며, Idempotency-Key로 이전 요청이 재현된 경우에는 200 OK를 반환합니다.

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "블랙 / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

title, image, shop_id, shop_name은 가능한 범위에서 최선으로 채워집니다. 이 값을 보강하려면 상품 상세 API가 필요한데, 여기에는 애플리케이션이 보유하지 않았을 수도 있는 마켓플레이스 인가가 요구됩니다. 사용할 수 없는 경우 해당 필드는 null로 남고 문의는 정상적으로 진행됩니다.

상품당 하나의 활성 문의

상품에 이미 활성 문의가 있으면 호출이 실패합니다.

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

반환된 inquiry_id를 사용해 후속 질문을 보내세요. 이전 대화가 completed 또는 failed 상태라면 생성 호출이 실패하는 대신 해당 대화를 다시 열고, 새 메시지는 follow_up으로 기록됩니다.

후속 질문 보내기

POST /v1/supplier-inquiries/{inquiry_id}/messages — 스코프 supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "500개 기준" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "500개 기준", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

cancelled 상태의 문의는 새 메시지를 409 INQUIRY_NOT_ACTIVE로 거부합니다. completed 또는 failed 상태의 문의는 다시 열립니다.

첨부 파일

두 쓰기 엔드포인트 모두 선택적인 attachments 배열을 받습니다. 참고 사진, SKU 스크린샷, 치수 도면, 사양서 PDF 등입니다. 첨부 파일은 함께 보낸 메시지에 귀속되므로, 대화의 각 차례가 각자의 첨부 파일을 가집니다.

필드	필수	설명
`url`	예	`https://`만 허용, 최대 2048자. `http:`, `file:`, `data:`, `javascript:`, `ftp:`는 `INVALID_ATTACHMENT_URL`로 거부됨
`type`	아니요	`image`, `document`, `other` 중 하나. 기본값은 `other`
`filename`	아니요	최대 255자
`mime_type`	아니요	최대 128자 — 여러분이 선언한 값이 그대로 저장됨

한 메시지당 첨부 파일은 최대 5개이며, 초과하면 400 TOO_MANY_ATTACHMENTS가 반환됩니다.

HIOBuy는 메타데이터와 URL만 저장하고 파일은 저장하지 않습니다. 첨부 파일 내용을 업로드하거나 다운로드하거나 복사하거나 프록시하지 않으며, 전달받은 URL을 직접 가져오지도 않습니다. 파일은 직접 호스팅하고, 대화가 열려 있는 동안에는 문의 서비스가 해당 URL에 접근할 수 있도록 유지하세요.

멱등성

두 쓰기 엔드포인트 모두에 Idempotency-Key(또는 X-Idempotency-Key, 최대 200자)를 전송하세요. 동일한 애플리케이션에서 같은 키를 재사용하면 처음 생성된 메시지를 상태 코드 201 대신 200으로 반환하며, 공급업체에 두 번 연락하는 일은 절대 없습니다.

시간 초과된 생성 요청은 항상 같은 키로 재시도하세요. 키가 없으면 재시도 과정에서 두 번째 대화가 열리거나 ACTIVE_INQUIRY_EXISTS가 발생할 수 있습니다.

Get Support

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

Email support