REST API · Bantuan Measure Map Online

Kelola proyek, folder, produk, dan anggota Anda dari perangkat lunak Anda sendiri, coba permintaan dari halaman Pengembang, dan terima webhook saat sesuatu terjadi.

REST API memungkinkan perangkat lunak Anda sendiri membaca dan mengubah isi akun Measure Map Online Anda: proyek beserta pengukurannya, folder, katalog produk, dan, pada Enterprise, anggota organisasi Anda. API ini menjawab dalam JSON. Referensi lengkapnya, dengan setiap kolom dan contoh, ada di dokumentasi API; halaman ini adalah ringkasannya.

Untuk membuka dokumentasi dari aplikasi, buka Pengembang > REST API lalu tekan Lihat dokumentasi.

URL dasar#

Setiap permintaan dikirim ke:

https://api.measuremaponline.com/api/v2

Autentikasi#

Kirim kunci API Anda, apa adanya, di header Authorization pada setiap permintaan. Buat kunci di halaman Pengembang: lihat kunci API.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Setiap permintaan diperiksa terhadap akses kunci (misalnya, Proyek Baca), langganan Anda, dan, untuk permintaan yang dikirim dari halaman web, pembatasan situs web kunci. Simpan kunci yang dapat mengubah data di server Anda: lihat jaga keamanan kunci Anda.

Live dan sandbox#

Ada satu URL dasar untuk keduanya. Kuncilah yang menentukan: kunci sandbox membaca dan menulis proyek, folder, dan produk sandbox, yang tidak pernah dilihat oleh kunci live. Anggotanya sama di keduanya, tetapi masuk sebagai anggota membutuhkan kunci live. Proyek tamu yang dibuat dengan kunci sandbox tidak pernah ditagih, dan proyek sandbox tidak dapat disematkan di situs web Anda. Token melaporkan lingkungan tempatnya berada.

Cakupan API#

Kelompok	Endpoint	Akses kunci yang dibutuhkan
Token masuk	`POST /auth/token`, `POST /auth/iframe/token`	Peta tersemat
Proyek dan folder	Menampilkan daftar proyek seseorang (semua, atau per halaman, hingga 200 per halaman) dan foldernya; mengambil sebuah proyek, pengukurannya (`/projects/{pid}/data`), komentarnya, atau file `.mmp`-nya (`/projects/{pid}/mmp`); mengambil sebuah folder; membuat, memperbarui, dan menghapus proyek dan folder	Proyek: Baca untuk membaca, Baca & ubah untuk mengubah
Produk	`GET /products`, `GET /products/{id}`, membuat, memperbarui, dan mengarsipkan dengan `DELETE /products/{id}`	Produk: Baca atau Baca & ubah
Anggota (Enterprise)	`GET /users`, `GET /users/{uid}`, `POST /users/new`, `PUT /users/{uid}`, `DELETE /users/{uid}`	Pengguna: Baca atau Baca & ubah
Masuk sebagai anggota (Enterprise)	`POST /auth/{uid}/login` memberikan token masuk untuk seorang anggota organisasi Anda	Pengguna: Baca & ubah

Beberapa hal yang perlu diketahui:

Sebuah kunci menjangkau proyek akunnya sendiri dan, pada Enterprise, proyek anggota organisasi.
Menghapus proyek atau folder melalui API bersifat permanen: tidak ada yang masuk ke Sampah. Folder ikut menghapus folder dan proyek di dalamnya yang milik akun Anda atau anggota Anda.
Dalam pengukuran sebuah proyek, sebuah bentuk mencantumkan produknya di productIds, sesuai urutan; productId adalah yang pertama.
/projects/{pid}/mmp memberikan file .mmp yang sama dengan yang diekspor aplikasi. Skemanya dipublikasikan di github.com/blueblinkone/mmp-validator. Elemen baru selalu ditambahkan sebagai elemen opsional, sehingga pembaca yang ditulis untuk file yang lebih lama tetap berfungsi.
Pada Open Guest, proyek yang dibuat melalui API dengan tingkat akses Open Guest dihitung dalam penggunaan dan anggaran Open Guest Anda, sama seperti proyek yang dimulai dari tautan tamu Anda.
Pada Open Guest, bagian Tautan tamu berisi panduan API Open Guest, dengan kode untuk server dan halaman Anda: server Anda mengambil token dari POST /auth/token dengan kunci live Anda lalu mengirim pengunjung ke proyek baru miliknya sendiri, dengan datanya sudah terisi.
Membuat anggota dengan POST /users/new memakai satu kursi, sama seperti undangan, dan memberinya peran default organisasi Anda.
Token dari POST /auth/{uid}/login membuka akun anggota tersebut, sehingga membutuhkan kunci yang boleh mengubah anggota, bukan kunci di sematan Anda. Token ini tidak diberikan untuk Admin atau Manajer, dan tidak dengan kunci sandbox.
Produk tidak pernah dihapus melalui API, hanya diarsipkan, dan harga pokok produk tidak pernah dikembalikan.
Parsel kadaster bukan bagian dari API.

Respons dan galat#

Permintaan yang berhasil menjawab dengan status 200 dan JSON (ekspor .mmp menjawab dengan XML). Permintaan yang gagal menjawab dengan status galat dan isi seperti:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

Status	`errorCode`	Apa yang perlu diperiksa
400	`invalid_body`, `invalid_uid`, `invalid_project_id`, `pagination_invalid_page_number`, `pagination_invalid_page_limit`	Sebuah nilai dalam permintaan tidak ada atau tidak diterima, seperti `page` dan `limit` pada daftar per halaman.
401	`unauthorized_action`	Permintaan dikirim dari halaman web di situs yang tidak diizinkan kunci, atau item tersebut tidak ada di akun Anda maupun akun anggota Anda.
402	`budget_limit_reached`	Open Guest: batas anggaran Anda sudah tercapai, sehingga tidak ada proyek tamu lagi pada periode ini.
403	`invalid_api_key`	Tidak ada kunci yang dikirim di header `Authorization`, atau kunci tidak dikenal, sudah dicabut, atau sudah melewati 24 jam setelah diganti.
403	`api_key_suspended`	Akses API akun Anda telah ditangguhkan. Hubungi dukungan.
403	`subscription_expired`, `invalid_subscription`	Langganan tidak aktif, atau paketnya tidak menyertakan API.
403	`insufficient_scope`	Kunci tidak memiliki akses yang dibutuhkan endpoint ini.
403	`scope_not_in_plan`	Paket Anda tidak menyertakan endpoint ini, misalnya anggota pada Open Guest.
404	`not_found`, `project_not_found`, `user_not_found`	Item tidak ada, atau orang tersebut bukan anggota organisasi Anda.
409	`enterprise_add_users_limit`	Saat membuat anggota: semua kursi sudah terpakai.
429	`too_many_requests`	Lebih dari 600 token dalam satu jam. Tunggu sebentar lalu coba lagi.
500	`server_error`	Permintaan tidak dapat diselesaikan. Periksa ID yang Anda kirim, coba lagi, dan hubungi dukungan jika masalahnya berlanjut.

Coba API dari halaman Pengembang#

Pengembang > Coba API mengirim permintaan sungguhan dengan kunci Anda dan menampilkan dengan tepat apa yang dikembalikan.

Pilih Live atau Sandbox.
Pilih sebuah Endpoint, seperti "Daftar semua proyek" atau "Ambil pengukuran".
Isi parameternya. Proyek atau produk dipilih berdasarkan nama dari yang dapat dibaca kunci; jika dibutuhkan seseorang, akun Anda sendiri sudah diisikan untuk Anda.
Tekan Kirim permintaan. Status dan responsnya muncul di bawah.

Hanya permintaan yang membaca yang ditawarkan, sehingga tidak ada yang berubah saat mencoba, dan permintaan ini tidak dihitung dalam penggunaan Anda. Jika kunci Anda tidak memiliki akses yang dibutuhkan sebuah endpoint, halaman ini memperingatkan bahwa endpoint tersebut akan menjawab 403.

Coba API dengan permintaan yang dikirim dan respons JSON-nya

Webhook#

Webhook memberi tahu server Anda saat sesuatu terjadi, seperti email notifikasi memberi tahu Anda. Webhook adalah bagian dari paket Enterprise dan Open Guest.

Menyiapkan webhook#

Di Pengembang > Webhook:

Ketik URL endpoint Anda: alamat https:// di internet. Alamat di jaringan privat ditolak, dan hal ini diperiksa lagi sebelum setiap pengiriman.
Centang Peristiwa yang Anda inginkan (lihat peristiwa). Endpoint baru dimulai dengan peristiwa yang dikirim paket Anda, dan setidaknya satu harus dicentang.
Tekan Simpan. Pertama kali, halaman ini menampilkan Secret penandatanganan Anda secara lengkap. Salin saat itu juga: setelah itu hanya beberapa karakter terakhirnya yang ditampilkan.
Tekan Kirim peristiwa uji lalu pilih sebuah peristiwa.

Uji ini mengirim contoh peristiwa tersebut, dengan nilai rekaan dan "test": true di data-nya, ke endpoint Anda yang tersimpan, meskipun peristiwa itu tidak dicentang atau endpoint sedang dinonaktifkan. Untuk menghentikan semua pengiriman, tekan Hapus: endpoint dan rahasianya dihapus.

Di bawah pengaturan, Referensi webhook berisi apa yang Anda butuhkan untuk menulis sisi penerima: header dan isi permintaan, kode yang memeriksa tanda tangan dalam Node.js, Python, dan PHP, serta contoh data untuk setiap peristiwa.

Webhook dengan endpoint dan peristiwa yang diterimanya

Apa yang diterima server Anda#

Setiap peristiwa adalah satu POST ke endpoint Anda, dengan isi JSON:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id unik untuk setiap peristiwa, created adalah waktu peristiwa terjadi dalam milidetik sejak 1 Januari 1970 (UTC), dan isi data bergantung pada peristiwanya. Permintaan ini juga memiliki header berikut:

Header	Nilai
`X-MMO-Event`	Nama peristiwa, sama dengan `type` di isi permintaan.
`X-MMO-Delivery`	`id` peristiwa.
`X-MMO-Signature`	`t=<milliseconds>,v1=<hex>`: kapan pengiriman ditandatangani, dan tanda tangannya.
`User-Agent`	`MeasureMapOnline-Webhooks/1`

Jawab dengan status 2xx dalam 8 detik, sebelum pekerjaan yang lambat. Status lain, pengalihan, atau batas waktu habis dihitung sebagai kegagalan.
Setiap peristiwa dikirim sekali dan tidak pernah dicoba ulang. Bagian ini menampilkan Pengiriman terakhir dan Kegagalan berturut-turut.
Setelah 10 kali gagal berturut-turut, endpoint dinonaktifkan dan pemilik menerima email. Perbaiki server Anda lalu tekan Simpan untuk mengaktifkannya kembali.
Sesekali sebuah peristiwa tiba dua kali atau tidak berurutan. Gunakan id untuk mengabaikan pengulangan dan created untuk mengurutkan peristiwa.

Periksa tanda tangan#

Siapa pun yang mengetahui alamat Anda dapat mengirim ke sana, jadi periksa setiap pengiriman sebelum Anda memercayainya:

Pisahkan header X-MMO-Signature di tanda koma menjadi t dan v1.
Hitung HMAC-SHA256 dari t, sebuah titik, dan isi permintaan mentah, dengan secret penandatanganan Anda sebagai kuncinya, ditulis dalam heksadesimal.
Bandingkan hasilnya dengan v1 menggunakan perbandingan waktu-konstan.
Tolak pengiriman jika t berselisih lebih dari 5 menit dari waktu saat ini. t dalam milidetik.

Gunakan isi permintaan persis seperti saat tiba: mengurai JSON lalu menuliskannya kembali akan mengubahnya, dan tanda tangannya tidak lagi cocok.

Ganti secret langsung mengganti secret dan menampilkan secret baru secara lengkap, satu kali. Perbarui server Anda segera setelah Anda merotasinya.

Peristiwa#

Peristiwa	Dikirim saat
`project.created`	Sebuah proyek dibuat di akun Anda. Di aplikasi, melalui API, atau dari sematan.
`project.deleted`	Sebuah proyek dihapus permanen (memindahkan ke tempat sampah tidak dihitung).
`project.comment.added`	Seseorang mengomentari proyek — biasanya klien Anda yang membalas.
`guest.project.created` (Tamu Terbuka)	Tamu memulai proyek dari tautan Anda atau melalui API. Hanya jika alamat email tamu diketahui.
`guest.measurement.completed` (Tamu Terbuka)	Tamu menyelesaikan pengukuran dan meninggalkan detail kontaknya.
`budget.warning_reached` (Tamu Terbuka)	Pengeluaran terukur melewati ambang peringatan Anda.
`budget.limit_reached` (Tamu Terbuka)	Pengeluaran terukur mencapai batas — proyek tamu berikutnya ditolak.
`enterprise.user.created` (Enterprise)	Sebuah kursi ditambahkan ke organisasi Anda, termasuk lewat single sign-on.