APIリファレンス

不正防止API

識別のためのブラウザSDK、リアルタイムイベントのための署名付きWebhook、そして履歴のための読み取り専用Server API。デバイスレベルで不正を止めるために必要なすべてがそろっています。

エンドポイント

SDK@tracio/sdk

クライアントSDKでブラウザ内の訪問者を識別します。サーバーへのラウンドトリップなしで、安定した訪問者IDとボット判定を返します。公開鍵はクライアントサイドコードに安全に組み込めます。

リクエスト

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

レスポンス

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

POST/webhook/tracio

TRACIOは識別のたびに、署名付きイベントをお客様のエンドポイントに配信します。X-Tracio-Signatureヘッダーを検証したうえで、フラットなJSONペイロードに基づいて処理してください。これはプッシュ型の面であり、ポーリングする必要はありません。事後に訪問を読み出す必要がある場合は、Server APIがrequestIdで応答します。

リクエスト

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

レスポンス

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

Webhook配信の検証に使うプラットフォームのEd25519公開鍵を取得します。このルートは認証不要で、5分間キャッシュされます。署名ヘッダー内のkidが、どの鍵を使うかを示します。

リクエスト

curl https://api.tracio.ai/.well-known/webhook-keys

レスポンス

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

シークレットキーを使って、Server APIから訪問者の履歴を読み出します。Proプランから利用できます。期間はプランに応じて制限され、実際に得られた期間はmetaで返されます。GDPRのアクセス権リクエストを支えます。

リクエスト

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

レスポンス

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

認証

TRACIOは面ごとに1つ、計3つの認証情報を使用します。ブラウザSDK用の公開鍵、Server API用にAuthorization: Bearerで送るシークレットキー（tracio_sk_…）、そしてWebhook配信を検証するためのHMAC署名シークレットです。シークレットキーはダッシュボードで作成され、表示は一度きりで、ブラウザに渡してはいけません。Server APIは意図的にCORSヘッダーを返しません。

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

レート制限

制限はワークスペース単位です。Server APIの呼び出しは識別回数とは別に集計されるため、自分の履歴を読み出しても課金対象のクォータを消費しません。すべてのレスポンスにX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれ、429のときはRetry-Afterも付きます。Server APIはFreeプランには含まれません。

プラン	Server APIのレート	Server API（1日あたり）	Webhookエンドポイント	クエリ期間
Free	対象外	対象外	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	無制限	100	365 days

エラーコード

すべてのエラーは同じエンベロープを返します。文字列のcode、人が読めるmessage、そして失敗した呼び出しのrequestIdを持つerrorオブジェクトです。

400Bad Requestクエリパラメータの形式不正、サポートされていない期間、または有効な訪問者IDではない識別子です。

401Unauthorized認証情報の欠落または無効です — 公開鍵（SDK）、シークレットキー（Server API）、またはWebhook署名。

402Upgrade Requiredお客様のプランにはServer APIへのアクセスが含まれていません。Proプランから利用できます。

404Not Foundその識別子に該当する訪問者またはセッションが、お客様のプランのクエリ期間内に見つかりません。

405Method Not AllowedServer APIは読み取り専用です。すべてのルートはGETのみに応答します。

429Rate Limited秒あたりのリクエストが多すぎるか、1日のクォータを使い切っています。Retry-Afterヘッダーとプランの制限を確認してください。

500Internal Errorサーバーエラーです。指数バックオフでリトライしてください。継続する場合は、requestIdを添えてサポートにお問い合わせください。

503Service UnavailableAPIが一時的に応答できません。指数バックオフでリトライしてください。

エラーレスポンスの形式

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

開発を始める

APIキーを取得し、5分以内に最初の識別リクエストを送信しましょう。

APIキーを取得 APIドキュメント全文