알라딘 OpenAPI 종료 대응: 대체 도서 API와 ZALNAS 적용안

작성 기준: 2026-11-05

이 문서는 대체 API 조사와 향후 구현 방법을 정리한 제안서다. 아래의 신규 Provider, 설정, 목록 생성 및 DB 확장은 아직 구현하지 않았다. 현재 운영에는 기존 카카오 검색과 오늘의 책 저장 목록 임시 복구만 적용되어 있다.

1. 결론

한 API로 알라딘의 모든 기능을 동일하게 대체하기보다 역할을 분리한다.

• 기본 도서 검색·ISBN 조회: 기존 다음(카카오) API를 우선 사용한다.
• 검색 보완: 네이버 책 검색을 선택적으로 추가한다.
• 인기·추천 후보: 도서관 정보나루의 대출 통계를 검토한다.
• 해외 도서·누락 정보: Google Books를 선택적 보완 수단으로 둔다.
• 오늘의 책: 운영자 선정 또는 공개한 선정 규칙으로 별도 구성한다.
• 신간: 주제별 검색 결과를 발간일순으로 모은다. 국내 전체 신간을 빠짐없이 수집한다고 표현하지 않는다.
• 베스트셀러: 검색 정확도순이나 대출순위를 판매순위로 바꾸어 표시하지 않는다. 판매순위 공급원을 별도 확보하거나 메뉴 변경 승인을 받는다.

2. 현재 장애와 운영 상태

알라딘 OpenAPI는 2026-10-30 종료되었다. 운영 서버에서도 기존 API가 종료 안내와 오류 코드 999를 반환하는 것을 확인했다. 새 도메인으로 단순 교체하는 문제가 아니다. 알라딘 공식 종료 안내

ZALNAS의 현재 상태는 다음과 같다.

• /books/search: KakaoBookProvider를 사용하는 기존 검색 흐름이 있다.
• /books/today: 마지막 정상 저장 목록 5권을 수집 기준일과 함께 표시한다. 운영에서 확인한 기준일은 2026-10-29이며 실시간 갱신이 아니다.
• /books/bestseller, /books/new: 기존 알라딘 목록 의존이 남아 있어 자동 갱신 대책이 필요하다.
• /books/view: 기존 DB 도서를 우선 조회하고 ISBN으로 카카오 검색을 사용할 수 있지만 알라딘 상세 보강 경로는 정리 대상이다.
• 카카오: 기존 운영 키로 실제 도서 검색 HTTP 200과 응답을 확인했다. 키 값은 문서에 기록하지 않는다.

현재 구현의 기준은 Book 기능 문서와 저장소 소스다.

3. 대체 API 비교

아래의 추천 조합과 적용 우선순위는 각 API의 기능을 ZALNAS에 맞게 해석한 설계 제안이다.

4. 다음·카카오 적용 방법

제공 기능과 요청

책 검색은 GET https://dapi.kakao.com/v3/search/book을 사용한다. Authorization: KakaoAK <REST_API_KEY> 헤더와 query를 전달한다. target은 제목·ISBN·출판사·인명 검색을 제한하며 sort=latest는 발간일순이다. 응답에는 제목, 소개, ISBN, 출판일, 저자, 출판사, 가격, 표지 URL 등이 있다. 카카오 공식 REST API 문서

실제 키 대신 서버에서 주입하는 환경변수를 사용하는 진단 예시다.

curl --silent --show-error --get 'https://dapi.kakao.com/v3/search/book' \
  --header "Authorization: KakaoAK ${KAKAO_REST_API_KEY}" \
  --data-urlencode 'query=미움받을 용기' \
  --data-urlencode 'target=title' \
  --data-urlencode 'size=5'

이는 서버 내부 확인용 예시다. 운영 구현에서는 HTTP 상태와 응답 구조를 검사하고 키가 담긴 헤더를 로그에 남기지 않는다.

기존 코드 활용

1. /admin/books/api의 기존 카카오 REST API 키 설정을 사용한다. 소셜 로그인 JavaScript 키나 Admin 키와 혼동하지 않는다.
2. app/Services/Books/KakaoBookProvider.php의 search(), searchIsbn()을 유지한다.
3. 현재 search()는 target=title로 고정되어 있다. 저자·출판사 검색까지 지원하려면 허용된 검색 대상만 받도록 메서드를 확장해야 한다.
4. BookNormalizer::fromKakao()와 BookModel::upsertBook()의 기존 저장 흐름을 활용하되, 빈 필드가 기존의 유효한 소개·표지·출판일을 덮어쓰지 않도록 병합 정책을 추가한다.
5. BookService::bookDetail()의 종료된 알라딘 보강 호출은 제거하거나 다른 공급원으로 교체한다. 기존 도서 ID와 공개 상세 주소는 유지한다.

카카오의 호출 한도는 앱 관리 화면과 공식 정책에서 확인한다. 문서 확인 시 책 검색 일간 쿼터는 30,000건이지만 상위 Daum 검색 한도와 월간 한도도 함께 적용될 수 있으므로 고정된 무제한 서비스로 설계하지 않는다. 쿼터 안내

5. 네이버 적용 방법

검색 주소는 https://openapi.naver.com/v1/search/book.json, 상세 검색은 https://openapi.naver.com/v1/search/book_adv.json이다. 요청 헤더에 X-Naver-Client-Id, X-Naver-Client-Secret을 보낸다. 일반 검색은 query, 상세 검색의 ISBN 조건은 d_isbn을 사용한다. sort=date는 출간일순이며 판매순위가 아니다. 네이버 공식 문서

적용 순서는 다음과 같다.

1. 네이버 개발자센터에서 검색 API를 사용할 수 있는 애플리케이션과 자격증명을 준비한다. 기존 소셜 로그인용 설정만으로 검색 API 권한이 있다고 가정하지 않는다.
2. 기존 관리자 설정의 book_api_naver_client_id, book_api_naver_client_secret을 활용한다.
3. 신규 app/Services/Books/NaverBookProvider.php와 BookNormalizer::fromNaver()를 추가한다.
4. 카카오 결과가 없을 때 보완 조회하거나 ISBN이 일치하는 항목에 한해 누락 필드를 보강한다. 제목만 비슷하다고 합치지 않는다.
5. items[]의 title, author, publisher, isbn, pubdate, image, description, discount, link를 공통 구조로 변환한다.

네이버 검색 API는 문서상 하루 25,000회 한도를 사용한다. 응답과 권한은 사용할 실제 애플리케이션으로 확인한다. 네이버의 할인 가격을 정가 필드로 복사하지 않는다. 검색 API 안내

6. 도서관 정보나루 적용 방법

정보나루는 인기대출도서(loanItemSrch), 추천도서(recommandList), 도서 상세(srchDtlList) 등의 API를 제공한다. 인기대출은 기간·지역·연령·KDC 등의 조건으로 조회할 수 있으며, 추천은 ISBN을 기준으로 활용할 수 있다. 공식 활용 가이드·매뉴얼

적용 순서는 다음과 같다.

1. 정보나루에서 API 이용을 신청하고 authKey를 발급받는다. 이번 조사에서는 유효한 새 키를 발급하거나 등록하지 않았다.
2. 신규 Data4LibraryBookProvider.php와 관리자 키 설정을 추가한다. 설정명 book_api_data4library_auth_key는 신규 제안이며 현재 존재하는 설정이 아니다.
3. https://www.data4library.kr/api/loanItemSrch에 authKey, 조회기간, 페이지 조건과 format=json을 전달한다. 실제 키로 이용 가능 여부와 허용 조건을 확인한 뒤 활성화한다.
4. HTTP 200이어도 response.errCode·response.error가 있으면 실패로 처리한다. 인증키 없이 보낸 HTTPS 요청에서 이러한 인증 오류를 실제 확인했다.
5. ISBN으로 카카오·네이버의 표지와 소개를 보완한다. 메타데이터 부족으로 내용을 생성해서 채우지 않는다.
6. 화면에 ‘인기대출 도서’와 집계기간을 표시한다. 기존 ‘베스트셀러’ 메뉴를 바꾸려면 별도 승인을 받는다.

주의: 기존 알라딘 CategoryId와 KDC는 다른 분류체계다. 숫자를 그대로 재사용하지 않고, 선택 카테고리와 KDC 사이의 검토된 매핑표를 별도로 둔다. 지역·연령 조건 등도 운영자가 확인할 수 있게 기록한다.

7. Google Books 보완 적용

검색은 https://www.googleapis.com/books/v1/volumes에 q를 전달한다. ISBN 검색에는 q=isbn:<ISBN>을 사용할 수 있다. 공개 데이터 요청도 문서상 API 키 또는 토큰을 통한 애플리케이션 식별이 필요하다. Google Books 공식 가이드

별도 키와 GoogleBooksProvider를 추가하는 선택 사항이다. 한국어·해외 도서 표본으로 제목, ISBN, 판형·판본, 표지 제공 여부를 확인한 뒤 누락 보완에만 사용한다. 쿼터는 해당 프로젝트 콘솔에서 확인하며, 공개 검색이 일부 성공하더라도 무인증·무제한 운영을 전제로 삼지 않는다.

8. 기존 메뉴별 적용 제안

‘오늘의 책’을 아무 검색 결과 5권으로 바꾸거나 대출순위를 판매순위로 표시하지 않는다. 선정 방식과 메뉴 의미가 달라지는 변경은 구현 전에 선택을 확정한다.

9. 공통 저장·캐시·오류 처리

다음은 향후 구현 시 적용할 정책 제안이다.

• 중복 식별은 유효한 ISBN13을 우선하고 ISBN10을 보조로 사용한다. ISBN 없는 자료를 빈 ISBN 하나로 병합하지 않는다.
• API마다 공통 필드로 정규화하되, 원천별 외부 ID·출처·수집시각과 목록 집계기간을 추적할 수 있게 한다. 기존 source_provider 하나만으로 여러 원천의 이력을 충분히 표현한다고 보지 않는다.
• 새 목록 타입을 분리한다. 예를 들어 daily_curated_v1, library_popular_v1, topic_new_v1을 제안하며 기존 hot_cover_big, bestseller_cover_big 데이터를 의미가 다른 목록으로 덮어쓰지 않는다.
• 검색 1일·상세 7일·목록 1일의 기존 캐시 기본값을 출발점으로 사용하되 공급원별 약관, 가격 신선도와 쿼터를 검토해 조정한다.
• HTTP 실패·인증 실패·API 오류 객체를 정상 결과로 하루 동안 저장하지 않는다. 성공 응답의 빈 배열과 실패 응답을 구분한다.
• 401·403은 설정 점검 대상으로, 429·일시 장애는 횟수 제한과 지수 지연 대상으로 구분한다. 모든 요청에서 연속 재시도하지 않는다.
• 목록 갱신은 정상 응답·정규화·저장까지 성공했을 때만 완료 표시한다. 실패 시 마지막 정상 목록과 실제 기준일을 유지한다.
• 비어 있는 값으로 기존 도서 정보를 지우지 않는다. 특히 가격 미제공을 무료 판매로 해석하지 않는다.
• API 키·Secret·authKey·전체 인증 URL은 본문·첨부·Git·공개 로그에 넣지 않는다. authKey가 쿼리에 들어가는 공급원은 URL 로그를 마스킹한다.
• 소개·이미지의 표시, 출처 표기와 캐시 허용 범위는 각 제공처의 최신 이용약관을 확인한다. 이미지가 없으면 임의의 다른 판본 표지를 붙이지 않는다.

10. 구현 순서와 변경 파일

1. 선정 방식과 베스트셀러 처리 방식을 먼저 확정한다. 오늘의 책의 현재 임시 복구는 유지한다.
2. 키를 준비한 공급원만 활성화하고, 비밀값은 기존 관리자 설정 또는 서버의 보호된 설정에 저장한다.
3. app/Services/Books에 신규 Provider와 정규화 코드를 추가하고 공급원별 성공·실패 형식을 테스트한다.
4. app/Services/BookService.php에서 검색·상세 보완과 목록 생성 역할을 분리한다. 알라딘으로의 신규 실호출은 제거한다.
5. app/Models/BookModel.php에 원천·집계기간 저장이 필요하면 실제 스키마를 확인해 마이그레이션을 설계한다. 운영 DB 변경은 백업·복구 SQL 및 별도 승인 후 수행한다.
6. BookController, app/Views/books, BookSeoService의 날짜·출처·목록 명칭을 맞춘다. 기존 URL 변경이 필요하면 별도 결정하며 일괄 변경하지 않는다.
7. modules/books/tools/book_api_sync.py의 알라딘 의존을 정리한다. 현재의 과거 NAS 웹 경로를 그대로 사용해 실행하지 않는다.
8. 로컬 집중 테스트 → 영향 범위 검증 → GitHub main 커밋·Push → 자동 운영 배포 → 실제 운영 Apache PHP 요청으로 검증한다.

이 문서 작성·게시만으로 위 구현이나 설정·스키마 변경이 승인·완료된 것은 아니다.

11. 완료 판정과 복구 기준

• 제목·ISBN·저자·출판사 검색을 실제 지원 범위에 맞게 점검한다.
• 같은 ISBN 중복, 다른 판본 오결합, ISBN 누락, 표지·소개 누락과 품절 가격을 테스트한다.
• 잘못된 키, 429, 타임아웃, HTTP 200 오류 객체와 정상 빈 결과를 각각 시험한다.
• 오늘의 책은 5권, 선정 규칙·실제 수집일·출처 안내를 확인한다.
• 신간 정렬, 판매순위와 대출순위 구분, 집계기간 표시를 확인한다.
• Windows 테스트만으로 완료하지 않고 운영 PHP의 TLS/CA·네트워크·캐시 상태까지 검증한다.
• 실패 시 신규 공급원을 비활성화하고 원래의 날짜가 붙은 마지막 정상 목록을 유지한다. 과거 데이터 삭제를 복구 수단으로 삼지 않는다.

12. 공식 자료와 확인 범위

• 알라딘 서비스 종료 공지: 종료 사실은 공식 공지 목록과 운영 API의 종료 응답으로 교차 확인했다.
• 카카오 도서 검색: 명세 확인 및 기존 운영 키 검색 성공. 실제 키·응답의 비밀값은 제외했다.
• 카카오 쿼터: 사용량과 한도는 앱별로 다시 확인한다.
• 네이버 책 검색: 명세 확인. 실제 검색 권한·응답 검증은 적용 단계에 남아 있다.
• 도서관 정보나루: 명세와 HTTPS 인증 오류 형식 확인. 유효한 authKey를 사용한 목록 조회는 아직 수행하지 않았다.
• Google Books: 명세 확인. 신규 키 발급과 실호출은 수행하지 않았다.

요금·쿼터·약관·제공 필드는 변경될 수 있으므로 실제 개발 착수 시 위 공식 자료를 다시 확인한다.