Daftar Isi Dokumentasi
MiniMaps v2.0 AWH Standard JSON

Dokumentasi Integrasi Sistem Peta Wisata 2D

MiniMaps adalah platform visual denah peta 2D interaktif (*site plan / layout*) untuk kawasan rekreasi dan tempat wisata. Platform ini dirancang untuk di-embed ke website eksternal dan terintegrasi dengan sistem tiket gelang pintar (*smart wristband*) untuk menampilkan anggota rombongan secara *real-time*.

1. Panduan Iframe Embed

Sistem peta siap disematkan di web portal, web promosi tiket, maupun webview aplikasi mobile.

Kode HTML Iframe Dasar:
<iframe 
  src="https://dev.mm.awh.co.id/embed/maps/sari-ater-resort" 
  width="100%" 
  height="600px" 
  allow="geolocation" 
  frameborder="0" 
  style="border-radius: 12px; border: 1px solid #cbd5e1;">
</iframe>
PENTING: Atribut allow="geolocation" wajib disertakan agar browser pengunjung mengizinkan fitur deteksi lokasi tombol "Saya".

2. Alur Scan QR Tiket Pengunjung

Setiap pengunjung memiliki kode tiket unik (misal: TIK-101). Saat pengunjung scan QR pada tiket / gelang, arahkan ke URL embed dengan parameter ?ticket_id=...:

https://dev.mm.awh.co.id/embed/maps/sari-ater-resort?ticket_id=TIK-101
Tampilan Pengunjung:
  • Hanya melihat diri sendiri & anggota satu rombongannya.
  • Tidak melihat pengunjung dari rombongan lain (privasi terjaga).
  • Anggota yang tidak membuka peta tetap terlihat posisinya.
Tampilan Admin:
  • Melihat seluruh pengunjung & seluruh rombongan di denah.
  • Dapat memfilter peta berdasarkan rombongan tertentu.
  • Memantau status pengunjung yang sedang di dalam (in) maupun yang sudah keluar (out).
POST /api/v1/attractions/{slug}/groups

Penyimpanan Data Kelompok / Rombongan

Dipanggil oleh aplikasi sistem tiket saat pengunjung membeli tiket atau saat salah satu pengunjung pertama kali membuka menu maps.

Bersifat Idempoten: Jika data dengan group_id dan ticket_id yang sama dikirim kembali, sistem tidak melempar error, melainkan tetap sukses (200 OK) tanpa mengubah/me-reset posisi pengunjung yang sedang berjalan.
Header Request:
Content-Type: application/json
Accept: application/json
Request Payload (JSON Body):
{
  "group_id": "GRP-12345",
  "group_name": "Keluarga Budi Santoso",
  "members": [
    {
      "ticket_id": "TIK-001",
      "name": "Budi Santoso",
      "status": "in"
    },
    {
      "ticket_id": "TIK-002",
      "name": "Ani Rahayu",
      "status": "in"
    },
    {
      "ticket_id": "TIK-003",
      "name": "Dika",
      "status": "out"
    }
  ]
}
Response Sukses Baru Disimpan (HTTP 201 Created):
{
  "success": true,
  "message": "Data kelompok dan pengunjung berhasil disimpan.",
  "data": {
    "group_id": "GRP-12345",
    "group_name": "Keluarga Budi Santoso",
    "total_members": 3,
    "members": [
      {
        "ticket_id": "TIK-001",
        "name": "Budi Santoso",
        "status": "in",
        "map_url": "https://dev.mm.awh.co.id/embed/maps/sari-ater-resort?ticket_id=TIK-001"
      },
      {
        "ticket_id": "TIK-002",
        "name": "Ani Rahayu",
        "status": "in",
        "map_url": "https://dev.mm.awh.co.id/embed/maps/sari-ater-resort?ticket_id=TIK-002"
      }
    ]
  }
}
Response Sukses Jika Data Sudah Ada (HTTP 200 OK):
{
  "success": true,
  "message": "Data kelompok dan tiket sudah terdaftar. Tidak ada perubahan data.",
  "data": { ... }
}
PATCH /api/v1/attractions/{slug}/tickets/{ticket_id}/status

Update Status Pengunjung (In / Out)

Dipanggil saat pengunjung melakukan tap / scan gelang di gerbang keluar atau masuk.

Request Payload (JSON Body):
{
  "status": "out"
}
Response Sukses (HTTP 200 OK):
{
  "success": true,
  "message": "Status tiket TIK-001 berhasil diubah menjadi out.",
  "data": {
    "ticket_id": "TIK-001",
    "name": "Budi Santoso",
    "status": "out"
  }
}
PATCH POST / PUT /api/v1/attractions/{slug}/tickets/{ticket_id}/name

Update Nama Pengunjung

Dipanggil saat ada perubahan nama pemegang tiket/pengunjung dari aplikasi ticketing.

Request Payload (JSON Body):
{
  "name": "Budi Santoso, S.Kom"
}
Response Sukses (HTTP 200 OK):
{
  "success": true,
  "message": "Nama pengunjung dengan tiket TIK-001 berhasil diperbarui.",
  "data": {
    "ticket_id": "TIK-001",
    "name": "Budi Santoso, S.Kom",
    "status": "in"
  }
}
PATCH POST /api/v1/attractions/{slug}/tickets/{ticket_id}/offline

Set Pengunjung Offline (Pulang)

Dipanggil saat pengunjung sudah pulang/keluar dari tempat wisata sehingga pin lokasinya otomatis tidak lagi muncul di denah maps.

Response Sukses (HTTP 200 OK):
{
  "success": true,
  "message": "Pengunjung dengan tiket TIK-001 berhasil di-set offline (pulang).",
  "data": {
    "ticket_id": "TIK-001",
    "name": "Budi Santoso",
    "status": "out",
    "is_online": false
  }
}

3. Standar JSON AWH

Semua endpoint API dibangun menggunakan trait AwhStandardJson dengan format seragam:

Format Sukses:
{
  "success": true,
  "message": "Ok",
  "data": { ... }
}
Format Error:
{
  "success": false,
  "message": "Pesan error",
  "errors": { ... }
}

Live API Tester (Playground)

Uji Coba Langsung

Gunakan form di bawah ini untuk menguji pengiriman data rombongan secara langsung ke sistem maps.