Konsep

Hal-hal yang akan menjelaskan perilaku yang mengejutkan sebelum Anda menemuinya.

Sandbox dan production

Dua project Firebase terpisah, bukan satu deployment dengan flag. Host berbeda, kunci penandatangan token berbeda, data berbeda, dan tidak ada kredensial yang berlaku di keduanya.

api-sandbox.tracive.id	API sandbox: token, pengecekan, profil.
sandbox.tracive.id	Origin authorize sandbox. Diklaim App Link oleh build sandbox aplikasi Tracive (com.pleistocent.tracive.sandbox).
api.tracive.id	API production.
tracive.id	Origin authorize production.

Jangan pernah menambahkan /v1 pada URL authorize. Versi itu milik API; authorize bukan endpoint API melainkan URL yang diserahkan sistem operasi ke aplikasi.

Siapa yang membayar

Di Tahap 1 hanya ada satu sumber biaya: creditSource: USER. Pengecekan dibebankan ke kredit langganan pengguna Tracive yang memberi izin, bukan ke saldo Anda.

· Kredit dari langganan bisa dipakai jalur partner.
· Kredit dari menonton iklan dan dari hadiah laporan tidak bisa. Keduanya didapat pengguna untuk dipakai sendiri.
· Kalau kreditnya habis, jawabannya 402 dengan insufficient_user_credits. Itu bukan error integrasi, dan aplikasi Anda sebaiknya menawarkan top-up alih-alih menampilkan kegagalan.

Charge-on-miss

Pengecekan yang tidak menemukan apa pun tetap ditagih satu kredit. Pencariannya tetap dilakukan; hasil kosong adalah jawaban, bukan kegagalan.

Konsekuensi praktisnya ada di grammar input: identifier yang dilipat berbeda dari yang dilipat pelapor menghasilkan miss berbayar, dan tidak ada apa pun di respons yang memberi tahu bahwa sebabnya bentuk masukan.

Cache dan cacheTtlSeconds

Setiap respons membawa cacheTtlSeconds. SDK menyimpan hasilnya terenkripsi dan menghormati angka itu, sehingga pengecekan berulang dalam jendela tersebut tidak menyentuh jaringan dan tidak menghabiskan kredit.

Ditemukan	30 hari. Verdict yang sudah ada cenderung stabil.
Tidak ditemukan	1 jam. Bisa basi begitu ada laporan baru masuk.

Nilai 0 berarti jangan simpan, dan menghapus entri yang sudah ada. Itu satu-satunya cara kami menarik kembali jawaban yang telanjur mendarat di perangkat, tanpa menunggu Anda merilis versi baru.

detail minimal dan full

minimal adalah bawaannya: tingkat risiko, jumlah laporan, tag, dan tanggal. full menambahkan kronologi dan komentar pelapor — tulisan orang tentang orang lain, jadi tampilkan dengan hati-hati.

Setiap partner boleh meminta full. Di Tahap 1 tarifnya sama, satu kredit, apa pun detailnya.

PPID: identitas pengguna

Anda tidak pernah menerima uid Tracive. Field sub berisi PPID, identitas semu yang diturunkan per client, sehingga pengguna yang sama tampil dengan nilai berbeda di client partner lain. Dua partner tidak bisa menggabungkan datanya untuk mengenali orang yang sama.

Yang Anda pegang untuk memetakan ke pelanggan Anda sendiri adalah partner_user_id, yang Anda tentukan sendiri. Lihat partner_user_id & penautan 1:1.

Katalog error

Endpoint data memakai amplop {"error":{"code","message","checkId"}}. Endpoint token dan revoke memakai bentuk datar RFC 6749 §5.2: {"error":"…","error_description":"…"}. Bentuknya berbeda karena spesifikasi yang mengaturnya berbeda, bukan karena kelalaian.

400 invalid_request	Bentuk permintaan salah.
400 unsupported_input_type	input.type di luar lima yang didukung.
400 unsupported_credit_source	creditSource PARTNER atau AUTO dikirim sebelum Tahap 2. Hapus field itu; kredit pengguna dipakai.
401 expired_token	Token kedaluwarsa. Refresh lalu ulangi.
401 invalid_token	Terminal. Buang grant dan minta otorisasi baru.
401 grant_revoked	Terminal. Pengguna mencabut akses, atau client dinonaktifkan.
402 insufficient_user_credits	Kredit pengguna habis.
403 missing_scope	Client tidak meminta scope yang dibutuhkan.
403 translation_not_permitted	Terjemahan diminta, tapi pengguna bukan premium. Ulangi tanpa locale untuk jawaban bahasa Inggris.
403 partner_suspended	Organisasi partner disuspensi atau tidak aktif. Bukan terminal: simpan refresh token dan ulangi setelah organisasi diaktifkan lagi.
409 idempotency_conflict	Idempotency-Key dipakai ulang dengan badan berbeda.
429 rate_limited	Saldo yang akan ditagih sedang ditulis check lain pada saat yang sama. Tidak ada yang ditagih: tunggu sesuai Retry-After, lalu ulangi.
429 daily_quota_exceeded	Hanya di sandbox: jatah 1.000 scammer check/hari per org habis. Retry-After menunjuk reset 00:00 UTC (07.00 WIB); jangan retry sebelum itu.

Hanya invalid_token dan grant_revoked yang terminal. Setiap 401 lain berarti “segarkan token lalu ulangi”. Kalau Anda memakai SDK, ini sudah ditangani.