Salesflare API

概述

使用本技能安全、一致地调用 Salesflare REST API。

默认操作流程：

1. 发现端点结构及必需字段
2. 首先执行读取/校验请求
3. 在修改数据前向用户请求确认
4. 执行变更操作，并返回包含 ID 的精简结果

快速开始

在发起请求前，请先设置 API 密钥：

export SALESFLARE_API_KEY='your_key_here'

• 基础 URL：https://api.salesflare.com（生产环境，默认）
• 认证请求头：Authorization: Bearer
• 可选本地覆盖：如需本地测试，可设置 SALESFLARE_BASE_URL 为预发布（staging）环境 URL。
• 本地密钥请仅存于被 .gitignore 忽略的 .env.local 文件或进程环境变量中。切勿将 API 密钥或 smoke-test 输出与本技能一同发布。

核心脚本

• scripts/sf.py — 统一 CLI 封装器（子命令包括：discover、request、get、post、put、patch、delete、smoketest）
• scripts/sf_discover.py — 基于 OpenAPI 发现/列出端点及其支持的 HTTP 方法
• scripts/sf_request.py — 执行 GET/POST/PATCH/PUT/DELETE 请求，内置重试机制；支持查询参数、JSON 请求体、自动分页
• scripts/sf_smoketest.py — 对 OpenAPI 定义的操作进行 smoke-test。默认为只读模式；生命周期写入测试需显式指定 --allow-write，而清理删除操作则需同时指定 --allow-write --allow-delete。

工作流

1) 发现端点及其结构

python scripts/sf.py discover --contains opportunities
python scripts/sf.py discover --tag Accounts

2) 通过读取请求验证

python scripts/sf.py get --path /accounts --query limit=5 --query search=acme

3) 写入前确认操作意图

执行 POST、PUT、PATCH 或 DELETE 操作前，必须始终获得用户明确确认。
对于 DELETE 操作，无论上下文如何，均须要求显式确认——不得基于先前对话推断用户同意。

4) 执行写入并返回报告

返回内容应包括：

• 已执行的操作类型
• 目标实体 ID（s）
• 发生变更的关键字段
• API 响应摘要

5) 安全地执行 smoke-test

默认 smoke test 为只读模式：

python scripts/sf.py smoketest

如需启用生命周期写入路径测试，请显式开启。该模式将：先创建受控测试记录；再执行 GET 列表查询及按 ID 查询；仅更新由本次 smoke-test 创建的记录；最后仅删除本次创建的记录：

python scripts/sf.py smoketest --allow-write --allow-delete

生命周期写入覆盖范围有意限定为 smoke test 可完全拥有并清理的数据类型：accounts、contacts、opportunities、tasks、meetings、internal notes/messages 和 tags。此外，还测试对测试 account 的 account-contact/account-user 关系更新，以及对测试 message 的 feedback 更新。其余写入端点若无法在该生命周期内被安全表示，则默认标记为跳过。

如需执行写入覆盖但不执行清理（即保留所创建的记录），请显式运行：

python scripts/sf.py smoketest --allow-write

变更操作安全规则

• POST/PUT/PATCH：执行前必须获得用户显式确认；严禁推断用户同意。
• DELETE：执行前必须获得用户显式确认；严禁推断用户同意。
• Smoke-test 默认为只读。如需带清理的生命周期写入测试，请使用 --allow-write --allow-delete。其中 PUT 和 DELETE 仅作用于本次 smoke-test 运行所创建的记录。
• 若生命周期写入测试意外中断，请在重新运行前，在 Salesflare 中搜索名称为 OpenClaw Smoke 的记录，或标签以 openclaw-smoke- 开头的记录。
• 未经显式确认，禁止执行批量变更操作。
• 优先采用单条记录更新，再考虑批量更新。
• 所有写入操作的输出中必须包含 ID，确保可追溯性。
• 遇到 HTTP 429（Too Many Requests）时，依赖脚本内置的重试与退避机制；若重试耗尽，请立即停止并清晰报告错误。

输出规范

• 默认输出：简洁摘要 + 关键 ID/字段
• 仅当用户明确要求完整载荷时，才提供原始 JSON
• 对于大型结果集，返回前 N 条，并在可用时注明总数

过滤方式

• 直接支持：通过重复使用 --query key=value 传入简单查询参数
• 高级 Salesflare 查询构建器过滤（q 对象/规则）：如需使用，请以原始序列化格式作为查询载荷传入
• 本技能不提供用于组合复杂 q 结构的高级 DSL

常用端点

/accounts       /contacts       /opportunities
/accounts/{account_id}/feed
/tasks          /pipelines      /users   /me
/tags           /workflows

具体命令示例与写入模式，请参阅 references/endpoints.md。

已知端点注意事项

• GET /accounts/{account_id}/feed — 当工作区启用了账户动态信息流（feed/timeline）功能时，该端点返回对应账户的 feed。若不可用，请联系 support@salesflare.com，并请求 Salesflare 启用账户 feed API 访问权限。
• GET /persons — 空参数调用可能返回 500 错误。建议改用 ?search=... 或 ?id=... 参数。
• GET /tags/{tag_id} — 即使传入有效 ID，也可能返回 500 错误；请改用 GET /tags 和 GET /tags/{tag_id}/usage。
• GET /persons 过滤字段 — GET /filterfields/person 将返回 400 错误；请改用 contact。
• 完整端点注意事项列表，请参阅 references/endpoints.md。

资源

scripts/

• sf.py — 统一 CLI 封装器
• sf_discover.py — 基于 OpenAPI 的端点发现工具
• sf_request.py — 认证 API 调用辅助模块
• sf_smoketest.py — 全量操作 smoke-test 执行器

references/

• endpoints.md — 实用请求示例、写入模式及各端点专属注意事项