REST API

REST API 让你自己的软件可以做应用能做的事：项目及其测量、文件夹和产品目录；在 Enterprise 中，是你的组织，就像Enterprise页面所管理的那样；在 Open Guest 中，是你的访客链接、访客项目和估价请求。它以 JSON 作答。包含每个字段和示例的完整参考是API 文档；本页是概览。

要从应用中打开文档，请前往 code开发者 > apiREST API，然后按 menu_book查看文档。

基础 URL#

所有请求都发往：

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

身份验证#

在每个请求的 Authorization 标头中，原样发送你的 API 密钥。密钥在“开发者”页面创建：参见 API 密钥。

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

每个请求都会根据密钥的权限（例如 Projects 读取）、你的订阅，以及对于从网页发出的请求，密钥的网站限制进行检查。能够更改数据的密钥请保存在你的服务器上：参见保管好你的密钥。

正式环境与沙盒#

两者使用同一个基础 URL，由密钥决定：沙盒密钥读写沙盒项目、文件夹和产品，正式密钥永远看不到它们。你的组织的用户、席位和团队在两者中是相同的，因此更改它们需要正式密钥。用沙盒密钥创建的访客项目永远不会计费，沙盒项目也不能嵌入你的网站。令牌会报告它们所属的环境。

API 涵盖的内容#

需要了解的几点：

• 密钥可以访问自己账户的项目，在 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 中，person_pin_circle访客链接 部分提供 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 删除，只会被归档，并且产品的成本价永远不会返回。
• 地籍地块不属于 API。

响应与错误#

成功的请求返回状态 200 和 JSON（.mmp 导出返回 XML）。失败的请求返回错误状态，响应体类似：

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

在“开发者”页面试用 API#

code开发者 > terminal试用 API 会用你的密钥发送真实的请求，并准确显示返回的内容。

1. 选择 正式 或 沙盒。
2. 选择一个 端点，例如“列出你的项目”、“获取测量数据”或“获取账户”。列表中提供的是你的套餐所包含的端点。
3. 填写它的参数。项目或产品按名称从该密钥可以读取的范围中选择；需要指定某个人时，会自动填入你自己的账户。
4. 按 play_arrow发送请求。状态和响应会显示在下方。

这里只提供读取类请求，所以试用不会更改任何内容，并且这些请求不计入你的用量。如果你的密钥没有某个端点所需的权限，页面会提醒你它将返回 403。

Webhook#

Webhook 会在有事情发生时通知你的服务器，就像通知邮件通知你一样。Webhook 是 Enterprise 和 Open Guest 套餐的一部分。

设置 webhook#

在 code开发者 > webhookWebhooks 中：

1. 输入你的 端点 URL：一个互联网上的 https:// 地址。私有网络上的地址会被拒绝，并且每次投递前都会再次检查。
2. 勾选你想要的 事件（参见事件）。新的端点默认包含你的套餐所发送的事件，并且至少要勾选一个。
3. 按 save保存。首次保存时，页面会完整显示你的 签名密钥。请此时复制它：之后只会显示它的最后几个字符。
4. 按 send发送测试事件 并选择一个事件。

测试会向你已保存的端点发送该事件的示例，其中的值是虚构的，并且 data 中带有 "test": true，即使该事件没有被勾选，或端点已关闭也会发送。若要停止所有投递，请按 delete_outline移除：端点及其密钥都会被删除。

在设置下方，Webhook 参考 提供了编写接收端所需的内容：标头和请求体、在 Node.js、Python 和 PHP 中校验签名的代码，以及每个事件的示例数据。

你的服务器会收到什么#

每个事件都是发往你端点的一次 POST，请求体为 JSON：

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

id 对每个事件是唯一的，created 是事件发生的时间，以自 1970 年 1 月 1 日 (UTC) 起的毫秒数表示，data 的内容取决于事件。请求还带有这些标头：

• 请在 8 秒内、在做任何耗时的处理之前，先返回 2xx 状态。任何其他状态、重定向或超时都算作失败。
• 每个事件只发送一次，绝不重试。该部分会显示 最近一次推送 和 连续失败次数。
• 连续失败 10 次后，端点会被关闭，所有者会收到一封电子邮件。请修复你的服务器，然后按 save保存 重新开启。
• 事件偶尔会重复到达或乱序到达。请用 id 忽略重复的事件，用 created 为事件排序。

校验签名#

任何知道你地址的人都可以向它发送请求，所以在信任每次投递之前都要先校验：

1. 将 X-MMO-Signature 标头在逗号处拆分为 t 和 v1。
2. 以你的签名密钥作为密钥，对 t、一个句点和原始请求体计算 HMAC-SHA256，并以十六进制表示。
3. 用恒定时间比较将结果与 v1 比较。
4. 如果 t 与当前时间相差超过 5 分钟，则拒绝该投递。t 以毫秒为单位。

请使用与收到时完全一致的请求体：解析 JSON 后再重新输出会改变它，签名就不再匹配。

autorenew轮换密钥 会立即替换密钥，并完整显示一次新密钥。轮换后请立即更新你的服务器。

事件#