Raise App API

版本 1.2.0。下载 OpenAPI 文件（YAML）

概述复制本节链接

给已安装的应用用的接口（主版本 v1）：客户中心、站点访客、经营记账、审计链、当前人员的权限与部门、成员、安装了本应用的企业、其他应用的服务、本应用的开放事件、记录链接。调用根地址是 https://api.{域名}/app/v1（https://app.{域名}/app/v1 同样可用）。 本文件里的路径已经去掉了这个前缀：GET /access 就是 GET https://api.{域名}/app/v1/access。它与 /open/v1（open-v1.openapi.yaml）是平台的两个接口面：/open/v1 给组织授权的集成读写组织数据，/app/v1 给已安装的应用调用平台能力；同一个生成器 tools/sdkgen 生成两套 SDK 客户端。

令牌与范围复制本节链接

• 令牌 应用自己的租户令牌（POST /open/v1/oauth/token，grant_type=client_credentials，见 open-v1 文档），或使用这个应用页面的人的页面会话。客户令牌不能调用这里（403 forbidden）。
• 范围 每个操作需要一个 app.… 范围（操作的 x-raise-scope，描述里也写着）。范围必须是应用在清单（manifest）uses 里声明过的：令牌里带着它们，页面会话也按清单给。没声明的范围是 403 scope_required。
• 租户 永远是令牌的租户。响应头 X-K3-Tenant 写出令牌实际指向的组织。
• 有些操作只收应用自己的令牌（没有人在背后），页面会话是 403 forbidden，操作描述里会写明。

约定复制本节链接

与 /open/v1 相同的约定：

• 错误 状态 ≥ 400 的正文都是 {"error":{"code","message","requestId","docUrl","details"}}。code 稳定，用它分支；message 给人看。details 没内容时是 {}。requestId 与响应头 X-Request-Id 相同，报问题时带上。
• 幂等 每个 POST 收 Idempotency-Key（1–255 字符）。范围是应用 + 组织。保存 24 小时。同键同方法同路径同正文 → 重放第一次的回答，并带 Idempotent-Replayed: true。同键不同正文 → 409 idempotency_conflict。第一次还在处理 → 409 idempotency_in_progress。状态 ≥ 500 的回答不保存。SDK 会在 POST 上自动生成 uuid v4。业务上的去重另有自己的键（记账的 sourceApp + sourceRef + kind、接触的 key、事件的 key、服务调用的 idempotencyKey），它们在正文里，与这个头无关。
• 限流 认证过的调用都带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。429 另带 Retry-After（秒）。Raise-Environment: test|live 说明这把令牌属于哪边。
• 时间 RFC 3339 UTC。金额 整数最小货币单位。JSON 字段 camelCase（GET /access 的正文例外，见该操作）。
• 正文里的未知字段会被拒绝（422）。

实时文档的同步连接（不在这个文件的路径里）复制本节链接

realtime 接口管文档的建立、服务端改动和读取；人在页面里的协同编辑走 WebSocket，由平台在应用自己的域名上提供（经应用网关，不在 api.{域名}）：GET /app/v1/realtime/sync?codec=&kind=（一条连接服务这个编码、这个种类的所有文档）和 GET /app/v1/realtime/docs/{id}/sync（同一条连接，编码与种类从文档读）。网关先检查应用令牌、安装、Origin 和连接数，再交给平台；页面一侧用 @21stware/raise-design 的实时文档组件或应用 SDK（packages/app-sdk/go/realtime）连接，不要自己拼协议。每份文档的权限是调用者在它所属资源上的级别（resources 接口）。

清单 realtime.docs[] 的每个种类还可以写三项。admit：本应用的一个权限点（permissions[].id），开同步连接的人必须持有，否则 403；不写则网关放进来的人都可以。topics：本应用声明的资源类型（resources[].type）；同步连接可以订阅 <类型>:<id>，平台在调用者对这个资源至少有查看级别时放行；<类型>:* 是这个类型的列表（有一个被新建、改名、归档或分享给人），持有 admit 权限点的人可以订阅（没写 admit 的种类没有列表主题）；其余主题一律拒绝；应用用 POST /realtime/topics/{topic}/publish 告诉订阅者有变化。store：这个种类的文档放在哪个命名空间，默认本应用 id；写别的应用 id 就是与它共用文档，平台只在对方已安装的清单里也声明了同一种类、同一 store、同一编码（双方都同意），且两个应用属于同一开发者组织时接受（提交版本时检查一次，每次使用时再检查）。共用命名空间不扩大权限：每个应用的人仍只按它自己声明的资源类型判断。English: each kind may also set admit (a permission point a person must hold to open a sync connection), topics (declared resource types whose <type>:<id> topics a client may subscribe to at view level or above, and <type>:*, the list of that type, for whoever holds the admit point) and store (the namespace, default the app id; another app's id shares that app's documents only when both declare the same kind, store and codec and both apps belong to one developer organisation).

用 Go 模块 github.com/21stware/raise-go（client.App.…）或 npm 包 @tokiter/raise-sdk（raise.app.…），不要自己拼重试。SDK 的基地址是 /open/v1 根，应用接口的根由它换成同级的 /app/v1。

地址复制本节链接

• /app/v1

认证方式复制本节链接

customers复制本节链接

客户中心：按手机号等身份找到或建立客户、读遮蔽后的资料、记录一次接触

POST /customers/resolve复制本节链接

按身份（手机号等）找到或建立客户，返回主客户的 id

需要范围 app.customers:resolve。English: finds the customer that owns one of the identities, or creates one, and answers the primary customer's id and whether this call created it.

identities 是这个人的身份（kind、value，可带 scope、verified）。name、owner、ownerUnit 在新建客户时使用。channel 与 sourceRef 是这位客户第一次从哪里来（来源应用是调用的应用，不能自己填）。public 标记匿名访客发起的调用。anonymous 要求新建一位没有任何身份的客户，此时 identities 必须为空，也不做任何匹配，所以一定新建。

查询 dryRun=1：只回答“会得到什么”，什么也不写（不建客户）；新建的客户 id 不会被任何别的调用认识。

数据范围：页面会话里的人找到的客户如果不在他「查看客户」（customer.read）的数据范围内，回答只有 id 与 created，没有 name；应用自己的调用（企业令牌）不受影响。

正文里的字段不合规是 422。

• 认证：bearer
• 范围：app.customers:resolve
• operationId：resolveCustomer

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /customers/{id}复制本节链接

读一位客户的遮蔽资料

需要范围 app.customers:read。English: the customer's profile with phone and e-mail masked.

id 是主客户的 id。若这个 id 的客户已被合并，返回的 id 是合并后的主客户（与你问的不同），mergedFrom 列出并入它的客户。客户中心没有这个 id 是 404 not_found。

数据范围：应用自己的调用（企业令牌）可读本企业任何客户；页面会话里的人只能读他在客户应用里「查看客户」（customer.read）数据范围内的客户，范围外的与不存在一样返回 404。

• 认证：bearer
• 范围：app.customers:read
• operationId：getCustomerProfile

参数

响应

200 响应正文（application/json）

POST /customers/touch复制本节链接

给客户的时间线记一次接触（同一个 key 只记一次）

需要范围 app.customers:resolve。English: appends one entry to the customer's timeline, once per key.

kind 写成 {应用}.{动作}（例如 coupons.redeem），ref 是指向所发生之事的 k3:// 引用，key 是幂等键（租户内唯一，用来源事件派生，例如 coupons:claim:cl_17），at 省略为现在。同一个 key 再来，written 为 false。

• 认证：bearer
• 范围：app.customers:resolve
• operationId：touchCustomer

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /customers复制本节链接

列出调用者（这个人）有权看的客户

需要范围 app.customers:list。English: a page of the customers inside the calling person's customer.read grant on the customer app.

数据范围是这个人在客户应用上的 customer.read 授权，不是应用自己的权限：应用用自己的令牌调用，或这个人没有 customer.read，都是 403。stage 是 lead、customer 或 dormant；limit 为 1 到 200；hint 只留下处在待处理合并建议一端的客户；wecomPending 只留下企业微信外部联系人尚未关联的客户。字段不合规是 422。

• 认证：bearer
• 范围：app.customers:list
• operationId：listCustomerPage

参数

响应

200 响应正文（application/json）

GET /customers/find复制本节链接

按手机号找到一位客户

需要范围 app.customers:read。English: finds the customer that owns the phone and answers the masked profile.

kind 目前只有 phone，value 是号码。没有这位客户是 404 not_found；kind 不对或 value 为空是 422。

• 认证：bearer
• 范围：app.customers:read
• operationId：findCustomer

参数

响应

200 响应正文（application/json）

GET /customers/{id}/timeline复制本节链接

读一位客户的时间线（新的在前）

需要范围 app.customers:read。English: the customer's timeline entries, newest first, paged by the id of the last one seen.

limit 为 1 到 200；before 是上一页最后一条的 id，只取比它早的。没有这个客户是 404 not_found。

• 认证：bearer
• 范围：app.customers:read
• operationId：listCustomerTimeline

参数

响应

200 响应正文（application/json）

POST /customers/{id}/rename复制本节链接

改客户的姓名

需要范围 app.customers:write。English: renames the customer. 没有这个客户是 404 not_found。

• 认证：bearer
• 范围：app.customers:write
• operationId：renameCustomer

参数

请求正文（必填）（application/json）

响应

POST /customers/{id}/links复制本节链接

把本应用的一条记录挂到客户上

需要范围 app.customers:write。English: links one of the calling app's own records to the customer.

ref 必须是本应用自己的记录（k3://<调用的应用>/…），别的应用的引用是 422。

• 认证：bearer
• 范围：app.customers:write
• operationId：linkCustomer

参数

请求正文（必填）（application/json）

响应

POST /customers/{id}/owner复制本节链接

改客户的负责人和归属部门

需要范围 app.customers:write。English: sets the customer's owner and owning unit.

owner 是员工 subject，ownerUnit 是部门 id；两个都可以是空串，表示清空。

• 认证：bearer
• 范围：app.customers:write
• operationId：setCustomerOwner

参数

请求正文（必填）（application/json）

响应

POST /customers/{id}/dealt复制本节链接

记这位客户成交了

需要范围 app.customers:write。English: marks the customer as having dealt, at the given time or now.

at 省略为现在。

• 认证：bearer
• 范围：app.customers:write
• operationId：markCustomerDealt

参数

请求正文（必填）（application/json）

响应

POST /customers/{id}/merge复制本节链接

把另一位客户并入这一位

需要范围 app.customers:write。English: merges the other customer into this one and answers the primary customer's id.

other 必填。两个 id 都可以是已被合并过的，返回的 primary 是合并后的主客户。

• 认证：bearer
• 范围：app.customers:write
• operationId：mergeCustomers

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /customers/{id}/erase复制本节链接

抹除一位客户的个人数据（不可撤销）

需要范围 app.customers:write。English: erases the customer's personal data; final.

正文是 {}。抹除之后不能恢复。

• 认证：bearer
• 范围：app.customers:write
• operationId：eraseCustomer

参数

请求正文（必填）（application/json）

类型 CustomerEraseRequest。空对象 {}

响应

GET /customers/tags复制本节链接

列出企业的客户标签库（opv2 J2 ④）

需要范围 app.customers:read。English: the tenant's tag dictionary; writable says which tags an app may put on and take off.

不含每个标签有多少客户。

• 认证：bearer
• 范围：app.customers:read
• operationId：listCustomerTags

响应

200 响应正文（application/json）

PUT /customers/{id}/tags/{tag}复制本节链接

给本企业的一位客户打上标签（opv2 J2 ④）

需要范围 app.customers:tag。English: puts a manual tag on a customer of the tenant.

只能是标签库里的手动标签：别的来源（企业微信）的标签只读，返回 422 validation_failed。客户或标签不存在是 404 not_found；客户被合并时作用在主客户上。重复调用结果相同。每次改动在企业的审计链里记一条（customer.tag / customer.untag，操作者是页面会话的人或应用自己）；一个应用在一个企业里每 10 分钟最多改 3000 次，超过返回 429。只限本企业的客户：应用自己的调用（企业令牌）可改本企业任何客户；页面会话里的人只能改他在客户应用里「编辑客户」（customer.write）的数据范围内的客户，范围外的客户与不存在一样返回 404。

• 认证：bearer
• 范围：app.customers:tag
• operationId：addCustomerTag

参数

响应

200 响应正文（application/json）

DELETE /customers/{id}/tags/{tag}复制本节链接

去掉本企业一位客户的标签（opv2 J2 ④）

需要范围 app.customers:tag。English: takes a manual tag off a customer of the tenant.

只能是标签库里的手动标签：别的来源（企业微信）的标签只读，返回 422 validation_failed。客户或标签不存在是 404 not_found；客户被合并时作用在主客户上。重复调用结果相同。每次改动在企业的审计链里记一条（customer.tag / customer.untag，操作者是页面会话的人或应用自己）；一个应用在一个企业里每 10 分钟最多改 3000 次，超过返回 429。只限本企业的客户：应用自己的调用（企业令牌）可改本企业任何客户；页面会话里的人只能改他在客户应用里「编辑客户」（customer.write）的数据范围内的客户，范围外的客户与不存在一样返回 404。

• 认证：bearer
• 范围：app.customers:tag
• operationId：removeCustomerTag

参数

响应

200 响应正文（application/json）

visitors复制本节链接

站点访客与客户的对应

GET /site-visitors/{site}/{visitor}复制本节链接

一位站点访客对应的客户，以及访客是否证明了自己是谁

需要范围 app.visitors:read。English: the customer a site visitor is tied to, and whether the visitor proved the tie.

没有对应的客户时 customer 为空字符串，verified 为 false。verified 为 true 表示访客自己证明过身份（微信、短信验证码）；表单或 Identify 写入的对应是 false。要授予访问权限请看 verified，只做归因看 customer 即可。

• 认证：bearer
• 范围：app.visitors:read
• operationId：getSiteVisitor

参数

响应

200 响应正文（application/json）

PUT /site-visitors/{site}/{visitor}复制本节链接

把一位站点访客认定为某位客户

需要范围 app.visitors:write。English: ties a site visitor to a customer.

正文 {customer}。返回写入后访客对应的客户 id。

• 认证：bearer
• 范围：app.visitors:write
• operationId：identifySiteVisitor

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /site-visitors复制本节链接

按顺序号列出已被认定的站点访客（给订阅端续读）

需要范围 app.visitors:read。English: the identified visitors after a sequence number; a reader keeps the last seq it handled.

after 是已处理的最后一个 seq（默认 0，不能为负）。limit 必填，1 到 500。其他值是 422。没有结果时 items 是 []。

• 认证：bearer
• 范围：app.visitors:read
• operationId：listIdentifiedSiteVisitors

参数

响应

200 响应正文（application/json）

access复制本节链接

当前人员在本应用里能做什么，以及所在部门

GET /access复制本节链接

当前人员对本应用某个权限点能做什么

需要范围 app.access:read。English: what the caller (the person of the page session) may do with one permission of this app.

point 必填，必须以 app.{本应用 id}. 开头，否则 403 forbidden。type 是对象类型 id（读对象类型时用来取字段可见性）。

正文的字段名不是 camelCase：它是权限求值器的结果原样输出（Managed、Allowed、All、Self、Units、Subject、Personal、Fields）。基础模式（组织没有启用权限模型）下，平台角色说了算，Allowed 与范围不适用。平台没有接通权限求值时，回答是只有 {"managed": false}（小写）。

• 认证：bearer
• 范围：app.access:read
• operationId：checkAccess

参数

响应

200 响应正文（application/json）

POST /access/points复制本节链接

当前人员对本应用多个权限点能做什么（一次问完）

需要范围 app.access:read。English: what the caller may do with several permissions of this app, in one call.

points 是 1 到 100 个 {point, type}，规则同 GET /access：每个 point 都必须以 app.{本应用 id}. 开头，有一个不是就整次 403 forbidden（什么都不问）；个数为 0 或超过 100 是 422。results[i] 就是 GET /access 对 points[i] 的回答（同一个求值器、同样不是 camelCase 的字段名；平台没有接通权限求值时每一项都是 {"managed": false}）。平台不记住答案：收回的权限在下一次调用就没有了。English: 1 to 100 {point, type}, each under the app.{app id}. prefix (one that is not refuses the whole call with 403 before anything is asked; none or over 100 is 422); results[i] is exactly GET /access's answer for points[i], nothing cached.

• 认证：bearer
• 范围：app.access:read
• operationId：checkAccessPoints

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /unit复制本节链接

当前人员所在的部门

需要范围 app.access:read。English: the department of the caller. 平台没有接通权限求值时是 501 capability_off。

• 认证：bearer
• 范围：app.access:read
• operationId：getUnit

响应

200 响应正文（application/json）

directory复制本节链接

企业的成员列表

GET /members复制本节链接

企业的成员列表

需要范围 app.directory:read。English: the members of the tenant. 没有成员时 items 是 []。

• 认证：bearer
• 范围：app.directory:read
• operationId：listDirectoryMembers

响应

200 响应正文（application/json）

ledger复制本节链接

向经营记账（本应用来源的记账行）

POST /ledger/posts复制本节链接

向经营记账记一笔（本应用来源）

需要范围 app.ledger:post。English: enqueues one posting in the platform's outbox and starts its delivery to the books; answers the outbox key.

sourceApp 必须是调用的应用，否则 403 forbidden；例外是本应用自己的网关收款按渠道记（与所有渠道记账一样）：sourceApp 为 channel:wechat 或 channel:alipay，sourceRef 为 k3://payments/order/{id}，那笔支付单是本应用在这个渠道建的、已付款，金额不超过它。English: sourceApp must be the calling app, or channel:{wechat|alipay} with sourceRef k3://payments/order/{id} of a paid payment order the app made on that channel, the amount within it. sourceApp + sourceRef + kind 是记账的去重键：同一组合只记一次。direction 是 in 或 out，amountCents 大于 0（分），currency 省略为组织的币种（不做换算，别的币种会被拒绝），occurredOn 省略为组织时区的今天。

reverses 写某个更早的同来源同引用的记账的 kind，本笔是它的冲销（金额必须相同、方向相反，不能同时是账单）。settles 写某笔开出账单的更早记账的 kind，本笔是对这张账单的付款。这两个字段互斥，也都不能与 bill 同用，违反是 422。

• 认证：bearer
• 范围：app.ledger:post
• operationId：postLedger

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

audit复制本节链接

向企业的审计链写入本应用的操作

POST /audit复制本节链接

向企业的审计链写入本应用的一条操作

需要范围 app.audit:write。English: appends one entry to the tenant's audit chain as the caller.

action 必须以 {本应用 id}. 开头，否则 403 forbidden。成功回答 204，没有正文。

• 认证：bearer
• 范围：app.audit:write
• operationId：appendAudit

参数

请求正文（必填）（application/json）

响应

installations复制本节链接

安装了本应用的企业（只收应用自己的令牌）

GET /installations复制本节链接

安装了本应用且已开启的企业

需要范围 app.installations:read。只收应用自己的令牌；页面会话是 403 forbidden。测试凭证的令牌列出装了本应用的测试企业（不论属于哪个开发者组织）；正式凭证的令牌只列真实组织。English: the tenants that have the app installed and switched on (the app's own calls only); a test credential's token lists the test enterprises that have the app installed, of any developer organisation, a live one real organisations only.

• 认证：bearer
• 范围：app.installations:read
• operationId：listInstallations

响应

200 响应正文（application/json）

services复制本节链接

调用其他应用声明的服务（只收应用自己的令牌）

POST /services/{owner}/{name}/calls复制本节链接

调用另一个应用声明的服务（排队，至少投递一次）

需要范围 app.services:call。只收应用自己的令牌；页面会话是 403 forbidden。English: starts one run of a service another app declares (the call trigger); the platform queues it and delivers it at least once.

owner 是声明服务的应用，name 是服务名。正文 input 是交给服务的 JSON，idempotencyKey 去重：同一个键就是同一次运行。第一次返回 202 且 created 为 true；这个键以前用过则 200，返回当时那次运行。

• 认证：bearer
• 范围：app.services:call
• operationId：callService

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

202 响应正文（application/json）

events复制本节链接

发出本应用在清单里声明的开放事件

POST /events/emit复制本节链接

发出本应用声明的一个开放事件

需要范围 app.events:emit。English: writes one open event of the app into the platform's outbox and starts its delivery.

type 必须是本应用在清单 events.emits 里声明的事件类型，并以 {本应用 id}. 开头，否则 403 forbidden。key 必填（最多 200 字符）：同一个键就是同一个事件。customer 是事件涉及的客户，data 是事件内容。返回 202。

应用之间的事件（opv2 J2 ②）：同一个事务里，事件也写进平台的发件箱，送给本租户里装了并开着、在清单 services[] 里声明了触发器 event:{type} 的应用（见 webhook event:{app}.{what}），至少一次，幂等键是 appevt:{本应用 id}:{key}（超过 128 字符时用摘要）。type 同时是平台登记的开放事件、且有 customer 时，才另外送给集成的 webhook。data 最多 16 KiB（JSON），超过返回 422；事件只用 id 指代人和记录，不放手机号、姓名。清单里声明了的类型只由声明它的应用发布：同名的审计动作不再作为事件送给服务。

• 认证：bearer
• 范围：app.events:emit
• operationId：emitEvent

参数

请求正文（必填）（application/json）

响应

202 响应正文（application/json）

links复制本节链接

其他应用的记录链接：搜索与解析

GET /links复制本节链接

按当前人员的权限搜索另一个应用的记录链接

需要范围 app.links:read。English: searches the records of another app as the caller sees them.

app 是要搜的应用；省略时搜这个组织已安装并开启的全部应用（每个应用最多 limit 条，installed 为 true）。q 是文字查询（省略为最近的）。limit 默认 20，1 到 50，超出是 422。指定的应用在这个组织没有安装或没有开启时，installed 为 false 且 items 是 []，选择器可以据此区分“没装”和“没找到”。English: app omitted searches every installed app.

• 认证：bearer
• 范围：app.links:read
• operationId：searchLinks

参数

响应

200 响应正文（application/json）

GET /links/resolve复制本节链接

解析一个 k3:// 引用：它指向什么，当前人员能不能看到

需要范围 app.links:read。English: what a reference points at and whether the caller may see it.

ref 必填，必须是 k3:// 引用，否则 422。不存在或看不到时 found 为 false，没有 link。

• 认证：bearer
• 范围：app.links:read
• operationId：resolveLink

参数

响应

200 响应正文（application/json）

GET /backlinks复制本节链接

列出提到本应用某条记录的其他应用的记录

需要范围 app.links:read。English: the records of other apps that mention one of the calling app's own records, as the page session's person sees them.

ref 必填，必须是调用应用自己的记录（k3://<应用>/…）：不是 k3:// 引用是 422，是别的应用的记录是 403（应用只能问谁提到了自己的记录）。各应用的提供者按当前人员的权限过滤，所以要用页面会话（有人）调用；应用自己的调用没有人，items 是 []。调用应用自己的记录不在其中（应用自己列）。limit 默认 50，1 到 100，超出是 422。English: items exclude the calling app's own records; the app's own token (no person) gets [].

• 认证：bearer
• 范围：app.links:read
• operationId：listBacklinks

参数

响应

200 响应正文（application/json）

entitlements复制本节链接

权益服务：模板、发放、预留与核销、退款、转让，以及其他应用声明的 granter

GET /entitlements/templates复制本节链接

列出权益模板

需要范围 app.entitlements:read。English: the tenant's entitlement templates, optionally of one app or only the active ones.

ownerApp 筛归属的应用；activeOnly 为 true 时只留启用的。没有时 data 是 []。

• 认证：bearer
• 范围：app.entitlements:read
• operationId：listEntitlementTemplates

参数

响应

200 响应正文（application/json）

POST /entitlements/templates复制本节链接

建立一个权益模板（归属永远是调用的应用）

需要范围 app.entitlements:write。English: creates a template owned by the calling app.

ownerApp 可省略；写了别的应用是 403 forbidden。种类（kind）建立后不能改。带请求头 K3-Dry-Run: 1 只预演，什么也不写。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：createEntitlementTemplate

参数

请求正文（必填）（application/json）

响应

201 响应正文（application/json）

GET /entitlements/templates/{id}复制本节链接

读一个权益模板

需要范围 app.entitlements:read。English: one template of the tenant.

• 认证：bearer
• 范围：app.entitlements:read
• operationId：getEntitlementTemplate

参数

响应

200 响应正文（application/json）

PUT /entitlements/templates/{id}复制本节链接

修改本应用的权益模板

需要范围 app.entitlements:write。English: changes a template of the calling app.

已发出的权益不受影响（权益是发放时的副本）。别的应用的模板是 403 forbidden。种类建立后不能改。带 K3-Dry-Run: 1 只预演。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：updateEntitlementTemplate

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /entitlements/grants复制本节链接

列出一位客户的权益（新的在前）

需要范围 app.entitlements:read。English: a holder's grants, newest first.

holder 必填。status 可选：active、not_started、frozen、expired、used_up、used、refunded、voided、transferred（按今天计算）。正文是 {data: [...]}，不分页。

• 认证：bearer
• 范围：app.entitlements:read
• operationId：listEntitlementGrants

参数

响应

200 响应正文（application/json）

POST /entitlements/grants复制本节链接

按本应用的模板向客户发放权益（同一个 key 只发一次）

需要范围 app.entitlements:write。English: issues count grants of one of the app's own templates to a customer, once per key.

key 在正文里；正文没写时用请求头 Idempotency-Key。同键重来返回 200 且 replay 为 true，不再发放；新发放返回 201。模板不是本应用的是 403 forbidden。count 为 1 到 1000，默认 1；code 只用于 count 为 1 的券或奖品。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：grantEntitlement

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

201 响应正文（application/json）

GET /entitlements/grants/{id}复制本节链接

读一项权益和它的流水

需要范围 app.entitlements:read。English: one grant with its ledger.

• 认证：bearer
• 范围：app.entitlements:read
• operationId：getEntitlementGrant

参数

响应

200 响应正文（application/json）

POST /entitlements/grants/{id}/refund复制本节链接

退本应用发出的一项权益

需要范围 app.entitlements:write。English: ends a grant of the app's own template and answers the amount to give back.

mode 省略或 times：按剩余次数的份额；amount：按 amountCents，不超过还没退的付款。reason 必填。路径里的 id 优先于正文里的 grant。别的应用的权益是 403 forbidden。服务不动钱，钱由调用方退。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：refundEntitlement

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /entitlements/stores/relink复制本节链接

把本应用权益里的旧门店 id 换成组织里的门店

需要范围 app.entitlements:write。English: rewrites a legacy store id to the organisation's store in the templates and grants the calling app owns, and in the redemptions of those grants.

scope 里的 store:<from> 换成 store:<to>，这些权益的核销记录的地点 from 换成 to。只动调用应用自己发出的模板与权益（所有者由平台按调用方定，正文不能指定）。重复调用不再改变任何东西。活动关联旧门店记录时用它（ADR-0057）。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：relinkEntitlementStore

参数

请求正文（必填）（application/json）

响应

POST /entitlements/grants/{id}/transfer复制本节链接

把本应用发出的一项权益转给另一位客户

需要范围 app.entitlements:write。English: gives what is left of a grant to another holder.

原权益结束，生成一项条款相同的新权益并返回。不能转让时是 422，说明原因。别的应用的权益是 403 forbidden。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：transferEntitlement

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /entitlements/redemptions复制本节链接

核销一次权益（原子，按 key 幂等）

需要范围 app.entitlements:write。English: uses a grant once or more, atomically.

pick 指定权益；不指定时服务在 holder 的权益里按“先到期的、无期限的最后、剩得少的、先发的”选。key 在正文里，没写时用请求头 Idempotency-Key；同键重来 replay 为 true，不再扣。任何权益都可以核销，不限本应用的模板。不能核销时是 422，error.message 是给人看的原因，error.details.items 逐项说明其他权益为什么不行。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：redeemEntitlement

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /entitlements/redemptions/{id}/void复制本节链接

作废一张核销单，次数退回

需要范围 app.entitlements:write。English: undoes a redemption of a grant of the app's own template; the times come back through the ledger.

核销单所用的权益不是本应用的是 403 forbidden。正文必须是 JSON 对象，reason 可省略。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：voidEntitlementRedemption

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /entitlements/reservations复制本节链接

预留一次使用（到时未确认自动释放）

需要范围 app.entitlements:write。English: keeps one use aside until it is confirmed, cancelled or expired.

正文是核销的字段加 ttlSeconds（5 到 86400，默认 900）。权益的选法同核销。预留期间别人不能用这份。同一个 key 返回同一个预留：200 且 replay 为 true；新预留 201。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：reserveEntitlement

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

201 响应正文（application/json）

GET /entitlements/reservations/{id}复制本节链接

读一个预留

需要范围 app.entitlements:read。English: one reservation. A live one past its expiry reads as expired.

• 认证：bearer
• 范围：app.entitlements:read
• operationId：getEntitlementReservation

参数

响应

200 响应正文（application/json）

POST /entitlements/reservations/{id}/confirm复制本节链接

确认预留：做出核销（恰好一次）

需要范围 app.entitlements:write。English: makes the reservation's redemption, exactly once.

再次确认返回同一张核销单且 replay 为 true。预留已过期或已取消是 409 conflict。不需要正文。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：confirmEntitlementReservation

参数

响应

200 响应正文（application/json）

POST /entitlements/reservations/{id}/cancel复制本节链接

取消预留，释放被留住的次数

需要范围 app.entitlements:write。English: gives a live reservation up; one that ended already is answered as it is.

已结束的预留原样返回且 replay 为 true。正文必须是 JSON 对象，reason 可省略。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：cancelEntitlementReservation

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /entitlements/granters复制本节链接

列出其他应用声明的可发放项（granter）的名字

需要范围 app.entitlements:read。English: the names of what apps declare they can issue (entitlements.grantable in a manifest).

• 认证：bearer
• 范围：app.entitlements:read
• operationId：listEntitlementGranters

响应

200 响应正文（application/json）

POST /entitlements/granters/{name}/grants复制本节链接

通过其他应用声明的 granter 发放

需要范围 app.entitlements:write。English: asks the app that declares the granter to issue something; at least once, once per key.

key 在正文里，没写时用请求头 Idempotency-Key，必填；holder 必填。没有应用声明这个名字是 404 not_found。params 是 granter 自己的词汇；dry 为 true 或带 K3-Dry-Run: 1 时只预演。返回 granter 给出的 ref。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：grantEntitlementVia

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /entitlements/codes/{code}复制本节链接

按券码读一项权益

需要范围 app.entitlements:read。English: the grant that carries the code.

不存在的券码和格式不对的券码得到同一个 404 not_found，所以猜码学不到任何东西。

• 认证：bearer
• 范围：app.entitlements:read
• operationId：getEntitlementByCode

参数

响应

200 响应正文（application/json）

GET /entitlements/granters/{name}/choices复制本节链接

列出一个 granter 能发放的东西

需要范围 app.entitlements:read。English: what the granter can issue, for a picker.

没有应用声明这个名字，或它不列出，data 是 []。priceCents 在 granter 按价出售时给出。

• 认证：bearer
• 范围：app.entitlements:read
• operationId：listEntitlementGranterChoices

参数

响应

200 响应正文（application/json）

POST /entitlements/granters/{name}/refunds复制本节链接

请 granter 收回它发出的东西

需要范围 app.entitlements:write。English: asks the app that declares the granter to take back what it issued (an order refunds what it collected); idempotent by key.

ref 是发出之物的 k3:// 引用。amountCents 省略时按 granter 自己的规则算现在值多少并收回，写了就按这个数收回。key 在正文里，没写时用请求头 Idempotency-Key，同键重来返回第一次的结果、不再收回。preview 为 true 或带 K3-Dry-Run: 1 时只回答值多少，什么也不收。没有应用声明这个名字是 404 not_found；granter 不收回是 409（错误码 not_refundable）；被拒绝时 422 用话说明原因。

• 认证：bearer
• 范围：app.entitlements:write
• operationId：refundEntitlementVia

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

secrets复制本节链接

平台密钥库：用每个主体一把的钥匙加密、解密、销毁本应用的个人数据

POST /secrets/encrypt复制本节链接

用这个主体的钥匙加密本应用的一段个人数据

需要范围 app.secrets:use。English: encrypts personal data under the key of one subject of the calling app.

subject 是本应用自己的 <种类>:<id>（种类是小写字母、数字和 -，以字母开头，最多 40 字符；id 最多 200 字符），否则 422 invalid。平台把它归到本应用和令牌的组织下，应用碰不到别的应用、别的组织的钥匙。plaintext 是 base64。正文最多 64 KiB（明文约 48 KiB），超出是 413 payload_too_large。返回的 ciphertext（base64）由应用自己保存。平台没有密钥库时是 503。

• 认证：bearer
• 范围：app.secrets:use
• operationId：encryptSecret

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /secrets/decrypt复制本节链接

用这个主体的钥匙解密本应用保存的密文

需要范围 app.secrets:use。English: decrypts a ciphertext of one subject of the calling app; the answer is not cached (Cache-Control: no-store).

subject 同加密时一样。ciphertext 是 base64，正文最多 64 KiB。钥匙已销毁，或密文不是这个主体的，都是 409 conflict，不说是哪一种。回答带 Cache-Control: no-store。解密的回答不为 Idempotency-Key 保存（带了也忽略，明文不留在平台）：它不改变任何东西，重试就是再问一次。

• 认证：bearer
• 范围：app.secrets:use
• operationId：decryptSecret

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /secrets/shred复制本节链接

永久销毁这个主体的钥匙（它的密文从此解不开）

需要范围 app.secrets:use。English: destroys the key of one subject of the calling app for good; its ciphertexts can no longer be decrypted.

subject 同加密时一样。销毁不能撤回；之后解密这个主体的密文是 409 conflict。成功回答 204，没有正文。

• 认证：bearer
• 范围：app.secrets:use
• operationId：shredSecret

参数

请求正文（必填）（application/json）

响应

sites复制本节链接

企业站点的名称、状态与访问量

POST /sites/summaries复制本节链接

读企业站点的名称、状态和一段日期里的访问量

需要范围 app.sites:read。English: the name, state and request count of the tenant's sites, one answer per request, in order.

requests 最多 200 条，超出是 422。每条问一个站点从 from 那天到 to 那天（省略：到今天）的访问量。不存在的站点回答空名字、0 次访问、没有 state。平台没有接上站点时是 501 capability_off。

• 认证：bearer
• 范围：app.sites:read
• operationId：summarizeSites

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

stores复制本节链接

组织里的门店，以及某人所在或管理的门店（只读）

GET /stores复制本节链接

列出组织里的门店，或某人所在、所管的门店

需要范围 app.stores:read。English: every store of the tenant in the tree's order, closed ones included; with of, the stores that person works at or manages.

省略 of：组织的全部门店（含已关闭的），按组织树的顺序。of 是人员的 subject：他所属或被任命的每个部门及其下面的门店（店员是自己的店，任命在大区的经理是大区下的每家店）。门店由平台维护，应用只读，用 id（部门 id）引用。平台没有接上门店时是 501 capability_off。

• 认证：bearer
• 范围：app.stores:read
• operationId：listStores

参数

响应

200 响应正文（application/json）

realtime复制本节链接

实时文档：本应用在清单里声明的协同文档（创建、服务端改动、投影、删除），同步连接由平台在应用自己的域名上提供

POST /realtime/docs复制本节链接

创建一份实时文档

需要范围 app.realtime:write。English: creates a real-time document of one of the kinds the app declares in realtime.docs[], and registers it as an instance of the kind's resource type.

kind 必须是本应用清单 realtime.docs[] 里声明的种类，否则 422 invalid。resource 是它所属资源的 id（资源类型由种类声明），文档的权限就是调用者在这个资源上的级别（见 resources 接口）。id 可省略，平台取 rd_…；自己取的 id 只能用字母、数字、- 和 _，最多 64 字符。创建是幂等的：同一命名空间里已有同 id、同种类、同资源类型的文档时返回 200 和它的文档头（应用可以在自己提交之前先建、失败后重试）；同 id 的其他文档是 409 conflict。 初始内容按种类的编码给：yjs-v1 给 doc（ProseMirror 文档，省略是空文档），ymap-v1 给 data（JSON 对象，必填），board-v1 给 board（看板，必填），Office 编码给 state（base64，由读过文件的浏览器生成，必填）。正文最大 8 MiB。 返回 201 和文档头。页面会话只能用自己有权的资源；应用自己的令牌不受级别限制（文档归应用）。

• 认证：bearer
• 范围：app.realtime:write
• operationId：createRealtimeDoc

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

201 响应正文（application/json）

GET /realtime/docs/{id}复制本节链接

读一份实时文档的头信息

需要范围 app.realtime:read。English: the header of one document: codec, epoch, schema version, the sequence of the log head and of the last projection, and its resource.

页面会话需要对所属资源至少有查看级别，没有时一律是 404 not_found（不暴露文档是否存在）。别的应用的文档、平台内置应用的文档也是 404。

• 认证：bearer
• 范围：app.realtime:read
• operationId：getRealtimeDoc

参数

响应

200 响应正文（application/json）

DELETE /realtime/docs/{id}复制本节链接

删除一份实时文档

需要范围 app.realtime:write。English: deletes the document, its log and its projection, and closes the open sync connections.

页面会话需要对所属资源有编辑级别以上，否则 404 not_found。资源的登记（访问名单）不随文档删除，由应用用 DELETE /access/{type}/{id} 另行删除。返回 204。

• 认证：bearer
• 范围：app.realtime:write
• operationId：deleteRealtimeDoc

参数

响应

POST /realtime/docs/{id}/edits复制本节链接

由服务端改一份实时文档

需要范围 app.realtime:write。English: applies one server-side edit to the document as the caller, returns the sequence it landed at and the projection after it.

edit 里写且只写一种改动，按顺序取第一个出现的：replace（整份 ProseMirror 文档）、append（追加的块）、title、data（ymap-v1：整个对象）、board（board-v1：整个看板）。什么也没写是 422 invalid。origin 是 draft、restore 或 system（默认 system），说明这次改动的来历。dry 为 true 只预演：回答和真做一样，什么也不留下。 声明了 guard 的种类，写入前会先问应用（清单 providers.realtimeGuard），应用拒绝是 422 invalid。需要编辑级别；代理（agent）只读，是 422 invalid。正文最大 8 MiB。

• 认证：bearer
• 范围：app.realtime:write
• operationId：editRealtimeDoc

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /realtime/docs/{id}/epoch复制本节链接

让一份实时文档从新的内容重新开始（换纪元）

需要范围 app.realtime:write。English: starts the document over from the given content; epoch + 1, so open editors reconnect from the new state. Use it for restore and import.

只有 ProseMirror 文档（yjs-v1）能这样重开，doc 省略是空文档；其他编码是 422 invalid。需要编辑级别。

• 认证：bearer
• 范围：app.realtime:write
• operationId：restartRealtimeDoc

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /realtime/docs/{id}/projection复制本节链接

读一份实时文档现在的投影

需要范围 app.realtime:read。English: the projection now: title, plain text, word count, references, and the content in the codec's form.

内容的形状随编码：yjs-v1 与 Office 编码给 doc（ProseMirror JSON），ymap-v1 给 data，board-v1 给 board。需要查看级别，没有时 404 not_found。投影完成后平台会把事件 realtime.doc.projected 送给应用（见 webhooks）。 带 minSeq 时，平台先让投影至少到这个序号（必要时当场投影），最多等 wait 毫秒（不超过 5000）；到时还没到是 409 behind，稍后再试。English: with minSeq, the platform first brings the projection to at least that sequence, waiting up to wait ms (at most 5000); 409 behind when it is not there in time.

• 认证：bearer
• 范围：app.realtime:read
• operationId：getRealtimeProjection

参数

响应

200 响应正文（application/json）

GET /realtime/docs/{id}/state复制本节链接

读一份实时文档完整的 CRDT 状态

需要范围 app.realtime:read。English: the document's whole CRDT state as it is now (its snapshot with every logged update merged), base64, and the sequence it is at.

应用把它存成一个版本（发布的副本），或交给只读的查看页。页面会话需要查看级别，没有时 404 not_found。

• 认证：bearer
• 范围：app.realtime:read
• operationId：getRealtimeState

参数

响应

200 响应正文（application/json）

POST /realtime/docs/{id}/scrub复制本节链接

把一份实时文档整理到平台现在的结构

需要范围 app.realtime:write。English: brings the document to the server's schema: removes from the CRDT what the schema no longer stores (a repair update) and compacts the log.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。文档正在别处投影或压缩时是 409 conflict，稍后再试。

• 认证：bearer
• 范围：app.realtime:write
• operationId：scrubRealtimeDoc

参数

响应

200 响应正文（application/json）

POST /realtime/docs/invalidate复制本节链接

让打开这些文档的连接重新核对权限

需要范围 app.realtime:write。English: re-authorises the sync connections that have these documents open (after a permission change, a move or a restore).

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。ids 1 到 100 个，都必须是这个种类在它的命名空间里的文档，否则 404 not_found（别的应用的文档不在这里）。返回 202。

• 认证：bearer
• 范围：app.realtime:write
• operationId：invalidateRealtimeDocs

参数

请求正文（必填）（application/json）

响应

POST /realtime/docs/revoke复制本节链接

从所有连接上收回这些文档

需要范围 app.realtime:write。English: takes these documents away from every sync connection, with a reason: forbidden, trashed or deleted.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。reason 是 forbidden（默认）、trashed 或 deleted。之后应用还要让这些文档的资源对人不再可见（否则重新连上又能打开）；DELETE /realtime/docs/{id} 已经收回了被删的文档。ids 的规则同上。返回 202。

• 认证：bearer
• 范围：app.realtime:write
• operationId：revokeRealtimeDocs

参数

请求正文（必填）（application/json）

响应

POST /realtime/topics/{topic}/publish复制本节链接

告诉一个主题的订阅者它变了

需要范围 app.realtime:write。English: tells the sync clients subscribed to a topic that it changed (they refetch over REST); fire and forget.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。topic 是 <资源类型>:<id>（<资源类型>:* 是这个类型的列表），类型必须在这个种类的 topics 里声明，否则 404 not_found（别的应用的类型也是）。version 原样交给订阅者。返回 202。

• 认证：bearer
• 范围：app.realtime:write
• operationId：publishRealtimeTopic

参数

请求正文（必填）（application/json）

响应

POST /realtime/connections/invalidate复制本节链接

让本企业的连接重新核对权限

需要范围 app.realtime:write。English: re-authorises every sync connection of the tenant (roles, departments or members changed), of one kind or, when kind is omitted, of every kind.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。正文可省略（省略即所有种类）。返回 202。

• 认证：bearer
• 范围：app.realtime:write
• operationId：invalidateRealtimeConnections

参数

请求正文（application/json）

响应

POST /realtime/connections/uninstalled复制本节链接

关闭本应用在本企业的所有连接

需要范围 app.realtime:write。English: closes every sync connection of the app in the tenant (close code 4004), of every kind; another app sharing a namespace keeps its own.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。返回 202。

• 认证：bearer
• 范围：app.realtime:write
• operationId：closeRealtimeConnections

参数

响应

POST /realtime/codecs/{codec}/meta复制本节链接

用平台的编码读一份 Office 状态的属性

需要范围 app.realtime:read。English: reads the properties of an Office state (the title, the hashes of the file's preserved parts, the engine) with the platform's codec. Codecs run only in the platform, so an app outside it checks an import here: the browser built the state from the file, and the app compares the state's properties with the file before it creates the document.

只收应用自己的令牌（页面会话是 403 forbidden）；每个应用在每个企业有调用额度（每秒 20 次，峰值 200），超过是 429，带 Retry-After。codec 必须是本应用清单 realtime.docs[] 里某个种类的编码，否则 404 not_found。只有 Office 编码（quire-v1、ledger-v1、lectern-v1）有属性；别的编码、读不了的状态是 422 invalid。state 是 base64，请求正文最大 24 MiB。English: the app's own token only, within the control budget; the codec must be one the app's manifest declares; only the Office codecs have properties; the body is at most 24 MiB.

• 认证：bearer
• 范围：app.realtime:read
• operationId：readRealtimeCodecMeta

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

resources复制本节链接

资源与分享：本应用声明的资源类型，由平台保存所有者、名单、通用访问、开关和申请，并批量回答谁能看；带 parent 的类型走树模型（继承的节点名单、状态、集合）

GET /access/{type}/{id}复制本节链接

读一个资源的访问名单（按调用者能看到的）

需要范围 app.resources:read。English: the list of one resource as the caller may see it: owner, general access, switches, grants, the caller's level.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

平铺类型上，应用自己的令牌可以读整个名单（包括已过期的条目，应用按自己的时钟判断）：me 为 manage。用于应用按自己的权限点决定谁能授权的类型（例如会员的敏感记录）。English: on a flat type the app's own token reads the whole list, expired grants included.

调用者对资源没有查看级别时是 404 not_found，要申请访问见 POST …/requests。

树类型：返回 AccessTreeView：显式名单 entries、根或节点指向的集合 set、调用者经状态限制后的级别 level 和原因 reason。页面会话没有查看级别时 404 not_found；应用自己的令牌可带 user 查某人的级别（不带就只有名单和集合），根或节点不存在时 404 not_found。English: on a tree type the answer is the explicit entries, the set and the caller's level after the states.

• 认证：bearer
• 范围：app.resources:read
• operationId：getResourceAccess

参数

响应

200 响应正文（application/json）

POST /access/{type}/{id}复制本节链接

登记一个资源（写下它的所有者）

需要范围 app.resources:write。English: registers a resource of a declared type with its owner; idempotent.

type 必须是本应用清单 resources[] 里声明的类型（以 {本应用 id}. 开头），否则 404 not_found。页面会话登记的资源，所有者就是这个人；应用自己的令牌必须在正文里写 owner。正文可省略。重复登记同一个资源不会出错。登记后文档、记录的名单、通用访问、开关都由平台保存。

树类型（清单里带 parent 的类型和被它当作 parent 的类型，规则见 POST …/check）：正文是 AccessTreePut。根类型写 archived、publishOnly；节点类型写 root（在根的顶层时必填，有 parent 时以父节点的根为准）、parent、inherit（省略为 true）、trashed。移到别的父节点或别的根时整棵子树跟着走，平台重新计算受影响节点的集合。只收应用自己的令牌（页面会话是 403 forbidden：移动会改变节点继承的名单，树的形状由应用按自己的规则维护）。返回 AccessTreeChanged，changed 是集合变了的节点 id 到新集合 id。一次改动最多重新计算 5000 个节点（整个根 20000 个），超过是 422 invalid。English: on a tree type the body puts a root's state or a node's place and state (idempotent, the app's token only); the answer lists the nodes whose set changed.

• 认证：bearer
• 范围：app.resources:write
• operationId：registerResource

参数

请求正文（application/json）

响应

200 响应正文（application/json）

DELETE /access/{type}/{id}复制本节链接

删除一个资源的登记（连同名单和申请）

需要范围 app.resources:write。English: drops the resource's row: its list and its requests.

页面会话需要对这个资源有管理级别，否则 404 not_found；应用自己的令牌不受级别限制。返回 204。

树类型：只收应用自己的令牌（页面会话是 403 forbidden）。删除节点只删这一个（应用写出整棵子树的每个节点），删除根连同它下面的全部节点和名单。English: on a tree type only the app's token removes; a node is removed alone (the app names the whole subtree), a root with every node under it.

• 认证：bearer
• 范围：app.resources:write
• operationId：dropResource

参数

响应

PUT /access/{type}/{id}/grants复制本节链接

整体替换树类型一个根或节点的显式名单

需要范围 app.resources:write。English: replaces every explicit entry of a root or node of a tree type and recomputes the sets that changes.

只用于树类型（平铺类型是 404 not_found）。entries 是全部条目：kind 为 user、unit（部门，含下级）、role、everyone（principal 为空字符串），level 为 view、comment、edit、manage，name 是显示名的快照。应用自己的令牌可以调用，并可用 by 写明替谁改；页面会话需要管理级别（名单给出的级别），看不到是 404 not_found，不能管理是 403 forbidden。返回 AccessTreeChanged；平台把事件 access.changed 送给应用，并记审计 access.tree.entries。

• 认证：bearer
• 范围：app.resources:write
• operationId：replaceResourceEntries

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

示例：

复制代码

{
  "type": "wiki.page",
  "id": "pg_1",
  "changed": {
    "pg_1": "5f0c2a9e41d7b3c8a6e2f104",
    "pg_2": "5f0c2a9e41d7b3c8a6e2f104"
  }
}

POST /access/{type}/{id}/grants复制本节链接

分享给一个人、部门、角色或所有人

需要范围 app.resources:write。English: adds or changes one grant on the resource.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

平铺类型上，应用自己的令牌也可以调用：以应用的名义加一条或改一条（不看调用者的级别，规则由应用自己定，例如会员的敏感记录只有持有管理授权权限的人能授），资源没登记时一并登记（所有者为 app:{应用 id}）；by 写明替谁授（名单上的 createdBy），note 是说明。级别、对象和到期时间的规则同上；不通知对方。审计动作 access.share。English: on a flat type the app's own token adds or replaces a grant as the app (registering the resource), with by and note.

kind 是 user、unit（部门）、role、everyone（所有人）之一，level 是 view、comment、edit 或 manage，expiresAt 省略为不过期。调用者需要有分享的权力（管理级别，或类型开着允许分享的开关）。给人的分享会通知对方。

树类型：在根或节点的显式名单上加一条或改一条（同一 kind + principal 只有一条），正文同上，expiresAt 是这一条的到期时间。级别不能超过类型声明的 levels。应用自己的令牌可以调用；页面会话需要对这个根或节点有管理级别（名单给出的级别，不看状态），或者在开了 reshare 的根下能编辑这个节点（只能给到、改到 edit），看不到是 404 not_found，看得到但不能管理是 403 forbidden。返回 AccessTreeChanged。审计动作 access.tree.entries。English: on a tree type adds or changes one explicit entry; a person needs manage.

• 认证：bearer
• 范围：app.resources:write
• operationId：shareResource

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

DELETE /access/{type}/{id}/grants/{kind}/{principal}复制本节链接

撤销一条分享

需要范围 app.resources:write。English: removes one grant.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

平铺类型上，应用自己的令牌也可以调用：以应用的名义删掉一条（没有这条是 404 not_found）。审计动作 access.revoke。English: on a flat type the app's own token removes a grant as the app.

对象是 everyone 的分享，principal 写 -。

树类型：从根或节点的显式名单删掉一条（没有这条是 404 not_found），权限规则同 POST …/grants，返回 AccessTreeChanged。English: on a tree type removes one explicit entry.

• 认证：bearer
• 范围：app.resources:write
• operationId：revokeResourceGrant

参数

响应

200 响应正文（application/json）

PUT /access/{type}/{id}/general复制本节链接

设置通用访问（企业内知道链接的人能做什么）

需要范围 app.resources:write。English: sets the general access of the resource.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

level 是空字符串（只有名单上的人）、view、comment 或 edit；类型不开放评论时不能设 comment。

• 认证：bearer
• 范围：app.resources:write
• operationId：setResourceGeneral

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

PUT /access/{type}/{id}/toggles复制本节链接

设置资源的开关

需要范围 app.resources:write。English: sets the switches the type declares (resources[].switches), e.g. explore, and returns the list.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

正文是 {开关名: true|false}，只能写类型声明过的开关。

• 认证：bearer
• 范围：app.resources:write
• operationId：setResourceToggles

参数

请求正文（必填）（application/json）

类型 ResourceToggles。开关名到值，只能写类型声明过的开关

响应

200 响应正文（application/json）

POST /access/{type}/{id}/owner复制本节链接

转让资源的所有权

需要范围 app.resources:write。English: transfers the owner of the resource to another person; notifies them.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

只有所有者（或管理员）能转让。to 必填，name 是对方的显示名。

• 认证：bearer
• 范围：app.resources:write
• operationId：transferResource

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /access/{type}/{id}/requests复制本节链接

读调用者自己对一个资源的申请

需要范围 app.resources:read。English: the caller's own requests on the resource, newest first, at most 100.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

• 认证：bearer
• 范围：app.resources:read
• operationId：listResourceRequests

参数

响应

200 响应正文（application/json）

POST /access/{type}/{id}/requests复制本节链接

为自己申请访问一个资源

需要范围 app.resources:write。English: files a request for access (or a higher level) on the resource, as the caller; notifies the people who decide.

正文与规则同平台内置应用的 /api/access/{type}/{id}…（同一套访问内核：规则、审计、通知都一样）。只收页面会话：应用自己的令牌是 403 forbidden（分享是人做的事）。类型不是本应用声明的，或资源没登记，一律 404 not_found。名单变了以后，平台把事件 access.changed 送给应用（见 webhooks）。

类型没有开放申请，或调用者已经有这个级别，是 409 conflict；被拒绝后 24 小时内不能再申请（retryAfter）。level 省略是 view。

• 认证：bearer
• 范围：app.resources:write
• operationId：requestResourceAccess

参数

请求正文（application/json）

响应

200 响应正文（application/json）

GET /access/requests复制本节链接

读调用者能处理的待处理申请

需要范围 app.resources:read。English: every pending request on this app's types that the caller may decide, with the resource's title, oldest first.

正文与规则同平台内置应用的 /api/access/requests…。只收页面会话：应用自己的令牌是 403 forbidden（申请和处理都是人做的事）。只含本应用在清单里声明、开放申请（requestable）的类型。平面类型由访问内核的名单决定谁处理（所有者和管理者）；树类型（知识库页面）的名单是应用自己的树，由应用通过提供者 accessRequests 回答调用者在资源上的级别、通知谁、批准怎么写入；应用不提供时，树类型不收申请（404）。

• 认证：bearer
• 范围：app.resources:read
• operationId：listDecidableResourceRequests

响应

200 响应正文（application/json）

GET /access/requests/mine复制本节链接

读调用者自己的申请

需要范围 app.resources:read。English: the caller's own requests on this app's types, newest first, at most 100 (no titles).

正文与规则同平台内置应用的 /api/access/requests…。只收页面会话：应用自己的令牌是 403 forbidden（申请和处理都是人做的事）。只含本应用在清单里声明、开放申请（requestable）的类型。平面类型由访问内核的名单决定谁处理（所有者和管理者）；树类型（知识库页面）的名单是应用自己的树，由应用通过提供者 accessRequests 回答调用者在资源上的级别、通知谁、批准怎么写入；应用不提供时，树类型不收申请（404）。

• 认证：bearer
• 范围：app.resources:read
• operationId：listMyResourceRequests

响应

200 响应正文（application/json）

POST /access/requests/{rid}/approve复制本节链接

批准一条申请

需要范围 app.resources:write。English: approves a pending request the caller may decide: the level (at most what was asked; omitted: what was asked), optionally until expiresAt.

正文与规则同平台内置应用的 /api/access/requests…。只收页面会话：应用自己的令牌是 403 forbidden（申请和处理都是人做的事）。只含本应用在清单里声明、开放申请（requestable）的类型。平面类型由访问内核的名单决定谁处理（所有者和管理者）；树类型（知识库页面）的名单是应用自己的树，由应用通过提供者 accessRequests 回答调用者在资源上的级别、通知谁、批准怎么写入；应用不提供时，树类型不收申请（404）。调用者不能处理是 404；已处理过是 409。树类型由应用写入批准，应用拒绝（例如超出处理人能给的级别）时原样返回它的状态和说明。

• 认证：bearer
• 范围：app.resources:write
• operationId：approveResourceRequest

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /access/requests/{rid}/deny复制本节链接

拒绝一条申请

需要范围 app.resources:write。English: refuses a pending request the caller may decide, with the reason the requester is told (required, at most 200 characters).

正文与规则同平台内置应用的 /api/access/requests…。只收页面会话：应用自己的令牌是 403 forbidden（申请和处理都是人做的事）。只含本应用在清单里声明、开放申请（requestable）的类型。平面类型由访问内核的名单决定谁处理（所有者和管理者）；树类型（知识库页面）的名单是应用自己的树，由应用通过提供者 accessRequests 回答调用者在资源上的级别、通知谁、批准怎么写入；应用不提供时，树类型不收申请（404）。

• 认证：bearer
• 范围：app.resources:write
• operationId：denyResourceRequest

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

DELETE /access/requests/{rid}复制本节链接

撤回自己的申请

需要范围 app.resources:write。English: withdraws the caller's own pending request.

正文与规则同平台内置应用的 /api/access/requests…。只收页面会话：应用自己的令牌是 403 forbidden（申请和处理都是人做的事）。只含本应用在清单里声明、开放申请（requestable）的类型。平面类型由访问内核的名单决定谁处理（所有者和管理者）；树类型（知识库页面）的名单是应用自己的树，由应用通过提供者 accessRequests 回答调用者在资源上的级别、通知谁、批准怎么写入；应用不提供时，树类型不收申请（404）。

• 认证：bearer
• 范围：app.resources:write
• operationId：cancelResourceRequest

参数

响应

200 响应正文（application/json）

GET /access/{type}复制本节链接

一个资源类型的声明

需要范围 app.resources:read。English: the declared kind as the platform keeps it: what one resource of it is called (name in Chinese, nameEn in English, from the manifest's resources[]; empty when not declared), its levels and switches, whether it takes requests or can be published, and whether it is a tree type (tree, with parent on a node type).

平台的分享对话框用 name / nameEn 称呼这个资源（「这个笔记」）；没写时说「这个内容」。levels 没声明时是全部四级，switches 没声明时是空对象。本应用当前安装的版本没有声明这个类型（或类型不以 {本应用 id}. 开头）是 404 not_found：分享对话框据此区分「类型没登记」和「这一项找不到」。

• 认证：bearer
• 范围：app.resources:read
• operationId：getResourceKind

参数

响应

200 响应正文（application/json）

POST /access/{type}/check复制本节链接

批量查一个人对多个资源的级别

需要范围 app.resources:read。English: the level of a person on each of up to 500 resources of one type (replaces a visibility SQL join).

ids 1 到 500 个。level 可省略；写了就另外给出每个 id 是否达到了这个级别（allowed）。页面会话查的是自己；应用自己的令牌必须在 user 写明查谁，否则 422 invalid。未登记的资源，级别是空字符串。单次读取要鉴权时用它，列表过滤用 GET …/visible。

树类型（清单里带 parent 的节点类型，和被它当作 parent 的根类型）：平台保存根和节点、它们的显式名单和状态，并把每个根和节点的有效名单存成不可变、去重的集合。节点继承父节点（顶层继承根）的名单再加上自己的条目；inherit 为 false 的节点只看自己的条目。每个 id 的级别是名单给出的级别经状态限制后的结果，reasons 给出原因：节点在回收站（trashed）时管理级别以下没有权限（原因 trashed）；根归档（archived）时最多 comment（原因 archived）；根只读发布版（publishOnly）时 edit 以下和智能体读已发布版本（原因 published_only，级别不变）。智能体最多 comment（正文 agent: true）。企业管理员绕过名单，等于处处 manage，同样受状态限制。不存在的根或节点级别为空字符串。English: on a tree type each id's level is the lists' level clamped by the states (trashed: nothing below manage; archived: at most comment; publish-only: read as published below edit and for an agent), with the reason.

• 认证：bearer
• 范围：app.resources:read
• operationId：checkResourceAccess

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /access/{type}/visible复制本节链接

分页列出一个人能看到的资源 id

需要范围 app.resources:read。English: the ids of the type's resources the person may see at least at the level, in id order, paged by cursor.

level 默认 view，limit 默认 200、最多 1000，cursor 用上一页的 next。页面会话列的是自己；应用自己的令牌必须带 user，否则 422 invalid。应用若维护自己的可见性镜像，用它刷新（再配合事件 access.changed），最终一致；单次读取仍应用 check。

树类型：列出这个类型（根类型列根、节点类型列节点）里此人经状态限制后达到 level 的 id，按 id 分页；企业管理员看到全部（仍受状态限制）。English: on a tree type the nodes (or roots) the person sees at the level after the states.

• 认证：bearer
• 范围：app.resources:read
• operationId：listVisibleResources

参数

响应

200 响应正文（application/json）

POST /access/{type}/naming复制本节链接

列出点到某个人的分享（按资源）

需要范围 app.resources:read。English: the grants of a flat type that name a person, their departments or their roles (expired ones too), by resource id; for an app that keeps the rules over the kernel's list (a member's sensitive records) and works a person's explicit level out before its own transaction.

只收应用自己的令牌（页面会话是 403 forbidden）。user 必填；units 是此人所在的部门（含上级：部门的条目也给下级）、roles 是此人的角色（企业角色 id，平台角色写作 platform:<角色>），都由应用自己算好传来，每项最多 500 个。ids 可省略：省略时查这个类型的全部资源，写了就只查这些（最多 500 个）。返回 grants：资源 id 到点到此人的分享（user 本人、所在部门、角色或 everyone），过期的也在内，由应用按自己的时钟判断；没有分享的资源不出现。企业管理员不因身份多出条目（这里只列名单，不做判断）。树类型 404 not_found。English: the app's own token only; units and roles are the app's own reading of the person; ids optional (absent: every resource of the type).

• 认证：bearer
• 范围：app.resources:read
• operationId：listResourceGrantsNaming

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "user": "u_1",
  "units": [
    "d_ops"
  ],
  "roles": [
    "platform:tenant.member"
  ],
  "ids": [
    "mb_1"
  ]
}

响应

200 响应正文（application/json）

POST /access/{type}/departure复制本节链接

收回点到一个离开的人的全部分享

需要范围 app.resources:write。English: the offboarding handover's part of a flat type whose rules are the app's: every grant naming the person (kind user, expired ones too) goes, and their pending access requests on the type are withdrawn (decided by to).

只收应用自己的令牌（页面会话是 403 forbidden）。user 和 to 必填且不能相同，否则 422 invalid。重复调用没有副作用。名单变了的每个资源都会发事件 access.changed，并写审计 access.departure。树类型 404 not_found。English: the app's own token only; idempotent; access.changed for every resource whose list changed.

• 认证：bearer
• 范围：app.resources:write
• operationId：departResourceGrants

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "user": "u_1",
  "to": "u_2"
}

响应

200 响应正文（application/json）

GET /access/{type}/mine复制本节链接

一个人在树模型每个集合里的级别

需要范围 app.resources:read。English: the person's level in every set of the tree model that names them, a page at a time (the app filters its own lists by the set id it keeps for each node).

type 是本应用的一个树类型，或 *（集合对所有类型是同一份）。页面会话查的是自己；应用自己的令牌必须带 user，否则 422 invalid。一页最多 10000 个集合，truncated 为 true 时用 next 作 after 再取。企业管理员绕过名单，集合里不体现：bypass 为 true 时应用把此人当作处处 manage（再受状态限制）。

• 认证：bearer
• 范围：app.resources:read
• operationId：mineResourceSets

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "sets": {
    "5f0c2a9e41d7b3c8a6e2f104": "edit"
  },
  "truncated": false,
  "next": "",
  "bypass": false
}

PUT /access/{type}/{id}/inherit复制本节链接

节点停止或恢复继承上面的名单

需要范围 app.resources:write。English: a node of a tree type stops or restores inheriting what is above it (the platform's share dialog: 「仅名单上的人可访问」). Its place does not change; moving stays the app's.

只用于树类型的节点类型。页面会话的人要能管理这个节点（状态限制之前的级别），应用自己的令牌不受限。停止继承时，节点现在的有效名单成为它自己的名单（名字从写下每一条的地方取），停止的人保留管理级别，所以开关本身不会让谁失去访问；没有管理者时是 422。恢复继承时，去掉上面已经以相同或更高级别给出的条目。和现在相同时什么也不改。之后发 access.changed，记审计 access.tree.inherit。返回集合变了的节点。

• 认证：bearer
• 范围：app.resources:write
• operationId：setResourceInherit

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "inherit": false
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "type": "wiki.page",
  "id": "pg_1",
  "changed": {
    "pg_1": "5f0c2a9e41d7b3c8a6e2f104",
    "pg_2": "5f0c2a9e41d7b3c8a6e2f104"
  }
}

POST /access/{type}/{id}/reconcile复制本节链接

用应用自己的树校正平台里一个根下的节点

需要范围 app.resources:write。English: makes the kernel's nodes of one root what the app's tree says (an app outside the platform writes the kernel first and its own rows after; a periodic reconcile repairs a failure between the two).

只用于树类型的根类型（id 是根），只收应用自己的令牌（页面会话是 403 forbidden）。spec 是根的状态，nodes 是这个根下应用的全部节点（inherit 省略为 true）：没列出的节点被删除，其余的按位置、继承和回收站状态写入。显式名单不校正（只存在平台里）。返回改了几个节点；大于 0 时记审计 access.tree.reconcile。

• 认证：bearer
• 范围：app.resources:write
• operationId：reconcileResourceTree

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

errors复制本节链接

本应用的错误：脱敏后给开发者组织（开发者平台「错误」、k3 logs --errors）

POST /errors复制本节链接

向开发者平台报告本应用的错误

需要范围 app.errors:report。English: reports the app's own errors to its developer organisation (ADR-0130 H8).

平台在保存前脱敏：message 与 frames 里的值（引号里的内容、数字、邮箱、网址、令牌、key=value 的值，以及 message 里所有非 ASCII 的文字，如中文）换成占位符；想让开发者读得懂，就报 code + 固定的 template（应用代码里的常量，原文保留）+ params，route 里像值的段换成 :id，code 与 kind 只收标识符。开发者平台只看到脱敏后的样子，看不到企业；params 是消息引用的值，永远不进开发者视图，只在企业批准的限时诊断里（去掉密钥后）给开发者看。一次 1–50 条，回答 202。每个应用每分钟最多保存 120 条，超过的不保存。

• 认证：bearer
• 范围：app.errors:report
• operationId：reportErrors

参数

请求正文（必填）（application/json）

响应

202 响应正文（application/json）

logs复制本节链接

本应用主动写的结构化日志：按企业脱敏后留 24 小时，给开发者组织实时看（开发者平台「实时日志」、k3 tail）

POST /logs复制本节链接

写本应用的结构化日志

需要范围 app.logs:write。English: writes the app's own structured log lines for its developer organisation (ADR-0149 §3); the developer reads them live (k3 tail, GET /api/dev/apps/{id}/tail). The process's stdout and stderr never reach the developer: only what the app writes here.

平台在保存前按企业脱敏：开发者组织自己的测试企业保留原文，只去掉密钥一类（令牌、sk-live-… 之类的密钥、password=…）；其他企业的 message 和每个字段值都脱敏（手机号、身份证、邮箱、长数字、引号里的值、key=value 的值、所有非 ASCII 文字换成占位符），字段名保留（不是标识符的字段名也脱敏），企业只给不透明的 tenantRef，原文不落库。template: true 声明消息是固定模板（应用代码里的常量）：模板里的中文保留，值仍脱敏，字段值照样脱敏。一次 1–100 行；message 最多 2 KiB、字段最多 20 个、每个值最多 256 字节，超出截断并标记。每个应用每秒最多保存 50 行，超出的丢弃并计数（开发者在实时日志里看到「丢了 N 行」），回答里的 dropped 是这一批丢了几行。回答 202。

• 认证：bearer
• 范围：app.logs:write
• operationId：writeLogs

参数

请求正文（必填）（application/json）

响应

202 响应正文（application/json）

traces复制本节链接

本应用对请求追踪加的段：处理请求的那一段和应用自己加的步骤（ADR-0155 §2）

POST /traces复制本节链接

写本应用的请求追踪段

需要范围 app.traces:write。English: sends the app's own spans of the platform's request traces (ADR-0155 §2): the handler of a request (kind server, the SDK's middleware) and the steps the app adds (kind internal, appkit.Trace.Span). The platform records the edge's, the gateway's and every /app/v1 call's span itself.

平台的网关为托管应用的每个请求开一个追踪，交给应用 traceparent 和带平台标记的 tracestate（raise=…）。每个段要带上它所在请求的 traceId 和这个标记（mark）：标记由平台为「本应用 + 这个令牌的企业 + 这个追踪」签发，对不上的段拒收（refused）。平台在尾部决定保留哪些追踪（所有 5xx、慢于本应用 p99 的，其余线上 1 %，测试企业按开发者的设置），段先缓冲 30 秒等决定。段名是应用代码里的常量：线上企业的段名保留文字、值脱敏；属性只收登记过的名字（http.method http.route http.status_code k3.version k3.op k3.dataset k3.table k3.event k3.service k3.provider k3.items db.system db.operation error.code error.type peer.service cache.hit retry.count messaging.operation rpc.method），值按企业脱敏，其他名字丢弃并计入 truncated。一次 1–200 段；每个应用在每个副本上每秒最多缓冲 500 段，超出的丢弃并计数。回答 202。

• 认证：bearer
• 范围：app.traces:write
• operationId：writeTraceSpans

参数

请求正文（必填）（application/json）

响应

202 响应正文（application/json）

analytics复制本节链接

本应用自定义的分析数据点：按清单登记的数据集写入，按企业脱敏后留 31 天，开发者组织按字段名查询（k3 analytics query）

POST /analytics复制本节链接

写本应用的分析数据点

需要范围 app.analytics:write。English: writes data points into the datasets the app's manifest declares (analytics: [{name, blobs, doubles}], ADR-0155 §1), for its developer organisation to query by field name (POST /api/dev/apps/{id}/analytics/query, k3 analytics query).

一个点属于一个数据集：最多 1 个索引 index（≤ 96 字节）、按登记顺序的字符串 blobs（最多 20 个，每个 ≤ 256 字节，超出截断）和数值 doubles（最多 20 个，有限数）。平台补上企业（只给不透明的 tenant 引用）、版本和 test/live。开发者组织自己的测试企业保留字符串原文（只去掉密钥一类）；其他企业的 index 和每个字符串都按日志的规则脱敏，原文不落库；数值原样保存。没登记的数据集、比登记多的值、超长的索引丢弃并计数；每个应用每秒最多保存 200 点，超出的丢弃并计数（开发者查询时看到 dropped）。保留 31 天，只追加不改。一次 1–250 点，回答 202。

• 认证：bearer
• 范围：app.analytics:write
• operationId：writeAnalytics

参数

请求正文（必填）（application/json）

响应

202 响应正文（application/json）

blobs复制本节链接

企业文件存储里本应用自己的文件夹：存取、元数据、列出、复制、删除，以及直传用的预签名地址

GET /blobs/objects/{key...}复制本节链接

读取本应用文件夹里一个对象的字节

需要范围 app.blobs:read。English: streams the bytes of the object key of the app's folder.

回答的正文是对象的原始字节，Content-Type、Content-Length、Last-Modified 取自对象，并带 X-Content-Type-Options: nosniff。对象不存在是 404 not_found。 SDK：Go App.Blobs.Get 回答 RawResponse（调用方读完 Body 后关闭），TS app.blobs.get 回答 fetch 的 Response。只要元数据用 blobs.head。

• 认证：bearer
• 范围：app.blobs:read
• operationId：getBlob

参数

响应

200 响应正文（application/octet-stream）

类型 string(binary)

PUT /blobs/objects/{key...}复制本节链接

把一段字节存成本应用文件夹里的一个对象

需要范围 app.blobs:write。English: stores the request body, raw bytes, as the object key in the app's folder of the tenant's file store (the platform's, or the tenant's own bucket).

路径里的 {key...} 吃掉余下的整个路径，键必须以 apps/{本应用 id}/ 开头，且其后至少还有一个字符；不能有空的、. 或 .. 段，不能有反斜杠和控制字符，最长 1024 字节。正文就是对象的字节（不是 JSON），Content-Type 请求头是对象的类型（没有时按 application/octet-stream），必须带 Content-Length（没有是 411）。经平台存的单个对象最大 512 MiB，更大的用 POST /blobs/presign 拿上传地址直传。企业的存储额度对两条路都有效。成功回答 204，没有正文。 SDK：Go App.Blobs.Put（io.Reader、长度、类型），TS app.blobs.put（Blob、ArrayBuffer、Uint8Array 或流）。

• 认证：bearer
• 范围：app.blobs:write
• operationId：putBlob

参数

请求正文（必填）（application/octet-stream）

类型 string(binary)

对象的字节

响应

DELETE /blobs/objects/{key...}复制本节链接

删除本应用文件夹里的一个对象

需要范围 app.blobs:write。English: deletes the object key; deleting what is not there is done.

成功回答 204，没有正文；对象本来就不存在也是 204。

• 认证：bearer
• 范围：app.blobs:write
• operationId：deleteBlob

参数

响应

GET /blobs/meta/{key...}复制本节链接

读取一个对象的元数据

需要范围 app.blobs:read。English: the size, type and last write time of the object key, without its bytes.

对象不存在是 404 not_found。

• 认证：bearer
• 范围：app.blobs:read
• operationId：headBlob

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "key": "apps/crm/exports/2026-10.csv",
  "size": 20480,
  "contentType": "text/csv",
  "modTime": "2026-10-31T08:00:00Z"
}

GET /blobs复制本节链接

列出本应用文件夹里某个前缀下的对象

需要范围 app.blobs:read。English: lists the objects below a prefix of the app's folder.

prefix 省略时列出整个文件夹 apps/{本应用 id}/；给了就必须在本应用的文件夹里，可以以 / 结尾。返回 {items}。

• 认证：bearer
• 范围：app.blobs:read
• operationId：listBlobs

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "items": [
    {
      "key": "apps/crm/exports/2026-10.csv",
      "size": 20480,
      "contentType": "text/csv",
      "modTime": "2026-10-31T08:00:00Z"
    }
  ]
}

POST /blobs/copy复制本节链接

在本应用的文件夹里复制一个对象

需要范围 app.blobs:write。English: copies the object src to dst, both in the app's folder.

src 不存在是 404 not_found。成功回答 204，没有正文。

• 认证：bearer
• 范围：app.blobs:write
• operationId：copyBlob

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "src": "apps/crm/exports/2026-10.csv",
  "dst": "apps/crm/archive/2026-10.csv"
}

响应

POST /blobs/delete-prefix复制本节链接

删除本应用文件夹里某个前缀下的全部对象

需要范围 app.blobs:write。English: deletes every object below prefix of the app's folder.

prefix 可以就是整个文件夹 apps/{本应用 id}/（删光本应用的文件）。成功回答 204，没有正文。

• 认证：bearer
• 范围：app.blobs:write
• operationId：deleteBlobPrefix

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "prefix": "apps/crm/tmp/"
}

响应

POST /blobs/presign复制本节链接

为一个对象拿一个不带令牌的上传或下载地址

需要范围 app.blobs:read；method 为 PUT（上传）时还需要 app.blobs:write，缺了是 403。English: a URL to PUT (upload) or GET (download) one object of the app's folder, usable without a token until expiresAt.

字节直接走到文件存储，不经平台，所以没有 512 MiB 的限制；企业的存储额度仍然有效。ttlSeconds 省略时取最大值：上传 900 秒、下载 300 秒，超过是 422。上传必须给 size（确切字节数，≤ 512 MiB）：大小签进地址，长度不符的上传被存储拒绝；放不进企业剩余额度的在签发前就是 413。下载地址要求对象已存在，不存在是 404 not_found。

• 认证：bearer
• 范围：app.blobs:read
• operationId：presignBlob

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "key": "apps/crm/imports/2026-10.csv",
  "method": "PUT",
  "ttlSeconds": 900,
  "size": 48213
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "url": "https://files.example.com/apps/crm/exports/2026-10.csv?X-Signature=abc123",
  "method": "GET",
  "expiresAt": "2026-10-31T08:10:00Z"
}

notify复制本节链接

以本应用的名义给企业成员发站内通知

POST /notify复制本节链接

以本应用的名义给企业成员发一条站内通知

需要范围 app.notify:send。English: tells people of the tenant something in the platform's message centre, as the app (its name, a link into it); best effort.

users 是企业成员的用户 id（空白项忽略，去掉后至少 1 个，最多 500 个），title 必填，body 是正文，link 只能是应用内的路由（以 / 开头）、k3:// 引用，或本应用清单 egress 里声明的域名下的 https:// 地址，其余 422。class 说明通知的性质，供推送到平台以外的渠道使用：approval.task、approval.result、mention，省略由渠道决定。只发给本企业的在职成员：其余的人数计入 rejected，不说明原因。同一个调用方（页面会话的人或应用本身）十分钟内最多通知 1000 人次，超过是 429 并带 Retry-After。回答 202，accepted 是收到通知的人数。

• 认证：bearer
• 范围：app.notify:send
• operationId：sendNotice

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "users": [
    "u_1001",
    "u_1002"
  ],
  "title": "有 3 张工单等你处理",
  "body": "客户“李明”的报修已分配给你",
  "link": "/tickets?status=open",
  "class": "approval.task"
}

响应

202 响应正文（application/json）

示例：

复制代码

{
  "accepted": 2,
  "rejected": 0
}

drafts复制本节链接

草稿：为成员起草变更由本人确认，以及当前人员审阅、修改、放弃、应用涉及本应用的草稿项，和记录的来源

GET /drafts复制本节链接

列出当前人员涉及本应用的草稿

需要范围 app.drafts:read。English: the person's drafts that have an item of this app.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。返回 {drafts}，最多 50 条；每条里本应用的项是完整的，其他应用的项只有数量。

• 认证：bearer
• 范围：app.drafts:read
• operationId：listDrafts

参数

响应

200 响应正文（application/json）

POST /drafts复制本节链接

为一位成员起草一批变更，由本人确认后才生效

需要范围 app.drafts:write。English: proposes changes with the app's own ops for a person to confirm, as the agent does.

正文是草稿服务自己的创建正文（sessionId、turn、summary、items）外加 for，即草稿属于的人。草稿是这个人的，由本应用代写（委托，作者是 app:{应用 id}）：本人在工作台或本应用的页面里审阅并应用；没有他们预先签下的策略，什么都不会自动生效。每个 items[].app 只能是本应用（省略时补上），否则 422。应用自己的令牌必须给 for（企业的在职成员；不是的一律 403 forbidden，不说明这个人是否存在）；页面会话的 for 省略或等于本人，给别人是 422。本应用十分钟内给同一个人最多起草 30 份，超过是 429 并带 Retry-After。应用凭证不因此获得这个人的任何权限：草稿只给本人审阅，委托方不能应用。草稿有待办项时，平台会通知本人“有 N 项变更等你确认”。返回 201 和草稿视图。

• 认证：bearer
• 范围：app.drafts:write
• operationId：createDraft

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "for": "u_1001",
  "summary": "把李明的会员有效期延长到 2027-03-31",
  "items": [
    {
      "key": "extend",
      "op": "member.update",
      "target": "k3://members/member/m_42",
      "reason": "客户投诉后补偿",
      "proposed": {
        "validUntil": "2027-03-31"
      }
    }
  ]
}

响应

201 响应正文（application/json）

示例：

复制代码

{
  "id": "d_01HZX",
  "owner": "u_1001",
  "summary": "把李明的会员有效期延长到 2027-03-31",
  "status": "open",
  "items": [
    {
      "id": "i_1",
      "app": "crm",
      "op": "member.update",
      "target": "k3://members/member/m_42",
      "revision": 1,
      "state": "pending",
      "fields": {},
      "mark": "ready",
      "applicable": true
    }
  ],
  "createdAt": "2026-10-31T08:00:00Z",
  "updatedAt": "2026-10-31T08:00:00Z"
}

GET /drafts/{id}复制本节链接

读取一份草稿：本应用的项是完整的

需要范围 app.drafts:read。English: one draft with this app's items in full (the review page).

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。revalidate=1 先把检查重跑一遍再回答。

• 认证：bearer
• 范围：app.drafts:read
• operationId：getDraft

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "d_01HZX",
  "owner": "u_1001",
  "summary": "把李明的会员有效期延长到 2027-03-31",
  "status": "open",
  "items": [
    {
      "id": "i_1",
      "app": "crm",
      "op": "member.update",
      "target": "k3://members/member/m_42",
      "revision": 1,
      "state": "pending",
      "fields": {},
      "mark": "ready",
      "applicable": true
    }
  ],
  "createdAt": "2026-10-31T08:00:00Z",
  "updatedAt": "2026-10-31T08:00:00Z"
}

PATCH /drafts/{id}/items/{item}复制本节链接

记下本人对一个草稿项的值和选择

需要范围 app.drafts:review。English: the person's values and choices for one item.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。revision 是本人看到的版本；fields 是他们填的值；pick 按字段说选哪个值（base 保持原样，某一轮则取那一轮的提议，空串取最新）。返回 {item}。

• 认证：bearer
• 范围：app.drafts:review
• operationId：reviewDraftItem

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "revision": 1,
  "fields": {
    "validUntil": "2027-06-30"
  }
}

响应

200 响应正文（application/json）

POST /drafts/{id}/items/{item}/abandon复制本节链接

放弃一个草稿项

需要范围 app.drafts:review。English: drops one item.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。返回 {ok: true}。

• 认证：bearer
• 范围：app.drafts:review
• operationId：abandonDraftItem

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "ok": true
}

POST /drafts/{id}/items/{item}/rebase复制本节链接

以记录现在的样子为基础继续这个草稿项

需要范围 app.drafts:review。English: goes on from the record as it is now.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。返回 {item}。

• 认证：bearer
• 范围：app.drafts:review
• operationId：rebaseDraftItem

参数

响应

200 响应正文（application/json）

POST /drafts/{id}/apply复制本节链接

应用本人审阅过的草稿项

需要范围 app.drafts:review。English: applies this app's items the person reviewed, with the pending items they depend on.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。items 里每项是 {id, revision, confirmed?}，revision 必须是本人看到的版本。返回草稿的新状态和每一项的结果（results 按项 id 索引）。

• 认证：bearer
• 范围：app.drafts:review
• operationId：applyDraft

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "items": [
    {
      "id": "i_1",
      "revision": 1,
      "confirmed": true
    }
  ]
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "status": "applied",
  "results": {
    "i_1": {
      "applied": true,
      "ref": "k3://members/member/m_42",
      "summary": "有效期延至 2027-03-31"
    }
  }
}

GET /provenance复制本节链接

查一条记录是谁写的

需要范围 app.drafts:read。English: who wrote a record of this app: a draft the person applied, or a policy they pre-signed.

只收页面会话：这里的“人”是令牌里的人，应用自己的令牌是 403 forbidden。ref 必填，是记录的 k3:// 引用。返回 {provenance}。

• 认证：bearer
• 范围：app.drafts:read
• operationId：getProvenance

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "provenance": [
    {
      "ref": "k3://members/member/m_42",
      "at": "2026-10-31T08:05:00Z",
      "app": "crm",
      "op": "member.update",
      "via": "draft",
      "draftId": "d_01HZX",
      "itemId": "i_1",
      "subject": "u_1001",
      "name": "王芳"
    }
  ]
}

outreach复制本节链接

触达：向客户排短信或公众号模板消息，读渠道、模板和消息记录（是否发出由平台在发送时判断）

POST /outreach/send复制本节链接

向一位客户排一条触达消息

需要范围 app.outreach:send。English: queues a message to a customer by a template of the tenant's; the platform decides at send time whether it may go.

应用不发送，也看不到手机号：同意、退订、免打扰、频次和企业上限都由平台在发送时判断。key 是这条消息的幂等键，必填；同键再来不会加新消息，回 200 和当初那条的 id（existing 为 true）；新排上的回 202。purpose 是 service（服务通知）或 marketing（营销）。

• 认证：bearer
• 范围：app.outreach:send
• operationId：sendOutreach

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "key": "o:k3://order/order/o_1|c_88|sms",
  "customer": "c_88",
  "channel": "sms",
  "template": "tpl_order_ok",
  "vars": {
    "order": "A1024"
  },
  "purpose": "service",
  "triggerRef": "k3://order/order/o_1"
}

响应

202 响应正文（application/json）

示例：

复制代码

{
  "id": "msg_01HZY",
  "existing": false
}

GET /outreach/channels复制本节链接

列出触达渠道及其是否就绪

需要范围 app.outreach:read。English: the tenant's outreach channels and whether each can send.

返回 {items}。渠道的密钥不会出现，只有 secret.set 和指纹。

• 认证：bearer
• 范围：app.outreach:read
• operationId：listOutreachChannels

响应

200 响应正文（application/json）

示例：

复制代码

{
  "items": [
    {
      "kind": "sms",
      "name": "短信",
      "registered": true,
      "configured": true,
      "enabled": true,
      "ready": true,
      "provider": "aliyun",
      "signature": "示例企业",
      "secret": {
        "set": true,
        "fingerprint": "a1b2c3"
      },
      "capabilities": {
        "needsTemplate": true,
        "receipts": true
      }
    }
  ]
}

GET /outreach/templates复制本节链接

列出消息模板

需要范围 app.outreach:read。English: the tenant's message templates.

channel 只要这个渠道的模板；archived=1 连归档的也要。返回 {items}。

• 认证：bearer
• 范围：app.outreach:read
• operationId：listOutreachTemplates

参数

响应

200 响应正文（application/json）

GET /outreach/templates/{id}复制本节链接

读取一个消息模板

需要范围 app.outreach:read。English: one message template.

不存在是 404 not_found。

• 认证：bearer
• 范围：app.outreach:read
• operationId：getOutreachTemplate

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "tpl_order_ok",
  "channel": "sms",
  "name": "订单确认",
  "purpose": "service",
  "body": "您的订单{order}已确认",
  "channelTemplateId": "SMS_NOTICE",
  "approvalState": "approved",
  "version": 1,
  "active": true,
  "variables": [
    "order"
  ],
  "used": 128,
  "createdAt": "2026-09-01T08:00:00Z",
  "updatedAt": "2026-09-01T08:00:00Z"
}

GET /outreach/messages/{id}复制本节链接

读取一条触达消息的状态

需要范围 app.outreach:read。English: one message of the outreach log, with its state and, when it was not sent, the reason.

不存在是 404 not_found。

• 认证：bearer
• 范围：app.outreach:read
• operationId：getOutreachMessage

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "msg_01HZY",
  "customer": "c_88",
  "channel": "sms",
  "template": "tpl_order_ok",
  "templateName": "订单确认",
  "templateVersion": 1,
  "purpose": "service",
  "vars": {
    "order": "A1024"
  },
  "state": "sent",
  "attempts": 1,
  "cost": 1,
  "sentAt": "2026-10-31T08:00:05Z",
  "createdAt": "2026-10-31T08:00:00Z",
  "updatedAt": "2026-10-31T08:00:05Z"
}

GET /outreach/customers/{id}/messages复制本节链接

本企业一位客户在各渠道收到过的消息（opv2 J2 ⑤）

需要范围 app.outreach:reach。English: the messages a customer of the tenant was sent on every channel, newest first, trimmed.

只限本企业的客户：别的 id 是 404 not_found；合并过的客户按主客户读（返回的 customer 是主客户）。应用自己的调用（企业令牌）可读本企业任何客户；页面会话里的人只能读他在客户应用里「查看客户」（customer.read）数据范围内的客户，范围外的与不存在一样返回 404。每条只有渠道、用途、状态、原因与时间；模板和触发来源只在本应用自己发的消息上给（mine）。没有消息内容、变量和接收号码。

• 认证：bearer
• 范围：app.outreach:reach
• operationId：listCustomerOutreach

参数

响应

200 响应正文（application/json）

POST /outreach/reachable复制本节链接

发送前问：这位客户现在能不能经这个渠道、为这个用途被触达（opv2 J2 ⑤）

需要范围 app.outreach:reach。English: whether the customer can be reached on the channel for the purpose now; nothing is reserved.

按发送时同样的顺序检查，只答能或不能和第一个不能的原因：渠道没开（channel_off）；撤回了同意（withdrawn）；营销消息没有同意（no_consent）；没有手机号或 openid（no_identity）；30 天内被服务商拦截过（blocked）；营销的每日、每周频控（freq_day、freq_week）；企业每日营销上限（tenant_cap）。能触达但在免打扰时段时，later 是会发出的时间。只读，不占频次；真正发送时平台会再查一遍。只限本企业的客户（别的 id 404）；页面会话里的人只限他「查看客户」数据范围内的客户，范围外 404。

• 认证：bearer
• 范围：app.outreach:reach
• operationId：checkReachable

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

options复制本节链接

选项列表：企业为本应用的文本字段维护的可选值

GET /options/{list}复制本节链接

读取企业为本应用某个字段维护的选项列表

需要范围 app.options:read。English: the list of choices the tenant keeps for a text field of the app.

企业从没保存过时，回答的是 default 给的默认值。返回 {items}。

• 认证：bearer
• 范围：app.options:read
• operationId：getOptions

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "items": [
    "门店",
    "线上",
    "转介绍"
  ]
}

PUT /options/{list}复制本节链接

整体替换或追加一个选项列表

需要范围 app.options:write。English: replaces the whole list (items), or adds one option (add).

items 与 add 至少给一个。列表的声明（title、maxLen、defaults）每次随调用带上。带 K3-Dry-Run: 1 时只检查，不保存。返回改动前（old）和改动后（now）的列表。

• 认证：bearer
• 范围：app.options:write
• operationId：putOptions

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "title": "客户来源",
  "maxLen": 20,
  "add": "展会"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "old": [
    "门店",
    "线上"
  ],
  "now": [
    "门店",
    "线上",
    "展会"
  ]
}

models复制本节链接

企业的服务模型：起草文字、读图片、转写语音（计入企业的用量与预算）

GET /models复制本节链接

问企业有没有开放服务模型

需要范围 app.models:use。English: whether a service model is on offer, whether speech is transcribed, and the model's name.

返回 model（有无模型）、transcribe（能否转写语音）、serviceModel（模型名，平台不说时省略）。

• 认证：bearer
• 范围：app.models:use
• operationId：getModelStatus

响应

200 响应正文（application/json）

示例：

复制代码

{
  "model": true,
  "transcribe": true,
  "serviceModel": "service-default"
}

POST /models/complete复制本节链接

用企业的服务模型起草文字

需要范围 app.models:use。English: drafts text with the model the tenant's administrator chose for service scenes.

调用算调用者的：页面会话的人被屏蔽、企业的预算和限流都照常生效，用量按 scene 计。scene 是小写字母开头的字母、数字和下划线（最长 64），system 加 user 最多 256 KiB。图片走 /models/read。企业没有开放模型时是 503，正文里 code 为 model_off（不在 ErrorCode 里，按状态和这个字段判断）；预算或限流的拒绝保留模型路由器的状态和原话。

• 认证：bearer
• 范围：app.models:use
• operationId：completeModel

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "scene": "reply_draft",
  "system": "你是客服，用简短、礼貌的口吻回复。",
  "user": "客户问：订单什么时候发货？"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "text": "您好，订单会在 24 小时内发出，发货后会短信通知您。"
}

POST /models/read复制本节链接

让企业的服务模型读文字加图片

需要范围 app.models:use。English: reads a document with pictures with the service model.

images 每张是 {mime, data}：mime 为 image/png、image/jpeg 或 image/webp，data 是 base64。整个请求最大 24 MiB。企业没有开放模型时是 503，正文里 code 为 model_off（不在 ErrorCode 里，按状态和这个字段判断）；预算或限流的拒绝保留模型路由器的状态和原话。

• 认证：bearer
• 范围：app.models:use
• operationId：readWithModel

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "scene": "reply_draft",
  "system": "你是客服，用简短、礼貌的口吻回复。",
  "user": "客户问：订单什么时候发货？"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "text": "您好，订单会在 24 小时内发出，发货后会短信通知您。"
}

POST /models/transcribe复制本节链接

把一段录音转成文字

需要范围 app.models:use。English: turns the recording in the body into text.

正文是录音的原始字节，Content-Type 必须是 audio/…，最大 25 MB，不能为空。回答 {text}。企业没有开放模型时是 503，正文里 code 为 model_off（不在 ErrorCode 里，按状态和这个字段判断）；预算或限流的拒绝保留模型路由器的状态和原话。 SDK：Go App.Models.Transcribe，TS app.models.transcribe；录音的 Content-Type 由调用方给出。

• 认证：bearer
• 范围：app.models:use
• operationId：transcribeAudio

参数

请求正文（必填）（audio/*）

类型 string(binary)

录音的字节

响应

200 响应正文（application/json）

示例：

复制代码

{
  "text": "您好，订单会在 24 小时内发出，发货后会短信通知您。"
}

intent复制本节链接

意图解析：把当前人员的一句话（可带图片）解析成本应用某个操作的输入建议，由本人确认后再提交

POST /intent/parse复制本节链接

把一句话解析成本应用某个操作的输入建议

需要范围 app.intent:parse。English: turns one sentence of the page session's person (and up to 3 photos) into a proposal for the input of one of this app's ops, the same answer an app in the platform's process gets at /api/intent/parse on its own origin. Nothing is submitted: the person confirms the proposal with the op itself.

只收页面会话：应用自己的令牌是 403，正文里 code 为 person_required（解析按人进行：他能用的操作、他看得到的记录）。app 可省略，省略时就是本应用；写了别的应用是 422。op 必须是本应用清单里的操作：当前人员看不到本应用是 404（code 为 app_not_available），操作不能解析是 422（code 为 op_not_parsable）。规则能读出的（日期、时间、金额、手机号、数量、页面所在的记录）不调模型、不计费；其余的经企业的服务模型（场景 intent）读出，按用量计点，usage 说明这次花了多少。text 最多 2000 个字符；attachments 最多 3 张图片（png、jpeg、webp、gif，每张最大 5 MiB，base64 或 data: URL），整个请求约 21 MiB；context.refs 最多 20 个 k3:// 引用。每人每分钟最多 30 次，超过是 429。Idempotency-Key 收下但不保存回答：解析不写任何东西，重试就是再解析一次（再计一次用量）。企业没有开放模型时只用规则读（by 为 rules）。平台没有接上解析服务时是 501（code 为 capability_off），接上了但没有配置解析器时是 503（code 为 intent_off）；模型这次读不出来是 502，code 为 intent_failed（页面改让人填表）。这几个 code 不在 ErrorCode 里，按状态和这个字段判断。

• 认证：bearer
• 范围：app.intent:parse
• operationId：parseIntent

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "op": "visit.create",
  "text": "张三明天下午三点复诊，做肩颈康复",
  "context": {
    "tz": "Asia/Shanghai"
  }
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "input": {
    "customer": "c_8f2",
    "startsAt": "2026-11-03T15:00:00+08:00"
  },
  "fields": {
    "customer": {
      "source": "stated",
      "ref": "k3://customer/customer/c_8f2",
      "label": "张三"
    },
    "startsAt": {
      "source": "stated"
    }
  },
  "missing": [],
  "by": "model",
  "usage": {
    "points": 0.02,
    "micros": 180
  }
}

pay复制本节链接

收款：经企业自己的支付宝或微信收款账户向客户收款、关闭未付的单、退款（只看得到本应用的收款单）

POST /pay/orders复制本节链接

经企业的收款账户向客户发起一笔收款

需要范围 app.pay:write。English: asks the tenant's customer to pay through the tenant's own Alipay or WeChat Pay account.

本应用是这张收款单的来源应用，只看得到自己的收款单；款项到账后，平台把结果送到本应用声明的 event:payment 服务。key 是这笔收款的幂等键：同一个业务动作只问一次，同键再来回答第一张单；没写时用请求头 Idempotency-Key，都没有是 422。这个键属于企业，别的应用用过的键是 409 conflict。amountCents 是整数分，ttlSeconds 是多久不付就失效。返回 201、收款单和客户的付款页 link；JSAPI 交易另有 payParams（交给微信的已签名参数，JSON 文本）。

• 认证：bearer
• 范围：app.pay:write
• operationId：createPayOrder

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "channel": "wechat",
  "amountCents": 9900,
  "subject": "会员年费",
  "sourceRef": "k3://members/member/m_42",
  "key": "renew-m_42-2026",
  "ttlSeconds": 1800
}

响应

201 响应正文（application/json）

示例：

复制代码

{
  "id": "po_01HZZ",
  "channel": "wechat",
  "product": "native",
  "outTradeNo": "po_01HZZ",
  "amountCents": 9900,
  "currency": "CNY",
  "subject": "会员年费",
  "status": "pending",
  "sourceApp": "crm",
  "sourceRef": "k3://members/member/m_42",
  "expiresAt": "2026-10-31T09:00:00Z",
  "refundedCents": 0,
  "createdAt": "2026-10-31T08:30:00Z",
  "settleAttempts": 0,
  "link": "https://pay.example.com/p/abc123"
}

GET /pay/orders/{id}复制本节链接

读取本应用的一张收款单

需要范围 app.pay:read。English: one order of the app.

不存在或不是本应用的是 404 not_found。

• 认证：bearer
• 范围：app.pay:read
• operationId：getPayOrder

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "po_01HZZ",
  "channel": "wechat",
  "product": "native",
  "outTradeNo": "po_01HZZ",
  "amountCents": 9900,
  "currency": "CNY",
  "subject": "会员年费",
  "status": "pending",
  "sourceApp": "crm",
  "sourceRef": "k3://members/member/m_42",
  "expiresAt": "2026-10-31T09:00:00Z",
  "refundedCents": 0,
  "createdAt": "2026-10-31T08:30:00Z",
  "settleAttempts": 0,
  "link": "https://pay.example.com/p/abc123"
}

POST /pay/orders/{id}/cancel复制本节链接

关闭一张还没付的收款单

需要范围 app.pay:write。English: closes an unpaid order.

已付的单不能关（用退款），那是 409 conflict。返回关闭后的收款单。

• 认证：bearer
• 范围：app.pay:write
• operationId：cancelPayOrder

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "po_01HZZ",
  "channel": "wechat",
  "product": "native",
  "outTradeNo": "po_01HZZ",
  "amountCents": 9900,
  "currency": "CNY",
  "subject": "会员年费",
  "status": "pending",
  "sourceApp": "crm",
  "sourceRef": "k3://members/member/m_42",
  "expiresAt": "2026-10-31T09:00:00Z",
  "refundedCents": 0,
  "createdAt": "2026-10-31T08:30:00Z",
  "settleAttempts": 0,
  "link": "https://pay.example.com/p/abc123"
}

GET /pay/orders/{id}/refunds复制本节链接

列出一张收款单的退款

需要范围 app.pay:read。English: the refunds of an order.

返回 {items}。

• 认证：bearer
• 范围：app.pay:read
• operationId：listPayRefunds

参数

响应

200 响应正文（application/json）

POST /pay/orders/{id}/refunds复制本节链接

给一张已付的收款单退款

需要范围 app.pay:write。English: refunds a paid order, in part or what is left.

amountCents 为 0 或省略是退剩下的全部。key 是这笔退款的幂等键，没写时用请求头 Idempotency-Key，都没有是 422。返回 201 和退款。

• 认证：bearer
• 范围：app.pay:write
• operationId：refundPayOrder

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "amountCents": 3000,
  "reason": "部分退款",
  "key": "refund-o_1-1"
}

响应

201 响应正文（application/json）

示例：

复制代码

{
  "id": "rf_01HZZ",
  "orderId": "po_01HZZ",
  "amountCents": 3000,
  "reason": "部分退款",
  "status": "processing",
  "createdAt": "2026-10-31T10:00:00Z"
}

approvals复制本节链接

审批：为本应用的对象提交、重新提交、撤回审批，读进度，处理当前人员的待办

GET /approvals复制本节链接

读取一个对象最近的审批

需要范围 app.approvals:read。English: the latest approval of an object of the app, for its requester or someone asked to decide, or for the app itself.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。subject 是对象的引用。别人的审批、或没有审批，是 404 not_found。

• 认证：bearer
• 范围：app.approvals:read
• operationId：getApproval

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "ap_01J",
  "kind": "hr.leave",
  "subject": "k3://hr/leave/l_17",
  "number": "QJ-2026-0042",
  "title": "王芳请假 2 天",
  "status": "running",
  "requester": "u_1001",
  "lines": [
    {
      "label": "日期",
      "text": "11-03 至 11-04"
    }
  ],
  "waiting": [
    "直属上级：鲍勃"
  ],
  "mine": [],
  "steps": [],
  "canWithdraw": true,
  "link": "/instances/ap_01J"
}

POST /approvals复制本节链接

为本应用的一个对象提交审批

需要范围 app.approvals:write。English: asks for the approval of one object of the app, as the person using it.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。kind 是本应用在清单 approvals 里声明的审批种类，subject 是对象的引用。事实和摘要不由人的令牌给：平台向应用发签名的 PREPARE 调用，由应用的回答决定；结果以签名的 DECIDED 事件送回应用。同一对象已有没结束的审批是 409 conflict；应用拒绝（对象不存在、状态不对）是 409 或 422，话是给人看的。返回 201 和审批的引用。

• 认证：bearer
• 范围：app.approvals:write
• operationId：submitApproval

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "kind": "hr.leave",
  "subject": "k3://hr/leave/l_17"
}

响应

201 响应正文（application/json）

示例：

复制代码

{
  "id": "ap_01J",
  "number": "QJ-2026-0042",
  "status": "running"
}

POST /approvals/{id}/resubmit复制本节链接

重新提交一个被退回的审批

需要范围 app.approvals:write。English: submits a returned approval again.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。正文同提交。返回审批的引用。

• 认证：bearer
• 范围：app.approvals:write
• operationId：resubmitApproval

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "kind": "hr.leave",
  "subject": "k3://hr/leave/l_17"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "ap_01J",
  "number": "QJ-2026-0042",
  "status": "running"
}

POST /approvals/{id}/withdraw复制本节链接

撤回自己提交的审批

需要范围 app.approvals:write。English: withdraws the person's own approval, or (the app's own token) any approval of the app's objects.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。reason 是撤回的原因，可省略。返回审批的引用。

• 认证：bearer
• 范围：app.approvals:write
• operationId：withdrawApproval

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "reason": "日期填错了"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "ap_01J",
  "number": "QJ-2026-0042",
  "status": "running"
}

GET /approvals/waiting复制本节链接

列出当前人员本应用的审批待办

需要范围 app.approvals:read。English: the tasks waiting for the person in the app's approvals.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。kind 只要这一种审批的待办。最多 100 条。返回 {items}。

• 认证：bearer
• 范围：app.approvals:read
• operationId：listWaitingApprovals

参数

响应

200 响应正文（application/json）

POST /approvals/tasks/{task}/actions复制本节链接

处理一条审批待办

需要范围 app.approvals:write。English: decides a task of the person's.

审批是人的：除 GET /approvals/participates、GET /approvals 与 POST /approvals/{id}/withdraw 外只收页面会话，应用自己的令牌是 403 forbidden；应用自己的令牌可以读取本应用任何对象的审批（不含个人的待办）、撤回本应用的任何审批（谁可以由应用判断）。action 是 approve、reject、return、transfer、presign、aftersign、cosign 之一；version 是人看到的待办版本，过期是 409 conflict；转交和加签用 target 或 users。返回处理后的审批。

• 认证：bearer
• 范围：app.approvals:write
• operationId：actOnApprovalTask

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "action": "approve",
  "version": 3,
  "comment": "同意"
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "id": "ap_01J",
  "kind": "hr.leave",
  "subject": "k3://hr/leave/l_17",
  "number": "QJ-2026-0042",
  "title": "王芳请假 2 天",
  "status": "running",
  "requester": "u_1001",
  "lines": [
    {
      "label": "日期",
      "text": "11-03 至 11-04"
    }
  ],
  "waiting": [
    "直属上级：鲍勃"
  ],
  "mine": [],
  "steps": [],
  "canWithdraw": true,
  "link": "/instances/ap_01J"
}

GET /approvals/participates复制本节链接

问某人是否参与一个对象的审批

需要范围 app.approvals:read。English: whether user takes part in the approval of subject (what lets the app show the object to them).

这一个操作应用自己的令牌也能调。返回 {participates}。

• 认证：bearer
• 范围：app.approvals:read
• operationId：approvalParticipates

参数

响应

200 响应正文（application/json）

示例：

复制代码

{
  "participates": true
}

calendar复制本节链接

日历：把本应用的日程（课节、面试、预订）放到相关人员的日历上

POST /calendar/projections复制本节链接

把本应用的一条日程放到相关人员的日历上，或取消它

需要范围 app.calendar:write。English: puts one fact of the app (a session, an interview, a booked room) on the people's calendars as a projection, or cancels it.

每个应用的每个 ref 只有一条投影。item 是投影；省略或为 null 表示取消。version 是这次推送的版本，必须是正数，用来排序：比已应用的更旧的推送回答 stale，什么也不改。回答 result 是日历条目的 id，或 stale。

• 认证：bearer
• 范围：app.calendar:write
• operationId：pushCalendarProjection

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "ref": "k3://rehab/session/s_7",
  "version": 1,
  "item": {
    "ref": "k3://rehab/session/s_7",
    "route": "/sessions/s_7",
    "owner": "u_2001",
    "attendees": [
      "u_3002"
    ],
    "start": "2026-11-03T02:00:00Z",
    "end": "2026-11-03T03:00:00Z",
    "tz": "Asia/Shanghai",
    "title": "康复课 · 术后康复",
    "titleEn": "Rehab session · Post-op",
    "place": "3 号诊室",
    "privacy": "health",
    "state": "booked"
  }
}

响应

200 响应正文（application/json）

示例：

复制代码

{
  "result": "cal_01K"
}

imports复制本节链接

历史导入：登记本应用导入的批次，并记下每条记录的来源

POST /imports/{batch}/items复制本节链接

登记本应用导入的一段历史数据（批次、每一行的结果、记录的来源）

需要范围 app.imports:write。English: records one chunk of a history import the app ran in its own process: the batch, what became of each row, and the provenance of each record a row wrote.

应用用自己的命令、在自己的数据库里按业务时刻写入旧系统的历史（ADR-0081），每写完一段就把结果报到这里。平台把批次与行记在跨应用的批次列表里（管理后台的「导入批次」），给每条写成的记录记一条来源（via 为 import，记录的「来源」与 GET /provenance 读到），每段写一条审计。平台不收行的数据：digest 是应用对这一行原文的摘要，同一批里同一个外部键再报一次，摘要必须一样。

只收页面会话，且必须是企业管理员（tenant.admin）本人：应用自己的令牌是 403 person_required，其他人是 403。batch 只能用字母、数字和 . _ : -，最多 80 个字符。一次 1 到 500 行，外部键在一次提交里不能重复；ok 的行要有 recordId，ref 必须是本应用的记录（k3://{本应用 id}/…），failed 的行要有 error、不能有记录；不合规是 422，整段不收。已经记为 ok 的外部键再报成另一行（摘要不同，或报成 failed）是 409 conflict，整段不收。正文最多 1 MiB。回答是批次现在的样子。平台没有数据库时是 503。

• 认证：bearer
• 范围：app.imports:write
• operationId：reportImportItems

参数

请求正文（必填）（application/json）

示例：

复制代码

{
  "label": "旧系统会员 2019–2025",
  "items": [
    {
      "key": "m-1001",
      "kind": "member",
      "status": "ok",
      "recordId": "mem_01K",
      "ref": "k3://membership/member/mem_01K",
      "businessAt": "2019-04-02T08:00:00Z",
      "digest": "9f2c…"
    },
    {
      "key": "m-1002",
      "kind": "member",
      "status": "failed",
      "businessAt": "2019-04-03T08:00:00Z",
      "digest": "1a7e…",
      "error": "手机号不对"
    }
  ]
}

响应

200 响应正文（application/json）

peers复制本节链接

其他应用的服务经平台去问：核销台、收银台、资源占用（治疗室与设备）、推广码；平台按已安装并开启的清单选提供者，本应用不指名也碰不到它

GET /peers/desk复制本节链接

其他应用的核销台：有没有，以及当前人员能做什么

需要范围 app.desk:use。English: whether an installed app serves the redemption desk, and what the caller may do there.

另一个应用的核销台，经平台去问：平台按这个组织已安装并开启的应用的清单选出提供它的应用，请求的应用不指名也碰不到它。available 说明有没有应用提供核销台；redeem、void 是当前人员能不能核销、作废。应用自己的调用（没有人在背后）这两项永远是 false。

• 认证：bearer
• 范围：app.desk:use
• operationId：getPeerDesk

响应

200 响应正文（application/json）

POST /peers/desk/http复制本节链接

把本应用页面的一个请求交给其他应用的核销台，以当前人员的身份

需要范围 app.desk:use。English: hands a request of the app's page (its /api/desk/… path, GET or POST, JSON body) to the redemption desk, as the page session's person.

另一个应用的核销台，经平台去问（平台按已安装并开启的清单选提供者，请求的应用不指名也碰不到它）。method 是 GET 或 POST，path 必须以 /api/desk/ 开头，query 是查询串，body 是 JSON。只有页面会话（页面上的人）可以；应用自己的调用是 403 person_required。没有应用提供核销台是 404 no_provider。回答是提供者的回答原样：status、contentType、body（字节，JSON 里是 base64）；提供者回的错误在 status 里，这个接口本身仍是 200。正文最多 1 MiB。

• 认证：bearer
• 范围：app.desk:use
• operationId：peerDeskHttp

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /peers/till复制本节链接

其他应用的收银台：有没有，以及当前人员能不能收银

需要范围 app.till:use。English: whether an installed app serves the till, and whether the caller may sell there.

另一个应用的收银台，经平台去问：平台按这个组织已安装并开启的应用的清单选出提供它的应用，请求的应用不指名也碰不到它。available 说明有没有应用提供收银台；sell 是当前人员能不能在那里收银。应用自己的调用（没有人在背后）sell 永远是 false。

• 认证：bearer
• 范围：app.till:use
• operationId：getPeerTill

响应

200 响应正文（application/json）

POST /peers/till/http复制本节链接

把本应用页面的一个请求交给其他应用的收银台，以当前人员的身份

需要范围 app.till:use。English: hands a request of the app's page (its /api/till/… path, GET or POST, JSON body) to the till, as the page session's person.

另一个应用的收银台，经平台去问（平台按已安装并开启的清单选提供者，请求的应用不指名也碰不到它）。method 是 GET 或 POST，path 必须以 /api/till/ 开头，query 是查询串，body 是 JSON。只有页面会话（页面上的人）可以；应用自己的调用是 403 person_required。没有应用提供收银台是 404 no_provider。回答是提供者的回答原样：status、contentType、body（字节，JSON 里是 base64）；提供者回的错误在 status 里，这个接口本身仍是 200。正文最多 1 MiB。

• 认证：bearer
• 范围：app.till:use
• operationId：peerTillHttp

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

GET /peers/holds复制本节链接

其他应用有没有提供资源占用（治疗室、设备）

需要范围 app.holds:read。English: whether an installed app offers resource holds.

另一个应用的资源占用，经平台去问：平台按这个组织已安装并开启的应用的清单选出提供者，请求的应用不指名也碰不到它。available 为 false 时，其余占用接口都是 404 no_provider，调用方可以不占资源直接预约。

• 认证：bearer
• 范围：app.holds:read
• operationId：getPeerHolds

响应

200 响应正文（application/json）

GET /peers/holds/holdable复制本节链接

可占用的治疗室和设备

需要范围 app.holds:read。English: the items another app may hold, as the caller sees them.

另一个应用的资源占用，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。没有应用提供资源占用是 404 no_provider。

• 认证：bearer
• 范围：app.holds:read
• operationId：listPeerHoldable

响应

200 响应正文（application/json）

POST /peers/holds/free复制本节链接

查一段时间里这些项目空不空

需要范围 app.holds:read。English: says, per item, whether it is free in [from, to), not counting the holds of except.

另一个应用的资源占用，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。except 是正在改期的来源，它自己的占用不算。没有应用提供资源占用是 404 no_provider。这是读操作，什么也不占。

• 认证：bearer
• 范围：app.holds:read
• operationId：checkPeerHoldsFree

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /peers/holds/hold复制本节链接

为本应用的一个对象占用这些项目

需要范围 app.holds:write。English: holds every free item for one object of the calling app; a taken item comes back with conflict and no hold.

另一个应用的资源占用，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。source 必须是本应用自己的 k3:// 引用（k3://{应用}/…），否则 422；资源应用在收回占用时据此告诉本应用。被占着的项目在回答里带 conflict，没有 holdId。没有应用提供资源占用是 404 no_provider。

• 认证：bearer
• 范围：app.holds:write
• operationId：createPeerHold

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /peers/holds/move复制本节链接

改一个占用的时间

需要范围 app.holds:write。English: moves a hold to [from, to).

另一个应用的资源占用，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。holdId 必填。新的时间里项目已被占是 409 hold_conflict；没有应用提供资源占用是 404 no_provider。

• 认证：bearer
• 范围：app.holds:write
• operationId：movePeerHold

参数

请求正文（必填）（application/json）

响应

POST /peers/holds/release复制本节链接

放掉一个占用

需要范围 app.holds:write。English: gives a hold back.

另一个应用的资源占用，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。holdId 必填，reason 是放掉的原因。没有应用提供资源占用是 404 no_provider。

• 认证：bearer
• 范围：app.holds:write
• operationId：releasePeerHold

参数

请求正文（必填）（application/json）

响应

GET /peers/referral-codes复制本节链接

其他应用有没有提供推广码

需要范围 app.referrals:read。English: whether an installed app offers promotion codes.

另一个应用的推广码，经平台去问：平台按这个组织已安装并开启的应用的清单选出提供者，请求的应用不指名也碰不到它。available 为 false 时，其余推广码接口都是 404 no_provider。

• 认证：bearer
• 范围：app.referrals:read
• operationId：getPeerReferralCodes

响应

200 响应正文（application/json）

POST /peers/referral-codes/code复制本节链接

一位推广人的推广码、链接和海报

需要范围 app.referrals:read。English: the promoter's code, link and posters.

另一个应用的推广码，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。promoter 必须写 customer 或 user 之一，否则 422；origin（https://host）是链接指向的企业站点。对方说不是推广人时是 404 not_found；没有应用提供推广码是 404 no_provider。这是读操作。

• 认证：bearer
• 范围：app.referrals:read
• operationId：getPeerReferralCode

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

POST /peers/referral-codes/promoter复制本节链接

一个推广码属于哪位推广人

需要范围 app.referrals:read。English: who owns a code that is in use.

另一个应用的推广码，经平台去问（提供者由平台按清单选，请求的应用不指名也碰不到它）。code 必填。码不存在或现在不带来任何人是 404 not_found；没有应用提供推广码是 404 no_provider。这是读操作。

• 认证：bearer
• 范围：app.referrals:read
• operationId：getPeerReferralPromoter

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

deals复制本节链接

成交事件：本应用的成交、退款与作废交给平台，由平台投递给订阅者

POST /deals复制本节链接

把本应用的一笔成交、退款或作废告诉平台，由平台投递给订阅者

需要范围 app.deals:write。English: hands one deal event of the calling app (a sale, a refund, a void) to the platform, which queues it for the deal subscribers exactly as in process.

source.app 必须是调用的应用，否则 422。key 省略时按 来源应用:来源引用:种类 补上，写了就必须等于它；同一个事件（同一个 key）再来一次不会再排队。事件只带内部引用和标签，不带手机号、openid、邮箱、证件号等个人信息（看得出来的会被拒绝，422）。回答的 queued 是排给了几个订阅者（0 表示这个组织现在没有订阅者）。事件不是账：钱归经营记账。English: queued is how many subscribers the event was queued for.

• 认证：bearer
• 范围：app.deals:write
• operationId：emitDeal

参数

请求正文（必填）（application/json）

响应

200 响应正文（application/json）

org复制本节链接

GET /org/units复制本节链接

企业的部门

需要范围 app.directory:read。English: the tenant's departments, for an app's own pickers and sharing rules. 没有部门时 items 是 []。

• 认证：bearer
• 范围：app.directory:read
• operationId：listOrgUnits

响应

200 响应正文（application/json）

GET /org/roles复制本节链接

企业自己的角色

需要范围 app.directory:read。English: the tenant's own roles. 没有角色时 items 是 []。

• 认证：bearer
• 范围：app.directory:read
• operationId：listOrgRoles

响应

200 响应正文（application/json）

GET /org/placement复制本节链接

一个人所在的部门和被指派的角色

需要范围 app.directory:read。English: the department chain of a person and the ids of the tenant roles assigned to them.

units 先是这个人自己的部门，再是逐级向上的父部门，直到根；然后是他被任命的各部门及其上级。没有部门或角色时是 []。缺 user 是 422。

• 认证：bearer
• 范围：app.directory:read
• operationId：getOrgPlacement

参数

响应

200 响应正文（application/json）

GET /org/members复制本节链接

调用者数据范围内的成员及其部门与角色（分页）

需要范围 app.org:read。按 id 排序分页列出本企业的在职成员（不含机器账号、未激活和已停用的成员）：id（账号 id）、name（显示名）、units（本人所属的部门和被任命的部门，不含上级）、roles（企业角色 id）。

人员按调用者的数据范围裁剪：point 必填，必须是本应用的权限点（以 app.{本应用 id}. 开头），否则 403 forbidden。平台按调用者在这个权限点上的数据范围回答：全部 → 本企业的全部成员；部门 → 所属或被任命的部门在范围内的成员；本人 → 调用者自己；调用者没有这个权限是 403 forbidden。组织没有启用权限模型（基础模式）时，企业管理员（tenant.admin）看到全部成员，其他人只看到自己。应用自己的调用（令牌背后没有人员）没有数据范围，拿不到成员列表：启用权限模型时是 403 forbidden，基础模式下是空列表（比 app.directory:read 的 /members 更严，有意如此）。next 是下一页的 cursor，最后一页是空字符串。limit 超出 1 到 500 是 422。平台没有接上权限求值、成员目录或组织架构时是 501 capability_off。English: the active members of the tenant (no machine accounts, no inactive or invited members), sorted by id and paged, cut to the caller's data scope on point, which must be one of this app's permissions (app.{app id}. prefix; another is 403 forbidden): all → every member; departments → members whose own or appointed department is in scope; self → the caller; no access → 403 forbidden. Basic mode (no permission model): a tenant administrator sees every member, anyone else only themselves. Each item has only id, name, units (own and appointed departments, no parents) and roles (tenant role ids). A limit outside 1 to 500 is 422; 501 capability_off when access, the directory or the organisation is not wired. The app's own call (no person behind the token) has no data scope and gets no member list: 403 forbidden with the permission model on, an empty list in basic mode (stricter than /members under app.directory:read, on purpose).

隐私规则：谁在哪个部门、担任什么角色是员工的个人数据，所以成员列表有自己的范围 app.org:read，与 app.directory:read 分开声明、分开审核；只回答令牌所属企业（租户）的数据，只含本企业的成员；按调用者的数据范围裁剪；分页；字段只有 id、显示名、部门和角色，从不包含联系方式（邮箱、手机号）或头像。English: privacy rules: who sits in which department with which role is personal data of the staff, so the member list has a scope of its own (app.org:read, declared and reviewed apart from app.directory:read), answers only the token's tenant and its own members, is cut to the caller's data scope and paged, and carries only ids, display names, departments and roles, never contact details (e-mail, phone) or a picture.

• 认证：bearer
• 范围：app.org:read
• operationId：listOrgMembers

参数

响应

200 响应正文（application/json）

事件（Webhooks）复制本节链接

平台向你登记的 https 地址推送的事件。每个事件是一个 POST 请求。

event:deal复制本节链接

平台把一笔成交（销售、退款、作废）送给声明了 event:deal 服务的应用

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点，至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义：2xx 完成；423 加 Retry-After 表示还没到时候；其他 4xx（408、429 除外）拒绝、不再重试；其余重试。 input 是 {caller, event}：caller 是代表租户的调用者（字段名是 Go 的大写形式 Tenant、User、Name、Roles、Agent、Via），event 是成交事件。幂等键是 deal: 加事件的 key。退款或作废先于它所冲销的销售到达时，回 423 加 Retry-After（销售还没到）。

• operationId：receiveDealEvent

参数

请求正文（必填）（application/json）

响应

event:payment复制本节链接

平台把一笔收款或退款结果送给声明了 event:payment 服务的应用

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点，至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义：2xx 完成；423 加 Retry-After 表示还没到时候；其他 4xx（408、429 除外）拒绝、不再重试；其余重试。 input 是 {kind, order, refund}：kind 为 paid 或 refunded，refund 只在退款时有。幂等键是 paid: 加订单 id，退款是 refund: 加退款 id。

• operationId：receivePaymentEvent

参数

请求正文（必填）（application/json）

响应

event:app.installed复制本节链接

租户里的应用有变化（安装、升级、开关、卸载）

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点，至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义：2xx 完成；423 加 Retry-After 表示还没到时候；其他 4xx（408、429 除外）拒绝、不再重试；其余重试。 input 是 {id, type, tenant, createdAt}，type 为 app.installed；幂等键是 id。它只说“变了”，要看现状请重新读取。

• operationId：receiveAppInstalledChange

参数

请求正文（必填）（application/json）

响应

event:permissions.changed复制本节链接

租户的部门、角色或分配有变化

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点，至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义：2xx 完成；423 加 Retry-After 表示还没到时候；其他 4xx（408、429 除外）拒绝、不再重试；其余重试。 input 同 event:app.installed，type 为 permissions.changed；幂等键是 id。它只说“变了”，要看现状请重新读取。

• operationId：receivePermissionsChanged

参数

请求正文（必填）（application/json）

响应

event:realtime.doc.projected复制本节链接

本应用的一份实时文档投影完成了

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点（应用不声明就收不到），至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义同其他服务事件。 input 是 {id, type, tenant, data}，type 为 realtime.doc.projected，data 是 {doc, kind, seq, actors}：哪份文档、什么种类、投影在哪个序号、上次投影以来谁写过。要内容请再调用 GET /realtime/docs/{id}/projection（读的是现在的投影，可能比事件的序号新；按序号去重，旧的事件不要覆盖新的投影）。

• operationId：receiveRealtimeDocProjected

参数

请求正文（必填）（application/json）

响应

event:access.changed复制本节链接

本应用的一个资源的访问名单变了

触发器 event:{kind}，由平台的服务运行时投递到应用在清单 services 里声明的端点（应用不声明就收不到），至少一次。正文是 {input, idempotencyKey, runId, trigger, attempt}；idempotencyKey 也在请求头 Idempotency-Key，处理程序按它去重。请求头 K3-Assertion 是平台签的短时断言，处理前要验证。回答的状态含义同其他服务事件。 input 是 {id, type, tenant, data}，type 为 access.changed，data 是 {type, id}：哪个资源。登记、删除、分享、撤销、通用访问、开关、转让、批准申请之后都会发。它只说“变了”；维护可见性镜像的应用据此用 GET /access/{type}/visible 刷新，最终一致。

• operationId：receiveAccessChanged

参数

请求正文（必填）（application/json）

响应

event:{app}.{what}复制本节链接

另一个应用发出的事件（它在清单 events.emits 里声明、经 POST /events/emit 发出）

触发器 event:{app}.{what}：订阅方在清单 services[] 里写 trigger: ["event:campaign.coupon.claimed"] 这样的触发器，平台在发布方每次发出这个类型的事件时，对同一租户里装了并开着订阅方的服务启动一次运行，由服务运行时投递到声明的端点，至少一次。正文、断言、回答的含义同其他服务事件（{input, idempotencyKey, runId, trigger, attempt}，请求头 K3-Assertion、Idempotency-Key；2xx 完成，423 稍后再送，其他 4xx 拒绝，5xx / 408 / 429 / 没有回答按退避重试，最多 5 次）。 input 是 {id, type, app, tenant, customer, data, createdAt}：app 是发布方，id 也是幂等键（appevt:{发布方}:{发布方的键}），customer 是客户中心的 id。只有在清单 events.emits 里声明了这个类型的应用（类型以它的 id 开头）能发布它；发布方的新版本不再声明时，事件不再送出。这个触发器随订阅方的版本审核。

• operationId：receiveAppEvent

参数

请求正文（必填）（application/json）

响应

event:customer.consent.changed复制本节链接

本企业的一位客户撤回或给出了同意（退订、撤回、员工改动、客户被抹除）

触发器 event:customer.consent.changed：只投给清单 uses 里有 app.customers:consent_events 的应用（客户的选择是个人信息），且要在 services[] 里声明这个触发器。由服务运行时投递到声明的端点，至少一次；正文、断言、回答的含义同其他服务事件。 input 是 {id, type, tenant, customer, channel, purpose, state, at}：customer 是客户中心的 id，channel 为 sms、wechat_template、wecom 或 any，purpose 为 service 或 marketing，state 为 granted 或 withdrawn。没有手机号、姓名或同意的来源。幂等键是 id。 撤回同意时，平台在写入撤回的同一个事务里先取消这位客户在这个渠道、这个用途下排队未发的消息，再把变化写进发件箱；应用收到时，这些消息已经不会发出。客户被抹除时，每一项仍然有效的同意都各发一次撤回。

• operationId：receiveConsentChanged

参数

请求正文（必填）（application/json）

响应

data:{kind}复制本节链接

平台的数据事件（租户删除、站点删除、客户合并、本应用被卸载）送给在清单 events.receives 里声明了它的应用

数据事件不经服务运行时：应用在清单 events.receives 里写要收的种类（tenant.deleted、site.deleted、customer.merged、app.uninstalled），平台在同一个事务里为每个声明了它、且（除 tenant.deleted 外）装在这个租户里的应用记一行，再投递到 POST /k3/events/{kind}，直到应用回 2xx，至少一次，失败后按退避（30 秒起翻倍，最长 6 小时）一直重试，不放弃。同一个事件可能来不止一次，处理程序第二次发现没什么可做就直接回 204。进程内的应用与独立进程的应用走同一条路、收到同样的调用。 请求头 K3-Assertion 是平台签的短时断言（via 为 event，租户与正文的 tenant 相同），处理前要验证；raise-go 的 appkit.Serve 已经做了，并只把清单声明了的种类交给 DataEventHandler，没声明的回 404。 subject 随种类而定：tenant.deleted 是租户 id；site.deleted 是站点 id；customer.merged 是 <被合并的客户 id>><保留的客户 id>（appkit.ParseMergedSubject），应用把指向前者的记录挪到后者；app.uninstalled 是本应用自己的 id，只发给被卸载的这个应用，卸载不删数据（ADR-0028），留不留由应用决定，租户可能再装回来。随租户一起删除的安装只发 tenant.deleted。

• operationId：receiveDataEvent

参数

请求正文（必填）（application/json）

响应

schedule复制本节链接

平台的时钟按清单里声明的 cron 启动一次服务运行（触发器 schedule）

触发器 schedule：服务在清单 services[] 里声明 trigger: ["schedule"] 和 schedule: {cron, timezone, missed}。平台每 30 秒看一次到点的时间，对每个装了并开着本应用的租户各启动一次运行，由服务运行时投递到声明的端点，至少一次；平台多副本时每个时间只启动一次。正文、断言、回答的含义同其他服务事件（{input, idempotencyKey, runId, trigger, attempt}，请求头 K3-Assertion、Idempotency-Key；2xx 完成，423 稍后再送，其他 4xx 拒绝，5xx / 408 / 429 / 没有回答按退避重试，最多 5 次）。 cron 是五段（分 时 日 月 星期；数字、*、a-b、/n、逗号列表；星期 0 和 7 都是周日；日和星期都限定时满足其一即可），按 timezone（IANA 名称，默认 Asia/Shanghai）读。幂等键是 schedule: 加这个时间（UTC 的 RFC 3339）。input 是 {scheduledAt, missed}。 错过的时间（平台重启、故障、服务暂停）：missed: "skip"（默认）时晚了超过 5 分钟的时间不再启动，只记数；missed: "once" 时只把其中最近的一个补跑一次，input.missed 说折进了几个。服务暂停期间到点的时间不启动运行，服务页上看得到原因。新装、升级、卸载最迟 5 分钟后生效。每次投递都记进开发者的请求日志（方向 out），失败的也是一条脱敏错误。

• operationId：receiveScheduledRun

参数

请求正文（必填）（application/json）

响应

通用响应复制本节链接

多个接口共用的响应。

CapabilityOff复制本节链接

501 capability_off：这个部署（或这个宿主）不提供这项能力，正文的 capability 是它的范围。不会好转，不要重试：应用照常运行，服务端回自己的调用方 503 capability_off，界面隐藏相应的入口（Raise 宿主规范 §5，ADR-0146）。SDK 把它读成 ErrCapabilityOff。English：this deployment (or host) does not provide the capability; capability names its scope. Do not retry.

正文（application/json）

Conflict复制本节链接

409。conflict：和当前状态冲突。idempotency_conflict：同一 Idempotency-Key 不同正文。idempotency_in_progress：第一次还在处理，稍后再读或换新键。

正文（application/json）

DraftRefused复制本节链接

草稿服务的拒绝，状态由它定（400、403、404、409、422 等）。正文是 {"error": "给人看的话", …}，外加这次拒绝带的字段（item、missing、confirm 等），不是通用的错误信封。应用自己的令牌打只收页面会话的草稿接口是 403。

正文（application/json）

Forbidden复制本节链接

403。scope_required：缺了操作描述里写的范围；范围必须在应用清单的 uses 里声明。forbidden：客户令牌不能调用这里；只收应用自己的令牌的操作遇到页面会话；或操作描述里写的归属检查没过（不是本应用的权限点、动作或事件类型，sourceApp 不是本应用）。wrong_environment：测试密钥打了正式组织，或正式密钥打了测试企业。not_installed：应用没装、关掉，或组织停用。no_scope：一把范围都没授。address_not_allowed：来源 IP 不在凭证允许名单。

正文（application/json）

Internal复制本节链接

500。平台出错，或依赖出了没有名字的错。带上 X-Request-Id 报给我们。

正文（application/json）

LengthRequired复制本节链接

411：没带 Content-Length。上传对象必须说明长度。正文是 {"error": "…"}。

正文（application/json）

NotFound复制本节链接

404 not_found：对应的记录不存在（客户中心没有这个客户，访客、服务或所指的东西不存在）。

正文（application/json）

PayloadTooLarge复制本节链接

413 payload_too_large：正文太大。

正文（application/json）

RateLimited复制本节链接

429。rate_limited：这把凭证的调用预算用完，看 Retry-After 和 X-RateLimit-*。

正文（application/json）

Refused复制本节链接

422：服务拒绝，或字段不被接受。权益服务的拒绝是给人看的话（例如剩余 0 次不能核销）：error.code 是 invalid，error.message 是原话，error.details.refused 为 true；有多项权益时 error.details.items 逐项说明（grant、name、reason）。

正文（application/json）

Unauthorized复制本节链接

401。token_required：没带 Bearer，先 POST /open/v1/oauth/token。invalid_token：令牌无效或过期，重新换（SDK 会自动换一次再重试）。credential_ended：凭证吊销、过期，或应用关掉、范围被收光。

正文（application/json）

Unavailable复制本节链接

503 unavailable：暂时不可用（这个部署不提供的能力是 501 capability_off）。按 Retry-After 重试；没有该头时 SDK 用指数退避。

正文（application/json）

Unprocessable复制本节链接

422：字段或参数不被接受（正文读不出来、有未知字段、缺必填、取值越界）。这个接口面上的处理程序回答的 code 是 invalid。

正文（application/json）