Referensi API

API Anti-Penipuan

SDK browser untuk identifikasi, webhook bertanda tangan untuk peristiwa real-time, dan API manajemen workspace. Semua yang Anda butuhkan untuk menghentikan penipuan di tingkat perangkat.

Dapatkan Kunci API API Playground

Endpoint

SDK@tracio/sdk

Identifikasi pengunjung di browser dengan SDK klien. Mengembalikan ID pengunjung yang stabil dan verdict bot tanpa perjalanan bolak-balik ke server. Kunci publik aman untuk disertakan dalam kode sisi klien.

Permintaan

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

Respons

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

POST/webhook/tracio

TRACIO mengirimkan peristiwa bertanda tangan ke endpoint Anda pada setiap identifikasi. Verifikasi header X-Tracio-Signature, lalu ambil tindakan berdasarkan payload JSON datar. Ini adalah permukaan peristiwa sisi server — tidak ada pembacaan REST poll-by-requestId.

Permintaan

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

Respons

{
  "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

Daftarkan endpoint webhook melalui API manajemen workspace. Diautentikasi dengan JWT sesi dasbor (Clerk) Anda dan diperiksa terhadap peran workspace Anda. Rahasia penandatanganan dikembalikan sekali saat pembuatan.

Permintaan

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": [] }'

Respons

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

Cari riwayat tersimpan pengunjung melalui API manajemen workspace, diautentikasi dengan JWT sesi dasbor (Clerk) Anda. Mendukung permintaan hak akses GDPR.

Permintaan

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

Respons

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

Autentikasi

TRACIO menggunakan tiga kredensial, satu per permukaan: kunci publik untuk SDK browser, JWT sesi dasbor (Clerk) Anda untuk API manajemen workspace, dan rahasia penandatanganan HMAC untuk memverifikasi pengiriman webhook. Tidak ada rahasia API mandiri.

# 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>

Batas Laju

Batas berlaku per workspace. Respons API Manajemen menyertakan header X-RateLimit-Limit, X-RateLimit-Remaining, dan Retry-After.

Paket	Identifikasi	Peristiwa webhook	API Manajemen	Pencarian pengunjung
Gratis	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

Kode Kesalahan

Semua kesalahan mengembalikan body JSON dengan field code, message, dan details.

400Bad RequestBody permintaan salah format atau field wajib hilang.

401UnauthorizedKredensial hilang atau tidak valid — kunci publik (SDK), Clerk JWT (API manajemen), atau tanda tangan webhook.

403ForbiddenPeran workspace Anda (RBAC) tidak memiliki izin untuk operasi ini.

404Not FoundID pengunjung atau webhook tidak ditemukan di workspace Anda.

429Rate LimitedTerlalu banyak permintaan. Periksa header Retry-After dan batas paket Anda.

500Internal ErrorKesalahan server. Coba lagi dengan exponential backoff. Jika terus berlanjut, hubungi dukungan.

Format Respons Kesalahan

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

Mulai Membangun

Dapatkan kunci API Anda dan buat permintaan identifikasi pertama Anda dalam waktu kurang dari 5 menit.

Dapatkan Kunci API Dokumentasi API Lengkap