스마트스토어 리뷰

채널 코드 naver_store_review · 수집 환경 linux

네이버 스마트스토어/브랜드스토어 상품 리뷰를 수집합니다. 비로그인·데이터센터 IP로는 '영수증 인증 캡차'에 막혀 로그인 세션이 필수입니다 — 허브 '수집 인증'에 네이버 계정을 쿠키 또는 아이디/비밀번호로 'naver_store_review'에 등록하면, 워커가 받아 로그인 상태로 접근합니다. 아이디/비밀번호로 등록하면 쿠키 만료 시 워커가 자동 재로그인해 갱신하므로 수동 관리가 필요 없습니다(2단계 인증은 꺼두세요). 입력은 상품 URL 하나면 됩니다. 차단에 민감하니 호출 간격을 넉넉히 두고 한 계정 과사용을 피하세요.

요청 파라미터

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

키	타입	필수	기본	설명
product_url	text	예	—	예: https://smartstore.naver.com/{스토어}/products/1234567890
limit	number	—	50	최대 수집 리뷰 수
sort	enum	—	REVIEW_RANKING	reviewSearchSortType 값(실측): 랭킹순=REVIEW_RANKING(기본, 빈값 ""도 랭킹순으로 처리) · 최신순=REVIEW_CREATE_DATE_DESC · 평점높은순=REVIEW_SCORE_DESC · 평점낮은순=REVIEW_SCORE_ASC. ※랭킹순은 내부적으로 파라미터를 생략해 호출(네이버 기본)
min_body_length	number	—	0	리뷰 본문이 이 글자 수보다 짧으면 제외(0=제한 없음). 너무 짧은/사진only 리뷰 걸러내기. 제외분은 수집 상한에 안 세고 다음 리뷰로 채움
exclude_keywords	text	—	—	이 단어가 리뷰 본문에 들어가면 제외. 쉼표로 여러 개

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

리뷰 본문 기준 — 이 단어가 리뷰 내용에 들어가면 결과에서 제외합니다.
비우면 → 제외 없이 전부 수집.

요청 예시

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_store_review",
    "params": {
        "product_url": "https://smartstore.naver.com/{스토어}/products/1234567890",
        "limit": 50,
        "sort": "REVIEW_RANKING",
        "min_body_length": 0,
        "exclude_keywords": "광고, 협찬"
    }
}'

응답 (202 Accepted)

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

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

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

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다.

진행 중 (pending / running)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_store_review",
        "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_store_review",
        "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": "12300045678",
                "url": "",
                "title": "[5점] LG 프라엘 제모기 · 본체 1구",
                "author": "nada*****",
                "posted_at": "2026-06-15T00:00:00+09:00",
                "views": null,
                "comment_count": 0,
                "recommends": 3,
                "body": "생각보다 주행 소음은 있는 편이에요. 그래도 잔털까지 깔끔하게 정리돼서 만족합니다 ...",
                "source": "스마트스토어 / lgcareglobal",
                "extra": {
                    "review_score": 5,
                    "product_name": "LG 프라엘 제모기",
                    "option": "본체 1구",
                    "attaches": [
                        "https://shop-phinf.pstatic.net/.../review_photo1.jpg"
                    ],
                    "review_type": "GENERAL",
                    "monthly_usage": null,
                    "product_no": "10478900033",
                    "source_kind": "store_review"
                }
            }
        ]
    }
}

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_store_review",
        "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. 재수집 중복 제거 키
url	빈 값(`""`) — 리뷰는 개별 URL이 없습니다
title / body	`title`은 `[N점] 상품명 · 옵션` 자동 생성 / `body`는 리뷰 본문
author	마스킹된 작성자 ID (예: `nada*****`)
posted_at	작성 시각 (ISO8601, KST) — 스토어 리뷰는 보통 날짜만 제공(시각 `00:00:00`)
views / comment_count	`null` / `0` — 리뷰는 조회수·댓글이 없습니다
recommends	'도움돼요' 수
source	`스마트스토어 / {스토어}`
extra.review_score	평점 (1~5)
extra.product_name	상품명
extra.option	구매 옵션
extra.attaches	첨부 이미지 URL 배열(포토 리뷰, 없으면 빈 배열)
extra.product_no	상품 번호(originProductNo)
extra.review_type	리뷰 유형
extra.monthly_usage	월 사용 횟수(제공될 때)
extra.source_kind	`store_review`

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