REST API
ทำจากซอฟต์แวร์ของคุณเองในสิ่งที่แอปทำกับโปรเจกต์ โฟลเดอร์ และสินค้าของคุณ องค์กร Enterprise ของคุณ และลีด Open Guest ของคุณ ลองส่งคำขอจากหน้านักพัฒนา และรับเว็บฮุกเมื่อมีเหตุการณ์เกิดขึ้น
REST API ให้ซอฟต์แวร์ของคุณเองทำสิ่งที่แอปทำได้ ได้แก่ โปรเจกต์และการวัดของโปรเจกต์ โฟลเดอร์ และแคตตาล็อกสินค้า ใน Enterprise คือองค์กรของคุณ ตามที่หน้า Enterprise จัดการ ใน Open Guest คือลิงก์ผู้เยี่ยมชม โปรเจกต์ของผู้เยี่ยมชม และคำขอใบประเมินราคา API ตอบกลับเป็น JSON เอกสารอ้างอิงฉบับเต็มที่มีทุกฟิลด์และตัวอย่างคือ เอกสาร API ส่วนหน้านี้เป็นภาพรวม
หากต้องการเปิดเอกสารจากแอป ไปที่ นักพัฒนา > REST API แล้วกด ดูเอกสาร
URL หลัก#
ทุกคำขอส่งไปที่:
https://api.measuremaponline.com/api/v2
การยืนยันตัวตน#
ส่งคีย์ API ของคุณตามที่เป็นในส่วนหัว Authorization ของทุกคำขอ
สร้างคีย์ในหน้านักพัฒนา: ดูคีย์ API
curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
-H "Authorization: YOUR_API_KEY"
แต่ละคำขอจะถูกตรวจสอบกับสิทธิ์ของคีย์ (เช่น Projects อ่าน) การสมัครสมาชิกของคุณ และสำหรับคำขอที่ส่งจากหน้าเว็บ คือการจำกัดเว็บไซต์ของคีย์ เก็บคีย์ที่เปลี่ยนข้อมูลได้ไว้บนเซิร์ฟเวอร์ของคุณ: ดู รักษาคีย์ของคุณให้ปลอดภัย
Live และ sandbox#
มี URL หลักเดียวสำหรับทั้งสองแบบ คีย์เป็นตัวกำหนด: คีย์ sandbox อ่านและเขียนโปรเจกต์ โฟลเดอร์ และสินค้าของ sandbox ซึ่งคีย์จริงไม่เคยเห็น ผู้ใช้ ที่นั่ง และทีมขององค์กรของคุณเป็นชุดเดียวกันในทั้งสองแบบ การเปลี่ยนแปลงจึงต้องใช้คีย์จริง โปรเจกต์ผู้เยี่ยมชมที่สร้างด้วยคีย์ sandbox จะไม่ถูกเรียกเก็บเงิน และโปรเจกต์ sandbox ฝังบนเว็บไซต์ของคุณไม่ได้ โทเค็นรายงานสภาพแวดล้อมที่ตนเป็นของ
API ครอบคลุมอะไรบ้าง#
| กลุ่ม | เอนด์พอยต์ | สิทธิ์คีย์ที่ต้องมี |
|---|---|---|
| โทเค็นลงชื่อเข้าใช้ | POST /auth/token, POST /auth/iframe/token |
แผนที่ที่ฝัง (ใน Open Guest คือ โปรเจกต์ผู้เยี่ยมชม) |
| บัญชี | แผน ที่นั่ง และคีย์ของบัญชีด้วย GET /account คำขอ API ใน 30 วันที่ผ่านมา และใน Open Guest คือโปรเจกต์ผู้เยี่ยมชมและงบประมาณของช่วงเวลานั้นด้วย GET /usage |
บัญชี: อ่าน |
| โปรเจกต์และโฟลเดอร์ | โปรเจกต์ของคุณ (GET /projects, ถังขยะ ด้วย trashed=true) และโฟลเดอร์ (GET /folders) ดึงโปรเจกต์ การวัด (/projects/{pid}/data) ความคิดเห็น หรือไฟล์ .mmp (/projects/{pid}/mmp) สร้าง อัปเดต และย้ายโปรเจกต์และโฟลเดอร์ รวมโปรเจกต์ (POST /projects/merge) ลบไปที่ ถังขยะ และกู้คืน (POST /projects/{pid}/restore) เวอร์ชันของโปรเจกต์ (/projects/{pid}/versions) ลบและกู้คืนความคิดเห็น แชร์โปรเจกต์หรือโฟลเดอร์ทางอีเมล (PUT /projects/{pid}/members) |
โปรเจกต์: อ่าน เพื่ออ่าน อ่านและเปลี่ยนแปลง เพื่อเปลี่ยน |
| ไฟล์และสำเนาของโปรเจกต์ | ส่งออกโปรเจกต์ในรูปแบบของแอป (POST /projects/{pid}/export) หรือดึงรายงาน PDF (GET /projects/{pid}/pdf) ทั้งสองแบบเป็นลิงก์ที่ใช้ได้ 24 ชั่วโมง คัดลอกโปรเจกต์ หรือทำเป็นแม่แบบ (POST /projects/{pid}/copy) |
โปรเจกต์: อ่าน, อ่านและเปลี่ยนแปลง เพื่อคัดลอก ราคาในรายงานต้องมี สินค้า: อ่าน |
| ประมาณการ | ประมาณการของโปรเจกต์ทีละบรรทัด (GET /projects/{pid}/estimate) |
โปรเจกต์ และ สินค้า: อ่าน |
| สินค้า | GET /products, GET /products/{id} สร้าง อัปเดต และเก็บถาวรด้วย DELETE /products/{id} |
สินค้า: อ่าน หรือ อ่านและเปลี่ยนแปลง |
| โปรไฟล์ | โปรไฟล์และการตั้งค่าอีเมล (/account/profile) สำหรับลูกค้าของพาร์ทเนอร์ ใครจ่ายแผน และคำเชิญ (/account/partner) |
บัญชี: อ่าน, อ่านและเปลี่ยนแปลง |
| การนำเข้า | นำเข้าไฟล์ลงในโปรเจกต์ (POST /projects/{pid}/imports) เหมือนการนำเข้าในแอป: เพิ่มหรือแทนที่ แล้วติดตามความคืบหน้า |
โปรเจกต์: อ่านและเปลี่ยนแปลง |
| คีย์และ webhook | คีย์ API ของบัญชี (/keys: แสดงรายการ เพิกถอน เว็บไซต์ ไม่ส่งคีย์เต็ม และไม่เกินสิทธิ์ของคีย์ที่เรียก) และ webhook (/webhook) |
นักพัฒนา: อ่าน, อ่านและเปลี่ยนแปลง |
| พาร์ทเนอร์ | ลูกค้าและคำเชิญ แผน ที่นั่ง งบประมาณ การชำระเงิน และใบแจ้งหนี้ของลูกค้า (/partner) |
ลูกค้า: อ่าน, อ่านและเปลี่ยนแปลง |
| Enterprise: ผู้ใช้ คำเชิญ ที่นั่ง ทีม | ผู้ใช้ (/enterprise/users): แสดงรายการ เปลี่ยนบทบาทหรือรายละเอียด ปิดและเปิดใช้งาน ออกจากระบบทุกที่ นำออกจากองค์กร ลบ ตั้งทีม โอนโปรเจกต์ คำเชิญ (/enterprise/invitations): เชิญ แสดงรายการ ส่งอีกครั้ง ถอนคืน ที่นั่ง (GET /enterprise/seats) ทีม (/enterprise/teams) โปรเจกต์ทั้งหมดขององค์กร (GET /enterprise/projects) และโปรเจกต์ในทีม |
ผู้ใช้: อ่าน หรือ อ่านและเปลี่ยนแปลง โปรเจกต์ต้องใช้ โปรเจกต์ |
| Enterprise: องค์กร | โปรไฟล์และนโยบาย (/enterprise/organization) การลงชื่อเข้าใช้แบบครั้งเดียว (GET /enterprise/sso) บันทึกกิจกรรม (GET /enterprise/activity) และการซื้อหรือคืนที่นั่ง (PUT /enterprise/seats) |
องค์กร: อ่าน หรือ อ่านและเปลี่ยนแปลง |
| Open Guest | ลิงก์ผู้เยี่ยมชมของคุณ (/open-guest/link: ดึง สร้างหรือแทนที่ หยุดชั่วคราว เลือกโฟลเดอร์) โปรเจกต์ผู้เยี่ยมชม (/open-guest/projects: แสดงรายการ เริ่มโปรเจกต์ให้ผู้เยี่ยมชม ดึงโปรเจกต์) คำขอใบประเมินราคาพร้อมใบประเมิน (/open-guest/requests) การใช้งานในรอบนี้ (GET /open-guest/usage) และงบประมาณ (PUT /open-guest/budget) |
ผู้เยี่ยมชม: อ่าน; อ่านและเปลี่ยนแปลง เพื่อเปลี่ยนแปลง |
ข้อควรรู้บางอย่าง:
- คีย์เข้าถึงโปรเจกต์ของบัญชีตัวเอง และใน Enterprise รวมถึงโปรเจกต์ของผู้ใช้ในองค์กร
- การลบโปรเจกต์จะย้ายไปที่ ถังขยะ เหมือนในแอป
และมีเพียงผู้สร้างเท่านั้นที่ทำได้ หากต้องการลบถาวร ให้ลบจาก ถังขยะ ด้วย
forever=trueการลบโฟลเดอร์จะย้ายโปรเจกต์ในโฟลเดอร์ไปที่ ถังขยะ - ในการวัดของโปรเจกต์ รูปทรงจะแสดงรายการสินค้าใน
productIdsตามลำดับproductIdคืออันแรกของรายการนั้น /projects/{pid}/mmpให้ไฟล์.mmpเดียวกับที่แอปส่งออก สคีมาของไฟล์ เผยแพร่ที่ github.com/blueblinkone/mmp-validator องค์ประกอบใหม่จะถูกเพิ่มเป็นแบบไม่บังคับเท่านั้น ดังนั้นโปรแกรมอ่านที่เขียน ไว้สำหรับไฟล์รุ่นเก่ายังคงใช้ได้- ใน Open Guest โปรเจกต์ผู้เยี่ยมชมที่เริ่มผ่าน API
(
POST /open-guest/projects) จะนับรวมในการใช้งานและงบประมาณ Open Guest ของคุณ เหมือนโปรเจกต์ที่เริ่มจากลิงก์ผู้เยี่ยมชมของคุณ - ใน Open Guest ส่วน ลิงก์ผู้เยี่ยมชม มีคู่มือ
Open Guest API พร้อมโค้ดสำหรับเซิร์ฟเวอร์และหน้าเว็บของคุณ:
เซิร์ฟเวอร์ของคุณรับโทเค็นจาก
POST /auth/tokenด้วยคีย์จริงของคุณ และ ส่งผู้เข้าชมไปยังโปรเจกต์ใหม่ของตนเองที่กรอกรายละเอียดไว้แล้ว - ผู้คนเข้าร่วมองค์กรของคุณได้ทางคำเชิญเท่านั้น (
POST /enterprise/invitations) เหมือนในหน้า Enterprise ผู้ที่ยังไม่มีบัญชีจะได้บัญชีและเลือกรหัสผ่านเอง API ไม่เคยสร้างบัญชีหรือตั้งรหัสผ่าน - การนำผู้ใช้ออก (
POST /enterprise/users/{uid}/remove) ทำให้บัญชียังอยู่ ส่วนการลบผู้ใช้ (DELETE /enterprise/users/{uid}) จะลบบัญชี ไม่ว่าแบบใด งานที่ผู้ใช้ทำไว้จะอยู่กับองค์กร ในโฟลเดอร์ใหม่ที่ใช้ชื่อของผู้ใช้ ซึ่งผู้ดูแลของคุณใช้ร่วมกัน - เมื่อผู้เยี่ยมชมขอใบประเมินราคาของคุณ
GET /open-guest/requests/{pid}จะตอบว่าเขาคือใคร เขาเขียนอะไร เขาวัดอะไร และถ้ามี สินค้า: อ่าน ก็จะได้ใบประเมินเอง - ใน Open Guest โทเค็นใช้เริ่มโปรเจกต์ผู้เยี่ยมชมให้ผู้เข้าชมของคุณ
POST /auth/iframe/tokenซึ่งลงชื่อเข้าใช้ให้ผู้เข้าชมในแผนที่ฝัง ใช้ได้กับคีย์ Enterprise - สินค้าไม่เคยถูกลบผ่าน API มีเพียงการเก็บถาวร และราคาต้นทุนของสินค้า จะไม่ถูกส่งคืนเลย
- แปลงที่ดินในทะเบียนที่ดิน (cadastral parcels) ไม่รวมอยู่ใน API
การตอบกลับและข้อผิดพลาด#
คำขอที่สำเร็จตอบด้วยสถานะ 200 และ JSON (การส่งออก .mmp ตอบด้วย XML)
คำขอที่ล้มเหลวตอบด้วยสถานะข้อผิดพลาดและเนื้อหาเช่น:
{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}
| สถานะ | errorCode |
สิ่งที่ต้องตรวจสอบ |
|---|---|---|
| 400 | invalid_body, invalid_uid, invalid_project_id, pagination_invalid_page_number, pagination_invalid_page_limit |
ค่าในคำขอขาดหายไปหรือไม่เป็นที่ยอมรับ เช่น page และ limit ของรายการแบบแบ่งหน้า |
| 401 | unauthorized_action |
คำขอถูกส่งจากหน้าเว็บบนเว็บไซต์ที่คีย์ไม่อนุญาต หรือรายการนั้นไม่ได้อยู่ในบัญชีของคุณหรือของสมาชิกของคุณ |
| 402 | budget_limit_reached |
Open Guest: ถึงขีดจำกัดงบประมาณของคุณแล้ว จึงไม่มีโปรเจกต์ผู้เยี่ยมชมเพิ่มในช่วงเวลานี้ |
| 403 | invalid_api_key |
ไม่ได้ส่งคีย์ในส่วนหัว Authorization หรือคีย์ไม่รู้จัก ถูกเพิกถอน หรือเกิน 24 ชั่วโมงหลังถูกเปลี่ยน |
| 403 | api_key_suspended |
การเข้าถึง API ในบัญชีของคุณถูกระงับ ติดต่อฝ่ายสนับสนุน |
| 403 | subscription_expired, invalid_subscription |
การสมัครสมาชิกไม่ได้ใช้งานอยู่ หรือแผนของคุณไม่มี API |
| 403 | insufficient_scope |
คีย์ไม่มีสิทธิ์ที่เอนด์พอยต์นี้ต้องการ |
| 403 | scope_not_in_plan |
แผนของคุณไม่รวมเอ็นด์พอยต์นี้ เช่น ส่วน Enterprise ใน Open Guest |
| 403 | embed_needs_enterprise |
แผนที่ฝังเป็นส่วนหนึ่งของแผน Enterprise คีย์ Open Guest เปิดได้เฉพาะโปรเจกต์ผู้เยี่ยมชมของตนเอง |
| 404 | not_found, project_not_found, user_not_found |
ไม่มีรายการนี้ หรือบุคคลนี้ไม่ใช่ผู้ใช้ขององค์กรของคุณ |
| 409 | enterprise_add_users_limit |
เมื่อเชิญบุคคล: ที่นั่งทั้งหมดถูกใช้แล้ว และที่นั่งอัตโนมัติปิดอยู่ |
| 409 | project_not_in_trash |
มีการขอกู้คืนหรือลบถาวรโปรเจกต์ที่ไม่ได้อยู่ใน ถังขยะ |
| 429 | too_many_requests |
เกิน 600 โทเค็นในหนึ่งชั่วโมง รอสักครู่แล้วลองอีกครั้ง |
| 500 | server_error |
ทำคำขอไม่สำเร็จ ตรวจสอบรหัสที่คุณส่ง ลองอีกครั้ง และติดต่อฝ่ายสนับสนุนหากยังเกิดขึ้น |
ลอง API จากหน้านักพัฒนา#
นักพัฒนา > ลองใช้ API ส่งคำขอจริง ด้วยคีย์ของคุณและแสดงสิ่งที่ส่งกลับมาอย่างตรงไปตรงมา
- เลือก ใช้งานจริง หรือ Sandbox
- เลือก ปลายทาง เช่น "แสดงรายการโปรเจกต์ของคุณ", "ดึงการวัด" หรือ "ดึงบัญชี" รายการ แสดงเอนด์พอยต์ที่แผนของคุณรวมอยู่
- กรอกพารามิเตอร์ โปรเจกต์หรือสินค้าเลือกตามชื่อจากที่คีย์อ่านได้ ส่วนที่ต้อง ระบุบุคคล ระบบจะกรอกบัญชีของคุณเองให้
- กด ส่งคำขอ สถานะและการตอบกลับจะปรากฏ ด้านล่าง
มีเฉพาะคำขอที่อ่านเท่านั้นที่เสนอให้ จึงไม่มีอะไรเปลี่ยนจากการลอง และคำขอเหล่านี้ ไม่นับรวมในการใช้งานของคุณ หากคีย์ของคุณไม่มีสิทธิ์ที่เอนด์พอยต์ต้องการ หน้านี้จะเตือนว่าจะตอบ 403
เว็บฮุก#
เว็บฮุกแจ้งเซิร์ฟเวอร์ของคุณเมื่อมีเหตุการณ์เกิดขึ้น เช่นเดียวกับที่อีเมลแจ้งเตือน แจ้งคุณ เว็บฮุกเป็นส่วนหนึ่งของแผน Enterprise และ Open Guest
ตั้งค่าเว็บฮุก#
ใน นักพัฒนา > Webhooks:
- พิมพ์ URL ปลายทาง ของคุณ: ที่อยู่
https://บนอินเทอร์เน็ต ที่อยู่บนเครือข่ายส่วนตัวจะถูกปฏิเสธ และมีการตรวจสอบอีกครั้งก่อนการส่งทุกครั้ง - ติ๊ก เหตุการณ์ ที่คุณต้องการ (ดูเหตุการณ์) เอนด์พอยต์ใหม่เริ่มด้วยเหตุการณ์ที่แผนของคุณส่ง และต้องติ๊กอย่างน้อยหนึ่งรายการ
- กด บันทึก ในครั้งแรก หน้าจะแสดง Secret สำหรับลงนาม ของคุณเต็ม ๆ ให้คัดลอกในตอนนั้น: หลังจากนั้นจะ แสดงเฉพาะอักขระตัวท้าย ๆ
- กด ส่งเหตุการณ์ทดสอบ และเลือกเหตุการณ์
การทดสอบส่งตัวอย่างของเหตุการณ์นั้น ด้วยค่าที่สมมติขึ้นและ "test": true
ใน data ไปยังเอนด์พอยต์ที่บันทึกไว้ของคุณ แม้เหตุการณ์นั้นไม่ได้ติ๊กไว้หรือ
เอนด์พอยต์ปิดอยู่ หากต้องการหยุดการส่งทั้งหมด กด
เอาออก: เอนด์พอยต์และ secret ของมัน
จะถูกลบ
ใต้การตั้งค่า เอกสารอ้างอิง Webhook มีสิ่งที่คุณต้องใช้เขียนฝั่งที่รับ: ส่วนหัวและเนื้อหา โค้ดที่ตรวจสอบลายเซ็นใน Node.js, Python และ PHP และข้อมูลตัวอย่างสำหรับทุกเหตุการณ์
สิ่งที่เซิร์ฟเวอร์ของคุณได้รับ#
แต่ละเหตุการณ์คือ POST หนึ่งครั้งไปยังเอนด์พอยต์ของคุณ พร้อมเนื้อหา JSON:
{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}
id ไม่ซ้ำกันสำหรับแต่ละเหตุการณ์ created คือเวลาที่เกิดขึ้นเป็นมิลลิวินาที
นับจาก 1 มกราคม 1970 (UTC) และสิ่งที่ data เก็บขึ้นอยู่กับเหตุการณ์ คำขอ
ยังมีส่วนหัวเหล่านี้:
| ส่วนหัว | ค่า |
|---|---|
X-MMO-Event |
ชื่อเหตุการณ์ เหมือน type ในเนื้อหา |
X-MMO-Delivery |
id ของเหตุการณ์ |
X-MMO-Signature |
t=<milliseconds>,v1=<hex>: เวลาที่ลงนามการส่ง และลายเซ็นของมัน |
User-Agent |
MeasureMapOnline-Webhooks/1 |
- ตอบด้วยสถานะ 2xx ภายใน 8 วินาที ก่อนทำงานที่ช้า สถานะอื่น การเปลี่ยนเส้นทาง หรือการหมดเวลานับว่าล้มเหลว
- แต่ละเหตุการณ์ถูกส่งครั้งเดียวและไม่เคยลองส่งใหม่ ส่วนนี้แสดง การส่งล่าสุด และ ความล้มเหลวติดต่อกัน
- หลังล้มเหลวติดต่อกัน 10 ครั้ง เอนด์พอยต์จะถูกปิดและเจ้าของจะได้รับอีเมล แก้ไขเซิร์ฟเวอร์ของคุณแล้วกด บันทึก เพื่อเปิดอีกครั้ง
- บางครั้งเหตุการณ์มาถึงสองครั้งหรือไม่เรียงลำดับ ใช้
idเพื่อข้ามรายการซ้ำ และcreatedเพื่อเรียงลำดับเหตุการณ์
ตรวจสอบลายเซ็น#
ใครก็ตามที่รู้ที่อยู่ของคุณโพสต์มาได้ ดังนั้นตรวจสอบทุกการส่งก่อนเชื่อถือ:
- แยกส่วนหัว
X-MMO-Signatureที่เครื่องหมายจุลภาคเป็นtและv1 - คำนวณ HMAC-SHA256 ของ
tเครื่องหมายจุด และเนื้อหาคำขอดิบ โดยใช้ signing secret ของคุณเป็นคีย์ เขียนเป็นเลขฐานสิบหก - เปรียบเทียบผลลัพธ์กับ
v1ด้วยการเปรียบเทียบแบบใช้เวลาคงที่ - ปฏิเสธการส่งหาก
tห่างจากเวลาปัจจุบันเกิน 5 นาทีtเป็นมิลลิวินาที
ใช้เนื้อหาตามที่มาถึงทุกประการ: การแยกวิเคราะห์ JSON แล้วเขียนออกมาใหม่จะ เปลี่ยนเนื้อหา และลายเซ็นจะไม่ตรงอีกต่อไป
เปลี่ยน secret เปลี่ยน secret ทันทีและแสดงอันใหม่ เต็ม ๆ เพียงครั้งเดียว อัปเดตเซิร์ฟเวอร์ของคุณทันทีที่หมุนเวียน
เหตุการณ์#
| เหตุการณ์ | ส่งเมื่อ |
|---|---|
project.created |
มีการสร้างโปรเจกต์ในบัญชีของคุณ ในแอป ผ่าน API หรือจากแผนที่ฝัง |
project.deleted |
โปรเจกต์ถูกลบถาวร (การย้ายไปที่ถังขยะไม่นับ) |
project.comment.added |
มีคนแสดงความคิดเห็นในโปรเจกต์ ซึ่งมักเป็นลูกค้าของคุณที่ตอบกลับ |
guest.project.created (Open Guest) |
ผู้เยี่ยมชมเริ่มโปรเจกต์จากลิงก์ของคุณหรือผ่าน API เฉพาะเมื่อทราบที่อยู่อีเมลของผู้เยี่ยมชม |
guest.measurement.completed (Open Guest) |
ผู้เยี่ยมชมวัดเสร็จและทิ้งข้อมูลติดต่อไว้ |
budget.warning_reached (Open Guest) |
ค่าใช้จ่ายตามการใช้งานเกินเกณฑ์แจ้งเตือนของคุณ |
budget.limit_reached (Open Guest) |
ค่าใช้จ่ายตามการใช้งานถึงขีดจำกัดของคุณ โปรเจกต์ผู้เยี่ยมชมต่อจากนี้จะถูกปฏิเสธ |
enterprise.user.created (Enterprise) |
มีการเพิ่มที่นั่งในองค์กรของคุณ รวมถึงผ่านการลงชื่อเข้าใช้ครั้งเดียว |
ยังต้องการความช่วยเหลือ?
เขียนถึงทีมสนับสนุนของเราและบอกว่าคุณพยายามทำอะไรอยู่ ภาพหน้าจอช่วยได้มาก