使用说明

开发者 API

通过明确的操作，将软件连接到数据源、处理、结果和管理功能。 本指南介绍在所述版本限制范围内可用的 API。 用户、权限、存储和积分仍与 Rapportly 账户绑定。

分三步准备集成

1. 1
   选择用户、环境和权限

   打开“账户 → 集成”。虚构模拟器使用测试密钥；使用虚构数据执行真实操作时，使用单独的生产密钥。管理员只授予必要权限并设置适当预算。

2. 2
   练习接收和错误处理

   先使用模拟器，再导入API 契约并查看合成示例。机密信息保存在你自己的服务器中；集合中的修改操作默认关闭。

3. 3
   跟踪完整任务

   保存输入和任务编号，检查启动和最终状态，读取结果，下载可用文件并核对用量。仅在获准使用的环境中进行此练习。

创建 API 密钥

基础地址

https://api.rapportly.io/api/rapportly/v1

密钥属于一个用户

密钥代表一个用户委派权限。管理员设置环境、权限上限、月度预算和到期时间。成员自行激活预先准备的密钥，密钥值仅显示一次。每次请求还会检查当前用户、套餐和对象权限。密钥管理使用用户会话；生产操作使用 API 密钥。将机密保存在服务器中，在“账户 → 集成”撤销丢失的密钥。现有 Zapier 事件有独立契约。

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

使用具体契约和示例

生产 OpenAPI 描述源代码契约，并标注部分输入或响应。清单列出待完成模式。Postman 集合初始使用无效地址、空密钥并关闭修改操作。请先导入审阅，再在已获准的环境中主动发送虚构数据。导入尚未经过测试。

• 下载生产 OpenAPI 规范
• 下载合成 Postman 集合
• 下载从来源到结果与下载的步骤
• 下载包含待办部分的模式清单

先用虚构任务练习

创建测试密钥，练习处理进行中的任务、结果、错误和预算不足。模拟器使用固定示例内容，不消耗积分。

1. 在“账户 → 集成”创建或激活环境为 Test 的密钥，并设置要练习的操作权限。
2. 请求 GET /test/scenarios，从响应中选择操作。此列表遵循当前密钥权限。
3. 发送 POST /test/opdrachten，仅包含 actie 和 scenario。场景可选 succes、verwerking_mislukt、creditbudget_bereikt 或 toegang_geweigerd。每个新练习任务使用独立的 Idempotency-Key。
4. 保存 opdracht_id。状态为 bezig 时，约五秒后读取 GET /test/opdrachten/{id}。始终检查状态：HTTP200 也可能包含处理失败。

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

此示例要求操作列表中有 rapport.start。连接出现问题时，使用相同输入和相同 Idempotency-Key 重复请求。

• 下载模拟器操作指南
• 下载 Postman 练习集合
• 下载模拟器 OpenAPI

只获取需要的数据

搜索可访问的客户文件夹、会话和报告。/acties 显示操作和权限，/gebruik 显示预算与预留量，/verzoeken 显示技术请求历史。处理尚未完成时还没有结果。报告下载链接有效期为 15 分钟；重新读取报告可获取新链接。

更新客户管理

你的软件可以修改事务所模板、保存个人搜索、记录访问并创建跟进流程。请使用相应的管理权限，并确认每次修改。先读取当前版本；如果响应丢失，请保留相同的请求标识。重放旧请求不得撤销较新的修改。生产环境测试检查搜索、访问和跟进流程，包括清理和密钥撤销。其中仅对事务所模板进行了读取；写入已在本地及 CI 中测试。可下载指南介绍了四条路由及其验证证据的范围。

比较两个已保存的版本

比较同一已保存报告文本字段或对话字段的两个现有版本号，无需进行新的 AI 处理。此契约已在本地及 CI 中测试；CRM 生产环境测试并不能证明比较功能在生产环境中的行为。缺失的历史记录不会用当前文本补齐。较长的差异会被截断至每侧最多 8000 个字符，并明确标示截断情况。此功能不比较 PowerPoint、报价计算、附函或格式。当前的读取权限和隐私条件仍然适用。

提前请求费用估算

通过 POST /generatieplan 获取报告、报价或会话任务的预计步骤和积分。使用 gebruik:lezen 权限。计算和团队设置与网站相同。

估算不会启动处理或扣除积分，也不是保证的最高价格。请展示不确定性，例如尚未确定的文件读取费用。实际启动会重新检查权限和可用积分。

下载费用估算指南和示例

从你的软件启动处理

API已接入档案、文档、上传、音频、转录、客户文件夹、样式、输出、工作流、Excel 和定向消息操作。每条路由都有各自的输入、权限、确认和版本检查。现有处理与积分结算规则继续适用。启动响应只证明请求已被接收；随后应读取具体状态。清单标明尚未完成的契约。

先创建档案

生成并保存 UUID。向 PUT /dossiers/{id} 仅发送 naam，最多 200 个字符。201 表示新建，200 表示相同请求的重复响应。档案属于密钥对应的用户和组织，创建不消耗积分。不同输入返回 409；无法访问或已删除的档案返回 404。GET /dossiers/{id} 在具备读取权限时返回当前 naam 和 klant_id。

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

报告、报价或演示文稿

从 dossierId 和 notities 开始。tier 可选值为 basis、standaard 或 max。不指定样式配置时使用中性排版。也可提供有权访问的 stijlprofielId、klantId、bronOpnameIds 和 taal。样式必须匹配文档类型。报价使用现有公司设置和安全编号；API 不会将报价发送给客户。

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

保存 versie_id，并通过 GET /rapporten/{versie_id} 跟踪；报价和演示文稿也使用该路由。仅在 klaar 状态下，resultaat 才包含可用文件：export_url 对应 PDF，export_url_docx 对应 Word，export_url_pptx 对应 PowerPoint。链接 15 分钟后失效。遇到 mislukt 时先检查处理和用量，不要自动换新密钥重新启动。

下载从来源到结果与下载的步骤

上传自己的样式示例

将一至三个示例文件作为完整集合提交。Rapportly 使用与网站相同的文件和样式检查。任务使用关联用户的存储和可用积分。

1. 发送文件、名称、文档类型、个人或团队范围、明确确认和固定任务编号。团队样式要求管理员或团队负责人权限。
2. 保存接收 ID 并读取状态。已接收表示完整集合已安全保存；之后可能还需预览检查和审批。
3. 中断后原样重复请求，不会创建第二个样式。不完整上传可在三十天内重试，随后会受控清理。

下载样式示例、multipart 和错误处理指南

连接日历或邮箱

让用户在 Google 或 Microsoft 亲自授权。软件可以跟踪请求并主动断开连接。供应商密码和令牌不会出现在 API 响应中。

连接使用 verbindingen:beheren 权限，日程使用 agenda:lezen。发送还需独立发送权限和明确请求。

保存申请编号、任务编号和当前基准。原样重复丢失的请求；旧的断开操作不得删除后来建立的连接。

API 也能选择默认邮箱，需要管理和发送权限。先读取当前选择和连接。旧请求的重复不会改变更新的选择，现有发送任务保留原发件人。

下载授权、日程、断开与恢复步骤

从文本生成会话结果

发送至少一百个字符的转录文本。使用返回的 gesprek_id 跟踪结果。可选字段：titel、tier、klantId 和 taal。

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

读取已有语言版本

读取现有的语言结果。所述用于启动、暂停、继续和故障恢复的工作流路由已在本地及 CI 中测试；CRM 生产环境测试并未验证这些语言处理功能。请仅在为此目的获准使用的环境中使用它们。原始用户、密钥、来源和费用始终与请求关联。仍需满足当前源状态、权限、预算和已验证结算的要求；源已过期或被删除不意味着有权重新启动。启用第二语言的批量处理仍然关闭，包括继承该设置的情况。付费补齐单个缺失翻译结果的功能仍不在支持范围内。

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

处理完成后自动接收通知

Rapportly 可向你的服务器发送技术引用。随后用适当读取权限获取内容，无需持续查询进度。

1. 在服务器创建 HTTPS 接收端，使用具备 webhooks:beheren 权限的生产密钥通过 POST /webhooks 注册。相关处理必须使用同一密钥。
2. 基于原始消息字节验证签名，确保每个事件 ID 只记录一次。将通知和后续任务安全保存后再确认接收。重复通知不得产生第二个任务。
3. 查看 GET /webhook-afleveringen 及每次投递的详情。临时错误最多重试八次；发生问题后可申请额外一轮。已接受只表示你的服务器接收了通知，后续处理需在自己的系统中确认。

• 下载 webhook 限制与恢复指南
• 下载 Node.js 签名验证示例

模拟器不发送真实通知。使用虚构数据和独立生产连接测试接收端。示例负责验证通知；你自己的服务器负责保存和后续操作。

错误代码是什么意思？

保护密钥和客户数据

• 只在服务器端使用密钥，不要放入公开的浏览器代码。
• 每个集成使用独立密钥，并撤销旧密钥。
• 不要将密钥、结果或临时下载链接写入公开日志或聊天。
• 按照你自己系统的访问规则保存取得的客户数据。