네이버 쇼핑 카테고리·필터 (윈도우 수집기)

채널 코드 naver_shopping_category_search · 수집 환경 windows

키워드마다 네이버 가격비교(search.shopping.naver.com) 검색 결과 화면의 필터 정보를 ID 와 함께 수집합니다 — 카테고리(catId·경로·상품 수) · 키워드추천 · 가격대 · 배송/혜택 · 색상 · 브랜드/제조사 · 속성 필터 · 연관 검색어 · 검색어가 속한 카테고리 · 판매처별 상품 수. 결과는 키워드 1개 = 1건(extra.filters[] 에 화면의 필터 행별 값). 사무실 윈도우 PC 의 쇼핑 수집기 앱이 사람이 네이버에 로그인해 둔 Chrome 으로 쇼핑 홈 검색창에 사람처럼 입력해 검색하므로 키워드당 약 15~25초(100개면 30~45분)가 걸리고, 한 서버는 한 번에 한 요청만 처리합니다. server 를 비우면 허브가 지금 가능한 쇼핑 수집 서버(온라인 · 네이버 로그인됨 · 대기 작업 적은 순)를 골라 배정합니다. ⚠️ 무인 운영 중 네이버 로그인이 풀리거나 보안 확인(캡차)·접속 제한 화면이 뜨면 기다리지 않고 failed 로 끝납니다(재시도 없음 — 수집 PC 의 Chrome 에서 사람이 처리한 뒤 다시 요청).

요청 파라미터

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

키	타입	필수	기본	설명
server	text	—	—	비우면 허브가 지금 쇼핑 수집이 가능한 서버(온라인 · 네이버 로그인됨 · 대기 작업 적은 순)를 골라 배정하고, 응답의 server 로 알려줌. 특정 서버로 보내려면 그 서버 ID(GET /shopping-servers 로 조회)
keywords	text	예	—	배열(["a","b"]) 또는 줄바꿈 · 쉼표 · 탭 · 세미콜론 구분 문자열. 앞뒤·연속 공백은 정리, 대소문자만 다른 중복은 하나로, # 으로 시작하는 항목은 무시. 최대 100개, 키워드당 100자. 키워드 1개 = 결과 1건
start_from_home	bool	—	true	켜면(기본) 키워드마다 쇼핑 홈 검색창에 입력, 끄면 첫 키워드 뒤로는 결과 화면 상단 검색창에 이어서 입력(조금 빠름)

요청 예시

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_category_search",
    "params": {
        "keywords": [
            "원피스",
            "파리바게트"
        ],
        "start_from_home": true
    }
}'

응답 (202 Accepted)

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

{ "success": true, "data": { "request_id": 42, "channel": "naver_shopping_category_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_category_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_category_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": "원피스",
                "url": "https://search.shopping.naver.com/search/all?query=%EC%9B%90%ED%94%BC%EC%8A%A4",
                "title": "원피스",
                "author": null,
                "posted_at": "2026-10-08T18:35:52+09:00",
                "views": null,
                "comment_count": null,
                "recommends": null,
                "body": "상품 수 16,699,071 · 검색어 유형 카테고리\n매칭 카테고리: 패션의류 > 여성의류 > 원피스 (50000000 > 50000167 > 50000807)\n연관: 홀복원피스 | 파티 원피스 | 하객 원피스\n카테고리: 패션의류(50000000) | 출산/육아(50000005)\n가격: 2만원 ~ 4만원 [HIT] | 4만원 ~ 7만원 · 직접입력 0 ~ 999,999,990원",
                "source": "패션의류 > 여성의류 > 원피스",
                "extra": {
                    "kind": "shopping_filters",
                    "source_kind": "naver_shopping_category_search",
                    "keyword": "원피스",
                    "status": "ok",
                    "query": "원피스",
                    "orig_query": "원피스",
                    "query_changed": false,
                    "total_products": 16699071,
                    "query_type": "카테고리",
                    "adult_query": false,
                    "matched_category": {
                        "path": "패션의류 > 여성의류 > 원피스",
                        "ids": "50000000 > 50000167 > 50000807",
                        "levels": [
                            {
                                "level": 1,
                                "id": "50000000",
                                "name": "패션의류",
                                "relevance": 0.99
                            }
                        ]
                    },
                    "matched_category_id": "50000807",
                    "related": [
                        "홀복원피스",
                        "파티 원피스",
                        "하객 원피스"
                    ],
                    "related_bottom": [
                        "여름 원피스",
                        "원피스 브랜드"
                    ],
                    "screen_rows": [
                        "카테고리",
                        "브랜드",
                        "키워드추천",
                        "소매기장",
                        "가격",
                        "배송/혜택",
                        "색상"
                    ],
                    "filters": [
                        {
                            "group": "카테고리",
                            "title": "카테고리",
                            "name": "category",
                            "type": "category",
                            "on_screen": true,
                            "param": "catId",
                            "values": [
                                {
                                    "title": "패션의류",
                                    "id": "50000000",
                                    "shp_id": "50000000, 전체>패션의류",
                                    "path": "전체>패션의류",
                                    "count": 8560028,
                                    "rank": 1,
                                    "on_screen": true
                                }
                            ]
                        },
                        {
                            "group": "가격",
                            "title": "가격",
                            "name": null,
                            "type": "price",
                            "on_screen": true,
                            "price_min": 0,
                            "price_max": 999999990,
                            "values": [
                                {
                                    "title": "2만원 ~ 4만원",
                                    "id": "20000-40000",
                                    "title2": "20,000 ~ 40,000원",
                                    "hit": true,
                                    "rank": 1,
                                    "on_screen": true
                                }
                            ]
                        },
                        {
                            "group": "색상",
                            "title": "색상",
                            "name": null,
                            "type": "color",
                            "on_screen": true,
                            "values": [
                                {
                                    "title": "블랙",
                                    "id": "0",
                                    "color": "#000000",
                                    "on_screen": true
                                }
                            ]
                        },
                        {
                            "group": "브랜드(요약)",
                            "title": "브랜드",
                            "name": null,
                            "type": "brand",
                            "on_screen": false,
                            "summary": true,
                            "values": [
                                {
                                    "title": "JJ지고트",
                                    "id": "157161",
                                    "count": 16611
                                }
                            ]
                        },
                        {
                            "group": "총기장",
                            "title": "총기장",
                            "name": null,
                            "type": "attribute",
                            "on_screen": false,
                            "filter_id": "10013381",
                            "values": [
                                {
                                    "title": "롱",
                                    "id": "M10013381|M10557685"
                                }
                            ]
                        }
                    ],
                    "sellers": [
                        {
                            "title": "전체",
                            "id": "total",
                            "count": 16699071
                        },
                        {
                            "title": "가격비교",
                            "id": "model",
                            "count": 120334
                        }
                    ],
                    "searched_at": "2026-10-08T18:35:52+09:00",
                    "source": "router"
                }
            }
        ]
    }
}

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "naver_shopping_category_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": "네이버 로그인 필요 — 수집 PC 의 수집용 Chrome 에서 다시 로그인해야 합니다 (로그인 화면이 떴습니다)"
    }
}

최상위 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	검색 키워드 그대로 — 결과는 키워드 1개 = 1건. 허브 축적본에서는 같은 키워드가 가장 최근 결과로 바뀌고, 요청별 결과(`GET /requests/{id}`)는 요청마다 따로 남습니다
url	그 키워드의 네이버 가격비교 검색 결과 화면 주소
title / body	`title`=키워드 / `body`=사람이 읽는 요약(여러 줄 — 상품 수 · 검색어 유형 · 매칭 카테고리(ID) · 연관 검색어 · 화면의 필터 행별 값, 카테고리는 `이름(ID)`). 프로그램에서는 `extra` 를 쓰세요
author	항상 `null`
posted_at	작성 시각 (ISO8601, KST) — 이 채널은 검색(수집) 시각입니다(`extra.searched_at` 과 같음, 글 작성 시각이 아님)
views / comment_count	항상 `null`
recommends	항상 `null`
source	검색어가 속한 카테고리 경로(`패션의류 > 여성의류 > 원피스`), 없으면 `네이버 가격비교`
extra.kind / source_kind	`shopping_filters` / `naver_shopping_category_search`
extra.keyword / status	키워드 · `ok`(결과 있음) 또는 `no_results`(검색 결과 없음 — 0건도 한 건으로 옴)
extra.query / orig_query / query_changed	네이버가 실제로 검색한 말 · 입력한 말 · 둘이 다른지(오타 교정 등)
extra.total_products / query_type / adult_query	전체 상품 수 · 네이버가 판단한 검색어 유형(예: `카테고리`) · 성인 검색어 여부
extra.matched_category / matched_category_id	검색어가 속한 카테고리 — `path`(경로) · `ids`(catId 경로) · `levels[]`(단계별 `{level, id, name, relevance}`) / 가장 깊은 단계의 catId
extra.related / related_bottom	연관 검색어(화면 상단 · 하단)
extra.screen_rows	화면 필터 표에 보이는 행 이름(순서대로)
extra.filters[]	필터 묶음 — `{group, title, name, type, on_screen, values[]}`(+ 카테고리 `param`=`catId` · 속성 `filter_id` · 요약 `summary`=true · 가격 `price_min/price_max`). `group` 은 화면 행 이름(카테고리 · 키워드추천 · 가격 · 배송/혜택 · 색상 · 브랜드 · 제조사 · 속성 이름), 브랜드·제조사 요약(상위 100개 + 상품 수)은 `브랜드(요약)`·`제조사(요약)`(`on_screen=false`)
extra.filters[].values[]	값 — `{title, id}` 는 항상, 나머지는 있을 때만: `shp_id`(화면의 `data-shp-contents-id`, 표시 글자와 같으면 생략) · `path` · `count`(상품 수) · `hit` · `color` · `title2` · `rank` · `on_screen` · `selected`
extra.sellers	판매처별 상품 수 `[{title, id, count}]`(전체 · 가격비교 · 네이버페이 …)
extra.searched_at / source	검색 시각(KST) · 데이터를 읽은 곳(`router` · `next_data` · 화면만으로 읽었으면 `dom`)

채널 참고

수집 서버 자동 선택 — server 는 선택입니다. 비우면 허브가 지금 쇼핑 수집이 가능한 서버(온라인 · 네이버 로그인됨 · 대기 작업 적은 순)를 골라 배정하고 202 응답의 server 로 알려줍니다. 가능한 서버가 없으면 409 no_shopping_server(이유 포함). 특정 서버로 보내려면 GET /shopping-servers 의 서버 이름을 넣으세요 — 오프라인이면 409 server_offline, 네이버 로그인이 풀린 상태면 409 account_login_required, 보안 확인(캡차)·접속 제한 화면에서 멈춘 상태면 409 account_blocked, 쇼핑 수집기가 없는 서버면 422 not_shopping_server. 배정은 요청 시점에 고정됩니다.
keywords 는 배열(["a","b"]) 또는 줄바꿈 · 쉼표 · 탭 · 세미콜론으로 나눈 문자열입니다. 앞뒤·연속 공백은 정리하고, 대소문자만 다른 중복은 하나로 합치며, # 으로 시작하는 항목은 무시합니다. 최대 100개 · 키워드당 100자 — 넘으면 요청 단계에서 422 invalid_params.
오래 걸립니다 — 수집 PC 의 Chrome 이 쇼핑 홈 검색창에 사람처럼 한 글자씩 입력해 검색하므로 키워드당 약 15~25초(키워드 사이 6~15초 휴식 · 20개마다 1~3분 휴식), 100개면 30~45분입니다. 한 서버는 한 번에 한 요청만 처리하므로 뒤에 온 요청은 앞 요청이 끝날 때까지 pending 으로 기다립니다(서버가 작업 중이면 대기 시간 상한으로 끊지 않음). 진행 중에는 progress.count 가 끝낸 키워드 수입니다.
결과에 없는 키워드 — 검색 결과가 없는 키워드는 extra.status = "no_results" 인 한 건으로 옵니다. 검색에 실패한 키워드(일시 오류 등)는 이전 결과를 빈 값으로 덮지 않도록 items 에서 빠지고 warnings.search_failed(키워드 배열)에 남습니다. 한 요청의 시간 상한(수집 PC 설정, 기본 60분)에 닿거나 연속 3개가 실패하면 그때까지 받은 키워드로 done 하고 못 돌린 키워드는 warnings.not_run({keywords, reason} — timeout · errors)입니다 — 그 키워드만 다시 요청하세요.
값 id 규칙: 카테고리 = catId · 브랜드/제조사 = 브랜드/제조사 ID · 속성 = M속성ID|M값ID · 가격대 = 최소-최대 · 색상 = 색상 번호 · 배송유형 = 코드(16/64/256) · 배송/혜택 = 화면 값 ID(arriveGuarantee · fastDelivery · freeDelivery · includeDeliveryFee · 4.8|5 · hotdeal · cardDiscount · coupon · point) · 키워드추천 = 그 말. 화면에 보이는 값만 쓰려면 on_screen=true 인 묶음·값을 고르세요.
로그인·보안 확인 — 수집 PC 의 Chrome 에 사람이 네이버에 로그인해 두고 그 세션을 씁니다(아이디/비밀번호를 API 로 보내지 않음). 무인 운영 중 로그인이 풀리거나 보안 확인(캡차)·접속 제한 화면이 뜨면 기다리지 않고 failed(재시도 없음)로 끝나고, 그 서버는 사람이 그 Chrome 에서 처리하고 [로그인 확인] 할 때까지 위 409 로 요청을 받지 않습니다. 결과 크기는 키워드당 약 10~70KB 입니다.

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