도매 상품 데이터 API

1. 시작하기

API 키 발급

키는 사전 신청 후 발급해 드립니다. 회사명·담당자·연락처·사용 목적을 적어 dev01@bk-go.co.kr 로 문의하시면 요금제 안내와 함께 키를 전달합니다. 발급된 평문 키는 발급 시 1회만 전달되며 이후에는 다시 조회할 수 없습니다. 분실 시에는 기존 키를 회수하고 새 키를 재발급합니다.

인증

모든 /api/v1 요청에 Authorization 헤더를 붙입니다. 키는 wsk_ 로 시작합니다.

Authorization: Bearer wsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/suppliers"

키는 서버 측에만 보관하세요. 브라우저·앱 등 클라이언트에 키를 심으면 그대로 노출됩니다.

인증 실패 응답 (401)

{
  "detail": "Invalid API key"
}

헤더가 없거나 형식이 잘못되면 "Missing or malformed Authorization header", 키가 없거나 회수됐거나 고객사가 비활성이면 "Invalid API key" 가 내려갑니다.

2. 엔드포인트 레퍼런스

GET /api/v1/suppliers

연동된 도매처 목록.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/suppliers?active=true"

[
  {
    "id": 1,
    "name": "도매토피아",
    "code": "dometopia",
    "base_url": "https://www.dometopia.com",
    "active": true,
    "scope": "all",
    "collector_type": "html",
    "last_crawled_at": "2026-08-14T09:12:33.412000+09:00"
  }
]

GET /api/v1/products

상품 목록. 활성 상품(active=true)만 반환하며 id 오름차순으로 정렬됩니다.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/products?supplier=dometopia&soldout=false&updated_after=2026-08-13T00:00:00&page=1&limit=50"

[
  {
    "id": 10231,
    "supplier_id": 1,
    "supplier_product_code": "DT-884120",
    "name": "스테인리스 보온병 500ml",
    "brand": "락앤락",
    "category": "주방용품 > 텀블러",
    "supply_price": 8900,
    "sale_price": 14900,
    "normal_price": 19000,
    "stock_status": "재고있음",
    "soldout": false,
    "product_url": "https://www.dometopia.com/goods/884120",
    "thumbnail_url": "https://img.dometopia.com/goods/884120_1.jpg",
    "active": true,
    "first_seen_at": "2026-07-02T09:03:11+09:00",
    "last_seen_at": "2026-08-14T09:11:02+09:00",
    "updated_at": "2026-08-14T09:11:02+09:00",
    "options": [
      {
        "option_code": "884120-BK",
        "option_name": "색상",
        "option_value": "블랙",
        "additional_price": 0,
        "stock_quantity": 37,
        "soldout": false
      }
    ]
  }
]

페이지네이션은 오프셋 방식입니다. 응답 배열 길이가 limit 보다 작으면 마지막 페이지입니다. 전량 동기화는 limit=500 으로 page 를 증가시키며 순회하고, 이후에는 마지막 동기화 시각을 updated_after 로 넘기는 증분 방식을 권장합니다.

GET /api/v1/products/{id}

상품 1건 상세. 응답 형태는 목록 항목 1건과 동일합니다(옵션 포함).

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/products/10231"

존재하지 않거나 비활성 처리(도매처에서 삭제)된 상품은 404 입니다.

{
  "detail": "Product not found"
}

GET /api/v1/changes

감지된 변경 이벤트 목록. 최신순(id 내림차순)입니다. sandbox 제외 — sandbox 플랜에서는 403 입니다.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/changes?supplier=dometopia&change_type=PRICE&since=2026-08-13T00:00:00"

[
  {
    "id": 88231,
    "product_id": 10231,
    "option_id": null,
    "change_type": "PRICE",
    "old_value": "8900",
    "new_value": "9400",
    "detected_at": "2026-08-14T09:11:02+09:00"
  }
]

3. 변경 이벤트 종류

수집 시 상품별로 아래 7종의 변경을 판정해 기록합니다. 변경 이력 API 공개 시 change_type 값으로 그대로 사용됩니다.

4. 트렌드 리포트

수집한 상품·변경 이력을 바로 쓸 수 있는 형태로 집계해 돌려주는 읽기 전용 리포트 3종입니다. 응답에는 항상 basis(산출 기준) 가 함께 실려, 수치가 무엇을 세었는지 응답만 보고 알 수 있습니다.

sandbox 미리보기 세 리포트 모두 sandbox 플랜에서도 호출할 수 있고, 결과가 10건으로 잘려 응답합니다(X-Sandbox-Limit: 10 헤더, 응답 본문의 sandbox_preview: true). 정식 플랜에서는 limit 파라미터로 요금제의 1요청 최대 건수까지 받을 수 있습니다.

GET /api/v1/reports/trending

판매량 상위 상품. 누적 판매수량(sales_count) 내림차순이며, 현재 판매중이고 최근 days 일 안에 도매처 목록에서 확인된 상품만 대상입니다. 수요지표의 일자별 스냅샷을 아직 쌓는 중이라, 이번 버전은 증가율이 아니라 누적 판매량 순위입니다.

이 엔드포인트에만 min_price(integer, 기본 1000) 파라미터가 추가로 있습니다. 공급가가 이 금액 미만인 상품은 더미·테스트 SKU 노이즈로 보고 제외합니다. min_price=0 이면 전부 포함합니다.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/reports/trending?days=7&limit=20&min_price=1000"

{
  "report": "trending",
  "basis": "현재 스냅샷의 누적 판매수량(sales_count) 상위 순. ...",
  "days": 7,
  "limit": 20,
  "sandbox_preview": false,
  "generated_at": "2026-08-19T06:42:39.290297Z",
  "items": [
    {
      "id": 5202,
      "supplier_id": 1,
      "supplier_product_code": "4212",
      "name": "[도토로] 손에 묻지 않는 크레용 12색",
      "supply_price": 930,
      "soldout": false,
      "product_url": "https://www.dometopia.com/goods/view?no=4212",
      "sales_count": 243402,
      "view_count": 38660,
      "review_count": 0,
      "event_order_count": 28,
      "rank": 1
    }
  ]
}

GET /api/v1/reports/price-drops

최근 days 일 안에 공급가가 내려간 상품을 인하율 내림차순으로 돌려줍니다. 한 상품에 인하가 여러 번 있었으면 인하율이 가장 큰 1건만 실립니다. drop_rate 는 퍼센트((old-new)/old×100) 입니다.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/reports/price-drops?days=30&limit=20"

{
  "report": "price-drops",
  "basis": "최근 days 일 안에 감지된 PRICE 변경 이력 중 공급가가 내려간 건(old > new)을 ...",
  "days": 30,
  "limit": 20,
  "sandbox_preview": false,
  "generated_at": "2026-08-19T06:42:39.310843Z",
  "items": [
    {
      "id": 10231,
      "supplier_id": 1,
      "supplier_product_code": "884120",
      "name": "스테인리스 보온병 500ml",
      "supply_price": 7600,
      "soldout": false,
      "product_url": "https://www.dometopia.com/goods/view?no=884120",
      "sales_count": 1820,
      "view_count": 9640,
      "review_count": 0,
      "event_order_count": null,
      "old_price": 8900,
      "new_price": 7600,
      "drop_amount": 1300,
      "drop_rate": 14.61,
      "detected_at": "2026-08-18T12:30:52.510629Z"
    }
  ]
}

GET /api/v1/reports/soldout-risk

최근 days 일 안에 품절이 잦았지만 지금은 판매중인 상품을, 품절 발생 횟수(soldout_events) 내림차순으로 돌려줍니다. 재고가 자주 끊기는 상품을 미리 알아 발주·판매 계획에 반영하기 위한 목록입니다.

curl -H "Authorization: Bearer wsk_..." \
  "https://api.api4u.kr/api/v1/reports/soldout-risk?days=30&limit=20"

{
  "report": "soldout-risk",
  "basis": "최근 days 일 안의 SOLDOUT 이벤트 발생 횟수 상위 순. ...",
  "days": 30,
  "limit": 20,
  "sandbox_preview": false,
  "generated_at": "2026-08-19T06:42:39.328136Z",
  "items": [
    {
      "id": 12404,
      "supplier_id": 1,
      "supplier_product_code": "77213",
      "name": "고급 시거잭 청소기",
      "supply_price": 3200,
      "soldout": false,
      "product_url": "https://www.dometopia.com/goods/view?no=77213",
      "sales_count": 412,
      "view_count": 3180,
      "review_count": 0,
      "event_order_count": null,
      "soldout_events": 3,
      "last_soldout_at": "2026-08-17T12:09:06.816591Z"
    }
  ]
}

수요지표 필드

아래 지표는 도매처가 제공하는 누적 수치이며 /api/v1/products 응답에도 함께 실립니다. 도매처가 값을 주지 않는 상품은 null 입니다. 지표만 바뀐 경우에는 변경 이벤트가 생기지 않고 updated_at 도 갱신되지 않으므로, updated_after 증분 동기화가 지표 변동 때문에 흔들리지 않습니다.

5. 요금제 · 호출 한도

한도는 세 가지로 나뉩니다.

• 1요청 최대 건수 — /api/v1/products 의 limit 상한. 더 크게 요청해도 오류 없이 상한으로 잘라서 응답하며, 실제 적용값은 응답 헤더 X-Applied-Limit 로 알려줍니다.
• 일 호출 수 — 초과 시 429.
• 월 호출 수 — 초과 시 429.

호출 수는 고객사 단위가 아니라 API 키 단위로 집계합니다. 일 한도는 UTC 자정, 월 한도는 매월 1일에 초기화됩니다.

샌드박스(sandbox) 플랜

신규로 발급되는 키는 평가용 sandbox 로 시작합니다. 결제 없이 응답 구조와 데이터 품질을 확인해 보시라는 용도입니다.

• GET /api/v1/products — 1페이지 10건만 조회됩니다. 더 크게 요청해도 10건으로 잘리고(X-Sandbox-Limit: 10 헤더), page=2 이상은 403 입니다.
• GET /api/v1/reports/* — 리포트 3종 모두 10건 미리보기로 열려 있습니다.
• GET /api/v1/products/{id}, GET /api/v1/suppliers — 제한 없이 사용할 수 있습니다.
• 상품 상세 조회는 샌드박스에서도 가능합니다 — 일 100회 한도 안에서 자유롭게 호출해 보세요.
• GET /api/v1/changes(변경 이벤트) — 제공되지 않습니다(403).
• 호출 한도 100회 / 일.

{
  "detail": "sandbox 플랜에서는 제공되지 않습니다. 정식 플랜 전환은 관리자에게 문의하세요."
}

정식 전환 — 과금이 확인되면 관리자가 요금제를 basic/pro 등으로 조정합니다. 이때 키를 다시 발급받을 필요는 없고, 쓰던 키 그대로 제한이 풀립니다. 전환 문의는 dev01@bk-go.co.kr 로 보내주세요.

한도 초과 응답 (429)

한도를 넘기는 그 요청부터 429 가 내려갑니다. Retry-After 헤더(초 단위)만큼 기다린 뒤 재시도하세요.

HTTP/1.1 429 Too Many Requests
Retry-After: 37820
Content-Type: application/json

{
  "detail": "Rate limit exceeded for plan 'free' (100/day)"
}

재시도는 Retry-After 를 존중하는 지수 백오프를 권장합니다. 무한 즉시 재시도는 차단 대상입니다.

6. 데이터 갱신 주기 · 이미지 정책

갱신 주기

도매처 데이터는 매일 09시 / 21시(KST) 하루 2회 수집합니다. 수집 직후 상품의 updated_at 이 갱신되므로, 동기화는 수집 시각 이후에 updated_after 로 받아가는 것이 가장 효율적입니다. 도매처 사정에 따라 회차가 지연될 수 있으며, 이 경우에도 updated_at 기준 증분은 누락 없이 이어집니다.

이미지 URL 정책

thumbnail_url 은 도매처 원본 이미지 URL 을 그대로 전달(pass-through)합니다. 이미지를 재호스팅하거나 캐시하지 않습니다.

• 원본 URL 은 도매처 사정으로 예고 없이 바뀌거나 사라질 수 있으며, 가용성·속도를 보장하지 않습니다.
• 상품 이미지의 저작권은 도매처/브랜드에 있습니다. 사용 권한은 이용자가 도매처와 직접 확인해야 합니다.
• 이미지를 상시 노출해야 한다면 이용자 측 스토리지로 복제해 사용하시기를 권장합니다.