Hello, bagaimana kami bisa membantu Anda?

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

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.

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)

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:

1
{
2
  "device_id": "123",
3
  "timestamp": "2025-01-01T10:00:00Z",
4
  "temperature": 27.5
5
}

JSON dipilih karena:

• Ringan dan mudah diparse
• Kompatibel dengan hampir semua bahasa pemrograman
• Ideal untuk REST API

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

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

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.

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

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.

Kemungkinan penyebab:

• Perangkat belum mengirim data
• Interval pengiriman belum tercapai

Solusi:

• Periksa status device
• Tunggu hingga siklus pengiriman berikutnya

Kemungkinan penyebab:

• Jaringan perangkat tidak stabil
• Delay pada proses ingestion

Solusi:

• Periksa konektivitas device
• Validasi timestamp data

Kemungkinan penyebab:

• Sensor error atau tidak terkalibrasi
• Data duplikat atau missing

Solusi:

• Lakukan kalibrasi sensor
• Validasi data di level aplikasi

Kemungkinan penyebab:

• Request tidak menggunakan parameter waktu terbaru
• Cache pada client

Solusi:

• Gunakan filter timestamp terbaru
• Disable cache jika diperlukan

Kemungkinan penyebab:

• Endpoint tidak dapat diakses (down / timeout)
• URL webhook salah

Solusi:

• Periksa endpoint server Anda
• Validasi URL dan response status (200 OK)

Kemungkinan penyebab:

• Polling terlalu cepat sebelum data tersedia
• Parameter waktu tidak sesuai

Solusi:

• Sesuaikan interval polling dengan device
• Gunakan filter timestamp terbaru

Kemungkinan penyebab:

• Retry dari server karena response gagal
• Tidak ada deduplication di client

Solusi:

• Implementasikan idempotency di sisi client
• Simpan unique identifier data

Kemungkinan penyebab:

• Volume data tinggi
• Endpoint tidak scalable

Solusi:

• Gunakan queue system (Kafka, RabbitMQ, dll)
• Tambahkan rate limiting atau buffering

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

Kemungkinan penyebab:

• API key tidak memiliki akses ke resource
• API key telah dicabut

Solusi:

Periksa permission API key Hubungi pihak Mertani jika diperlukan

Kemungkinan penyebab:

• API key tidak memiliki akses ke data tertentu
• Parameter request tidak sesuai

Solusi:

Validasi endpoint dan parameter Periksa scope akses API key

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

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

Kemungkinan penyebab:

• Proses aktivasi belum selesai
• Password belum diterima melalui email

Solusi:

• Pastikan pengguna telah membuka link undangan
• Minta pengguna terima undangan

Kemungkinan penyebab:

• Invite belum diproses sepenuhnya
• Halaman belum diperbarui

Solusi:

• Refresh halaman
• Periksa kembali status undangan

Kemungkinan penyebab:

• Salah memilih role saat invite
• Perubahan belum tersimpan

Solusi:

• Gunakan fitur Assign Role untuk memperbaiki
• Pastikan konfigurasi role benar saat invite

Kemungkinan penyebab:

• Form belum diisi dengan benar
• Validasi sistem gagal

Solusi:

• Pastikan semua field wajib sudah diisi
• Periksa kembali format data

Kemungkinan penyebab:

• Cache browser belum diperbarui
• Gangguan sinkronisasi

Solusi:

• Refresh halaman
• Coba login ulang jika diperlukan

Kemungkinan penyebab:

• Tidak memiliki permission yang cukup
• Akun dibatasi oleh sistem

Solusi:

• Gunakan akun dengan akses lebih tinggi
• Periksa kebijakan sistem terkait akses edit

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

Kemungkinan penyebab:

• Tidak ada device yang dipilih saat konfigurasi

Solusi:

• Edit kembali akses device
• Pastikan minimal satu device dipilih

Kemungkinan penyebab:

• Device belum terdaftar dalam sistem
• Device berada di instansi berbeda

Solusi:

• Pastikan device sudah dibuat dan aktif
• Periksa kembali scope instansi

Kemungkinan penyebab:

• Cache browser belum diperbarui
• Session belum sinkron

Solusi:

• Refresh halaman
• Logout dan login kembali jika diperlukan

Kemungkinan penyebab:

• Pembatasan belum tersimpan dengan benar
• Ada konflik dengan konfigurasi lain

Solusi:

• Ulangi proses dan pastikan klik simpan
• Validasi kembali konfigurasi akses user

• Pastikan role sudah berhasil disimpan
• Refresh halaman atau reload sistem

• Pastikan permission sudah dikonfigurasi
• Periksa apakah ada override dari sistem lain

• Pastikan nama role tidak duplikat
• Periksa koneksi atau validasi input

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

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

Kemungkinan penyebab:

• Cache browser belum diperbarui
• Sinkronisasi data tertunda

Solusi:

• Refresh halaman
• Logout dan login kembali jika diperlukan

Kemungkinan penyebab:

• Tidak ada komunikasi perubahan
• Nama baru tidak cukup jelas

Solusi:

• Informasikan perubahan kepada pengguna terkait
• Gunakan nama yang lebih deskriptif dan familiar

• Pastikan halaman telah di-refresh
• Periksa apakah cache browser mempengaruhi tampilan

• Validasi kembali konfigurasi permission pada role
• Pastikan tidak ada konflik konfigurasi

• Periksa apakah Anda memiliki permission yang cukup
• Pastikan role tujuan tidak dibatasi oleh sistem

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

Kemungkinan penyebab:

• Data belum ter-refresh
• Role sudah dihapus sebelumnya

Solusi:

• Refresh halaman
• Periksa kembali dengan filter atau pencarian

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

Kemungkinan penyebab:

• Gangguan koneksi
• Validasi sistem gagal

Solusi:

• Coba ulangi proses beberapa saat kemudian
• Pastikan koneksi stabil

Kemungkinan penyebab:

• Permission belum diberikan pada role
• Role yang digunakan tidak sesuai

Solusi:

• Periksa dan tambahkan permission yang diperlukan
• Validasi role pengguna

Kemungkinan penyebab:

• UI menampilkan tombol, tetapi permission backend tidak mengizinkan

Solusi:

• Periksa konfigurasi permission di sistem
• Pastikan aksi yang dipilih sudah diaktifkan

Kemungkinan penyebab:

• Cache browser belum diperbarui
• Sinkronisasi session belum terjadi

Solusi:

• Refresh halaman
• Logout dan login kembali jika diperlukan

Penjelasan:

• Permission berlaku global untuk role

Solusi:

• Buat role baru jika membutuhkan variasi akses
• Hindari perubahan langsung pada role yang digunakan banyak user

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)

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

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

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

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)

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

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

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

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

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

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.

Ya. Sistem hanya menerima file dalam format CSV (Comma-Separated Values).

Solusi:

• Pastikan file berekstensi .csv
• Jika dari Excel, gunakan Export → CSV

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

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:

1
water_level,area
2
4.0,40.4
3
3.9,39.0
4
4.0,40.4
5
3.9,39.0

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

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)

Sangat disarankan.

Penjelasan:

• Data yang terurut mempermudah proses lookup
• Mengurangi risiko hasil tidak akurat

Best practice:

• Urutkan data secara konsisten (ascending atau descending)

Tidak disarankan.

Dampak:

• Sistem dapat menghasilkan output yang tidak konsisten
• Lookup menjadi ambigu

Solusi:

• Pastikan setiap nilai referensi unik

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

Ya.

Contoh:

water_level,area,volume,flow

Penggunaan:

• DATASET(“slug”, x, “area”)
• DATASET(“slug”, x, “volume”)

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

Tidak.

Penjelasan:

• Dataset hanya berlaku untuk data setelah konfigurasi disimpan
• Data historis tidak akan berubah

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

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.

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

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