네이버쇼핑 검색

채널 코드 naver_shopping_search · 수집 환경 linux

네이버쇼핑에서 키워드로 상품 리스트를 정렬별(추천/낮은가격/높은가격/리뷰많은/판매많은/신상품)로 검색·수집합니다. 로그인 기반으로 동작하며 스마트스토어 리뷰와 같은 네이버 계정 세션을 공유합니다 — 허브 '수집 인증'의 'naver_store_review' 계정(쿠키 또는 아이디/비밀번호)을 그대로 사용합니다. 수집 서버는 Windows 위장 + 실제 Chrome + 로그인으로 접근해 영수증 캡차 발생을 최대한 억제하며, 그래도 캡차가 뜨면 풀지 않고 바로 멈춥니다(더 요청하지 않음 — 받은 데까지 담기고, 없으면 실패). ⚠️ 검색 엔드포인트는 차단(평판)에 더 민감하니 호출 간격을 넉넉히 두고, 대량은 레지덴셜/로테이션 IP 사용을 권장합니다. 결과는 상품명·가격·판매몰·리뷰수·평점·이미지(각 항목 extra)입니다.

요청 파라미터

아래 값들을 POST /api/v1/collect 의 params 객체에 담아 보냅니다.

키	타입	필수	기본	설명
keyword	text	예	—	네이버쇼핑 검색어(예: 카누)
sort	enum	—	RECOMMEND	ns/search의 sort 파라미터(실측): RECOMMEND(추천,기본)·LOW_PRICE(낮은가격)·HIGH_PRICE(높은가격)·PURCHASE(판매많은)·REVIEW(리뷰많은)·RECENT(신상품)
limit	number	—	50	최대 수집 상품 수
min_price	number	—	—	이 가격 미만 상품 제외(0/빈값=제한 없음)
max_price	number	—	—	이 가격 초과 상품 제외(0/빈값=제한 없음)
exclude_keywords	text	—	—	이 단어가 상품명에 들어가면 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용
exclude_ads	bool	—	false	체크하면 광고(스폰서) 상품을 제외하고 수집합니다. 기본은 광고 포함

제외 키워드(exclude_keywords)
이 단어가 들어간 글은 수집 단계에서 걸러집니다. 쉼표(,)로 여러 개를 넣고, 한 단어 안에 띄어쓰기도 쓸 수 있습니다(예: "무료 나눔, 광고" → 무료 나눔·광고 두 개). 대소문자는 구분하지 않고 부분 일치로 판정합니다.

기본은 제목 기준 — 상세 요청을 보내기 전에 걸러서 빠르고, 수집 상한(limit)도 차감하지 않습니다.
비우면 → 제외 없이 전부 수집.

요청 예시

curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "naver_shopping_search",
    "params": {
        "keyword": "로얄캐닌",
        "sort": "RECOMMEND",
        "limit": 50,
        "min_price": 10,
        "max_price": 10,
        "exclude_keywords": "광고, 협찬",
        "exclude_ads": false
    }
}'

응답 (202 Accepted)

요청은 즉시 큐에 적재되고 request_id 를 돌려줍니다. 실제 수집은 워커가 비동기로 처리합니다.

{ "success": true, "data": { "request_id": 42, "channel": "naver_shopping_search",
    "status": "pending", "status_url": "https://scraper.conbus.co.kr/api/v1/requests/42" } }

결과 조회 — `GET /requests/{id}`

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다. 결과(items)는 요청별로 보관되므로 같은 글이 다른 요청(다른 키워드·재수집)에 겹쳐도 이 요청의 결과는 그대로입니다 — 여러 요청에 걸친 중복 정리는 post_id로 호출 쪽에서 하세요. 보존 기간은 완료 후 7일입니다. 이 채널은 '지금 상태'가 중요한 데이터라 짧게 보관합니다 — 결과는 받은 즉시 저장하세요. 보존 기간이 지나면 items 는 빈 배열이고 items_expired: true, items_keep_days 가 함께 옵니다(status 는 그대로 done).

진행 중 (pending / running)

아직 끝나지 않았으면 progress 로 진행 상황만 옵니다(items 없음).

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_shopping_search",
        "status": "running",
        "external_ref": null,
        "result_count": null,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": null,
        "duration_ms": null,
        "duration_sec": null,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:01:30+09:00",
        "progress": {
            "count": 12,
            "phase": "list"
        },
        "elapsed_ms": 85000
    }
}

완료 (done)

status 가 done 이면 data.items[] 에 결과가 담깁니다. 실패 시엔 status: "failed" 와 error 가 옵니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_shopping_search",
        "status": "done",
        "external_ref": null,
        "result_count": 1,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:02:00+09:00",
        "duration_ms": 115000,
        "duration_sec": 115,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:02:00+09:00",
        "items": [
            {
                "post_id": "82184942308",
                "url": "https://smartstore.naver.com/examplestore/products/82184942308",
                "title": "카누 미니 마일드 로스트 아메리카노 0.9g",
                "author": "커피생활",
                "posted_at": null,
                "views": null,
                "comment_count": 35201,
                "recommends": 35201,
                "body": null,
                "source": "네이버쇼핑 / 검색:카누",
                "extra": {
                    "mall": "커피생활",
                    "price": 18900,
                    "review_score": 4.8,
                    "review_count": 35201,
                    "product_url": "https://smartstore.naver.com/examplestore/products/82184942308",
                    "is_ad": false,
                    "is_super_point": false,
                    "ad_label": "",
                    "image": "https://shopping-phinf.pstatic.net/.../product1.jpg",
                    "brand": "카누",
                    "category": "식품>커피>커피믹스",
                    "keyword": "카누",
                    "sort": "RECOMMEND",
                    "source_kind": "shopping_search"
                }
            }
        ]
    }
}

실패 (failed)

status 가 failed 면 error 에 사유가 옵니다(items 없음). 일시적 실패는 자동 재시도되며, 위 응답은 마지막 시도 기준입니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_shopping_search",
        "status": "failed",
        "external_ref": null,
        "result_count": 0,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:00:16+09:00",
        "duration_ms": 11000,
        "duration_sec": 11,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:00:16+09:00",
        "error": "수집 실패 — 잠시 후 다시 시도하세요"
    }
}

최상위 data에는 항상 request_id·channel·status·external_ref·result_count·started_at·finished_at·duration_ms·duration_sec·created_at·updated_at이 포함되고, 상태에 따라 items(done)·progress+elapsed_ms(진행 중)·error(failed/cancelled)가 추가됩니다. duration_*는 허브가 잰 수집 소요 시간(시작~종료) — 자세히는 비동기 & 콜백. 요청을 잘못 시작했다면 취소 API로 중단할 수 있습니다.

결과 필드 (`items[]`)

필드	설명
post_id	상품 고유 ID(`nvMid` / channelProductId). 재수집 중복 제거 키
url	상품 페이지 URL(`productUrl.pcUrl`)
title / body	`title`=상품명 / `body`는 `null` (상품 검색은 본문이 없습니다)
author	판매몰(`mall`) 이름을 `author`에도 담습니다
posted_at	작성 시각 (ISO8601, KST) — 상품 검색은 `null`(작성일 개념 없음)
views / comment_count	`views`=`null` / `comment_count`=리뷰 수(표시 일관용, `extra.review_count`와 같은 값)
recommends	리뷰 수 (`comment_count`와 동일 값)
source	`네이버쇼핑 / 검색:{키워드}`
extra.mall	판매몰(샵) 이름
extra.price	판매가(할인 적용가 우선, 원)
extra.review_score	별점(평균 평점). 없으면 `null`
extra.review_count	리뷰 수
extra.product_url	상품 링크(`url`과 동일 값)
extra.is_ad	상단 스폰서 광고면 `true`
extra.is_super_point	슈퍼적립 광고 상품이면 `true`
extra.ad_label	광고 표기 — 일반=빈 문자열(`""`) · `"광고"` · `"슈퍼적립 광고"`
extra.image	상품 썸네일 이미지 URL
extra.brand	브랜드명(없으면 빈 문자열)
extra.category	카테고리명(없으면 빈 문자열)
extra.keyword	검색 키워드(요청값)
extra.sort	정렬 값(요청값)
extra.source_kind	`shopping_search`

채널 참고

네이버쇼핑 검색에는 상품 순위(rank) 값이 없습니다(rank는 쿠팡 검색만 제공). 결과는 선택한 정렬 순서대로, 페이지에 노출된 그대로 나옵니다.
광고는 두 종류 — 상단 스폰서(ad_label: "광고", is_ad=true)와 슈퍼적립(ad_label: "슈퍼적립 광고", is_super_point=true). exclude_ads: true면 둘 다 제외됩니다.
로그인 기반 — 스마트스토어 리뷰와 같은 네이버 계정 세션을 공유합니다(허브 수집 인증의 naver_store_review 계정). 검색 엔드포인트는 평판·캡차에 민감하니 호출 간격을 넉넉히 두세요.
result_count가 요청 limit보다 적으면 오류가 아니라 가용 상품 부족이거나 일시 차단입니다.

결과 수신(폴링·콜백) 방식은 비동기 & 콜백을 참고하세요.