쿠팡 상품 리뷰

채널 코드 coupang_review · 수집 환경 linux

쿠팡 상품 리뷰를 수집합니다. 로그인 불필요(공개 리뷰). 수집 서버가 Windows 위장 + 실제 Chrome으로 접근합니다. 차단(Access Denied)되면 바로 멈추고 더 요청하지 않습니다(다른 IP로 우회하지 않음) — 받은 데까지 담기고, 받은 리뷰가 없으면 실패로 끝납니다. 입력은 상품 URL 하나면 됩니다. ⚠️ 한 정렬로 접근 가능한 리뷰는 최대 약 1,500개입니다(쿠팡 리뷰 API 페이지 깊이 제한) — limit이 1,500을 넘으면 별점(1~5)별로 나눠 자동으로 더 수집합니다. 최신순(DATE_DESC)은 별점만 누른 짧은 리뷰가 많아 min_body_length 필터와 함께 쓰면 목표보다 적게 모일 수 있으니, 많이 받으려면 베스트순을 권장합니다. result_count가 limit보다 적으면 오류가 아니라 가용 리뷰 부족(정렬 캡/필터) 또는 일시 차단입니다.

요청 파라미터

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

키	타입	필수	기본	설명
product_url	text	예	—	예: https://www.coupang.com/vp/products/1234567890
limit	number	—	50	최대 수집 리뷰 수. 한 정렬당 최대 약 1,500개 접근 가능(쿠팡 API 깊이 제한) — 초과 시 별점별 분할로 자동 수집
sort	enum	—	ORDER_SCORE_ASC	베스트순=ORDER_SCORE_ASC(본문 있는 리뷰 비율↑, 기본), 최신순=DATE_DESC(별점만 누른 짧은 리뷰 많음). 상품마다 정렬별 가용량이 다름
min_body_length	number	—	0	리뷰 본문이 이 글자 수보다 짧으면 제외(0=제한 없음). 제외분은 수집 상한에 안 세고 다음 리뷰로 채움. ⚠️ 최신순은 짧은 리뷰가 많아 이 필터와 함께 쓰면 목표보다 적게 모일 수 있음
exclude_keywords	text	—	—	이 단어가 리뷰 본문에 들어가면 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용(예: 광고, 협찬, 체험단). 제외분은 수집 상한에 안 세고 다음 리뷰로 채움

제외 키워드(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": "coupang_review",
    "params": {
        "product_url": "https://smartstore.naver.com/{스토어}/products/1234567890",
        "limit": 50,
        "sort": "ORDER_SCORE_ASC",
        "min_body_length": 0,
        "exclude_keywords": "광고, 협찬"
    }
}'

응답 (202 Accepted)

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

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

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

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

진행 중 (pending / running)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "coupang_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": "coupang_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": "8978437291_924505635",
                "url": "https://www.coupang.com/vp/products/8978437291",
                "title": "식기세척기 첫 세제로 대성공! 기름때까지 깔끔",
                "author": "쿠*****",
                "posted_at": "2026-06-17T17:31:38+09:00",
                "views": null,
                "comment_count": 0,
                "recommends": 3,
                "body": "식기세척기 첫 세제로 골랐는데 기름때까지 깔끔하게 빠지네요. 잔여물도 없고 만족합니다 ...",
                "source": "쿠팡 / OO유통",
                "extra": {
                    "rating": 5,
                    "helpful_count": 3,
                    "images": [
                        "https://image1.coupangcdn.com/.../review_photo1.jpg"
                    ],
                    "seller": "OO유통",
                    "item_name": "1박스(120정)",
                    "review_id": "924505635",
                    "product_id": "8978437291",
                    "via_proxy": true,
                    "source_kind": "coupang_review"
                }
            }
        ]
    }
}

실패 (failed)

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

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "coupang_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 — `상품ID_리뷰ID`. 재수집 중복 제거 키
url	상품 페이지 URL — 리뷰는 개별 URL이 없어 상품 URL이 들어갑니다
title / body	`title`은 헤드라인(없으면 본문 앞 60자) 자동 생성 / `body`는 리뷰 본문
author	마스킹된 작성자명
posted_at	작성 시각 (ISO8601, KST)
views / comment_count	`null` / `0` — 쿠팡 리뷰는 조회수·댓글이 없습니다
recommends	'도움돼요' 수
source	`쿠팡 / 판매자` (판매자명 없으면 `쿠팡`)
extra.rating	평점 (1~5)
extra.helpful_count	도움돼요 수
extra.images	리뷰 이미지 URL 배열(없으면 빈 배열)
extra.seller	판매자명
extra.item_name	구매 옵션/품목명
extra.review_id	리뷰 ID
extra.product_id	상품 ID
extra.via_proxy	프록시로 우회 수집됐으면 `true`(데이터센터 직수집이면 없음)
extra.source_kind	`coupang_review`

채널 참고

한 정렬(베스트순/최신순)으로 접근 가능한 리뷰는 최대 약 1,500개입니다 — 쿠팡 리뷰 API의 페이지네이션 깊이 제한(약 50페이지). limit이 1,500을 넘으면 별점(1~5)별로 나눠 자동으로 더 수집합니다.
상품마다 정렬별 가용량이 다릅니다 — 최신순(DATE_DESC)은 별점만 누른 짧은 리뷰가 많고, 베스트순(ORDER_SCORE_ASC)은 본문 있는 리뷰 비율이 높습니다. 한 정렬에서 적게 나오면 다른 정렬로 시도해 보세요.
min_body_length로 짧은 리뷰를 거르면 그만큼 더 많이 훑어야 하므로, 위 1,500 한도 안에서 요청한 수보다 적게 수집될 수 있습니다(특히 최신순엔 짧은 리뷰가 많음). 많이 모으려면 필터를 낮추거나 베스트순을 쓰세요.
exclude_keywords로 특정 단어가 든 리뷰를 거를 수 있습니다(리뷰 본문 기준, 쉼표로 여러 개·대소문자 무시·부분일치). 예: 광고, 협찬, 체험단. 제외된 리뷰는 limit에 세지 않고 다음 리뷰로 채웁니다(단, min_body_length처럼 1,500 한도 안에선 목표보다 적게 모일 수 있음).
result_count가 요청 limit보다 적으면 — 오류가 아니라 가용 리뷰 부족(정렬 캡/필터)이거나 일시 차단입니다. 응답의 review_total(상품 전체 리뷰 수)과 비교해 판단하세요.
로그인 불필요(공개 리뷰). 익명으로 접근하며, 차단(Access Denied)되면 바로 멈추고 더 요청하지 않습니다(다른 IP로 우회하지 않음 — 받은 데까지 담기고 warnings.blocked, 받은 리뷰가 없으면 failed). 대량 수집은 사람처럼 페이지마다 텀을 둬 시간이 걸립니다.

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