Sistem Manajemen Leads dengan Hierarki Wilayah & Progress Tracking Otomatis
API ini dirancang untuk mendukung alur pemilihan wilayah secara bertahap (Drill-down) dengan informasi progress pengerjaan di setiap levelnya.
Logika Progress: Sebuah lead dianggap "Selesai" jika statusnya telah diubah dari nilai default 'Belum Dikunjungi'.
API ini menerapkan 2 lapis keamanan. Lapisan pertama adalah Fixed Token, dan lapisan kedua adalah JWT (Auth Token) untuk mengetahui session user yang login.
Header Name: x-api-key
Header Value: marketing-secret-key-123
Header Name: Authorization
Header Value: Bearer <jwt_token>Tersedia helper class JavaScript untuk memudahkan integrasi di frontend. Kamu bisa menyertakan file /api-service.js di project kamu.
// Contoh penggunaan di browser
const service = new MarketingService('http://localhost:3000');
// 1. Ambil Kategori (dengan progress)
const categories = await service.getCategories();
console.log(categories[0]); // { id: 1, name: 'Mebel', total_leads: 150, finished_leads: 45 }
const selectedCat = categories[0].id;
// 2. Ambil data kota berdasarkan kategori
const cities = await service.getCities(selectedCat);
console.log(cities); // [{ id: 1, name: 'Malang', total_leads: 5, finished_leads: 1 }]Login untuk mendapatkan JWT Token dan detail user. Akun harus sudah di-acc (is_approved=true).
// Request Body
{ "username": "...", "password": "..." }
// Response
{ "token": "jwt_token...", "user": { "id": 1, "username": "...", "role": "marketing" } }Mendaftar akun baru. Akun baru tidak bisa langsung digunakan hingga disetujui oleh super admin.
// Request Body
{ "username": "...", "password": "...", "role": "marketing|admin" }Mengambil daftar pengguna untuk halaman admin panel.
Menyetujui pendaftaran user agar bisa login.
Mengambil daftar semua kategori yang tersedia beserta total progress leads di setiap kategori.
// Response Preview
[
{
"id": 1,
"name": "Mebel",
"total_leads": 150,
"finished_leads": 45
},
{
"id": 2,
"name": "Sekolah",
"total_leads": 80,
"finished_leads": 10
}
]Mengambil daftar semua kota beserta jumlah total leads dan leads yang sudah selesai di kota tersebut, **difilter berdasarkan kategori**.
| Param | Required | Description |
|---|---|---|
category_id | ✅ Yes | ID dari kategori yang dipilih. |
// Response Preview
[
{
"id": 1,
"name": "Kota Malang",
"total_leads": 50,
"finished_leads": 12
}
]Mengambil daftar kecamatan untuk kota tertentu dan kategori tertentu.
| Param | Required | Description |
|---|---|---|
city_id | ✅ Yes | ID dari kota yang dipilih. |
category_id | ✅ Yes | ID dari kategori yang dipilih. |
Mengambil daftar kelurahan/desa untuk kecamatan tertentu dan kategori tertentu.
| Param | Required | Description |
|---|---|---|
district_id | ✅ Yes | ID dari kecamatan yang dipilih. |
category_id | ✅ Yes | ID dari kategori yang dipilih. |
Mengambil daftar leads. Bisa difilter berdasarkan village_id dan category_id untuk alur drill-down.
| Param | Type | Description |
|---|---|---|
category_id | number | Filter berdasarkan kategori (Mebel, dll). |
village_id | number | Filter leads di desa tertentu. |
search | string | Cari nama/alamat. |
page | number | Pagination (Default: 1). |
// Response Preview
{
"data": [...],
"summary": {
"total": 15,
"finished": 1
},
"pagination": {...}
}Mengupdate status pengerjaan dan kendala lapangan. Sistem otomatis akan mencatat *history* update ini berdasarkan Token JWT yang dikirimkan.
// Request Body (JSON)
{
"status": "Sudah Dikunjungi",
"keterangan": "Kendala: Pemilik toko sedang tidak ada di tempat."
}Mengambil detail lead beserta array history dari seluruh pembaruan status dan keterangan.