사기 방지 Data API

Data API는 Web SDK의 서버 측 대응물입니다. 판정을 가져오고, 통계를 집계하고, 보고 및 대조를 위해 데이터를 내보내는 데 사용하세요 — 당신의 시스템이 합의하는 수치를 끌어옵니다.

Base URL

https://apiv1.captcha.la

인증

모든 Data API 요청은 사기 방지 애플리케이션 자격 증명으로 인증되며, 헤더로 전송됩니다.

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret은 서버 측 전용입니다. 브라우저, 모바일 앱, 또는 공개 저장소에 절대 노출하지 마세요. 페이지 SDK는 항상 공개 appKey만 사용합니다.

엔드포인트

판정 가져오기

단일 방문에 대한 판정을 조회합니다(예: 특정 방문을 대조하기 위해).

GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

응답의 data는 BotVerdict 객체입니다.

{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}

집계 통계

시간 범위에 걸친 버킷 집계를 가져옵니다 — 총계, 봇 비율, 그리고 action/level별 분해 — 대시보드와 품질 보고서를 위해.

GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}

내보내기

오프라인 대조를 위해 시간 범위의 방문별 판정 행을 내보냅니다.

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

각 행은 방문의 식별자, 타임스탬프, 그리고 판정 필드(is_bot, score, level, action)를 담으므로, 자신의 로그와 다시 조인할 수 있습니다.

클릭별 대조

유료 트래픽 시나리오에서는 단일 방문을 특정 전달된 클릭으로 다시 묶어 두 당사자가 그에 대해 정산할 수 있습니다. 이는 클릭 토큰을 사용하며 광고 사기 가이드에서 다룹니다.

클릭 토큰 레퍼런스 (트래픽 공급자용)

트래픽 공급자는 자체 서버에서 click token에 서명한 뒤 이를 목적지 URL에 추가합니다. 그러면 해당 방문에 대한 판정이 다시 공급자에게 귀속됩니다. 서명은 오프라인으로 이루어지며 API 호출이 필요하지 않습니다.

서명 자격 증명 발급받기

대시보드에서 앱 → Fraud Prevention → 서명 키 발급으로 이동합니다. 다음을 받게 됩니다.

• bot_kid — 공개 키 ID (토큰의 pkid로 들어갑니다).
• bot_hmac_secret — 서명 시크릿으로, 한 번만 표시됩니다. 서버 측에 보관하세요.

토큰 형식

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body는 JSON 페이로드의 base64url이며, 서명은 그 body 문자열에 대해 계산됩니다.

페이로드 필드

필드	필수	설명
pkid	예	사용자의 bot_kid. 백엔드는 이를 사용해 시크릿을 조회하고 서명을 검증합니다
cid	예	이 클릭의 고유 ID이며 정산 키입니다. 클릭마다 새로운 고유 값을 생성하세요
aud	아니오	대상 광고주의 app_key. 설정되면 해당 광고주 페이지에서만 토큰이 인정됩니다. 생략하면 모든 광고주 페이지에서 수락됩니다
click_ts	아니오	클릭이 발생한 시각 (unix 초)
exp	아니오	만료 시각 (unix 초). 만료된 토큰은 거부됩니다

링크에 추가하기

광고주의 목적지 URL에 토큰을 _ctk 쿼리 파라미터로 추가합니다.

https://advertiser.example/lp?_ctk=ct.<...>.<...>

광고주의 SDK는 _ctk를 자동으로 읽습니다(tokenParam으로 설정 가능). 하나의 cid는 한 번만 사용할 수 있습니다(재전송 방지). 보안 모델을 참고하세요.

예시 (의사 코드)

const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`

다음 단계

• Verdict Reference — 이 엔드포인트들이 반환하는 필드
• Web SDK — 페이지에서 판정 수집하기