데이터 수집 요청 V4

• Authorization: Header
  해시스크래퍼 API 키. Bearer <api_key> 형식으로 전달합니다.

  예시 Bearer YOUR_API_KEY
• schedule_id: String (path)
  수집을 요청할 크롤링 봇의 ID. URL 경로의 {schedule_id}로 전달합니다. 봇 ID는 봇 상세 페이지의 작업 → 봇 ID 복사하기에서 복사할 수 있습니다.

  예시 8f3a7c1e9b5d24f6
• params: optional Object
  수집 파라미터 그룹. 크롤링 봇이 사용하는 paramN 키들을 이 안에 담습니다.

  • param1 ~ param10: optional String
    params 그룹 안에 param1~param10 형식의 키로 전달합니다. 봇에 영문 별칭(alias)이 설정돼 있으면 paramN 대신 그 alias를 키로 쓸 수 있습니다. 라벨명(param_info의 name·name_en)은 표시용이라 키로 인식되지 않습니다. 크롤링 봇에서 사용으로 지정된 항목은 필수이며, 사용 안 함이면 보내도 무시됩니다. 빈 문자열("")은 의도적 빈 값으로 허용되어 워커에게 그대로 전달됩니다. 어느 항목이 사용 중인지는 GET /v4/api/schedules/{id}/param_info로 확인하세요.
  • <alias>: optional String
    paramN 대신 봇에 설정한 영문 별칭(alias)을 키로 보낼 수 있습니다. 예: param1 대신 keyword.
• settings: optional Object
  엔드포인트 옵션 그룹. 수집 동작과 관련된 메타 옵션을 이 안에 담습니다.

  • param_save: optional Boolean
    settings.param_save. true이면 보낸 파라미터를 크롤링 봇 자체에 저장하여 다음 실행의 기본값으로 사용합니다. false(기본값)이면 이번 호출에만 적용됩니다.

    허용값 true, false

• result: String
  요청 처리 결과.

  허용값 success, error
• version: String
  API 버전.

  예시 v4
• request_id: String
  요청 추적용 ID. 클라이언트가 X-Request-ID 헤더에 req_ 접두사 ID를 보내면 그대로 echo, 그 외에는 서버가 생성(req_<uuid>)합니다.

  예시 req_5a8c1f1c-...
• elapsed_sec: Float
  응답 생성에 걸린 시간(초 단위 Float).

  예시 0.0123
• data: Object
  수집 요청 결과 정보.

  • schedule_id: String
    요청한 크롤링 봇의 ID(echo).
  • name: String
    크롤링 봇의 이름.
  • schedule_result_id: Integer
    이번 수집으로 생성된 데이터셋 ID(정수). 이후 상태·결과 조회의 입력값으로 사용합니다.
  • param_save: Boolean
    요청 시 전달한 settings.param_save 값(echo).
  • param_info: Object
    이번 수집에 사용된 파라미터. 키는 param1~paramN으로 안정적이며, 각 항목은 name(라벨)과 value를 포함합니다. options(허용값 목록)는 포함되지 않습니다. 옵션 목록은 GET /v4/api/schedules/{id}/param_info에서 확인합니다.

에러 응답

• MISSING_API_KEY
  Authorization 헤더가 없거나 형식이 올바르지 않습니다. Authorization: Bearer <api_key> 형태로 전달하세요. (HTTP 401)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "MISSING_API_KEY",
    "message": "API key is missing.",
    "elapsed_sec": 0.0008,
    "details": { "hint": "Send `Authorization: Bearer <api_key>` header." }
  }

• INVALID_API_KEY
  전달된 API 키와 일치하는 사용자가 없습니다. (HTTP 401)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "INVALID_API_KEY",
    "message": "API key is invalid.",
    "elapsed_sec": 0.0011
  }

• MISSING_PARAM
  크롤링 봇에서 사용으로 지정된 파라미터 중 키 자체가 누락된 항목이 있습니다. details.param_name으로 어느 파라미터인지 확인할 수 있습니다. (HTTP 400)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "MISSING_PARAM",
    "message": "Required parameter is missing.",
    "elapsed_sec": 0.0014,
    "details": { "param_name": "param2" }
  }

• VALIDATION_FAILED
  여러 파라미터가 동시에 누락된 경우 details.errors[]에 항목별 오류가 함께 반환됩니다. (HTTP 400)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "VALIDATION_FAILED",
    "message": "Validation failed.",
    "elapsed_sec": 0.0017,
    "details": {
      "errors": [
        { "code": "MISSING_PARAM", "param_name": "param1" },
        { "code": "MISSING_PARAM", "param_name": "param2" }
      ]
    }
  }

• SCHEDULE_NOT_FOUND
  전달된 ID로 크롤링 봇을 찾을 수 없거나 접근 권한이 없습니다. (HTTP 404)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "SCHEDULE_NOT_FOUND",
    "message": "Schedule not found.",
    "elapsed_sec": 0.0021,
    "details": { "resource": "schedule", "id": "8f3a7c1e9b5d24f6" }
  }

• TICKET_EXPIRED
  이용권 기간이 만료되었거나 등록된 이용권이 없습니다. (HTTP 402)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "TICKET_EXPIRED",
    "message": "Service ticket expired",
    "elapsed_sec": 0.0033,
    "details": { "reason": "ticket_expired" }
  }

• CREDIT_EXHAUSTED
  보유 크레딧을 모두 소진하여 수집을 시작할 수 없습니다. (HTTP 402)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "CREDIT_EXHAUSTED",
    "message": "Credit exhausted",
    "elapsed_sec": 0.0033,
    "details": { "reason": "credit_exhausted" }
  }

관련 가이드

• 수집 V2
• 수집 상태 V2