Mengirim data lewat HTTP

Satu permintaan POST untuk satu bacaan. Token perangkat ada di alamatnya, jadi tidak perlu header otorisasi.

POST https://app.include.co.id/api/v1/YOUR_DEVICE_TOKEN/telemetry
Content-Type: application/json

Ganti YOUR_DEVICE_TOKEN dengan Device Token dari layar Koneksi & Integrasi. Alamat lengkapnya juga bisa disalin langsung dari layar itu.

Program lengkap dalam setiap bahasa ada di Contoh kode.

Isi permintaan

Objek JSON. Setiap kunci menjadi satu parameter perangkat.

{ "temperature": 25.4, "humidity": 61 }

• Nilai boleh angka, teks, atau true/false. Nilai lain (objek, daftar, null) diabaikan.
• Paling banyak 100 parameter dalam satu kiriman, dan paling besar 32 KB.
• Kunci tanpa tanda kutip juga diterima: {temperature:25}. Berguna saat mengetik di cmd Windows.
• Nama kunci bebas, tetapi tetap sama dari kiriman ke kiriman: temperature dan Temperature adalah dua parameter berbeda.

Waktu bacaan

Tanpa keterangan waktu, bacaan dicatat pada saat diterima. Untuk mengirim waktu sendiri, misalnya bacaan yang tertahan saat jaringan putus, tambahkan ts dalam milidetik Unix (UTC) dan taruh nilainya di values:

{ "ts": 1761980400000, "values": { "temperature": 25.4 } }

Token di header

Kalau token tidak boleh tampak di alamat, misalnya karena alamat tercatat di log proxy, kirim ke alamat tetap dan taruh token di header:

curl -X POST https://app.include.co.id/api/v1/device/telemetry \
  -H "X-Device-Token: YOUR_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 25.4}'

Authorization: Bearer YOUR_DEVICE_TOKEN juga diterima.

Membaca pengaturan dari server

Nilai yang Anda isi di bagian Config Server → Device pada layar Koneksi & Integrasi, misalnya setpoint = 25, bisa dibaca perangkat:

GET https://app.include.co.id/api/v1/YOUR_DEVICE_TOKEN/attributes

Jawabannya objek JSON, semua nilai berupa teks:

{ "setpoint": "25", "interval": "30" }

Hanya beberapa kunci: tambahkan ?keys=setpoint,interval.

Pengaturan MQTT perangkat

Perangkat yang hanya tahu tokennya bisa mengambil semua yang dibutuhkan untuk MQTT:

GET https://app.include.co.id/api/v1/YOUR_DEVICE_TOKEN/mqtt-config

{
  "deviceId": "fCYit_6N7CLa0Uw5NYi_V",
  "name": "Sensor Gudang",
  "label": "",
  "groupId": "ruang_kerja_rina",
  "customerId": "ruang_kerja_rina",
  "solutionSlug": "custom",
  "mqttHost": "app.include.co.id",
  "mqttPort": 8883,
  "mqttPortPlain": 1883,
  "mqttPortTls": 8883
}

mqttPortPlain (1883, tanpa TLS) dan mqttPortTls (8883) adalah dua pilihan port. mqttPort selalu 8883, untuk firmware IncludeBox yang membacanya. Topik telemetrinya: includeapps/{groupId}/{solutionSlug}/{deviceId}/telemetry. Lihat Mengirim data lewat MQTT.

Jawaban server

Kode	Arti
202	Diterima: {"ok":true}. Status perangkat menjadi online.
400	Isi bukan JSON, tidak ada nilai yang bisa dipakai, atau lebih dari 100 parameter.
401	Token salah atau tidak ada.
409	Perangkat belum terdaftar ke Organisasi mana pun.
429	Terlalu sering. Kirim lebih jarang.
503	Bacaan gagal disimpan. Kirim ulang beberapa detik kemudian.

Kalau ada galat, isinya menjelaskan sebabnya:

{ "error": "RATE_LIMITED", "message": "Terlalu banyak pesan; kurangi frekuensi kirim device" }

Batas kiriman

Setiap perangkat boleh mengirim paling sedikit 20 pesan per detik. Paket yang memberi kuota data per detik lebih besar menaikkan batas itu sesuai paketnya. Lihat Paket, kuota, dan uji coba.

Sekali kirim tiap 10 sampai 60 detik sudah cukup untuk hampir semua sensor, dan menghemat kuota serta baterai.