API 레퍼런스

안티프라우드 API

식별을 위한 브라우저 SDK, 실시간 이벤트를 위한 서명된 웹훅, 그리고 워크스페이스 관리 API. 디바이스 수준에서 사기를 막는 데 필요한 모든 것.

엔드포인트

SDK@tracio/sdk

클라이언트 SDK로 브라우저에서 방문자를 식별합니다. 서버 왕복 없이 안정적인 방문자 ID와 봇 판정을 반환합니다. 공개 키는 클라이언트 측 코드에 포함해도 안전합니다.

요청

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

응답

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

TRACIO는 매 식별마다 서명된 이벤트를 여러분의 엔드포인트로 전달합니다. X-Tracio-Signature 헤더를 검증한 다음 평면(flat) JSON 페이로드에 따라 대응하세요. 이것은 서버 측에서 이벤트를 받는 채널입니다 — requestId로 폴링하는 REST 읽기는 없습니다.

요청

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

응답

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}

POST/api/v1/workspaces/{workspaceId}/webhooks

워크스페이스 관리 API를 통해 웹훅 엔드포인트를 등록합니다. 대시보드 세션(Clerk) JWT로 인증하며 워크스페이스 역할에 따라 검사됩니다. 서명 시크릿은 생성 시 한 번만 반환됩니다.

요청

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

응답

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}

GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

워크스페이스 관리 API를 통해 방문자의 저장된 이력을 조회합니다. 대시보드 세션(Clerk) JWT로 인증합니다. GDPR 열람권(right-of-access) 요청을 지원합니다.

요청

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

응답

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

인증

TRACIO는 연동 지점마다 하나씩, 세 가지 자격 증명을 사용합니다: 브라우저 SDK용 공개 키, 워크스페이스 관리 API용 대시보드 세션(Clerk) JWT, 그리고 웹훅 전달을 검증하기 위한 HMAC 서명 시크릿입니다. 별도의 API 시크릿은 없습니다.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

속도 제한

제한은 워크스페이스별로 적용됩니다. 관리 API 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After 헤더가 포함됩니다.

플랜	식별	웹훅 이벤트	관리 API	방문자 조회
무료	100/day	100/day	50/day	100/day
Pro	1,000/min	1,000/min	500/min	1,000/min
Enterprise	10,000/min	10,000/min	5,000/min	10,000/min

오류 코드

모든 오류는 code, message, details 필드가 포함된 JSON 본문을 반환합니다.

400Bad Request잘못된 형식의 요청 본문 또는 필수 필드 누락.

401Unauthorized자격 증명 누락 또는 유효하지 않음 — 공개 키(SDK), Clerk JWT(관리 API), 또는 웹훅 서명.

403Forbidden여러분의 워크스페이스 역할(RBAC)에 이 작업에 대한 권한이 없습니다.

404Not Found워크스페이스에서 방문자 ID 또는 웹훅을 찾을 수 없습니다.

429Rate Limited요청이 너무 많습니다. Retry-After 헤더와 플랜 제한을 확인하세요.

500Internal Error서버 오류. 지수 백오프로 재시도하세요. 계속되면 지원팀에 문의하세요.

오류 응답 형식

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

개발 시작하기

API 키를 발급받고 5분 이내에 첫 식별 요청을 실행하세요.

API 키 발급받기 전체 API 문서