REST API · Trợ giúp Measure Map Online

Làm từ phần mềm riêng của bạn những gì ứng dụng làm với dự án, thư mục và sản phẩm của bạn, tổ chức Enterprise và khách hàng tiềm năng Open Guest của bạn; thử các yêu cầu từ trang Nhà phát triển, và nhận webhook khi có sự kiện xảy ra.

REST API cho phép phần mềm riêng của bạn làm những gì ứng dụng làm: dự án và các phép đo của chúng, thư mục và danh mục sản phẩm; ở Enterprise, tổ chức của bạn, như trang Enterprise vận hành; ở Open Guest, liên kết khách, dự án khách và các yêu cầu báo giá. API trả lời bằng JSON. Tài liệu tham chiếu đầy đủ, với mọi trường và ví dụ, là tài liệu API; trang này là phần tổng quan.

Để mở tài liệu từ ứng dụng, vào Nhà phát triển > REST API và nhấn Xem tài liệu.

URL gốc#

Mọi yêu cầu đều gửi tới:

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

Xác thực#

Gửi khóa API của bạn, nguyên như nó có, trong header Authorization của mọi yêu cầu. Hãy tạo khóa trên trang Nhà phát triển: xem khóa API.

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

Mỗi yêu cầu được kiểm tra theo quyền truy cập của khóa (ví dụ Dự án Đọc), gói đăng ký của bạn và, với yêu cầu gửi từ một trang web, hạn chế trang web của khóa. Hãy giữ các khóa có thể thay đổi dữ liệu trên máy chủ của bạn: xem giữ khóa của bạn an toàn.

Live và sandbox#

Cả hai dùng chung một URL gốc. Khóa quyết định: một khóa sandbox đọc và ghi các dự án, thư mục và sản phẩm sandbox, mà khóa live không bao giờ thấy. Người dùng, chỗ và nhóm của tổ chức bạn giống nhau ở cả hai, nên thay đổi chúng cần khóa live. Các dự án khách tạo bằng khóa sandbox không bao giờ bị tính phí, và dự án sandbox không thể nhúng vào trang web của bạn. Token cho biết môi trường mà chúng thuộc về.

API bao gồm những gì#

Nhóm	Endpoint	Quyền truy cập khóa cần có
Token đăng nhập	`POST /auth/token`, `POST /auth/iframe/token`	Bản đồ nhúng (với Open Guest, Dự án của khách)
Tài khoản	Gói, số chỗ và khóa của tài khoản với `GET /account`; các yêu cầu API trong 30 ngày qua và, với Open Guest, các dự án khách và ngân sách của kỳ với `GET /usage`	Tài khoản: Đọc
Dự án và thư mục	Dự án của bạn (`GET /projects`, Thùng rác với `trashed=true`) và thư mục (`GET /folders`); lấy một dự án, các phép đo (`/projects/{pid}/data`), bình luận hoặc tệp `.mmp` của nó (`/projects/{pid}/mmp`); tạo, cập nhật và di chuyển dự án và thư mục; gộp dự án (`POST /projects/merge`); xóa vào Thùng rác và khôi phục (`POST /projects/{pid}/restore`); các phiên bản của một dự án (`/projects/{pid}/versions`); gỡ và khôi phục bình luận; chia sẻ dự án hoặc thư mục qua email (`PUT /projects/{pid}/members`)	Dự án: Đọc để đọc, Đọc và thay đổi để thay đổi
Tệp dự án và bản sao	Xuất một dự án theo các định dạng của ứng dụng (`POST /projects/{pid}/export`) hoặc lấy báo cáo PDF của nó (`GET /projects/{pid}/pdf`), cả hai đều là liên kết có hiệu lực trong 24 giờ; sao chép một dự án, hoặc tạo mẫu từ nó (`POST /projects/{pid}/copy`)	Dự án: Đọc; Đọc và thay đổi để sao chép. Giá trong báo cáo cần Sản phẩm: Đọc
Dự toán	Dự toán của một dự án, từng dòng một (`GET /projects/{pid}/estimate`)	Dự án và Sản phẩm: Đọc
Sản phẩm	`GET /products`, `GET /products/{id}`, tạo, cập nhật, và lưu trữ bằng `DELETE /products/{id}`	Sản phẩm: Đọc hoặc Đọc và thay đổi
Hồ sơ	Hồ sơ và cài đặt email (`/account/profile`); với khách hàng của đối tác: ai trả tiền gói của họ và lời mời (`/account/partner`)	Tài khoản: Đọc, Đọc và thay đổi
Nhập	Nhập tệp vào dự án (`POST /projects/{pid}/imports`), như tính năng Nhập của ứng dụng: thêm hoặc thay thế, rồi theo dõi tiến trình	Dự án: Đọc và thay đổi
Khóa và webhook	Các khóa API của tài khoản (`/keys`: liệt kê, thu hồi, trang web; không bao giờ trả đầy đủ, không vượt quá quyền của khóa đang gọi) và webhook (`/webhook`)	Nhà phát triển: Đọc, Đọc và thay đổi
Đối tác	Khách hàng và lời mời, gói, ghế, ngân sách, thanh toán và hóa đơn của khách hàng (`/partner`)	Khách hàng: Đọc, Đọc và thay đổi
Enterprise: người dùng, lời mời, chỗ, nhóm	Người dùng (`/enterprise/users`): liệt kê, đổi vai trò hoặc thông tin, vô hiệu hóa và kích hoạt, đăng xuất ở mọi nơi, gỡ khỏi tổ chức, xóa, đặt nhóm của họ, bàn giao dự án của họ. Lời mời (`/enterprise/invitations`): mời, liệt kê, gửi lại, thu hồi. Chỗ (`GET /enterprise/seats`). Nhóm (`/enterprise/teams`). Mọi dự án của tổ chức (`GET /enterprise/projects`) và dự án trong nhóm	Người dùng: Đọc hoặc Đọc và thay đổi; các dự án cần Dự án
Enterprise: tổ chức	Hồ sơ và chính sách của tổ chức (`/enterprise/organization`), đăng nhập một lần (`GET /enterprise/sso`), nhật ký hoạt động (`GET /enterprise/activity`), và mua hoặc trả lại chỗ (`PUT /enterprise/seats`)	Tổ chức: Đọc hoặc Đọc và thay đổi
Open Guest	Liên kết khách của bạn (`/open-guest/link`: lấy, tạo hoặc thay thế, tạm dừng, chọn thư mục của nó); dự án khách (`/open-guest/projects`: liệt kê, bắt đầu một dự án cho khách truy cập, lấy một dự án); yêu cầu báo giá kèm báo giá (`/open-guest/requests`); mức sử dụng của kỳ này (`GET /open-guest/usage`) và ngân sách (`PUT /open-guest/budget`)	Khách: Đọc; Đọc và thay đổi để thay đổi

Vài điều cần biết:

Một khóa truy cập được các dự án của chính tài khoản đó và, ở Enterprise, của người dùng trong tổ chức.
Xóa một dự án sẽ đưa nó vào Thùng rác, như trong ứng dụng, và chỉ người tạo mới làm được; xóa vĩnh viễn từ Thùng rác bằng forever=true. Xóa một thư mục sẽ đưa các dự án của nó vào Thùng rác.
Trong các số đo của dự án, một hình liệt kê các sản phẩm của nó trong productIds, theo thứ tự; productId là sản phẩm đầu tiên trong số đó.
/projects/{pid}/mmp trả về đúng tệp .mmp mà ứng dụng xuất ra. Lược đồ của nó được công bố tại github.com/blueblinkone/mmp-validator. Các phần tử mới luôn chỉ được thêm vào dưới dạng tùy chọn, nên trình đọc viết cho tệp cũ hơn vẫn hoạt động.
Ở Open Guest, một dự án khách được bắt đầu qua API (POST /open-guest/projects) được tính vào mức sử dụng và ngân sách Open Guest của bạn, giống như dự án bắt đầu từ liên kết khách của bạn.
Với Open Guest, phần Liên kết khách có hướng dẫn Open Guest API, kèm mã cho máy chủ và trang của bạn: máy chủ lấy token từ POST /auth/token bằng khóa live và đưa khách truy cập tới một dự án mới của riêng họ, với thông tin của họ đã được điền sẵn.
Mọi người chỉ tham gia tổ chức của bạn qua lời mời (POST /enterprise/invitations), như trên trang Enterprise: ai chưa có tài khoản sẽ được tạo một tài khoản và tự chọn mật khẩu. API không bao giờ tạo tài khoản hay đặt mật khẩu.
Gỡ một người dùng (POST /enterprise/users/{uid}/remove) để họ giữ tài khoản; xóa một người dùng (DELETE /enterprise/users/{uid}) sẽ xóa tài khoản. Trong cả hai trường hợp, công việc họ đã làm vẫn ở lại tổ chức, trong một thư mục mới mang tên họ mà các quản trị viên của bạn chia sẻ.
Khi một khách yêu cầu báo giá của bạn, GET /open-guest/requests/{pid} trả lời họ là ai, họ đã viết gì, họ đã đo gì và, với Sản phẩm: Đọc, chính báo giá đó.
Với Open Guest, token bắt đầu các dự án khách cho khách truy cập của bạn. POST /auth/iframe/token, dùng để đăng nhập khách truy cập vào bản đồ nhúng, dành cho khóa Enterprise.
Sản phẩm không bao giờ bị xóa qua API, chỉ được lưu trữ, và giá vốn của sản phẩm không bao giờ được trả về.
Thửa đất địa chính không thuộc API.

Phản hồi và lỗi#

Yêu cầu thành công trả về mã trạng thái 200 và JSON (xuất .mmp trả về XML). Yêu cầu thất bại trả về mã lỗi và phần nội dung như sau:

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

Trạng thái	`errorCode`	Cần kiểm tra gì
400	`invalid_body`, `invalid_uid`, `invalid_project_id`, `pagination_invalid_page_number`, `pagination_invalid_page_limit`	Một giá trị trong yêu cầu bị thiếu hoặc không được chấp nhận, chẳng hạn `page` và `limit` của danh sách chia trang.
401	`unauthorized_action`	Yêu cầu được gửi từ một trang web không được khóa cho phép, hoặc mục đó không thuộc tài khoản của bạn hay của các thành viên.
402	`budget_limit_reached`	Open Guest: đã đạt giới hạn ngân sách của bạn, nên không còn dự án khách nào trong kỳ này.
403	`invalid_api_key`	Không có khóa nào trong header `Authorization`, hoặc khóa không xác định, đã bị thu hồi, hoặc đã quá 24 giờ sau khi bị thay.
403	`api_key_suspended`	Quyền truy cập API trên tài khoản của bạn đã bị tạm ngưng. Hãy liên hệ hỗ trợ.
403	`subscription_expired`, `invalid_subscription`	Gói đăng ký không còn hiệu lực, hoặc gói của bạn không có API.
403	`insufficient_scope`	Khóa không có quyền truy cập mà endpoint này cần.
403	`scope_not_in_plan`	Gói của bạn không bao gồm endpoint này, ví dụ phần Enterprise ở Open Guest.
403	`embed_needs_enterprise`	Bản đồ nhúng thuộc gói Enterprise. Khóa Open Guest chỉ mở các dự án khách của chính nó.
404	`not_found`, `project_not_found`, `user_not_found`	Mục không tồn tại, hoặc người đó không phải người dùng của tổ chức bạn.
409	`enterprise_add_users_limit`	Khi mời ai đó: mọi chỗ đã được dùng và chỗ tự động đang tắt.
409	`project_not_in_trash`	Đã yêu cầu khôi phục hoặc xóa vĩnh viễn một dự án không có trong Thùng rác.
429	`too_many_requests`	Hơn 600 token trong một giờ. Hãy đợi một lát rồi thử lại.
500	`server_error`	Không thể hoàn thành yêu cầu. Hãy kiểm tra các ID bạn đã gửi, thử lại, và liên hệ hỗ trợ nếu lỗi vẫn tiếp diễn.

Thử API từ trang Nhà phát triển#

Nhà phát triển > Thử API gửi các yêu cầu thật bằng khóa của bạn và hiển thị chính xác những gì trả về.

Chọn Thực tế hoặc Sandbox.
Chọn một Điểm cuối, chẳng hạn "Liệt kê dự án của bạn", "Lấy số đo" hoặc "Lấy tài khoản". Danh sách đưa ra các endpoint mà gói của bạn bao gồm.
Điền các tham số của nó. Dự án hoặc sản phẩm được chọn theo tên từ những mục mà khóa đọc được; khi cần một người, tài khoản của chính bạn được điền sẵn cho bạn.
Nhấn Gửi yêu cầu. Trạng thái và phản hồi xuất hiện bên dưới.

Chỉ những yêu cầu đọc mới được đưa ra, nên thử không thay đổi gì, và các yêu cầu này không được tính vào mức sử dụng của bạn. Nếu khóa của bạn không có quyền truy cập mà một endpoint cần, trang sẽ cảnh báo rằng nó sẽ trả về 403.

Thử API với một yêu cầu đã gửi và phản hồi JSON của nó

Webhook#

Webhook báo cho máy chủ của bạn khi có điều gì xảy ra, giống như các email thông báo báo cho bạn. Webhook thuộc các gói Enterprise và Open Guest.

Thiết lập webhook#

Trong Nhà phát triển > Webhook:

Nhập URL điểm cuối của bạn: một địa chỉ https:// trên internet. Địa chỉ trong mạng riêng bị từ chối, và việc này được kiểm tra lại trước mỗi lần gửi.
Đánh dấu các Sự kiện bạn muốn (xem sự kiện). Một endpoint mới bắt đầu với các sự kiện mà gói của bạn gửi, và phải đánh dấu ít nhất một sự kiện.
Nhấn Lưu. Lần đầu tiên, trang hiển thị đầy đủ Khóa bí mật ký của bạn. Hãy sao chép ngay lúc đó: sau này chỉ hiển thị vài ký tự cuối.
Nhấn Gửi sự kiện thử nghiệm và chọn một sự kiện.

Bài kiểm tra gửi một mẫu của sự kiện đó, với giá trị giả và "test": true trong data, tới endpoint đã lưu của bạn, ngay cả khi sự kiện không được đánh dấu hoặc endpoint đang tắt. Để dừng mọi lần gửi, nhấn Gỡ bỏ: endpoint và secret của nó bị xóa.

Bên dưới phần cài đặt, Tài liệu tham khảo webhook có những gì bạn cần để viết phía nhận: các header và phần thân, mã kiểm tra chữ ký bằng Node.js, Python và PHP, và dữ liệu mẫu cho mọi sự kiện.

Webhook với một endpoint và các sự kiện nó nhận

Máy chủ của bạn nhận được gì#

Mỗi sự kiện là một POST tới endpoint của bạn, với phần thân JSON:

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

id là duy nhất cho mỗi sự kiện, created là thời điểm sự kiện xảy ra tính bằng mili giây kể từ 1 tháng 1 năm 1970 (UTC), và nội dung của data phụ thuộc vào sự kiện. Yêu cầu cũng có các header sau:

Header	Giá trị
`X-MMO-Event`	Tên sự kiện, giống `type` trong phần thân.
`X-MMO-Delivery`	`id` của sự kiện.
`X-MMO-Signature`	`t=<milliseconds>,v1=<hex>`: thời điểm lần gửi được ký, và chữ ký của nó.
`User-Agent`	`MeasureMapOnline-Webhooks/1`

Hãy trả lời bằng mã trạng thái 2xx trong vòng 8 giây, trước mọi công việc chậm. Mọi mã trạng thái khác, một chuyển hướng hoặc hết thời gian chờ đều được tính là thất bại.
Mỗi sự kiện chỉ được gửi một lần và không bao giờ được thử lại. Phần này hiển thị Lần gửi gần nhất và Số lần thất bại liên tiếp.
Sau 10 lần thất bại liên tiếp, endpoint bị tắt và chủ sở hữu nhận được email. Hãy sửa máy chủ của bạn và nhấn Lưu để bật lại.
Đôi khi một sự kiện đến hai lần hoặc không đúng thứ tự. Hãy dùng id để bỏ qua các lần lặp và created để sắp xếp thứ tự sự kiện.

Kiểm tra chữ ký#

Bất kỳ ai biết địa chỉ của bạn đều có thể gửi tới đó, nên hãy kiểm tra mọi lần gửi trước khi tin nó:

Tách header X-MMO-Signature tại dấu phẩy thành t và v1.
Tính HMAC-SHA256 của t, một dấu chấm và phần thân yêu cầu gốc, với signing secret của bạn làm khóa, viết dưới dạng thập lục phân.
So sánh kết quả với v1 bằng phép so sánh thời gian không đổi.
Từ chối lần gửi nếu t cách thời gian hiện tại hơn 5 phút. t tính bằng mili giây.

Hãy dùng phần thân đúng như khi nó đến: phân tích JSON rồi ghi lại sẽ làm nó thay đổi, và chữ ký không còn khớp.

Xoay vòng khóa bí mật thay secret ngay lập tức và hiển thị secret mới đầy đủ, một lần. Hãy cập nhật máy chủ của bạn ngay khi bạn xoay vòng.

Sự kiện#

Sự kiện	Được gửi khi
`project.created`	Một dự án được tạo trên tài khoản của bạn. Trong ứng dụng, qua API hoặc từ một bản nhúng.
`project.deleted`	Một dự án bị xóa vĩnh viễn (chuyển vào thùng rác không tính).
`project.comment.added`	Ai đó bình luận trên một dự án — thường là khách hàng của bạn trả lời.
`guest.project.created` (Open Guest)	Một khách bắt đầu một dự án từ liên kết của bạn hoặc qua API. Chỉ khi biết địa chỉ email của khách.
`guest.measurement.completed` (Open Guest)	Một khách hoàn tất một phép đo và để lại thông tin liên hệ.
`budget.warning_reached` (Open Guest)	Chi tiêu tính theo mức dùng vượt ngưỡng cảnh báo của bạn.
`budget.limit_reached` (Open Guest)	Chi tiêu tính theo mức dùng chạm giới hạn của bạn — các dự án khách tiếp theo bị từ chối.
`enterprise.user.created` (Enterprise)	Một chỗ được thêm vào tổ chức của bạn, kể cả qua đăng nhập một lần.