← 여행사 연락처 정리 · 설정 파일 만들기 · 무인 관제탑 · B2C 홈

네이버 웹문서 검색 API 키 발급·설정 절차

여행사 홈페이지 URL 자동·수동 수집(api/travel-agency-collect-websites.php)에 사용합니다. 문서 버전 2026-04-13

아래는 네이버 쪽 화면을 따라가는 상세 단계입니다. 화면 이름은 개편에 따라 조금 다를 수 있습니다.

1단계: 네이버 개발자센터 접속 및 로그인

1. 브라우저에서 네이버 개발자센터에 접속합니다.
2. 네이버 계정으로 로그인합니다. (사업용·공용 계정을 쓰면 퇴사·이관 시 관리가 쉽습니다.)

2단계: 애플리케이션 등록

1. 애플리케이션 목록에서 기존 앱을 고르거나 애플리케이션 등록으로 새 앱을 만듭니다. (로그인 필요 · 구형 메뉴: Application → 애플리케이션 등록)
2. 애플리케이션 이름: 예) OMNI-NEXUS KCTA TOUR 여행사 홈페이지 수집 등 구분 가능한 이름을 입력합니다.
3. 사용 API: 검색을 선택합니다.
4. 비로그인 오픈API 선택 화면이 있으면 검색 관련 항목을 포함해 등록합니다. (웹문서 검색은 검색 API 안에 있습니다.)
5. 환경 추가: 웹 서비스 URL에 https://ikcta.or.kr (필요 시 https://www.ikcta.or.kr)를 넣습니다. 요구 항목이 있으면 안내에 맞게 작성합니다.
6. 등록을 완료해 Client ID와 Client Secret이 발급되는 화면까지 갑니다.

3단계: “웹문서 검색” API 사용 설정

1. 설정 다시 확인: OMNI-NEXUS KCTA TOUR에 쓰는 앱은 애플리케이션 개요(Overview)에서 Client ID·Client Secret을 확인합니다. 화면에 보이는 값이 api/naver-search-config.local.php 안의 naver_client_id·naver_client_secret과 한 쌍으로 정확히 같아야 합니다. Secret이 가려져 있거나 오래됐으면 재발급 후 새 문자열 전체를 복사해 파일을 고치고 FTP로 다시 올립니다.
2. 같은 앱 화면에서 API 설정(또는 Application / 사용 API)으로 들어가 검색 → 웹문서 검색(또는 웹문서)을 사용(ON)으로 둡니다.
3. 다른 앱을 쓰는 경우에는 애플리케이션 목록에서 해당 앱을 연 뒤 위와 같이 확인합니다.
4. 일일 호출 한도는 네이버 정책에 따릅니다. 여행사 목록 일괄 수집 시 한도를 넘기지 않도록 max 건수·실행 주기를 조절하세요.

호출 URL (직접 테스트할 때)

웹문서 검색의 **정식 경로**는 아래와 같습니다. 문서에 “/v1/search/웹문서”처럼 한글로만 적힌 경우가 있어도, 실제 주소는 **영문 코드 webkr** 입니다.

GET https://openapi.naver.com/v1/search/webkr.json?query=테스트&display=10&start=1

검색어(UTF-8): 한글 등은 그대로 URL에 붙이면 안 되고, UTF-8 기준으로 퍼센트 인코딩한 값을 query=에 넣습니다. (예: PHP rawurlencode(), Python urllib.parse.quote().) 서버 수집 스크립트는 이미 이렇게 호출합니다.

헤더: X-Naver-Client-Id, X-Naver-Client-Secret (값은 앱 상세에 표시된 것과 동일 앱이어야 합니다.)

검색 대상 API 코드(참고)

경로는 모두 /v1/search/{코드}.json 형태입니다. 여행사 URL 수집에는 webkr만 필요합니다.

이미지 사이즈 필터 (이미지 검색만 해당)

이미지 검색 API(image)에만 해당하는 옵션입니다. 웹문서(webkr)·여행사 홈페이지 수집과는 무관합니다.

• 사이즈 필터 예: all(전체), large(큰 사이즈), medium(중간), small(작은 사이즈) — 네이버 문서의 파라미터 이름에 따름

정렬 옵션 sort (참고)

일부 검색 API는 결과 정렬을 sort=sim(유사도순), sort=date(날짜순) 등으로 바꿀 수 있습니다.

• 적용: blog, news, book, cafearticle, kin, image, shop
• 비적용: encyc, webkr, doc, adult, errata — 여행사 홈페이지 수집에 쓰는 웹문서(webkr)는 sort를 쓰지 않습니다. OMNI-NEXUS KCTA TOUR 서버·PC 스크립트도 sort 파라미터를 붙이지 않습니다.
• shop 추가: asc(가격 오름차순), dsc(가격 내림차순)
• book 추가: count(판매량순)

오류 SE05 — “존재하지 않는 검색 api”

• URL이 webkr.json이 아니라 웹문서 등 **잘못된 경로**이면 SE05가 납니다. 위 정식 URL을 사용하세요.
• 앱에 **검색 → 웹문서 검색**이 **꺼져 있거나**, 다른 앱의 Client ID/Secret을 섞어 쓴 경우에도 비슷한 오류가 날 수 있습니다. 같은 앱에서 발급한 ID·Secret인지 확인하세요.

오류 “NID AUTH Result Invalid (28) … 인증에 실패했습니다”

네이버가 Client ID·Client Secret 조합을 인정하지 못할 때 나는 메시지입니다. 서버 URL이나 OMNI-NEXUS KCTA TOUR 코드 문제가 아니라, 개발자센터에 등록한 키 값을 다시 확인하는 단계입니다.

• 같은 앱 상세 화면에서 복사한 ID와 Secret인지 확인합니다. (A앱 ID + B앱 Secret 조합이면 28이 납니다.)
• 앱에서 검색 사용 및 웹문서 검색이 사용(ON)인지 확인합니다.
• Secret을 재발급했다면, 예전 Secret이 들어 있는 naver-search-config.local.php는 반드시 새 Secret으로 다시 저장·FTP 업로드합니다.
• 복사 시 앞뒤 공백·줄바꿈이 붙지 않았는지 메모장으로 열어 확인합니다. (마법사로 다시 만들면 따옴표 안 값만 정리됩니다.)

4단계: 서버에 설정 파일 두기

1. 프로젝트의 api/naver-search-config.example.php를 복사합니다.
2. 복사본 이름을 api/naver-search-config.local.php로 바꿉니다. (반드시 .local.php 확장자)
3. 파일을 열어 아래 두 항목에 3단계에서 확인한 값을 그대로 넣습니다.
   • 'naver_client_id' => '여기에_Client_ID'
   • 'naver_client_secret' => '여기에_Client_Secret'
4. 수집 API는 Referer(ikcta.or.kr)와 위 두 값만 사용합니다. 예전에 쓰던 bot_shared_secret 항목이 있으면 삭제하거나 무시해도 됩니다.

5단계: FTP로 서버에 업로드

1. FTP(또는 호스팅 파일관리자)로 사이트 웹 루트의 api 폴더에 연결합니다.
2. naver-search-config.local.php 한 파일을 업로드합니다. (기존에 빈 파일이 있으면 덮어씁니다.)
3. 업로드 후 서버 경로 예: public_html/api/naver-search-config.local.php (호스팅마다 표시 이름만 다를 수 있음)

6단계: 동작 확인

1. 여행사 연락처 정리에 관리자로 들어갑니다.
2. 1차 자동 수집 또는 2차 수동 수집을 눌러 봅니다.
3. 설정이 없거나 키가 비어 있으면 안내 문구에 no_config 또는 empty_keys류 메시지가 표시될 수 있습니다. 파일 경로·따옴표·PHP 문법을 다시 확인합니다.
4. 네이버 API 오류 시 화면에 오류 요약이 나올 수 있습니다. 앱에서 웹문서 검색이 켜져 있는지, Client ID/Secret이 맞는지 확인합니다.

문의: webmaster@ikcta.or.kr