SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场commercetools-intake

commercetools-intake

智能体与模型

查看项目

更新于 10-21 19:29

技能介绍

用途

commercetools-intake 用于让渠道适配器把一条非结构化请求转换为一个 commercetools 实体。其 HTTP 接口是单个无状态端点，每次调用都会启动一次全新运行，返回已创建的实体或错误。它不会恢复之前的运行，因此后续邮件或工单评论并不是同一次调用的另一轮。

适配器需要自行做出 Intake 不会做的三个决定：创建哪种实体、消息属于哪个 Customer，以及该入站事件是新请求还是对已创建实体的回复。

主要能力

  • 通过无状态响应 API 调用 Intake，将非结构化输入转换为 commercetools 实体。
  • 支持多种输入渠道的映射，包括邮箱（email.md）和 Zendesk（zendesk.md），其他渠道（表单、云盘文件夹、其他帮助台）使用 call-responses.md 中的相同映射。
  • 支持文件上传，使用 files 部分，最多 3 个文件，仅限允许的内容类型。
  • 提供文档搜索脚本（docs-search.mjs）和 OpenAPI schema 获取脚本（openApi-schemata.mjs）。
  • 提供 outputType 选择指南（choose-output.md）和结果处理指南（handle-outcome.md）。

使用方式

文档搜索（必需，首先运行）

在会话中首次使用此技能时，必须在回答前运行文档搜索脚本，以获取最新验证文档作为主要依据：

node "<this skill's directory>/scripts/docs-search.mjs" \
  --query "Intake responses API Cart Quote Request Shopping List file upload" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>" \
  --commercetools-project-key "<if known>" \
  --commercetools-region "<if known>" \
  --limit 10

仅在上下文中已有 project key 和 region 时才传入，否则两者都省略。不要搜索文件或向用户索要。

获取 REST schema

在编写请求或解析响应前，运行：

node scripts/openApi-schemata.mjs \
  --resource-name "api-AgentResponsesSuccess" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出为该资源的 OpenAPI 规范。如果名称无法识别，脚本会打印有效名称。当后续操作是对 Intake 创建的实体进行更新而非另一次 Intake 调用时，改用 api-Cart-write、api-QuoteRequest 或 api-ShoppingList 重新运行。

确认 Project 可接受调用

  • Intake 已为 Project 启用（否则 FeatureDisabled）。
  • API 客户端具有 manage_intake_agent:{projectKey} scope。
  • Product Search 已启用（否则 ProductSearchNotEnabled）。
  • 买家已作为 Customer 存在。Intake 通过 email 查找 Customer，不会创建 Customer。

在编写适配器前于 Merchant Center 运行相同提示

将提示和任何文件粘贴到 Merchant Center Intake。在那里失败说明是 Project、目录或 Customer 的问题；在那里成功而 API 失败说明是集成发送的请求有问题；需要澄清问题才成功的提示不算数，产生实体的提示才是 API body 必须包含的提示。

选择 outputType

阅读 choose-output.md。该字段为必填，Intake 绝不会从消息中推断它。

将渠道映射为一个请求

阅读 call-responses.md，然后阅读渠道文件：邮箱使用 email.md，Zendesk 使用 zendesk.md，其他投放（表单、云盘文件夹、其他帮助台）使用 call-responses.md 中的相同映射。新渠道意味着新的规范化器，而不是新的 Intake 契约。

每个新请求调用一次并记录

端点没有幂等键。有条件地插入渠道自身的 id（邮件 Message-ID、Zendesk ticket id）及规范化请求作为排队工作，确认投递，然后在 POST 前立即将该行标记为结果未知的调用。成功后，将该 id 与 threadId、entity.id 以及（对于 Quote Request）cartId 一起存储。恢复可能发送从未标记的排队行，但不得重发已标记的行。第二次 POST 会创建第二个实体。

处理结果并写回

使用 handle-outcome.md。201 仍可能携带警告。400 会指明缺失内容。不要用相同 body 再次调用来回应 400。

按存储的结果路由同一线程上的后续消息

已存储的实体使用常规 Cart、Quote Request 或 Shopping List API 更新。已确认的无写入失败（未创建任何内容的 400）在回复提供缺失输入时允许一次修正的 Intake 尝试。待处理的排队行、结果未知的调用或部分创建（带 cartId 的 QuoteRequestCreationFailed）从该存储状态解决，不要再次 POST 来完成它。

适用场景

  • 将邮箱、Zendesk 或其他渠道的非结构化客户请求转换为 commercetools 实体。
  • 需要从邮件、支持工单、PDF、表格、CSV 或自由文本中创建 Cart、Quote Request 或 Shopping List。
  • 构建渠道适配器以自动化入站请求处理。

限制

  • 不负责构建或自动化 Merchant Center Intake UI。该 UI 应在编写适配器前使用一次，以确认相同提示能创建实体。UI 可以提出澄清问题，此端点不能。
  • 不负责连接连接器、事务性邮件和 CRM 同步，这些属于 commercetools-integrations。
  • 不负责 Quote Request 存在后的报价协商（Staged Quote、Quote、Order），那属于 Quotes API。
  • 端点无状态，不恢复之前的运行。
  • 端点没有幂等键，第二次 POST 会创建第二个实体。
  • Intake 通过 email 查找 Customer，不会创建 Customer。
  • outputType 为必填，Intake 不会推断。
  • 文件上传最多 3 个，仅限允许的内容类型。
  • 关于具体收费、价格、平台支持范围等事实，资料中暂未提供。