> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docku.mertani.com/general-faq/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docku.mertani.com/_mcp/server. # Hello, bagaimana kami bisa membantu Anda? Dapatkan dukungan yang Anda butuhkan untuk sukses dengan Mertani. Jelajahi pusat bantuan kami, kontak kami, atau telusuri dokumentasi kami untuk menemukan jawaban dengan cepat. #### [Open API](./api-reference/external-api/get-list-devices) API Mertani memungkinkan integrasi data IoT dari perangkat di lapangan #### [Support Mertani](https://api.whatsapp.com/send/?phone=%E2%80%AA6285117481856%E2%80%AC\&text=Nama%3A%0AInstansi%3A%0AEmail%3A%0AKebutuhan+Saya%3A%0A\&type=phone_number\&app_absent=0) Ajukan pertanyaan langsung kepada support Mertani ## **Frequently Asked Questions** Find answers to common questions about Mertani dashboard app ### API Technical Specifications #### Metode otentikasi apa saja yang didukung? Mertani API menggunakan **Basic Authentication** sebagai metode autentikasi utama. Setiap request harus menyertakan header: ``` Authorization: Basic base64(api_key:secret_key) ``` * `api_key` berfungsi sebagai username * `secret_key` berfungsi sebagai password * Authentication bersifat **stateless** (tidak menggunakan session atau token) Untuk keamanan: * Gunakan HTTPS di semua request * Jangan expose API key di frontend * Simpan credential di environment variables #### Bagaimana batas frekuensi / rate limit dihitung? Saat ini, rate limit tidak selalu diekspos secara eksplisit, namun sistem menerapkan mekanisme proteksi untuk menjaga stabilitas. **Secara umum:** * Request berulang dalam waktu singkat dapat dibatasi * Polling berlebihan dapat menyebabkan throttling * Beban tinggi dari satu API key dapat memicu pembatasan sementara Best practice: * Gunakan interval request sesuai interval device (misalnya 1 jam) * Hindari polling setiap detik * Gunakan caching di sisi client Untuk kebutuhan high-frequency access, disarankan menggunakan **Webhook API**. #### Endpoint API apa saja yang tersedia? Mertani menyediakan beberapa kategori endpoint utama: **1. Device API** * Mendapatkan daftar device * Informasi detail device **2. Sensor Data API** * Data sensor terbaru * Data historis berdasarkan timestamp Semua endpoint berada di bawah base URL: ``` https://app.mertani.co.id/external/v1 ``` Struktur endpoint mengikuti prinsip REST: * `GET /devices` * `GET /devices/{id}` (Detail endpoint dapat berbeda tergantung konfigurasi instansi) #### Format apa saja yang didukung? API Mertani menggunakan format standar industri untuk pertukaran data: **Request:** * Header: JSON / HTTP standard * Authentication: Basic Auth **Response:** * Format utama: **JSON** * Encoding: UTF-8 * Timestamp: ISO 8601 / Unix timestamp (tergantung endpoint) Contoh response: ```json { "device_id": "123", "timestamp": "2025-01-01T10:00:00Z", "temperature": 27.5 } ``` JSON dipilih karena: * Ringan dan mudah diparse * Kompatibel dengan hampir semua bahasa pemrograman * Ideal untuk REST API #### Apakah API ini bersifat real-time? Secara default, API Mertani **tidak bersifat real-time per detik**, melainkan mengikuti interval pengiriman data dari device. * Umumnya interval: `1 jam` sekali * API hanya menyajikan data yang sudah tersimpan di database Untuk kebutuhan real-time: * Gunakan Webhook API (push-based) * Atau lakukan polling dengan interval yang disesuaikan #### Apakah saya dapat mengakses perangkat secara langsung? `Tidak.` Arsitektur Mertani bersifat decoupled, sehingga: * Client tidak pernah berkomunikasi langsung dengan device * Semua akses harus melalui API * Data diambil dari database, bukan dari perangkat secara live Ini memastikan: * Keamanan sistem * Konsistensi data * Skalabilitas #### Bagaimana konsistensi data dijamin? Data yang masuk ke Mertani melalui beberapa tahap: * Validasi device * Validasi format data * Normalisasi * Penyimpanan ke database Sistem juga menggunakan `timestamp` dari device sebagai referensi utama. Namun: * Delay dapat terjadi jika jaringan tidak stabil * Data duplikat bisa terjadi jika device retry Disarankan untuk melakukan validasi tambahan di sisi client. #### Apa yang terjadi jika permintaan saya gagal? API akan mengembalikan HTTP status code standar: * 200 → Success * 400 → Bad request * 401 → Unauthorized * 403 → Forbidden * 500 → Server error Best practice: * Implementasikan retry mechanism * Logging error response * Validasi request sebelum dikirim #### Kapan sebaiknya saya menggunakan REST API dan kapan Webhook? Gunakan: **REST API jika:** * Membutuhkan data historis * Membangun dashboard * Kontrol penuh terhadap request **Webhook jika:** * Membutuhkan data real-time * Ingin sistem event-driven * Menghindari polling Dalam banyak kasus, kombinasi keduanya adalah pendekatan terbaik. #### Data tidak muncul di API Kemungkinan penyebab: * Perangkat belum mengirim data * Interval pengiriman belum tercapai Solusi: * Periksa status device * Tunggu hingga siklus pengiriman berikutnya #### Data terlambat muncul Kemungkinan penyebab: * Jaringan perangkat tidak stabil * Delay pada proses ingestion Solusi: * Periksa konektivitas device * Validasi timestamp data #### Data tidak konsisten Kemungkinan penyebab: * Sensor error atau tidak terkalibrasi * Data duplikat atau missing Solusi: * Lakukan kalibrasi sensor * Validasi data di level aplikasi #### API tidak mengembalikan data terbaru Kemungkinan penyebab: * Request tidak menggunakan parameter waktu terbaru * Cache pada client Solusi: * Gunakan filter timestamp terbaru * Disable cache jika diperlukan #### Data tidak masuk ke sistem external (Webhook) Kemungkinan penyebab: * Endpoint tidak dapat diakses (down / timeout) * URL webhook salah Solusi: * Periksa endpoint server Anda * Validasi URL dan response status (200 OK) #### REST API tidak mengembalikan data terbaru Kemungkinan penyebab: * Polling terlalu cepat sebelum data tersedia * Parameter waktu tidak sesuai Solusi: * Sesuaikan interval polling dengan device * Gunakan filter timestamp terbaru #### Webhook mengirim data duplikat Kemungkinan penyebab: * Retry dari server karena response gagal * Tidak ada deduplication di client Solusi: * Implementasikan idempotency di sisi client * Simpan unique identifier data #### Server client overload karena webhook Kemungkinan penyebab: * Volume data tinggi * Endpoint tidak scalable Solusi: * Gunakan queue system (Kafka, RabbitMQ, dll) * Tambahkan rate limiting atau buffering #### 401 Unauthorized Kemungkinan penyebab: * Header Authorization tidak ada * Format Basic Authentication salah * Base64 encoding tidak valid Solusi: Pastikan header dikirim dengan benar Periksa format: api\_key:secret\_key sebelum encoding Generate ulang Base64 #### 403 Forbidden Kemungkinan penyebab: * API key tidak memiliki akses ke resource * API key telah dicabut Solusi: Periksa permission API key Hubungi pihak Mertani jika diperlukan #### Request berhasil tapi data kosong Kemungkinan penyebab: * API key tidak memiliki akses ke data tertentu * Parameter request tidak sesuai Solusi: Validasi endpoint dan parameter Periksa scope akses API key #### Kredensial bocor atau tidak aman Kemungkinan penyebab: * API key tersimpan di frontend * Repository tidak diamankan Solusi: Segera rotasi API key Pindahkan kredensial ke server-side Gunakan secret manager jika tersedia ### App Dashboard Mertani #### Undangan tidak diterima Kemungkinan penyebab: * Email salah atau tidak aktif * Email masuk ke folder spam Solusi: * Periksa kembali alamat email * Minta pengguna cek folder spam atau promotion * Kirim ulang undangan jika tersedia #### User tidak bisa login setelah invite Kemungkinan penyebab: * Proses aktivasi belum selesai * Password belum diterima melalui email Solusi: * Pastikan pengguna telah membuka link undangan * Minta pengguna terima undangan #### User tidak muncul di daftar pengguna Kemungkinan penyebab: * Invite belum diproses sepenuhnya * Halaman belum diperbarui Solusi: * Refresh halaman * Periksa kembali status undangan #### Role tidak sesuai setelah login Kemungkinan penyebab: * Salah memilih role saat invite * Perubahan belum tersimpan Solusi: * Gunakan fitur **Assign Role** untuk memperbaiki * Pastikan konfigurasi role benar saat invite #### Perubahan tidak tersimpan Kemungkinan penyebab: * Form belum diisi dengan benar * Validasi sistem gagal Solusi: * Pastikan semua field wajib sudah diisi * Periksa kembali format data #### Data tidak berubah setelah disimpan Kemungkinan penyebab: * Cache browser belum diperbarui * Gangguan sinkronisasi Solusi: * Refresh halaman * Coba login ulang jika diperlukan #### Tidak bisa mengedit pengguna Kemungkinan penyebab: * Tidak memiliki permission yang cukup * Akun dibatasi oleh sistem Solusi: * Gunakan akun dengan akses lebih tinggi * Periksa kebijakan sistem terkait akses edit #### Nomor HP tidak valid Kemungkinan penyebab: * Format nomor tidak sesuai * Mengandung karakter yang tidak diperbolehkan Solusi: * Gunakan format nomor yang benar (angka saja atau sesuai standar sistem) * Hindari spasi atau simbol tambahan #### User tidak melihat device apapun Kemungkinan penyebab: * Tidak ada device yang dipilih saat konfigurasi Solusi: * Edit kembali akses device * Pastikan minimal satu device dipilih #### Device tidak muncul di daftar pilihan Kemungkinan penyebab: * Device belum terdaftar dalam sistem * Device berada di instansi berbeda Solusi: * Pastikan device sudah dibuat dan aktif * Periksa kembali scope instansi #### Perubahan tidak terlihat di dashboard Kemungkinan penyebab: * Cache browser belum diperbarui * Session belum sinkron Solusi: * Refresh halaman * Logout dan login kembali jika diperlukan #### User masih bisa akses device lain Kemungkinan penyebab: * Pembatasan belum tersimpan dengan benar * Ada konflik dengan konfigurasi lain Solusi: * Ulangi proses dan pastikan klik simpan * Validasi kembali konfigurasi akses user #### Role tidak muncul saat assign user? * Pastikan role sudah berhasil disimpan * Refresh halaman atau reload sistem #### Role tidak memiliki akses? * Pastikan permission sudah dikonfigurasi * Periksa apakah ada override dari sistem lain #### Gagal membuat role? * Pastikan nama role tidak duplikat * Periksa koneksi atau validasi input #### Tidak bisa mengubah nama role Kemungkinan penyebab: * Role merupakan role default atau dilindungi sistem * Anda tidak memiliki permission yang cukup Solusi: * Gunakan akun dengan akses lebih tinggi * Periksa apakah role termasuk protected role #### Nama role tidak bisa disimpan Kemungkinan penyebab: * Nama role sudah digunakan (duplikat) * Input tidak valid (kosong atau karakter tidak diperbolehkan) Solusi: * Gunakan nama yang unik * Pastikan format nama sesuai aturan sistem #### Perubahan tidak terlihat Kemungkinan penyebab: * Cache browser belum diperbarui * Sinkronisasi data tertunda Solusi: * Refresh halaman * Logout dan login kembali jika diperlukan #### User bingung dengan perubahan nama role Kemungkinan penyebab: * Tidak ada komunikasi perubahan * Nama baru tidak cukup jelas Solusi: * Informasikan perubahan kepada pengguna terkait * Gunakan nama yang lebih deskriptif dan familiar #### Perubahan tidak terlihat? * Pastikan halaman telah di-refresh * Periksa apakah cache browser mempengaruhi tampilan #### Akses pengguna tidak sesuai setelah perubahan? * Validasi kembali konfigurasi permission pada role * Pastikan tidak ada konflik konfigurasi #### Tidak bisa mengubah role? * Periksa apakah Anda memiliki permission yang cukup * Pastikan role tujuan tidak dibatasi oleh sistem #### Tidak bisa menghapus role Kemungkinan penyebab: * Role masih digunakan oleh satu atau lebih pengguna * Role termasuk role default sistem Solusi: * Pindahkan semua pengguna ke role lain melalui fitur **Assign Role** * Pastikan role bukan bagian dari role bawaan sistem #### Role tidak muncul dalam daftar Kemungkinan penyebab: * Data belum ter-refresh * Role sudah dihapus sebelumnya Solusi: * Refresh halaman * Periksa kembali dengan filter atau pencarian #### Aksi hapus tidak tersedia Kemungkinan penyebab: * Anda tidak memiliki permission untuk menghapus role * Role dilindungi oleh sistem (protected role) Solusi: * Gunakan akun dengan akses lebih tinggi (misalnya Admin) * Periksa kebijakan sistem terkait role yang tidak bisa dimodifikasi #### Terjadi kesalahan saat konfirmasi Kemungkinan penyebab: * Gangguan koneksi * Validasi sistem gagal Solusi: * Coba ulangi proses beberapa saat kemudian * Pastikan koneksi stabil #### User tidak bisa mengakses fitur tertentu Kemungkinan penyebab: * Permission belum diberikan pada role * Role yang digunakan tidak sesuai Solusi: * Periksa dan tambahkan permission yang diperlukan * Validasi role pengguna #### Aksi ditolak meskipun tombol tersedia Kemungkinan penyebab: * UI menampilkan tombol, tetapi permission backend tidak mengizinkan Solusi: * Periksa konfigurasi permission di sistem * Pastikan aksi yang dipilih sudah diaktifkan #### Perubahan permission tidak terlihat Kemungkinan penyebab: * Cache browser belum diperbarui * Sinkronisasi session belum terjadi Solusi: * Refresh halaman * Logout dan login kembali jika diperlukan #### Semua user dalam role terkena dampak perubahan Penjelasan: * Permission berlaku global untuk role Solusi: * Buat role baru jika membutuhkan variasi akses * Hindari perubahan langsung pada role yang digunakan banyak user #### Kenapa hasil kalibrasi tidak berubah setelah saya simpan? Kemungkinan penyebab: * Kalibrasi hanya berlaku untuk data baru, bukan data historis * Tidak ada data baru yang masuk setelah kalibrasi disimpan * Rumus tidak valid sehingga tidak dieksekusi Solusi: * Pastikan device mengirim data terbaru * Cek timestamp data terakhir * Periksa kembali rumus (hindari typo atau format salah) #### Kenapa nilai hasil kalibrasi menjadi 0 atau null? Kemungkinan penyebab: * Rumus menghasilkan nilai tidak valid (misalnya pembagian dengan 0) * Referensi parameter \[parameter] tidak ditemukan * Dataset tidak mengembalikan nilai (lookup gagal) Solusi: * Validasi rumus secara manual * Pastikan ID sensor atau parameter benar * Pastikan dataset memiliki range nilai yang sesuai dengan input #### Kenapa muncul error saat input rumus kalibrasi? Kemungkinan penyebab: * Salah syntax (contoh: x + tanpa nilai lanjutan) * Salah operator (misalnya ^ вместо \*\*) * Fungsi tidak didukung atau salah format Solusi: * Gunakan operator yang didukung (+ - \* / \*\*) * Pastikan semua tanda kurung seimbang * Gunakan fungsi sesuai dokumentasi (contoh: sqrt(x)) #### Kenapa parameter lain tidak bisa dipanggil dengan \[parameter]? Kemungkinan penyebab: * ID sensor salah atau tidak ada di device yang sama * Penulisan tidak sesuai format (\[id\_sensor]) * Sensor belum memiliki data Solusi: * Pastikan ID sensor benar (case-sensitive) * Gunakan fitur = untuk memilih parameter otomatis * Pastikan sensor referensi aktif dan mengirim data #### Kenapa hasil DATASET() tidak sesuai atau kosong? Kemungkinan penyebab: * Slug dataset salah * Kolom output tidak ditemukan * Nilai input tidak ada dalam range dataset Solusi: * Periksa slug dataset sesuai yang disimpan * Pastikan nama kolom output benar * Pastikan dataset mencakup seluruh range nilai input (interpolasi jika perlu) #### Kenapa hasil kalibrasi terlihat tidak masuk akal (terlalu besar/kecil)? Kemungkinan penyebab: * Salah konversi unit (cm ke m, dll) * Kesalahan dalam rumus (misalnya urutan operasi) * Referensi parameter yang tidak sesuai Solusi: * Validasi dengan perhitungan manual * Cek kembali unit sebelum dan sesudah kalibrasi * Gunakan nilai sample untuk testing #### Kenapa grafik dan dashboard tidak sesuai dengan raw data? Ini bukan error. Penjelasan: * Sistem menggunakan Sintetik Data (hasil kalibrasi) untuk: * Dashboard * Grafik * Laporan * Sedangkan Raw Data hanya sebagai referensi Solusi: * Bandingkan raw vs sintetik melalui unduh data untuk validasi * Pastikan rumus kalibrasi sudah benar #### Kenapa perubahan units tidak berpengaruh pada nilai? Penjelasan: * Units hanya label, tidak mengubah nilai * Nilai berubah hanya jika rumus kalibrasi diubah Solusi: Pastikan rumus sudah sesuai dengan unit baru Contoh: * cm → m harus menggunakan x/100 * lalu update unit menjadi meter #### Kenapa sensor turunan (virtual parameter) tidak muncul di sistem? Kemungkinan penyebab: * Kalibrasi belum disimpan * Parameter tidak digunakan di dashboard * Tidak ada data masuk Solusi: * Klik Simpan setelah input rumus * Pastikan parameter digunakan di tampilan * Tunggu data baru masuk #### Bagaimana cara memastikan rumus kalibrasi sudah benar sebelum digunakan? Best practice: * Uji dengan sample data manual * Gunakan nilai sederhana terlebih dahulu (misal x/100) * Bandingkan hasil dengan perhitungan di luar sistem Tips: * Hindari langsung menggunakan rumus kompleks tanpa validasi * Bangun rumus secara bertahap #### Apakah sensor turunan (virtual sensor) dapat digunakan sebagai faktor kalibrasi? `Tidak` Parameter turunan (virtual sensor) tidak dapat digunakan sebagai faktor kalibrasi kembali. Tips: * Hindari menggunakan parameter turunan sebagai faktor kalibrasi. * Lakukan kalibrasi yang sama untuk mendapat nilai dari parameter turunan, kemudian kalibrasikan perhitungan tersebut. Contoh: * Water level: `120-x` * Debit (virtual sensor): `[water_level]*[velocity]` * Virtual sensor x: `[debit]*10` -> **tidak boleh** akan error. #### Apakah format file dataset harus CSV? Ya. Sistem hanya menerima file dalam format **CSV (Comma-Separated Values)**. Solusi: * Pastikan file berekstensi `.csv` * Jika dari Excel, gunakan **Export → CSV** #### Apakah kolom pertama wajib digunakan sebagai referensi? Ya, **kolom pertama wajib menjadi nilai referensi (input lookup)**. Penjelasan: * Sistem akan mencocokkan nilai sensor ke kolom pertama * Kolom lain hanya digunakan sebagai output Jika kolom pertama tidak sesuai: * Lookup akan menghasilkan nilai yang tidak akurat atau kosong #### Apakah baris pertama harus header? Ya, **baris pertama wajib berisi header kolom**. Penjelasan: * Header digunakan sebagai identifier kolom output dalam fungsi `DATASET()` * Tanpa header, sistem tidak dapat mengenali kolom hasil Contoh benar: ```csv water_level,area 4.0,40.4 3.9,39.0 4.0,40.4 3.9,39.0 ``` #### Kenapa dataset tidak terbaca setelah upload? Kemungkinan penyebab: * Format file bukan CSV * Tidak ada header di baris pertama * Struktur kolom tidak sesuai * File corrupt atau encoding tidak valid Solusi: * Pastikan format CSV valid * Gunakan delimiter koma (,) * Pastikan file dapat dibuka di editor teks #### Kenapa hasil DATASET() kosong atau null? Kemungkinan penyebab: * Nilai input tidak ditemukan dalam kolom referensi * Slug dataset salah * Nama kolom output tidak sesuai header Solusi: * Pastikan nilai input berada dalam range dataset * Periksa slug dataset * Gunakan nama kolom output sesuai header (case-sensitive) #### Apakah nilai pada kolom referensi harus berurutan? `Sangat disarankan.` Penjelasan: * Data yang terurut mempermudah proses lookup * Mengurangi risiko hasil tidak akurat Best practice: * Urutkan data secara konsisten (ascending atau descending) #### Apakah boleh ada nilai duplikat pada kolom referensi? `Tidak disarankan.` Dampak: * Sistem dapat menghasilkan output yang tidak konsisten * Lookup menjadi ambigu Solusi: * Pastikan setiap nilai referensi unik #### Apakah dataset mendukung interpolasi otomatis? `Tidak selalu.` Penjelasan: * Sistem melakukan lookup berdasarkan nilai yang tersedia * Jika nilai tidak ditemukan secara langsung, hasil bisa kosong atau tidak akurat Solusi: * Gunakan interval data yang lebih rapat * Tambahkan nilai di antara (intermediate values) jika diperlukan #### Apakah satu dataset bisa memiliki banyak kolom output? `Ya.` Contoh: `water_level,area,volume,flow` Penggunaan: * DATASET("slug", x, "area") * DATASET("slug", x, "volume") #### Kenapa upload dataset gagal atau error? Kemungkinan penyebab: * File terlalu besar * Format tidak sesuai * Header kosong atau duplikat * Encoding tidak standar (bukan UTF-8) Solusi: * Gunakan CSV dengan encoding UTF-8 * Pastikan header unik dan tidak kosong * Periksa batas ukuran file #### Apakah perubahan dataset mempengaruhi data lama? `Tidak.` Penjelasan: * Dataset hanya berlaku untuk data setelah konfigurasi disimpan * Data historis tidak akan berubah #### Bagaimana cara memastikan dataset sudah benar sebelum digunakan? Checklist: * Kolom pertama = referensi (input) * Baris pertama = header * Tidak ada nilai kosong di kolom referensi * Range data mencakup nilai sensor * Tidak ada duplikasi nilai referensi Best practice: * Uji dengan beberapa nilai sample * Bandingkan hasil manual dengan hasil sistem ### Device Status #### 🔴 Device Offline #### Kemungkinan Penyebab * Device mati * Kehabisan daya * Gangguan jaringan * SIM card tidak aktif * Modem bermasalah #### Langkah Pengecekan 1. Pastikan device dalam kondisi menyala 2. Periksa sumber daya / baterai 3. Verifikasi koneksi internet 4. Cek kualitas sinyal modem 5. Restart device apabila diperlukan #### Rekomendasi Jika device tetap offline lebih dari 24 jam, lakukan pengecekan lapangan. #### 🟡 Device Delay #### Kemungkinan Penyebab * Koneksi jaringan tidak stabil * Server mengalami latency * Interval pengiriman terlalu kecil * Gangguan modem sementara #### Langkah Pengecekan 1. Periksa kualitas sinyal 2. Pastikan koneksi internet stabil 3. Verifikasi interval pengiriman device 4. Monitor apakah status berubah menjadi offline #### ⚪ Device Maintenance #### Informasi Status maintenance biasanya diatur manual oleh admin atau teknisi. #### Rekomendasi * Dokumentasikan aktivitas maintenance * Nonaktifkan alarm sementara jika diperlukan * Pastikan status dikembalikan setelah maintenance selesai > Everything you need to build the best developer experience