사용 가이드

인증, 응답 형식, 공통 엔드포인트, 에러 코드입니다. 채널별 파라미터는 좌측 수집 채널에서 확인하세요.

인증

모든 요청에 발급받은 API 키를 헤더로 포함합니다. 키는 관리자에게 발급받으세요(없거나 비활성이면 401).

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY 헤더로 보내도 됩니다.

화이트리스트 IP — 키 없이 호출
관리자가 API 키에 허용 IP를 등록해 두면, 그 IP에서 오는 요청은 키(헤더) 없이도 해당 키로 인증됩니다(요청한 클라이언트의 실제 IP 기준).

키를 보내면 → 항상 키로 인증(허용 IP 무관).
키가 없으면 → 요청 IP가 어떤 키의 허용 IP에 맞으면 그 키로 통과, 아니면 401.
허용 IP는 단일 IP·CIDR 대역(IPv4/IPv6)을 지원합니다. 등록은 관리자 → API 키에서.

응답 형식

// 성공
{ "success": true, "data": { ... } }

// 실패
{ "success": false, "error": { "code": "invalid_params", "message": "..." } }

엔드포인트

GET/channels

호출 가능한 채널과 파라미터 정의를 반환합니다.

POST/collect

수집 요청 생성. 202로 request_id를 즉시 반환(수집은 백그라운드 진행).

필드	타입	필수	설명
channel	string	예	채널 코드 (좌측 수집 채널 참고)
params	object	예	채널별 파라미터
callback_url	URL	아니오	완료 시 결과 요약 POST 받을 주소
external_ref	string	아니오	클라이언트 식별자(응답·콜백에 반환)
priority	int	아니오	클수록 먼저 처리

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

GET/requests/{request_id}

상태 조회. 완료 시 data.items에 결과 배열 포함. (본인 키로 만든 요청만 조회)

{ "success":true, "data":{ "status":"done", "result_count":30,
    "items":[ { "post_id":"...", "title":"...", "author":"...", ... } ] } }

GET/requests

본인 키로 만든 최근 요청 목록(최대 50건).

GET/cafe-servers

네이버 카페(윈도우 수집기) 채널 전용 — 수집 서버 → 계정(로그인 상태) → 가입 카페 목록을 돌려줍니다. naver_cafe_win 요청의 server / account / cafe_id 는 이 목록 안의 조합이어야 하며, 서버가 online:false 이거나 계정이 login_state:"out"(로그인 필요) 또는 "blocked"(네이버 차단·보호조치 의심, 사람이 해제할 때까지) 이면 요청이 409 로 거절됩니다.

{ "success":true, "data":{ "channel":"naver_cafe_win", "servers":[
    { "server":"win-office-01", "online":true, "status":"active",
      "accounts":[ { "account":"기본", "login_state":"in",
        "cafes":[ { "cafe_id":"10258021", "name":"강아지를 사랑하는 모임" } ] } ] } ] } }

GET/flex-servers

flex(HR) 윈도우 수집기 채널(flex_notice · flex_time_off · flex_member) 전용 — flex 수집기 앱이 있는 수집 서버와 flex 로그인 상태를 돌려줍니다. 요청의 server 는 선택입니다 — 비우면 허브가 이 목록 중 지금 가능한 서버(온라인 · 로그인됨 · 대기 작업 적은 순)를 골라 배정하고, 지정한다면 이 목록 안이어야 하며, online:false 이거나 login_state 가 "out"(자동 로그인까지 실패) · "blocked"(추가 인증 화면) 이면 409 로 거절됩니다. 로그인 세션이 풀려도 수집 PC 가 자동으로 다시 로그인하므로 평소에는 "in" 입니다.

{ "success":true, "data":{ "channels":["flex_notice", "flex_time_off", "flex_member"], "servers":[
    { "server":"win-flex-01", "online":true, "status":"active", "login_state":"in", "version":"flex-win-1.0.0" } ] } }

GET/shopping-servers

네이버 쇼핑 카테고리·필터(윈도우 수집기) 채널(naver_shopping_category_search) 전용 — 쇼핑 수집기 앱이 있는 수집 서버와 네이버 로그인 상태를 돌려줍니다. 요청의 server 는 선택입니다 — 비우면 허브가 이 목록 중 지금 가능한 서버(온라인 · 로그인됨 · 대기 작업 적은 순)를 골라 배정하고, 지정한다면 이 목록 안이어야 하며, online:false 이거나 login_state 가 "out"(네이버 로그인 필요) · "blocked"(보안 확인·접속 제한 화면) 이면 409 로 거절됩니다. 자동 로그인은 없으므로 "out"·"blocked" 는 사람이 수집 PC 의 Chrome 에서 처리할 때까지 그대로입니다.

{ "success":true, "data":{ "channels":["naver_shopping_category_search"], "servers":[
    { "server":"win-shop-01", "online":true, "status":"active", "login_state":"in", "version":"shopping-win-1.0.0" } ] } }

GET/trends-servers

구글 트렌드(윈도우 수집기) 채널(google_trends_explore 탐색 · google_trends_trending 실시간 인기) 전용 — 트렌드 수집기 앱이 있는 수집 서버와 구글 접속 상태를 돌려줍니다. 요청의 server 는 선택입니다 — 비우면 허브가 이 목록 중 지금 가능한 서버(온라인 · 접속 막힘 아님 · 대기 작업 적은 순)를 골라 배정하고, 지정한다면 이 목록 안이어야 하며, online:false 이거나 login_state 가 "blocked" 이면 409 로 거절됩니다. 구글 트렌드는 로그인이 없어 login_state 는 접속 상태입니다 — "in" 정상 · "unknown" 아직 확인 전(요청은 받음) · "blocked" 막힘. 막힘이면 blocked_kind 가 이유입니다: captcha(보안 확인) · consent(쿠키 동의) — 둘 다 사람이 수집 PC 에서 처리할 때까지 그대로입니다. blocked_since 는 막힌 시각입니다. 구글이 요청을 잠시 거절(429)하는 것은 막힘이 아닙니다(수집 PC 가 쉬었다가 다시 하고, 안 되면 그 요청만 약 10분 뒤 자동 재시도). 두 채널 중 하나라도 허용된 키면 조회할 수 있습니다.

{ "success":true, "data":{ "channels":["google_trends_explore", "google_trends_trending"], "servers":[
    { "server":"win-trends-01", "online":true, "status":"active", "login_state":"blocked", "blocked_kind":"captcha", "blocked_since":"2026-10-14T13:20:05+09:00", "version":"trends-win-1.0.1" } ] } }

에러 코드

HTTP	code	의미
401	unauthorized	API 키 없음/유효하지 않음
403	forbidden_channel	허용되지 않은 채널
404	unknown_channel / not_found	없는 채널 / 없는 요청
422	invalid_params	필수 파라미터 누락/형식 오류
422	unknown_server / unknown_account / account_disabled / cafe_not_linked	고정 배정 채널(`naver_cafe_win`): 등록되지 않은 수집 서버·계정 / 비활성 계정 / 계정에 연결되지 않은 카페 — `GET /cafe-servers` 로 확인
409	no_flex_server	flex 채널에서 `server` 를 비웠는데 지금 가능한 flex 수집 서버가 없음(오프라인 · 로그인 필요 등, 메시지에 서버별 이유) — 서버를 켜거나 로그인 확인 후 다시 요청
422	not_flex_server	flex 채널(`flex_*`): 그 서버에 flex 수집기가 없음 — `GET /flex-servers` 로 확인
409	no_shopping_server	쇼핑 카테고리·필터 채널에서 `server` 를 비웠는데 지금 가능한 쇼핑 수집 서버가 없음(오프라인 · 네이버 로그인 필요 등, 메시지에 서버별 이유)
422	not_shopping_server	쇼핑 카테고리·필터 채널(`naver_shopping_category_search`): 그 서버에 쇼핑 수집기가 없음 — `GET /shopping-servers` 로 확인
409	no_trends_server	구글 트렌드 채널에서 `server` 를 비웠는데 지금 가능한 트렌드 수집 서버가 없음(오프라인 · 보안 확인 · 쿠키 동의 등, 메시지에 서버별 이유)
422	not_trends_server	구글 트렌드 채널(`google_trends_*`): 그 서버에 트렌드 수집기가 없음 — `GET /trends-servers` 로 확인
409	server_offline / server_paused / account_login_required / account_blocked	고정 배정 채널: 수집 서버 오프라인·일시정지 / 계정 로그인 필요 / 차단·보안 확인 화면에서 멈춤 — 서버가 올라온 뒤(또는 로그인·확인 후) 다시 요청. 구글 트렌드의 `account_blocked` 는 보안 확인(캡차)·쿠키 동의 화면(사람이 수집 PC 에서 풀 때까지 — 구글 요청 제한 429 는 막힘이 아님)
429	(throttle)	분당 요청 한도 초과