跳转到主要内容

Scoutello API

Scoutello API 是一个服务器到服务器的 API,用于双向同步组织的联系人、任务、协议、商机、项目、里程碑和事件。它还提供只读的外发邮件历史记录、可分配成员查询以及实体感知的标签发现功能。本版本使用增量 GET/list 路由和幂等批量 upsert 作为同步基础操作。本 API 不提供删除操作或 Webhook。

API 基础 URL:

https://admin.scoutello.com/api/v1

该地址也显示在 组织设置 → 开发者/API 中。OpenAPI 文档位于:

https://admin.scoutello.com/api/v1/openapi.json

创建并保护密钥​

对于模块化组织,除密钥所需的权限范围外,CRM 模块也必须处于启用状态。有效密钥无法启用缺失的模块。当 CRM 访问不可用时,请求会返回 HTTP 403,并附带错误代码 module_not_active。组织管理员可以在订阅中查看或启用 CRM;访问权限生效后重试。

组织管理员可以在 组织设置 → 开发者/API 中创建集成和 API 密钥。完整密钥只会显示一次。关闭对话框前,请将其复制到密钥管理器中;Scoutello 无法再次显示完整密钥。

  • 为每个外部系统和环境分别使用独立的集成和密钥。
  • 仅授予该系统所需的权限范围。
  • 切勿将密钥放入浏览器代码、URL、源代码管理系统、日志、支持消息或客户端存储中。
  • 按计划轮换密钥。轮换处于活跃状态的集成时,替换密钥会立即生效,旧密钥最多继续有效 15 分钟,以便外部系统在不中断服务的情况下完成切换。旧密钥原有的过期时间仍然有效,因此旧密钥可能会更早失效。
  • 如果密钥可能已经泄露,请先暂停集成,再进行轮换。暂停会暂时拒绝该集成的所有密钥。暂停期间进行轮换不会产生重叠有效期:旧密钥会继续保持禁用状态,替换密钥也会一直禁用,直到恢复集成为止。
  • 断开外部系统连接时,请永久撤销整个集成。撤销会禁用该集成的所有密钥,且无法撤销此操作。

在每个经过身份验证的请求中发送密钥:

Authorization: Bearer YOUR_API_KEY

建议使用 Bearer 身份验证。无法设置 Authorization 的客户端可以改用 x-api-key。不要同时发送这两个标头;如果两个标头的值不同,请求会被拒绝。

该 API 面向后端客户端,不支持跨源浏览器访问。

配置密钥后,使用 GET /whoami 验证集成、组织、权限范围和密钥限制,而不会获取用户个人数据。

权限范围​

范围允许的操作
contacts.read列出和检索联系人。不包括组织账户联系人以及拥有访问权限的成员联系人。
contacts.write验证并应用联系人的新增或更新操作。
tasks.read列出和检索非私有任务。
tasks.write验证并应用任务的新增或更新操作。
protocols.read列出和检索非私有协议。
protocols.write验证并应用协议的新增或更新操作。
opportunities.read列出和检索商机。
opportunities.write验证并应用商机的新增或更新操作。
projects.read列出和检索项目。
projects.write验证并应用项目及参与者的新增或更新操作。
milestones.read列出和检索项目里程碑。
milestones.write验证并应用里程碑的新增或更新操作。
members.read仅列出已接受成员的成员 Customer ID、User ID 和显示名称。
events.read列出和检索事件及核心日程。
events.write验证并应用事件的新增或更新操作。
mails.read读取组织所有的已发送和发送失败的外发邮件历史记录。
mail-drafts.read读取此集成独立的邮件审批草稿及发送状态。
mail-drafts.write准备或修改邮件草稿以供人工审批;不得审批或发送邮件。
tags.read查找受支持实体类型可选择的标签。

此 API 永远不会返回私有任务和协议。缺少范围会返回授权错误,不会被视为空结果。

即使非成员 CRM 联系人与 Scoutello 登录账号关联,也可以读取和引用该联系人。响应中仅包含组织的 CRM 字段,绝不会包含 User 身份或访问权限字段。具有角色、权限、邀请、接受状态或组织账户状态的联系人仍会被隐藏。禁止编辑与登录账号关联的联系人(protected_contact),包括编辑原本未发生变化的 CRM 字段。要在任务或协议中引用现有的可读联系人,contacts.write 可以仅使用 externalId、scoutelloId 和可选的 externalUpdatedAt 建立其外部链接。之后仅更新链接元数据时,使用 externalId 和可选的 externalUpdatedAt;建立链接后省略初始的 scoutelloId。此操作绝不会更改联系人或其 User。已接受成员的分配使用独立的 members.read 投影。

新密钥使用 sctl_api_ 前缀,并且仅以 contacts.write 开头。其他所有作用域都必须明确选择加入,并由组织管理员在创建或轮换密钥时授予。现有凭据保留当前作用域并继续有效。

与项目关联的联系人和邮件草稿​

联系人新增或更新接受可选的 projectScoutelloId / projectExternalId 和 companyScoutelloId / companyExternalId 对(每对选择一个)。每个条目中的联系人、公司关系和项目成员关系会以原子方式保存。添加项目成员关系需要 projects.write;省略引用会保留其他关系和成员关系。授予 projects.read 后,联系人详情读取结果会包含 projectParticipations。销售项目代理必须明确包含项目引用,即使重复使用已有联系人。

独立草稿使用现有的人工审批系统,不涉及工作流运行:

方法路径用途
GET/mail-drafts分页返回由集成拥有的草稿;可选的 projectScoutelloId 和 status 过滤条件。
GET/mail-drafts/{scoutelloId}当前版本、审核链接、内容哈希、审批/发送状态以及最终邮件 ID。
GET/mail-drafts/external/{externalId}查询稳定的集成外部 ID。
POST/mail-drafts/batch-upsert验证或应用草稿准备。

草稿准备需要 mail-drafts.write、contacts.read 和 projects.write。引用的联系人会成为项目参与者。审批人必须是已接受邀请且拥有邮件编辑权限的组织成员。发件人选择使用该成员现有获准的组织发件人设置或个人发件人设置;不接受任意 From 地址。

{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}

重复执行 mode: "apply" 前,检查每个验证结果。读取返回的 ID,以获取 reviewUrl、draftVersion、contentHash、status、dispatchStatus 和 mailScoutelloId。仅在创建时使用 expectedVersion: 0,修订时使用当前返回的版本。上下文和审批人不可变;已审核或已发送的草稿拒绝内容变更。相同的重试会返回原始草稿。

草稿会显示在项目/联系人“邮件”标签页和仪表盘审批通知中。API 准备不会发送邮件,包括通知邮件;现有工作流通知邮件的行为保持不变。受指派的人员可以编辑收件人、主题、正文和受支持的附件,保存版本,然后点击 批准并发送。集成无法执行审批或发送操作。发送失败或结果不明确时,绝不会盲目重试。转换基于协议的草稿时,请保留协议并交叉引用其替代项。

MCP 访问​

相同的 Scoutello API 密钥和作用域可用于可流式传输的 HTTP MCP 端点:

https://admin.scoutello.com/api/v1/mcp

将 MCP 客户端配置为发送 Authorization: Bearer YOUR_API_KEY。旧版 /api/mcp URL 仍作为路径兼容别名保留,但新客户端应使用带版本的端点。不再接受原有的 sctl_mcp_ 凭据;请将其替换为 Scoutello API 集成密钥。

MCP 工具直接映射到 REST 契约,并使用相同的运行时架构、租户检查、集成生命周期、速率限制和服务方法。例如,contacts_list、contacts_get、contacts_get_by_external_id 和 contacts_batch_upsert 分别对应四个联系人路由。任务、协议、商机、项目、里程碑和事件也采用相同模式;邮件提供 mails_list 和 mails_get,成员提供 members_list,标签则提供 tags_list。

服务器只会公布当前密钥作用域允许使用的工具。拥有 contacts.read 的密钥可以发现联系人读取工具,但无法发现 contacts_batch_upsert;拥有 contacts.write 的密钥可以使用批量更新工具,但无法使用读取工具。whoami 始终可用。写入工具与对应 REST 工具具有相同的即时效果,因此当调用方需要在应用批处理前检查批处理内容时,请使用 mode: "validate"。

MCP 同样采用服务器到服务器的通信方式,不会启用跨源浏览器访问。其 JSON-RPC 传输需要专用 URL,因此即使身份验证和数据行为相同,也不能与单个 REST 资源 URL 共用。

如需完整的客户端配置、验证、工具映射和故障排除说明,请参阅 MCP 集成指南。

读取记录​

联系人、任务、协议、商机、项目、里程碑和事件使用相同的读取路由:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

对于其他同步资源,请将 contacts 替换为 tasks、protocols、opportunities、projects、milestones 或 events。当记录已由此集成关联时,读取 DTO 中会出现 externalId。

列表响应的封装如下:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit 必须介于 1 到 100 之间。结果先按其公开 API 表示发生变更的有效时间排序,再按 Scoutello ID 排序。当集成链接元数据发生变更时,此有效时间可能晚于返回实体的 updatedAt。游标是不透明的:请原样存储并发送,不要根据其内容推断含义。

首次响应会为该遍历固定 snapshotAt。在开始另一次增量读取前,请持续跟随 nextCursor,直到 hasMore 为 false。这样可以避免分页期间记录发生变化而导致当前遍历不稳定。

进行增量同步时,请消费游标的每一页,然后将该遍历的 snapshotAt 持久化为高水位时间戳。在下一次遍历中,将其作为 ISO 8601 updatedSince 值传入。下限为包含边界,因此重试已完成的快照可能会返回边界记录,但不会跳过这些记录。

单条记录响应的封装如下:

{
"data": {},
"requestId": "request-id"
}

单个联系人响应还包含一个 relations 数组。每个关系都会保留其 Scoutello 关系 ID、创建时间、类型、备注,以及 connectedFrom 和 connectedTo 联系人引用。联系人引用包含 Scoutello ID,以及存在时该集成的外部 ID。受 API 组织访问隐私边界排除的联系人不会通过关系公开。 联系人列表响应保持精简,不包含关系;需要关系详情时,请使用任一单联系人路由。

处理筛选条件和游标范围​

联系人列表接受 search、type(person、company、supplier、other)、status 和 tagIds。搜索内容会被去除首尾空格,不区分大小写,且限制为 200 个字符 / 10 个以空格分隔的词元。每个词元都必须至少出现在 firstName、lastName 或 companyName 之一中,包括存储在 lastName 中的旧公司名称。% 和 _ 等字符会按字面匹配。标签采用任一匹配,支持 1–50 个 ID。所有提供的筛选条件都以 AND 组合。REST 将标签 ID 编码为重复参数;MCP 提供一个数组:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

联系人游标与组织、集成及每个筛选条件绑定。每一页都必须保留筛选条件;更改筛选条件会导致游标被拒绝。标签顺序/重复项,以及搜索词元的顺序、大小写和空格,不会改变有效筛选条件。

工作列表路由接受以下额外筛选条件;其他资源/字段组合会被拒绝:

资源筛选条件
任务projectScoutelloId、milestoneScoutelloId、status、statusType、priority、parentState、blockedState、assignedScoutelloUserId、dueBefore、dueAfter
协议projectScoutelloId、milestoneScoutelloId、status(draft 或 final)
商机projectScoutelloId、stage、ownerScoutelloUserId
项目status、assignedContactScoutelloId
里程碑projectScoutelloId、status、assignedContactScoutelloId、dueBefore、dueAfter

dueBefore 为排他边界;dueAfter 为包含边界。它们会比较任务到期日期或里程碑结束日期;没有相应日期的记录不会匹配。请提供包含时区的 ISO 日期时间。所有筛选条件都会在分页前应用。继续使用游标时,必须使用完全相同的筛选条件,包括 updatedSince,以及相同的组织/集成。页面大小可以更改。本次发布后,旧的未限定游标必须从保存的高水位时间戳重新开始。

项目、里程碑、分配和备注​

GET /members(MCP members_list)使用标准分页,并要求提供 members.read。它会返回 scoutelloId(成员 Customer ID)、scoutelloUserId(User ID)和 displayName。只有具有角色且已接受邀请的组织成员会显示;该查询不会公开电子邮件地址或权限。

任务接受 assignedScoutelloUserIds;商机使用 ownerScoutelloUserId。项目和里程碑使用 assignedContacts: [{"scoutelloId":"member-customer-id"}]。分配对象必须是凭据所属组织中已接受邀请的成员。省略分配对象会保持原状;[] 会清除分配对象。项目、里程碑、任务和协议的导入均为静默操作:不会发送分配通知或其他通信。

事件 assignedContacts 支持可读的 CRM 联系人,以及通过成员 Customer ID 提供的已接受邀请的成员。已接受邀请的成员不能作为普通 CRM 联系人引用或外部链接目标使用;如需指定团队责任人,请使用成员分配字段。

使用 name 以及 projectScoutelloId 或 projectExternalId 创建里程碑。里程碑支持 description(Markdown)、status(open、in_progress、completed、closed)、可为 null 的 startDate/endDate、order(默认为 0)以及 assignedContacts。结束日期不能早于开始日期。每个里程碑都有一个作用域限定在相应集成中的稳定外部链接。无法通过 API 更改其所属项目。创建和更新操作会根据组织语言对名称和描述进行本地化。

任务和协议接受项目、里程碑及商机引用,可使用 <entity>ScoutelloId 或 <entity>ExternalId,例如 milestoneExternalId。每个关系只能提供一种拼写形式,包括使用 null 清除关系时。所有关系都必须属于凭据所属的组织。仅提供里程碑引用时,系统会推断项目;如果项目冲突,或在保留里程碑的同时明确清除项目,系统将拒绝请求。已关联且包含项目的商机必须与工作项的项目一致。省略关系会保留当前值;在剩余上下文有效时,明确提供 null 会清除关系。读取结果会同时公开两种 ID 拼写形式及任务分配。

任务规划和工作流​

任务 status 是任务有效工作流中某个状态的不可变键,而不是固定枚举。使用 GET /task-workflows 并指定 tasks.read 作用域,读取组织和项目可用的工作流。每个状态都包含其键、标签、生命周期 type(backlog、unstarted、started、completed 或 cancelled)、颜色、顺序、默认标志和归档状态。项目条目会指明是否继承组织工作流。工作流配置仍由控制面板中的管理人员负责。

任务接受可为 null 的 priority(low、medium、high 或 urgent)和 estimatedEffortMinutes,以及可为 null 的 startDate 和 dueDate。任务读取结果包括反规范化的 statusType、父任务引用、紧凑的子任务引用,以及 blockedBy / blocks 引用。

使用 parentTaskScoutelloId 或 parentTaskExternalId 创建或更新一级子任务;null 可将其提升为顶级任务。依赖关系使用 { "scoutelloId": "..." } 或 { "externalId": "..." } 引用数组,并放在 blockedBy 和 blocks 中。省略关系字段会保留现有关系,而空依赖数组会清除对应方向的依赖关系。API 会拒绝嵌套子任务、父子任务之间的依赖关系、跨组织依赖关系、重复项、自引用,以及直接或传递形成的循环依赖。

任务列表筛选器支持精确匹配的工作流 status、生命周期 statusType、priority、parentState(top_level、subtask 或 parent),以及 blockedState(blocked、blocking 或 unblocked)。

协议还支持 status: "draft" | "final"(新记录默认使用 final)。新协议必须包含 type、date,以及联系人或有效的项目/里程碑上下文。仅当项目/里程碑上下文仍然存在时,contactExternalId: null 才会清除其联系人。因此,无需虚构客户即可创建和读取项目内部备注。草稿/最终状态描述备注的状态,绝不会发送任何通信。私人任务和协议仍然无法访问。

项目参与者​

项目 participants 包含以 contact 引用为键的增量式更新,例如:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

参与者用于描述与项目相关的潜在客户/客户;负责成员通过分配关系指定。省略参与者、使用空数组,以及省略参与者字段,都会保留现有数据。null 会清除 role、notes 或 groupScoutelloId。单个请求负载中解析到的重复联系人会被拒绝。群组必须已属于所选项目;读取结果包括 participantGroups(ID/名称)、参与者 ID、联系人、角色、备注和群组 ID。目前可在控制面板中移除参与者或创建群组。

批量更新记录​

通过资源的批量路由写入最多 100 条记录:

POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}

任务批次会先解析任务记录,然后应用父任务和依赖关系。通过这种两阶段处理,父任务、阻塞任务或被阻塞任务可以使用外部 ID 引用同一批次中创建的其他任务,而不受记录顺序影响。

请使用每个资源的 OpenAPI 文档了解其字段和验证约束。每条记录都必须包含稳定的 externalId,长度介于 1 到 200 个字符之间。将其视为不透明的技术标识符:不得使用电子邮件地址、姓名、API 密钥或其他个人数据。externalUpdatedAt 为可选字段,但如果源系统提供可靠的修改时间戳,强烈建议填写。

请求正文大小上限为 1 MiB。mode 默认为 apply:

  • apply 会验证并写入通过验证的记录。
  • validate 会执行相同的验证和匹配,但不会写入数据,并返回 would_* 结果。

对于联系人导入,可在请求中将 matchByEmail 设置为 true。其默认为 false;外部 ID 是更安全的默认身份边界。

省略字段会保留当前值。显式提供 null 会清除可为空字段;提供空的分配数组或标签数组会清除相应关联。项目 participants 采用追加式更新或插入:空数组不会改变成员列表。联系人、任务、商机和事件的标签写入使用 Scoutello 标签 ID。关系外部 ID 仅通过属于当前集成的链接进行解析;用于所有权或责任分配的 Scoutello 用户 ID 必须对应当前组织中已获接受的成员。

创建商机时必须关联账户或联系人;已输的商机必须提供丢失原因。金额以整数分表示。项目和事件的名称及描述会按照组织配置的语言读取和写入。事件写入支持指定日期,以及带排除日期的每日、每周或每月重复;已发布的可见性层级仍受 Scoutello 的法律就绪门槛限制。API 不提供活动票务、参与者、媒体、模板、新闻简报、协作或其他高级活动管理控制项。

发现标签​

在提供 tagIds 之前,请使用标签端点:

GET /tags?entity=events&type=category

entity 为必填项,可接受 contacts、tasks、opportunities 或 events。它会映射到相应存储的标签相关性。type 为可选项,可接受 category 或 attribute。可选择的类别可能归组织所有,也可能是全局类别;可选择的属性来自 Scoutello 精选的全局属性集。结果包括 scoutelloId、以组织语言本地化的名称、type 和 relevancy。跨组织、相关性错误或不可选择的标签 ID 将导致受影响的批处理项被拒绝。

阅读外发邮件历史​

邮件历史记录为只读:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

仅返回 sent 或 failed 状态的组织所有邮件。响应包含常见的已存储邮件头和正文、密送(BCC)、状态和时间戳、项目/活动/新闻简报引用、附件 ID 和类型,以及收件人送达/打开/点击/退信/投诉/拒收的汇总统计。草稿、排队中或已安排的邮件、逐收件人记录、渲染快照、原始服务商错误和附件下载 URL 永远不会公开。后续的收件人送达更新会推进邮件的有效同步时间戳,因此该邮件会再次出现在增量读取中。没有邮件写入路由。

应用结果可以是 created、updated、linked、unchanged、stale_ignored 或 rejected。验证使用 would_create、would_update、would_link、would_leave_unchanged、would_ignore_stale 或 rejected。即使个别记录被拒绝,有效的批量请求仍会返回 HTTP 200,因此务必检查每个项目和响应摘要。请求 Scoutello 支持团队调查失败时,请保留响应 requestId。

时间戳和冲突​

如果存在 externalUpdatedAt,Scoutello 会使用它拒绝过期更改,而不会使批次中的其余记录失败。stale_ignored 结果表示该较旧载荷已终止处理;请先获取当前记录,再决定是否发送更新版本。

将时间戳视为 UTC ISO 8601 值。保留其原始精度,不要用同步任务执行时间替代源记录的修改时间。

幂等性​

幂等性边界由集成和 externalId 共同构成。Scoutello 会比较规范化载荷哈希和可选的 externalUpdatedAt 值,因此重试同一记录不会创建重复项,并且可能返回 unchanged。

对于 externalUpdatedAt,相同的时间戳和载荷会被判定为 unchanged,较早的时间戳会被判定为 stale_ignored,而相同时间戳配合不同载荷则构成版本冲突。对于从未接受过时间戳的链接,不带时间戳的相同载荷仍会保持 unchanged,而更改后的载荷则按到达顺序应用。链接接受时间戳后,省略 externalUpdatedAt 的更改载荷会被拒绝并判定为版本冲突,因此无版本数据无法覆盖已有版本状态。这也是强烈建议使用源修改时间戳的原因。

审计跟踪​

已接受的 API 创建、更新和仅链接同步操作会出现在 Scoutello 变更日志中,来源标记为 Public API,并与负责的集成相关联。运行摘要会保留请求 ID 和结果汇总数量,便于排查问题;不会保留记录载荷或 API 密钥。

错误与重试​

请求级错误使用以下信封格式:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

对 HTTP 429 和暂时性 5xx 响应使用指数退避和抖动进行重试。在存在 Retry-After 时遵循其要求。网络故障可能发生在 Scoutello 接受请求之后;由于每条记录都通过外部 ID 和规范载荷实现幂等,因此可以安全地再次发送同一批次。未经修改请求,不要自动重试身份验证、授权、验证、版本冲突或单条 rejected 结果。

推荐的双向同步循环​

  1. 在设置期间调用 /whoami,并验证预期的组织和作用域。
  2. 读取自上次完成的高水位标记以来发生变化的所有页面,并以幂等方式将这些变更应用到外部系统。
  3. 将外部变更发送到 /batch-upsert,使用稳定的外部 ID 和源系统修改时间戳。
  4. 仅在处理完所有页面和项目结果后持久化检查点。
  5. 根据源系统的所有权规则解决冲突;不要通过发送空记录来模拟删除。

Scoutello 在此首个版本中不会提供公开的删除路由。在引入有文档说明的生命周期操作之前,请在 API 之外处理删除或归档策略。

供人工审核的社交帖子​

社交 API 会为指定的人工审核人员准备帖子,但无法批准或发布帖子。REST 和 MCP 使用相同的作用域和服务。

作用域/api/v1 下的端点
social-channels.readGET /social-channels
social-posts.readGET /social-posts、GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts、GET /social-post-drafts/{scoutelloId}、GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert、POST /social-media/uploads、POST /social-media/uploads/{assetId}/finalize

新作用域必须明确授予。现有凭据不会自动获得额外访问权限。使用 members.read 查找成员用户 ID,并选择具有发帖权限的审核人员(newsletter.edit)。草稿不需要 CRM 联系人或项目。

{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}

使用 publishMode: "now" 和 scheduledAt: null 在获得批准后发布。每个 渠道变体都包含完整文本、设置和有序的媒体 ID。 渠道发现会返回受支持的格式、限制和设置。目前支持的渠道包括 LinkedIn 个人资料/主页、Facebook、Instagram 和 Threads。 Instagram 需要媒体。每个变体最多接受十张图片或视频。

批量请求在现有 1 MiB 请求 限制内最多接受 100 个唯一外部 ID。mode: "validate" 会检查引用和版本,但不会保存草稿、 上传资源、创建通知或将工作加入队列。应用结果包括 ID、审核链接、版本和每条记录的处理结果。部分失败不会 回滚已成功处理的其他记录。通知失败时会返回警告,并附带已保存的审核 URL。

修改待处理草稿前,先获取最新的 draftVersion。相同的 重试具有幂等性,并会保留之后由人员进行的编辑。审核人员无法原地更改。批准或拒绝后,如需提交其他提案, 请使用新的外部 ID。 草稿读取仅限发起调用的集成;发布历史涵盖组织中所有已持久化的、由 Scoutello 创建的营销活动,包括控制面板、 脚本和旧版 Scoutello 帖子。不会导入外部渠道的历史记录。

列表使用标准的 limit、cursor 和 updatedSince 参数。帖子和 草稿还接受 channelId、status、after、before 和 search;后续游标分页中需保留 所有筛选条件。日期筛选适用于发布时间(即时待处理草稿则适用于创建时间)。草稿 status 筛选审批 状态;帖子 status 匹配营销活动或渠道投递状态。读取结果会显示最新已知的投递状态、每个渠道的失败情况、公开链接和对账时间戳。草稿增量读取还会反映营销活动投递状态的变化。

上传媒体​

  1. 使用 POST /social-media/uploads 调用 clientUploadId,并以字节形式传入 filename、contentType、size,以及原始字节的英文小写十六进制 sha256。支持的类型包括 PNG、JPEG、WebP、MP4、WebM、QuickTime 和 M4V。上传上限为 500 MiB。
  2. 使用 HTTP PUT 将原始字节发送到返回的 upload.url,并使用其中的请求标头。上传 URL 在 15 分钟后过期。对同一文件的重试使用 clientUploadId;会话过期或文件发生变化时,需要使用新的 ID。
  3. 使用包含 {} 的 JSON 请求体调用 POST /social-media/uploads/{assetId}/finalize。最终确认会检查大小、类型、签名和校验和,冻结一份私有副本,并返回用于 mediaIds 的资源 ID。重复执行最终确认是安全的。

上传所有权与组织和集成绑定。草稿可以引用其所属组织中已最终确认的资源。预览 URL 是临时的;重新获取草稿即可刷新这些 URL。对于已最终确认的对象,系统不会签发上传 URL。

人工审核与交付​

审核人员会收到仪表板通知,并可从 Postings 或审核 URL 打开帖子。编辑会创建另一个不可变版本。批准操作使用显示的版本和内容哈希值,重新检查成员资格、渠道和资源,并以原子方式创建一个持久活动。如果计划时间已过,审核人员必须保存一个明确的新时间,或选择在批准时发布。

队列重试会复用活动及其平台回执。已批准的活动无法原地编辑。通过仪表板取消会保留其批准历史和媒体;取消无法中断正在进行的发送。轮询草稿或活动,以区分批准状态和实际的平台交付状态。