TEMU Documentation & API Specs - Telegram Lost & Found Reward Bot

🤖 Bot 1: TEMU USER BOT

Digunakan oleh Poster (pemilik kehilangan) dan Finder (penemu barang).

Fitur Utama: Buat laporan kehilangan, upload foto & lokasi, ciri rahasia terlindungi, Dynamic QRIS otomatis, radius matching 2 km, klaim penemuan, verifikasi pemilik, COD aman, dan pemilihan e-wallet.

🛡️ Bot 2: TEMU ADMIN BOT

Digunakan oleh Admin & Operator untuk monitoring dan tata kelola.

Handle: @temuadmin_akasia_bot

Fitur Utama: Manajemen kasus (Cases), persetujuan klaim (Claims), resolusi sengketa (Disputes), pencairan manual reward (Payouts), kontrol pengguna (Users), dan ringkasan finansial (Summary).

🔄 Case State Machine (Section 43)

Setiap laporan kehilangan mengikuti siklus hidup terpadu yang menjamin keamanan dana dan barang:

DRAFT → PAYMENT_PENDING → SEARCHING → CLAIMED → VERIFICATION → VERIFIED → COD_SCHEDULED → COD_READY → RETURNED → RELEASE_READY → PAID

Aturan Penguncian Dana: Status reward adalah LOCKED saat pembayaran berhasil, berubah menjadi RELEASE_READY hanya setelah Owner mengonfirmasi barang diterima (RETURNED), lalu menjadi PAID saat Admin transfer ke e-wallet Finder.

⚡ Interactive QRIS Payment Simulator

Simulasi Webhook Pembayaran QRIS

Gunakan form ini untuk menguji webhook payment secara instan tanpa perlu transfer nyata. Masukkan Merchant Order ID (misal: ORD-TEMU-123456).

Merchant Order ID:

Aturan Bisnis & Pembayaran (Section 9 & 50)

Komponen	Perhitungan	Contoh
Reward Finder	Nominal yang dipilih Poster	Rp 1.000.000
Fee TEMU	15% dari Reward Finder	Rp 150.000
Total Bayar	Reward + Fee TEMU	Rp 1.150.000

* Fee TEMU dikunci permanen saat transaksi dibuat sehingga perubahan tarif fee di masa depan tidak mempengaruhi laporan lama.

📍 Matching Engine (Section 12, 13, 14, 44)

Prinsip Geografis 2 KM

Sistem menggunakan formula Haversine untuk menghitung jarak presisi antara koordinat barang hilang dan lokasi terakhir Finder.

Radius Maksimal: 2.0 Kilometer (MATCH_RADIUS = 2 KM)
Masa Berlaku Lokasi: 2 Jam (LOCATION_VALIDITY = 2 HOURS)
Perlindungan Privasi: Finder hanya menerima nama area umum, koordinat latitude/longitude asli tidak pernah ditampilkan.

Penggabungan Notifikasi (Batching)

Jika terdapat lebih dari 1 kasus dalam radius Finder, sistem menggabungkannya ke dalam 1 notifikasi tunggal (contoh: "3 BARANG HILANG DI SEKITAR ANDA"), bukan pesan terpisah.

Mencegah spam: Aturan 1 Finder × 1 Case = 1 initial notification dicatat di tabel case_notifications.

🔌 REST API Endpoints

POST /api/payment/webhook

Idempotent

Endpoint callback dari Payment Provider / Payment Gateway QRIS.

POST /api/payment/webhook
Headers:
  Content-Type: application/json
  x-temu-signature: <optional-secret-signature>

Body:
{
  "merchant_order_id": "ORD-TEMU-123456",
  "provider_transaction_id": "QRIS-TX-998822",
  "amount": 1150000,
  "status": "PAID"
}

Response (200 OK):
{
  "ok": true,
  "message": "Payment verified and case activated to SEARCHING",
  "case_number": "TEMU-123456",
  "status": "SEARCHING"
}

GET /api/stats

Mengembalikan metrik operasional dan keuangan sistem TEMU secara real-time.

GET /api/stats

Response (200 OK):
{
  "ok": true,
  "data": {
    "lostCases": 12,
    "claims": 8,
    "verified": 6,
    "returned": 5,
    "totalPayment": 7475000,
    "rewardFinder": 6500000,
    "temuFee": 975000,
    "rewardsPaid": 5000000
  }
}

GET /health

Memeriksa kesiapan service, status database pool, dan bot Telegram.

GET /health

Response (200 OK):
{
  "status": "UP",
  "database": "CONNECTED",
  "bots": {
    "userBot": "RUNNING",
    "adminBot": "RUNNING"
  },
  "timestamp": "2026-09-12T01:30:00.000Z"
}

🗄️ PostgreSQL Database Schema (Section 42)

Nama Tabel	Kolom Kunci	Keterangan
`users`	id, telegram_id, username, trust_score, status	Identitas Telegram user, skor reputasi, status akun (ACTIVE, RESTRICTED, BANNED).
`lost_items`	case_number, owner_id, secret_1, secret_2, lat, lon, reward, fee	Laporan barang hilang, ciri rahasia pemilik, status state machine.
`finder_locations`	finder_id, latitude, longitude, area, expires_at	Titik koordinat terakhir Finder dengan masa aktif 2 jam.
`payments`	merchant_order_id, amount, qr_data, status, paid_at	Catatan transaksi Dynamic QRIS dan verifikasi webhook.
`claims`	lost_item_id, finder_id, find_code, evidence_file_id	Klaim penemuan dengan Find Code unik 6-digit dan foto bukti.
`returns`	claim_id, handover_code, owner_confirmed, status	Data COD, kode serah terima, dan konfirmasi pemilik.
`payouts`	finder_id, amount, ewallet_type, ewallet_number, status	Pencairan reward Finder ke OVO / GoPay / ShopeePay / DANA.
`disputes`	lost_item_id, claim_id, opened_by, reason, resolution	Kasus sengketa COD untuk mediasi Admin.
`audit_logs`	case_id, actor_id, action, old_status, new_status, metadata	Audit trail lengkap untuk setiap aksi dan perubahan state.
`case_notifications`	finder_id, case_id, notified_at	Pencegahan duplikasi notifikasi (1 Finder × 1 Case).