Referensi API

API Anti-Penipuan

SDK browser untuk identifikasi, webhook bertanda tangan untuk peristiwa real-time, dan Server API read-only untuk riwayat. 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": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "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 push: Anda tidak perlu melakukan polling. Kalau Anda memang perlu membaca sebuah kunjungan setelahnya, Server API menjawab berdasarkan requestId.

Permintaan

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

Respons

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

Ambil kunci publik Ed25519 platform yang dipakai untuk memverifikasi pengiriman webhook. Rute ini tidak memerlukan autentikasi dan di-cache selama lima menit. Nilai kid pada header tanda tangan memberi tahu kunci mana yang harus dipakai.

Permintaan

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

Respons

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

GET/v1/visitors/{visitorId}

Baca riwayat pengunjung dari Server API dengan secret key Anda. Tersedia mulai paket Pro. Jendelanya dibatasi sesuai paket Anda dan jendela yang benar-benar Anda dapatkan dilaporkan kembali di meta. Mendukung permintaan hak akses GDPR.

Permintaan

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

Respons

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

Autentikasi

TRACIO menggunakan tiga kredensial, satu per permukaan: kunci publik untuk SDK browser, secret key (tracio_sk_…) yang dikirim sebagai Authorization: Bearer untuk Server API, dan rahasia penandatanganan HMAC untuk memverifikasi pengiriman webhook. Secret key dibuat di dasbor, ditampilkan sekali, dan tidak boleh sampai ke browser — Server API sengaja tidak mengembalikan header 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>

Batas Laju

Batas berlaku per workspace. Panggilan Server API dihitung terpisah dari identifikasi, jadi membaca riwayat Anda sendiri tidak pernah menghabiskan kuota yang Anda bayar. Setiap respons membawa X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset, plus Retry-After pada 429. Server API tidak termasuk dalam paket Free.

Paket	Laju Server API	Server API per hari	Endpoint webhook	Jendela kueri
Gratis	Tidak termasuk	Tidak termasuk	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	Tanpa batas	100	365 days

Kode Kesalahan

Setiap kesalahan mengembalikan amplop yang sama: objek error dengan code berupa string, message yang terbaca manusia, dan requestId dari panggilan yang gagal.

400Bad RequestParameter kueri salah format, jendela yang tidak didukung, atau pengenal yang bukan ID pengunjung yang valid.

401UnauthorizedKredensial hilang atau tidak valid — kunci publik (SDK), secret key (Server API), atau tanda tangan webhook.

402Upgrade RequiredPaket Anda tidak menyertakan akses Server API. Akses dimulai pada paket Pro.

404Not FoundTidak ada pengunjung atau sesi dengan pengenal itu di dalam jendela kueri paket Anda.

405Method Not AllowedServer API bersifat read-only. Setiap rute hanya menjawab GET dan tidak lebih.

429Rate LimitedTerlalu banyak permintaan per detik, atau kuota harian sudah habis. Periksa header Retry-After dan batas paket Anda.

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

503Service UnavailableAPI untuk sementara tidak dapat menjawab. Coba lagi dengan exponential backoff.

Format Respons Kesalahan

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

Mulai Membangun

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

Dapatkan Kunci API Dokumentasi API Lengkap