[S] HashScraper API 가이드

엔드포인트

GET /v5/api/bots/{bot_id}/settings 입력 값·입력 방식·엑셀 파일·유니온 조회
PATCH /v5/api/bots/{bot_id}/settings 보낸 키만 바꾸기(inputs·input_mode·union)
PUT /v5/api/bots/{bot_id}/settings/excel 엑셀 파일 올리기(멀티파트)

설정 조회

칸	설명
`inputs`	`{ param1: { name, value } }` — 봇이 쓰는 칸의 지금 값.
`input_mode`	`direct`(직접 입력) 또는 `excel`(엑셀 파일).
`excel_file`	지금 쓰는 엑셀 파일 `{ name, uploaded_at }`, 없으면 `null`.
`union`	`{ enabled, target_dataset_id }` — 결과를 이어 쌓는지, 이어 쌓을 데이터셋(`null`이면 가장 나중 데이터셋을 자동으로).

curl 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    },
    "input_mode": "direct",
    "excel_file": null,
    "union": {
      "enabled": false,
      "target_dataset_id": null
    }
  }
}

설정 변경

본문에 보낸 키만 바뀝니다. 키가 하나라도 거절되면 아무것도 저장되지 않습니다. 모르는 최상위 키는 INVALID_PARAM(details.allowed에 허용 키), 아무것도 안 보내면 MISSING_PARAM입니다.

inputs — { "param1": "값" }. 값을 null로 보내면 그 칸을 비웁니다.
input_mode — direct 또는 excel. excel은 엑셀을 쓸 수 있는 봇이고 올려 둔 파일이 있어야 하며, 파일이 없으면 422 EXCEL_FILE_REQUIRED입니다.
union — { "enabled": true, "target_dataset_id": 239758028 }. target_dataset_id는 이 봇의 데이터셋이어야 하고(아니면 404 DATASET_NOT_FOUND), null이면 가장 나중 데이터셋을 자동으로 잇습니다.

curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "param1": "running shoes"
  }
}'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "running shoes"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    },
    "input_mode": "direct",
    "excel_file": null,
    "union": {
      "enabled": false,
      "target_dataset_id": null
    },
    "plans_out_of_sync": [
      {
        "plan_id": "513",
        "name": "주기 3",
        "label": "매일 18:00 (KST)",
        "changes": [
          {
            "key": "param1",
            "name": "Keyword",
            "plan_value": "boots",
            "bot_value": "running shoes"
          }
        ]
      }
    ]
  }
}

curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "union": {
    "enabled": true,
    "target_dataset_id": 239758028
  }
}'

curl -X PATCH 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "direct"
}'

주기에 미치는 영향

봇 설정을 따라가는 주기(주기 1)는 바뀐 값으로 돕니다. 주기 2부터와 조건을 따로 정한 주기는 영향받지 않습니다.

어긋난 주기가 생기면 응답의 plans_out_of_sync가 알려 줍니다 — 바뀐 조건이 그 주기의 값과 달라진 주기와 칸(plan_value·bot_value)입니다. 여러 주기 기능이 닫힌 계정에는 이 칸이 없습니다. 주기 쪽 값을 맞추려면 주기 불러오기(copy_settings)를 쓰세요.

엑셀로 수집하는 기능은 v5 에 아직 없습니다. input_mode가 excel인 봇의 수집 요청은 422 EXCEL_NOT_SUPPORTED_YET입니다. 직접 입력(direct)으로 바꾼 뒤 수집하세요.

엑셀 올리기

멀티파트 폼의 file 한 칸으로 올립니다. .xlsx·.xls·.csv, 최대 20MB. 확장자와 파일 내용이 모두 맞아야 하며(INVALID_PARAM), 스프레드시트로 읽히지 않거나 비어 있으면 422 EXCEL_FILE_UNREADABLE입니다.

올리면 이전 파일은 꺼지고 새 파일이 지금 쓰는 파일이 됩니다. 응답은 읽은 결과 — rows(행 수)·columns(열 수)·first_row(첫 행이 입력 칸에 들어가는 모양)입니다. 올린다고 입력 방식이 바뀌지는 않으므로, 쓰려면 input_mode를 excel로 바꿉니다.

curl -X PUT 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/settings/excel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'file=@products.xlsx'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "detected_type": "xlsx",
    "file": {
      "name": "products.xlsx",
      "uploaded_at": "2026-10-04T09:12:00+09:00"
    },
    "rows": 120,
    "columns": 2,
    "first_row": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      },
      "param2": {
        "name": "Sort",
        "value": "popular"
      }
    }
  }
}

설정 V5 (beta)