Marketing Leads API | Documentation

🗺️ Alur Hierarki & Progress

API ini dirancang untuk mendukung alur pemilihan wilayah secara bertahap (Drill-down) dengan informasi progress pengerjaan di setiap levelnya.

Kota
1/5 Selesai

Kecamatan
1/10 Selesai

Kelurahan
Data Mebel

Detail Mebel
Input Kendala

Logika Progress: Sebuah lead dianggap "Selesai" jika statusnya telah diubah dari nilai default 'Belum Dikunjungi'.

🔐 Autentikasi

Gunakan API Key berikut pada header untuk setiap request:

Header Name: x-api-key
Header Value: marketing-secret-key-123

🛠️ Frontend Service

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');

// Ambil data kota
const cities = await service.getCities();
console.log(cities); // [{ id: 1, name: 'Malang', total_leads: 5, finished_leads: 1 }]

🚀 Endpoints Wilayah

GET /api/cities Supports Progress

Mengambil daftar semua kota beserta jumlah total leads dan leads yang sudah selesai di kota tersebut.

// Response Preview
[
  {
    "id": 1,
    "name": "Kota Malang",
    "total_leads": 50,
    "finished_leads": 12
  }
]

GET /api/districts Supports Progress

Mengambil daftar kecamatan untuk kota tertentu.

Param	Required	Description
`city_id`	✅ Yes	ID dari kota yang dipilih.

GET /api/villages Supports Progress

Mengambil daftar kelurahan/desa untuk kecamatan tertentu.

Param	Required	Description
`district_id`	✅ Yes	ID dari kecamatan yang dipilih.

📦 Endpoints Leads (Mebel)

GET /api/leads Supports Progress

Mengambil daftar mebel. Bisa difilter berdasarkan village_id untuk alur drill-down.

Param	Type	Description
`village_id`	number	Filter mebel di desa tertentu.
`search`	string	Cari nama/alamat.
`page`	number	Pagination (Default: 1).

// Response Preview
{
  "data": [...],
  "summary": {
    "total": 15,
    "finished": 1
  },
  "pagination": {...}
}

PUT /api/leads/:id

Mengupdate status pengerjaan dan kendala lapangan.

// Request Body (JSON)
{
  "status": "Sudah Dikunjungi",
  "keterangan": "Kendala: Pemilik toko sedang tidak ada di tempat."
}