키햐 상품 API

빠른 시작

1. 이메일을 인증하고 프로젝트를 신청합니다.
2. 프로젝트와 제공 상품 범위가 승인되면 API 키를 발급합니다.
3. 키를 서버의 비밀 설정에 보관하고 아래 예제로 호출합니다.
4. /policy와 전체 상품 목록을 조회한 뒤 표시·갱신 규칙을 적용합니다.

curl --fail-with-body \
  -H "Authorization: Bearer $KIHYA_API_KEY" \
  -H "Accept: application/json" \
  "https://developers.kihya.com/api/v1/products?limit=100"

const response = await fetch(
  'https://developers.kihya.com/api/v1/products?limit=100',
  { headers: { Authorization: `Bearer ${process.env.KIHYA_API_KEY}` } }
);
if (!response.ok) {
  throw new Error(`KIHYA API returned ${response.status}`);
}
const page = await response.json();
// Follow meta.next_cursor until meta.complete is true.
// Replace the stored catalog only after every page succeeds.

English Quickstart

인증

HTTPS 요청의 Authorization: Bearer <YOUR_API_KEY> 헤더를 사용합니다. 키를 URL, query, 브라우저 코드, 앱 패키지와 공개 저장소에 넣지 마세요. v1은 서버 간 호출을 지원합니다.

• 키는 발급 직후 한 번만 확인할 수 있습니다. 분실하면 새 키를 발급합니다.
• catalog:read는 상품·변경 내역 조회, catalog:export는 CSV 조회 권한입니다. /policy는 모든 유효한 프로젝트 키로 조회할 수 있습니다.
• 프로젝트당 활성 키는 최대 2개입니다. 교체하면 기존 키는 최대 24시간 뒤 만료됩니다. 서버에 새 키를 반영한 뒤 기존 키를 폐기해 주세요.
• 프로젝트 중단·키 폐기·만료는 다음 요청부터 적용됩니다. 여러 키도 같은 프로젝트 호출 한도를 공유합니다.

키 발급·교체는 최근 10분 이내 이메일 인증이 필요합니다. 재인증 후 작업을 다시 진행해 주세요.

상품 API

목록 파라미터

상품 응답 예시

{
    "data": [
        {
            "product_id": "9999990001",
            "offer_id": "9999990001:base",
            "name": "예시 준마이 사케 720ml",
            "volume_ml": 720,
            "pack_quantity": 1,
            "price": {
                "amount": 32000,
                "currency": "KRW",
                "basis": "public_sale"
            },
            "canonical_url": "https://m.kihya.com/goods/goods_view.php?goodsNo=9999990001",
            "referral_url": "https://m.kihya.com/goods/goods_view.php?goodsNo=9999990001&utm_source=example&utm_medium=referral&utm_campaign=catalog",
            "availability": "in_stock",
            "display_allowed": true,
            "fulfillment": {
                "mode": "store_pickup",
                "label": "온라인 주문 · 매장 픽업",
                "region_label": "상품 페이지에서 가능 매장 확인"
            },
            "adult_required": true,
            "source_updated_at": null,
            "verified_at": "2026-09-08T10:00:00+09:00",
            "valid_until": "2026-09-10T10:00:00+09:00"
        }
    ],
    "removed": [],
    "meta": {
        "snapshot_id": "example-snapshot",
        "next_cursor": null,
        "complete": true,
        "recommended_sync_interval_seconds": 3600
    }
}

상품 필드

단건도 data 배열로 응답합니다. 같은 상품의 용량·지역·옵션이 다르면 서로 다른 offer_id로 구분합니다. 승인되지 않거나 존재하지 않는 상품의 단건 조회는 동일하게 404를 반환합니다.

CSV 내보내기

GET /api/v1/catalog.csv에 동일한 Bearer 인증을 적용합니다. CSV에는 catalog:export 권한이 필요합니다. 대시보드의 제공 상품 화면에서도 CSV를 받을 수 있습니다.

CSV는 UTF-8이며 판매 조건마다 한 행을 반환합니다. 열 이름으로 파싱하고 상품번호를 문자열로 보존하세요. 텍스트의 쉼표, 따옴표, 줄바꿈은 CSV 규칙으로 이스케이프하며, 스프레드시트 수식 실행을 막는 처리를 적용합니다.

product_id,offer_id,name,volume_ml,pack_quantity,price_krw,currency,
canonical_url,referral_url,availability,display_allowed,
fulfillment_mode,fulfillment_label,region_label,
verified_at,valid_until,action

action=upsert는 갱신할 판매 조건, action=remove는 제거할 식별자입니다. 제거 행에서는 상품명·가격을 제공하지 않습니다. 다운로드가 실패하면 기존 목록을 유지하세요.

데이터 표시 규칙

• 판매처명은 키햐로 표시하고 상품명·용량·원화 판매가·기준일·수령 방식을 함께 표시합니다.
• 판매 조건의 용량·병 수·지역을 유지합니다. 서로 다른 조건을 이름만으로 합쳐 최저가로 표시하지 않습니다.
• 키햐 연결 버튼은 제공된 referral_url을 사용합니다.
• display_allowed=false, 품절, 판매 종료 또는 유효 기간 만료 상태에서는 가격·판매처 영역을 숨깁니다.
• 이미지·상세 콘텐츠·주문·회원 데이터는 v1 기본 이용 범위에 포함되지 않습니다.

위 안내 문구를 판매처·가격 영역에 상시 표시해 주세요. “온라인 주문 · 매장 픽업”은 실제 해당 수령 방식의 상품에만 적용합니다.

갱신·삭제·중단 처리

권장 수집 주기는 1시간, 최소 기준은 하루 1회입니다. 데이터 유효 기간 상한은 마지막 실제 검증 후 48시간이며, 할인 종료 등으로 더 짧아질 수 있으므로 항상 상품의 valid_until을 따릅니다.

1. 전체 수집은 첫 페이지에서 시작해 같은 snapshot_id에 묶인 next_cursor를 끝까지 따라갑니다.
2. meta.complete=true까지 성공적으로 받은 뒤 전체 목록을 교체합니다. 중간 오류를 전체 삭제로 해석하지 않습니다.
3. removed의 식별자는 즉시 제거합니다. 성공적으로 완주한 전체 목록에 없는 기존 항목도 제거합니다.
4. 커서는 30분간 유효합니다. 409 SYNC_RESTART_REQUIRED이면 첫 페이지부터 다시 수집합니다.
5. 판매·공개 상태와 프로젝트 범위가 바뀌면 기존 수집이 무효화될 수 있습니다.

제공 정책 확인

/policy는 가격 수집과 별개로 최대 5분 간격으로 확인합니다. 프로젝트가 중단되면 전체 가격·판매처 표시를 중단합니다. 15분 동안 유효한 제공 상태를 확인하지 못하면 표시를 보류하고, 정책을 다시 확인한 뒤 복구합니다.

키를 폐기해도 이미 저장한 데이터는 남습니다. 서비스에서 해당 정보를 숨기는 처리와 수동 중단 절차를 준비하세요.

증분 API

GET /api/v1/changes를 커서 없이 호출하면 meta.initialization_required=true와 시작 커서를 반환합니다. 이 커서를 먼저 저장한 다음 상품 전체를 동기화하고, 저장한 커서로 변경 내역을 적용합니다. 초기 응답의 빈 data를 상품 전체 삭제로 처리하지 마세요.

변경 응답의 sequence, action, offer_id, product_id, data, changed_at을 사용합니다. action=upsert는 최신 판매 조건을 갱신하고, action=remove는 해당 판매 조건을 제거합니다. meta.has_more=true이면 다음 커서로 계속 요청합니다.

변경 커서는 7일간 유효합니다. 정책·승인 범위 변경이나 커서 만료로 409가 발생하면 시작 커서를 새로 받고 전체 수집부터 재시작합니다. 증분을 사용하더라도 최소 하루 1회 전체 수집을 유지해 누락을 점검해 주세요.

오류·호출 제한

오류는 JSON으로 반환됩니다. 고정 오류 code, 안내 message와 request_id를 확인하고, 문의 시 인증 키를 제외한 요청 ID를 함께 전달해 주세요.

기본 한도는 프로젝트 합산 분당 60회 · 하루 10,000회입니다. 일일 API 호출 한도는 UTC 00:00, 한국 시간 09:00에 초기화됩니다. 대시보드의 날짜별 사용량은 한국 시간 기준으로 집계하므로 두 지표의 기간이 다를 수 있습니다. 여러 키나 CSV 요청도 프로젝트 한도를 공유합니다. 실제 승인 한도는 프로젝트 대시보드와 정책 응답을 우선합니다.

변경 이력

• 2026.09.08

  상품 API v1 베타 공개

  이메일 로그인, 프로젝트 신청, API 키 관리, 상품 JSON·CSV, 변경 내역·정책 조회, 사용량 대시보드를 제공합니다. 프로젝트와 상품 범위 승인 후 이용할 수 있습니다.

v1의 기존 필드 의미를 유지하며, 필드 제거·타입·가격 기준 등 호환되지 않는 변경은 새 버전으로 분리합니다. 폐지는 원칙적으로 90일 전에 공지합니다.