---
title: 사기 방지 — Data API
---

# 사기 방지 Data API

Data API는 [Web SDK](./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`만 사용합니다.
:::

## 엔드포인트

### 판정 가져오기

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

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

응답의 `data`는 [`BotVerdict`](./verdict-reference) 객체입니다.

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

### 집계 통계

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

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

```json
{
  "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 }
  }
}
```

### 내보내기

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

```bash
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`)를 담으므로, 자신의 로그와 다시 조인할 수 있습니다.

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

## 다음 단계

- [Verdict Reference](./verdict-reference) — 이 엔드포인트들이 반환하는 필드
- [Web SDK](./web-sdk) — 페이지에서 판정 수집하기