비동기 & 콜백

수집은 시간이 걸립니다. 요청은 즉시 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로 바뀝니다. running 중에는 progress로 진행 상황을 볼 수 있습니다.

# 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"} }
# done    → { "status":"done", "result_count":30, "items":[ ... ] }

콜백(웹훅)

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). 그래도 실패하면 중단되며, 결과는 폴링으로 받을 수 있습니다.

API 콘솔에서 콜백 URL을 넣고 직접 시험해 보세요.