비동기 & 콜백

수집은 시간이 걸립니다. 요청은 즉시 request_id를 돌려주고, 결과는 폴링하거나 콜백(웹훅)으로 받습니다.

흐름

1. 요청 — POST /collect → { request_id, status: "pending" }
2-A. 폴링 — GET /requests/{id}를 주기적으로 호출 → status: "done"이면 items
2-B. 콜백 — 요청 시 callback_url을 주면 완료 시 그 주소로 알림 POST

짧은 수집은 폴링(2~5초 간격), 다량/장시간은 콜백을 권장합니다. 콜백을 받더라도 전체 결과는 GET /requests/{id}로 가져옵니다(콜백 본문엔 요약만).

폴링

상태가 pending → running → done | failed | cancelled로 바뀝니다. running 중에는 progress와 elapsed_ms(경과)로 진행 상황을 볼 수 있습니다.

# done 까지 반복 조회
curl https://scraper.conbus.co.kr/api/v1/requests/42 -H "Authorization: Bearer YOUR_API_KEY"

# running → { "status":"running", "progress":{"count":12,"phase":"list"}, "elapsed_ms":8200 }
# done    → { "status":"done", "result_count":30, "duration_ms":42100, "duration_sec":42.1, "items":[ ... ] }

수집 소요 시간

완료(또는 실패/취소)된 요청은 허브가 측정한 수집 소요 시간을 함께 돌려줍니다 — 워커가 작업을 가져간(started_at) 시점부터 결과 제출(finished_at)까지입니다.

started_at / finished_at — 수집 시작·종료 시각(ISO8601, KST). 진행 중이면 finished_at은 null.
duration_ms / duration_sec — 소요 시간(밀리초 / 초). 진행 중이면 null, 대신 elapsed_ms로 현재까지 경과를 제공.

소요 시간은 큐 대기 시간을 제외한 순수 수집 시간입니다(요청 생성 created_at → 수집 시작 started_at 사이가 대기 시간). 재시도가 있었다면 마지막 시도 기준입니다.

요청 취소 (force-cancel)

실수로 시작한 수집을 강제로 중단합니다. 같은 API 키로 발급한 요청만 취소할 수 있습니다.

POST /api/v1/requests/{id}/cancel

curl -X POST https://scraper.conbus.co.kr/api/v1/requests/42/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 (200)

{ "success":true, "data":{ "request_id":42, "channel":"dcinside",
    "status":"cancelled", "cancelled_at":"2026-06-16T09:01:30+09:00" } }

동작 / 규칙

pending(아직 시작 안 함) → 즉시 취소되어 워커가 가져가지 않습니다.
running(수집 중) → 수집 서버가 다음 하트비트(최대 ~60초) 내에 감지해 진행 중인 수집을 중단합니다. 그 사이 수집이 먼저 끝나면 정상 done으로 남을 수 있습니다(취소가 근소하게 늦은 경우).
이미 cancelled → 200(멱등, 그대로 취소 상태).
이미 done/failed → 409 already_finished(완료된 건 취소 불가).
다른 키의 요청이거나 없는 id → 404 not_found.
취소된 요청을 GET /requests/{id}로 조회하면 status:"cancelled" + error에 취소 사유가 옵니다.

콜백(웹훅)

callback_url 지정 시 완료/실패에 아래 요약 알림이 POST됩니다.

POST {your callback_url}
Content-Type: application/json

{ "event":"request.completed"|"request.failed", "request_id":42,
  "channel":"dcinside", "status":"done", "result_count":30,
  "external_ref":"my-001", "result_url":"https://scraper.conbus.co.kr/api/v1/requests/42" }

결과 확인 (인증은 여기서)

콜백 자체엔 서명이 없습니다 — 트리거(알림)로만 쓰고, 실제 데이터는 콜백 안의 result_url(= GET /requests/{id})을 본인 API 키로 호출해 받으세요. 인증·검증은 그 호출에서 이뤄집니다(키가 맞아야 200, 본인 요청만 조회 가능).

# 콜백 받으면 result_url 을 키로 조회
curl https://scraper.conbus.co.kr/api/v1/requests/42 -H "Authorization: Bearer YOUR_API_KEY"

재시도

콜백이 2xx를 반환하지 않으면 자동 재시도합니다 — 최대 5회, 점증 백오프(60s → 5m → 15m → 1h). 그래도 실패하면 중단되며, 결과는 폴링으로 받을 수 있습니다.

플레이그라운드에서 직접 시험해 보세요.