FAQ

예스24 회원이라면 별도 가입 없이 바로 이용할 수 있습니다.
상단 로그인 버튼으로 예스24 계정으로 로그인한 뒤, API Key 신청 페이지에서 서비스 정보를 입력하면 즉시 Key가 발급됩니다.

아니요. 예스24 Open API는 예스24 계정을 통한 로그인이 필요합니다.
API 문서, 카탈로그, 오류 코드, FAQ는 로그인 없이 확인할 수 있으나, Key 발급 및 관리는 로그인 후에만 가능합니다.

계정당 API Key는 1개만 발급할 수 있습니다.
이미 발급된 Key가 있는 경우 새 Key를 신청할 수 없습니다. 새 Key가 필요하다면 API Key에서 기존 Key를 폐기한 뒤 다시 신청하세요. Key는 즉시 발급됩니다.

모든 API 요청의 X-Api-Key 헤더에 발급받은 Key 값을 포함합니다. 별도의 토큰 발급 절차는 없습니다.

API Key 페이지 하단 Danger Zone에서 기존 Key를 폐기한 뒤, API Key 신청에서 새 Key를 발급받으세요.
폐기 즉시 기존 Key로의 API 호출은 모두 거부되며, 새 Key는 신청 즉시 발급됩니다. 사용 중인 애플리케이션에 새 Key를 반영해야 합니다.

로그인 후 우측 상단 프로필을 클릭하면 나오는 메뉴에서 API Key와 이용 현황으로 이동할 수 있습니다.
이용 현황에서는 기간별 호출량 추이, Endpoint별 집계를 확인할 수 있습니다. 통계는 전일까지의 집계 데이터를 기준으로 표시됩니다.

즉시 API Key 페이지 하단 Danger Zone에서 해당 Key를 폐기하세요.
폐기 즉시 해당 Key로의 모든 API 호출이 차단됩니다. 이후 API Key 신청에서 새 Key를 즉시 발급받아 서비스에 반영하세요.
Key는 소스 코드, GitHub, 로그 파일 등 외부에 노출될 수 있는 곳에 저장하지 마세요.

아니요. 폐기된 API Key는 복구할 수 없습니다.
폐기 즉시 해당 Key로의 모든 호출이 차단되며, 이전 Key 값은 재사용되지 않습니다.
새 Key가 필요하다면 API Key 신청에서 신규 발급받으세요.

예스24 계정을 탈퇴하면 발급된 API Key는 즉시 폐기되고 비활성화됩니다.
탈퇴 이후 해당 Key로의 API 호출은 모두 거부되며, 약관 동의 및 발급 이력도 함께 삭제됩니다.

안 됩니다. API Key를 JavaScript 코드, HTML 소스, 모바일 앱 바이너리 등 클라이언트에 포함하면 누구나 Key를 추출해 악용할 수 있습니다.
반드시 서버사이드에서만 Key를 보관하고 호출하세요. API Key는 환경변수 또는 보안 저장소에 보관하고, 소스 코드에 직접 포함하지 마세요.
프론트엔드에서 API 데이터가 필요하다면 아래 구조로 연동하세요.
브라우저·모바일 앱 → 이용자의 백엔드 서버 → 예스24 Open API
백엔드가 예스24 API를 호출한 뒤 결과를 클라이언트에 전달하는 방식입니다.

기본 한도는 일 20,000회입니다. 한도는 API Key가 아닌 계정(사용자) 단위로 누적되므로, Key를 폐기하고 재발급해도 당일 호출 카운트는 초기화되지 않습니다.
본인에게 적용된 정확한 한도와 당일 사용량은 이용 현황에서 확인할 수 있습니다.
한도 초과 시 429 Too Many Requests 오류가 반환되며, 한도는 한국 표준시(KST, UTC+9) 기준 매일 00시에 초기화됩니다.

429 Too Many Requests는 두 가지 경우에 반환됩니다.
① 초당 버스트 한도 초과 — 짧은 시간에 요청이 집중되면 일일 잔여 호출량이 남아 있어도 발생할 수 있습니다. 고정된 속도로 분산 호출하고, 429 발생 시 응답 헤더의 Retry-After 값(초 단위)만큼 대기 후 재시도하세요.
② 일일 한도 초과 — 한국 표준시(KST) 자정에 초기화됩니다.
반복 호출이 필요한 구조라면 지수 백오프(exponential backoff)를 적용해 서버 부하를 줄이는 것을 권장합니다.

기본 한도보다 높은 호출량이 필요하다면 1:1 문의로 요청해 주세요.
서비스 목적, 예상 호출량, 사용 방식을 함께 전달하시면 검토 후 안내드립니다. 파트너·엔터프라이즈 등급은 별도 협의를 통해 적용됩니다.

일별 호출 통계는 매일 1회 배치로 집계되며, 전일까지의 데이터가 표시됩니다.
당일 호출 현황은 이용 현황 페이지 상단에서 실시간으로 확인할 수 있습니다.

이용 현황에서는 최근 90일 이내의 데이터만 조회할 수 있습니다.
90일 이전 날짜를 선택하면 조회가 제한됩니다.

공통 응답은 success, message, data, errorCode 구조를 사용합니다.
data 안의 상세 필드는 API별로 다릅니다. 각 API 문서에서 응답 예시를 확인하세요.

목록형 API는 page와 pageSize 파라미터를 사용합니다.
기본값은 page=1이며, pageSize는 최대 100입니다.

searchType으로 ISBN13 또는 ItemId를 선택합니다.
ISBN 기반 조회가 필요하면 ISBN13을, 예스24 상품 번호를 알고 있으면 ItemId를 사용합니다.

상품 검색(/v1/goods/itemList)은 입력한 검색어로 결과가 없는 경우, 검색 엔진이 검색어를 자동으로 교정(맞춤법 수정·유사어 치환 등)하여 결과를 반환할 수 있습니다.
이때 응답 데이터는 요청한 검색어가 아닌 교정된 검색어 기준입니다. 예를 들어 베루나르 베르베르로 검색해 결과가 없으면 베르나르 베르베르 기준 결과가 반환될 수 있습니다.
자세한 내용은 상품 검색 API 문서에서 확인하세요.

목록형 카테고리 API는 엔드포인트 뒤에 /export를 붙이면 결과를 Excel(.xlsx) 파일로 반환합니다. 예: /v1/category/bestseller/export, /v1/category/newproduct/export.
응답은 Excel 형식의 파일(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)이며, 브라우저에서 호출하면 저장 대화상자가 나타나고 API 클라이언트에서는 응답 바이너리를 .xlsx로 저장하면 됩니다.
일반 조회와 동일하게 X-Api-Key 헤더가 필요하며, 결과가 없으면 404가 반환됩니다.

date 파라미터를 생략하면 어제 날짜 기준으로 조회됩니다. 오늘 순위는 아직 집계 전이므로 가장 최근 확정 데이터인 전일 기준으로 반환합니다.
특정 날짜를 조회하려면 date를 yyyy-MM-dd 형식으로 전달하세요. 일별 조회는 해당 일자, 월별 조회는 해당 연월 기준으로 집계됩니다.

네. API 테스트는 입력한 실제 API Key로 예스24 Open API를 직접 호출하므로, 실제 운영 데이터가 그대로 반환됩니다.
실제 호출이기 때문에 일일 호출 한도에 포함됩니다. 응답의 상태 코드·응답 시간·cURL 명령을 함께 확인할 수 있어, 연동 전 요청 파라미터와 응답 구조를 실제 데이터로 검증하는 용도로 사용할 수 있습니다.

예스24 Open API를 통해 제공되는 데이터는 예스24의 지적 재산입니다.
상업적 서비스에 적용하려면 제공 범위, 호출량, 데이터 노출 방식에 따라 별도 검토와 계약이 필요할 수 있습니다. 서비스 출시 전 반드시 1:1 문의로 사용 목적을 알려 주세요.
무단 수집·재배포·재판매는 금지됩니다.

link는 항상 예스24 원본 상품 상세 URL입니다.
애드온에 신청한 회원의 Key로 호출하면 addOnLink에 애드온 클릭 URL(https://apis.yes24.com/a/{userKey}/goods/{상품번호})이 내려갑니다.
미신청 회원의 Key로 호출하면 addOnLink는 공란으로 반환됩니다.

애드온은 예스24 Open API의 부가 서비스입니다.
상품 API 응답의 addOnLink 필드로 이용 회원 전용 수익 연결 URL이 제공되며, 사용자가 해당 링크를 통해 예스24에서 구매하면 이용 회원에게 수익이 귀속됩니다.
애드온이란 무엇이고 어떻게 활용하는지는 애드온 안내에서 자세히 확인할 수 있습니다.

API Key 페이지의 부가서비스 영역에서 신청하기를 누르고 애드온 이용약관에 동의하면 신청됩니다. 동의 시 즉시 활성화되며, 신청 후에는 해제할 수 없습니다.
신청 후 발급된 Key로 상품 API를 호출하면 addOnLink에 애드온 클릭 URL이 반환됩니다.
단계별 절차는 애드온 안내에서 확인하세요.

애드온 수익 연결이 필요한 화면에서는 응답의 addOnLink를 연결하면 됩니다.
애드온 신청 회원의 Key로 호출한 경우 addOnLink가 애드온 클릭 URL로 반환되며, 사용자가 클릭하면 애드온 시스템을 거쳐 예스24 상품 페이지로 이동하고 수익이 연결됩니다.
addOnLink가 공란이면 애드온 미신청 상태이므로 일반 상품 이동에는 link를 사용해 주세요.

다음 항목을 순서대로 확인하세요.
1) X-Api-Key 헤더가 요청에 포함되어 있는지
2) Key 값에 오타나 공백이 없는지
3) API Key에서 해당 Key가 활성 상태인지 (폐기된 Key는 사용 불가)

공통 오류 코드는 문서 > 오류 코드에서 확인할 수 있습니다.