API 参考

面向开发者的接口:公开端点、聊天小部件、登录以及带 API 密钥的 REST API。

API 参考说明了 Zentor App 的接口,您可以从自己的网站和程序中调用它们:用于表单、产品配置器和内容的公开端点、聊天小部件、演示聊天机器人,以及包括单一登录的登录功能。每个端点页面都列出方法、路径、身份验证方式、参数、请求和响应示例以及文档记录的错误代码。

身份验证:表单、产品配置器和内容的端点可在不登录的情况下调用。聊天小部件的端点要求在 `X-Widget-Token` 请求头中提供您小部件的嵌入令牌,并且只接受来自该小部件已获批准域名的调用。登录端点会为用户会话发出访问令牌(JWT)和刷新令牌。

通过 API 密钥进行 API 访问:对于您自己的程序和服务器间集成,REST API 可在基础 URL `https://zentor-app.de/api/v1` 下使用。Zentor 会按请求为您的账户开通 API 访问权限。之后,管理员可在仪表盘的“API 密钥”下创建自己的密钥,并设定其权限(scope)——涉及预约与预定、聊天机器人、通信、文件、知识库、报告以及网页数据。每个领域都有一个只读 scope(`<领域>.read`,仅 GET)和一个写入 scope(`<领域>.write`,包含读取权限),例如 `appointments.read` 或 `knowledge.write`。请在 `Authorization: Bearer <API 密钥>` 请求头中发送密钥,或者改用 `X-API-Key` 请求头。可使用 `GET /api/v1/me` 查看某个密钥所属的账户及其 scope。

完整密钥仅在生成时显示一次。请妥善保管,并仅在服务器端保存——切勿写入浏览器代码或移动应用。密钥可以设置过期时间、进行轮换和撤销。通过 REST API 只能访问您套餐中包含的功能,所有数据均限定在您的账户范围内。常见错误:401 `API_KEY_INVALID`、`API_KEY_EXPIRED` 或 `API_KEY_REVOKED`(密钥缺失、错误、已过期或已被撤销)、403 `API_ACCESS_NOT_ENABLED`(账户尚未开通 API 访问)、403 `API_SCOPE_MISSING`(密钥缺少所需 scope)、403 `TENANT_NOT_ACTIVE` 或 `TENANT_LOCKED`(账户未激活或已被锁定),以及 404 `API_ENDPOINT_NOT_AVAILABLE`(该端点无法通过 REST API 访问)。

响应与限制:所有端点均以 JSON 响应。成功响应的状态码为 2xx,并带有 `"ok": true`;错误响应包含机器可读的错误代码(位于 `error` 或 `error.code` 字段)及一条消息。每个 IP 地址在 15 分钟内最多可发出 2,000 次请求;表单、验证和登录端点适用更严格的限制,具体说明见各自页面。超出限制时,服务器会以 429 `RATE_LIMIT_EXCEEDED` 响应。标记为非幂等的端点,在连接中断后不应自动重试,否则可能产生重复的请求或消息。

请仅通过 HTTPS 在请求体或请求头中传输密码、令牌、API 密钥和验证码——切勿放在 URL、日志或支持请求中。

身份验证 (5)登录、令牌刷新、密码重置、SSO 完成——以及通过 API 密钥进行的 API 访问。公开表单 (11)联系、咨询请求、访问申请、付款与账户激活。产品配置器 (5)套餐目录、价格预览、电子邮件确认和配置提交。公开内容 (6)法律文本、营销页面、网站主题和文字颜色。聊天小部件 (9)嵌入您网站的聊天小部件所使用的所有端点。演示聊天机器人与 SSO (13)公开演示聊天机器人以及单一登录端点(SAML/OIDC)。
← 返回概览