コンテンツへスキップ

APIリファレンス

不正防止API

識別のためのブラウザSDK、リアルタイムイベントのための署名付きWebhook、そしてワークスペース管理API。デバイスレベルで不正を止めるために必要なすべてがそろっています。

APIキーを取得API Playground

エンドポイント

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ヘッダーを検証したうえで、フラットな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を通じてWebhookエンドポイントを登録します。ダッシュボードセッション（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のアクセス権リクエストを支えます。

リクエスト

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は面ごとに1つ、計3つの認証情報を使用します。ブラウザSDK用の公開鍵、ワークスペース管理API用のダッシュボードセッション（Clerk）のJWT、そしてWebhook配信を検証するための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の各ヘッダーが含まれます。

プラン識別回数Webhookイベント管理API訪問者照会
Free100/day100/day50/day100/day
Pro1,000/min1,000/min500/min1,000/min
Enterprise10,000/min10,000/min5,000/min10,000/min

エラーコード

すべてのエラーは、code、message、detailsフィールドを持つJSONボディを返します。

400Bad Requestリクエストボディの形式不正、または必須フィールドの欠落です。
401Unauthorized認証情報の欠落または無効です — 公開鍵（SDK）、Clerk JWT（管理API）、またはWebhook署名。
403Forbiddenお客様のワークスペースのロール（RBAC）に、この操作の権限がありません。
404Not Found訪問者IDまたはWebhookが、お客様のワークスペースに見つかりません。
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ドキュメント全文