The API contract for headless storefronts (Hydrogen, Next.js and other custom storefronts). Create API keys in the CustomersSay app (Headless page). The document is shown as plain Markdown text.
# CustomersSay Headless Storefront API v1(契约)
> 面向 Shopify headless 店面(Hydrogen / Oxygen、Next.js 等自建前端,以及关闭了 Online Store 的店铺)。
> 本文是 v1 路由、嵌入脚本与 React/Hydrogen 组件包三方共同遵守的契约;响应示例见 `fixtures/headless-v1/*.json`
> (路由测试与组件包测试都读取这些文件,结构漂移会在两边同时失败)。
- 基础地址:`https://<应用域名>/api/storefront/v1`(生产:`https://app-next.customerssay.ai/api/storefront/v1`)
- 所有接口返回 JSON(`embed.js` / `embed.css` 除外)。
- **与主题店接口一致**:v1 的读写接口复用 App Proxy 接口(`/apps/customerssay/...`)的同一套处理逻辑,
请求参数与响应结构相同,区别只在鉴权方式。主题 JS 在 headless 模式下改用 v1 基础地址即可工作。
## 1. 鉴权
商家在后台「Headless」页面创建密钥:
| 密钥 | 前缀 | 放在哪里 | 能做什么 |
|---|---|---|---|
| 公钥 | `pk_live_` | 浏览器(可公开) | 读;在后台登记过的 Origin 下写入(提交评论 / 点赞 / 提问 / 上传媒体) |
| 私钥 | `sk_live_` | 只放在商家服务端 | 读写;可代访客提交并传入可信的访客 IP 与已登录顾客 ID |
### 公钥(浏览器)
- 请求头 `X-CustomersSay-Key: pk_live_...`;**GET 请求**也可以用查询参数 `?key=pk_live_...`(不触发 CORS 预检)。
- 浏览器请求的 `Origin` 必须在该公钥登记的允许列表中(精确匹配 `scheme://host[:port]`,只接受 https,本地开发可用 `http://localhost`)。
- **创建或编辑公钥时必须至少登记 1 个 Origin**(每个公钥最多 20 个):空列表的公钥在浏览器里不可用,后台会拒绝保存;
服务端调用请使用私钥。后台「Headless」页的接入说明会预填最新创建的、未吊销且已登记 Origin 的公钥。
- **写请求(POST)只接受请求头里的公钥,且必须带已登记的 Origin**;没有 Origin(服务端调用)的公钥写入一律 403——服务端写入请用私钥。
- 公钥请求中的 `X-CustomersSay-Client-IP` / `X-CustomersSay-Client-UA` / `X-CustomersSay-Customer-Id` 会被忽略。
- 公钥提交的评论**不会自动标记"已验证购买"**(浏览器无法证明顾客身份),可由商家在后台手动标记。
### 私钥(商家服务端)
- 请求头 `Authorization: Bearer sk_live_...`。
- **请求带 `Origin` 头(说明来自浏览器)一律 403**;预检也不放行 `Authorization`,浏览器无法跨域发出私钥请求。
- 可选可信请求头:
- `X-CustomersSay-Client-IP`:真实访客 IP(用于点赞去重与限流;不传则所有访客会被视为你的服务器 IP)。
- `X-CustomersSay-Client-UA`:访客浏览器的 `User-Agent`(原样转发入站请求的 `User-Agent`,最长 1024 字符,超过视为未提供)。
商品评论 / 问答的点赞、点踩按指纹 `md5("{访客IP}:{浏览器UA}")` 识别访客;SSR 取 `/reviews`、`/questions` 时同时传它和
`X-CustomersSay-Client-IP`,响应里的 `userReaction` 才能对上访客之前在浏览器里的反应
(不传时按你服务器自身的 `User-Agent` 计算,对不上,`userReaction` 为 `null`)。代访客调用三个 `*-reactions` 接口时同样适用。
- `X-CustomersSay-Customer-Id`:经 Shopify Customer Account API 确认的已登录顾客 ID(纯数字或 `gid://shopify/Customer/123`)。
传入后,评论按"顾客身份"核对订单来判定"已验证购买";不传则不自动判定。
### 通用规则
- 店铺由密钥决定;请求中的 `shop` 可省略,若提供必须与密钥所属店铺一致(大小写不敏感),否则 403。店铺须处于已安装状态。
- 查询参数 `shop` 不一致:鉴权层 403 `shop_mismatch`;
- 请求体里的 `shop`(JSON 字段或表单字段;所有写接口:`/reviews`、`/questions`、`/store-reviews`、三个 `*-reactions`、
`/media-upload`、`/store-media-upload`)不一致:业务层 403 `{ "success": false, "error": "Shop mismatch" }`,不写库、不上传。
- 限流:每个(密钥 + 访客 IP)读 120 次/分钟、写 20 次/分钟;超出返回 429 `rate_limited` 与 `Retry-After`。
不设每把密钥共用的总量硬上限,避免公开密钥额度被第三方耗尽,以及不同 SSR 访客共享额度。写入接口自身的限流仍然有效。
私钥 SSR 应转发可信访客 IP;缺失时所有访客会共用服务端出口 IP 的额度。分布式滥用需在可信边缘部署 WAF / 风险控制。
各接口另有与主题店相同额度的业务限流(如评论 / 问答 / 店铺评论点赞每分钟 30 次、提问每 10 分钟 5 次、
同一邮箱提交评论间隔 4 秒、上传每 10 秒约 10 次),
v1 请求按(店铺 + 访客 IP)单独计数,不与主题店访客、其它店铺共用。
- 访客 IP(用于上述按 IP 的限流、点赞去重与用户资料里的 IP / 国家):
- 私钥请求:取 `X-CustomersSay-Client-IP`(须为合法 IP);没带或不合法时按下一条取(即你服务器的出口 IP);
- 公钥请求(以及没带可信头的私钥请求):服务端取 `X-Forwarded-For` **从右数第 N 项**,N 为 CustomersSay 部署配置的可信代理跳数
(见下);客户端自己填写的最左侧项一律不读,伪造 `X-Forwarded-For` 不能换到别的限流桶。
`X-Forwarded-For` 缺失、项数不足或该项不是合法 IP(去掉部分负载均衡追加的端口后用 `net.isIP` 校验)时取 `X-Real-IP`(同样校验);
仍拿不到时记为 `unknown`,这类请求共用同一个按 IP 的限流桶。
- **部署配置 `STOREFRONT_TRUSTED_PROXY_HOPS`**(CustomersSay 服务端环境变量,正整数,默认 `1`):应用前面有几层**自己控制**、
会向 `X-Forwarded-For` 追加对端地址的反向代理 / 负载均衡就填几。只有一层 nginx(`$proxy_add_x_forwarded_for`)或负载均衡时为 `1`
(默认);前面再加一层 Cloudflare(Cloudflare 追加访客 IP,nginx 再追加 Cloudflare 边缘节点 IP)时为 `2`。
填小了会把最近一层代理的地址当作访客(所有访客共用一个桶),填大了会读到客户端可伪造的项;缺失、`0`、负数、小数或非数字按 `1` 处理。
多层时内层代理应只接受来自外层的连接(例如 nginx 只放行 Cloudflare 的 IP 段),否则绕过外层直连内层的请求仍可伪造被信任的那一项。
- CORS:`OPTIONS` 预检返回 204;实际响应只对已登记 Origin 返回 `Access-Control-Allow-Origin`(回显该 Origin),
v1 的 JSON 接口**绝不返回** `Access-Control-Allow-Origin: *`。
例外:`/embed.js`、`/embed.css` 是无需密钥的公开静态资源,成功响应(200,以及 `If-None-Match` 命中时的 304)返回
`Access-Control-Allow-Origin: *`(另有 `Cross-Origin-Resource-Policy: cross-origin`、`Cache-Control: public, max-age=300` 与 `ETag`);
资源暂时不可用时返回 503(`Cache-Control: no-store`、`Retry-After: 60`),**不带** `Access-Control-Allow-Origin`
——`<script>` / `<link>` 引用照常按加载失败处理,不受影响。
- 请求方法:只写接口(`/review-reactions`、`/question-reactions`、`/store-review-reactions`、`/media-upload`、`/store-media-upload`)
只接受 `POST`(`Allow: POST, OPTIONS`),读写接口(`/reviews`、`/questions`、`/store-reviews`)接受 `GET` / `POST`
(`Allow: GET, POST, OPTIONS`),只读接口(`/rating-summary`、`/featured`、`/widget-settings`、`/json-ld`)只接受 `GET`
(`Allow: GET, OPTIONS`);其它方法(含只写接口上的 `GET`、只读接口上的 `POST` / `PUT` / `DELETE`)
返回 405 + `Allow` 头,业务错误格式 `{ "success": false, "error": "Method not allowed" }`,不需要密钥。
### 请求体大小与 Content-Length(写接口)
- 写接口(multipart 与 JSON)**可以带 `Content-Length`,也可以分块传输**(`Transfer-Encoding: chunked`,或经关闭请求缓冲的反向代理、
HTTP/2 → HTTP/1.1 负载均衡、隧道等转发后不再带 `Content-Length`),读取表单 / 解析 JSON 之前按下表上限限制请求体:
- 带合法 `Content-Length` 且超过上限:**立即**返回 413 `{ "success": false, "error": "Request body too large" }`,不解析请求体;
不超过上限则照常处理;
- 不带 `Content-Length`(或分块传输):服务端按上限**边读边计**,未超过则照常处理;累计超过上限即停止缓冲并立即返回同样的 413。
分块数量另有上限 **65,536 块**(每次读取计一块,含空块):超过同样立即 413——正常客户端、代理转发的块远大于 512 字节,
31 MB 的上限按 TCP 报文段计也只有约 2.3 万块,只有逐字节分块之类的异常发送方式才会触发;
- **超限返回 413,服务端随后读完并丢弃剩余请求体**:413 不带 `Connection: close`,连接保持 keep-alive;
返回 413 之后,服务端在后台继续读取并丢弃剩余请求体(不缓冲、不解析),**最多 32 MB、最多 65,536 块、最多 10 秒**:
- 剩余部分在这个范围内读完(例如声明 22 MB 的上传超过 21 MB 上限):连接照常复用,客户端可靠收到 413,
同一连接上的下一个请求正常处理;
- 剩余超过 32 MB(分块传输时才会出现,声明长度超过 32 MB 的见下一条)、读取超过 65,536 块(逐字节发送之类的异常方式),
或发送过慢(10 秒内发不完):服务端在 413 已发出后停止读取并关闭连接,
客户端**可能在收到 413 之后、甚至尚未读到 413 时看到连接重置**(`ECONNRESET` / `EPIPE` / 上游 502;浏览器表现为 `Failed to fetch`)。
上传大文件时遇到这类连接错误,应按"请求体过大"处理,不要原样重发同一个请求体;
- **例外:声明的 `Content-Length` 超过 32 MB**(例如声明 40 MB 传到 21 MB 上限):剩余部分注定读不完,413 **带 `Connection: close`**,
服务端不读取请求体,写完 413 即关闭连接。读到 413 的客户端不会再复用这条连接(下一个请求走新连接);
同样可能在读到 413 之前就看到连接重置,按"请求体过大"处理即可;
- 同样的"读完并丢弃"也适用于其它不读请求体就返回的写请求(鉴权失败 401 / 403 / 429、缺参数 400、上传限流 429 等),
keep-alive 连接上的后续请求不受影响;
- **客户端(尤其浏览器)应在发送前先在本地按下表校验文件 / 请求体大小**:浏览器在上传途中收到 413 时能否把响应交给页面
取决于浏览器实现与超出的大小,本地预检是唯一可靠的方式;收到 413 后应停止发送;
- `Content-Length` 不是十进制非负整数(如 `abc`、`-1`):400 `{ "success": false, "error": "Invalid Content-Length header" }`,不解析请求体。
- 上限:
| 接口 | 上限 | 说明 |
|---|---|---|
| `POST /media-upload`、`POST /store-media-upload` | 21 MB | 单文件上限(视频 20 MB / 图片 2 MB,读表单前无法区分,取较大值)+ 1 MB 表单余量;类型对应的大小限制在读表单后另行校验(超出 400) |
| `POST /reviews` | 31 MB | 直传媒体累计上限 30 MB + 1 MB 表单余量(通常先预上传,请求体只有文本字段) |
| `POST /questions`、`POST /store-reviews`、`POST /review-reactions`、`POST /question-reactions`、`POST /store-review-reactions`(JSON) | 256 KB | 问题 / 店铺评论正文最多 65,535 字节(数据库 TEXT 列),JSON 转义最多翻倍,加标题、昵称、邮箱、`tempIds` 等字段最大约 131 KB,留约 2 倍余量;反应接口的请求体通常不到 1 KB。超限 413 时不解析 JSON、不写库 |
- 浏览器 `fetch` / `XMLHttpRequest` 发送 `FormData` 或 JSON 字符串时会自动带 `Content-Length`;商家服务端(BFF)把收到的请求体以流的形式
原样转发(`duplex: "half"`,分块传输)也可以,无需先缓冲。超过上限的请求都会被拒绝(见上),客户端应先在本地校验文件大小。
### 缓存与 Vary
- 鉴权通过后的 v1 响应(含业务错误)都带 `Vary: Origin, Authorization, X-CustomersSay-Key`(与处理逻辑原有的 `Vary` 合并,不覆盖);
鉴权层错误(401/403/429)与 `OPTIONS` 预检只带 `Vary: Origin`,且不带 `Cache-Control`。
- 部分读接口带 `Cache-Control`(`/rating-summary`、`/featured`、`/json-ld` 为 `max-age=300`):
- 私钥请求(`Authorization`)或公钥放在请求头 `X-CustomersSay-Key` 时:改为 `private, max-age=300`(只允许浏览器 / 调用方私有缓存,
CDN / 反向代理等共享缓存不得复用——这类请求的 URL 不含密钥,共享缓存可能把响应交给不带密钥的请求);
- 公钥走查询参数 `?key=` 时:密钥本身就在 URL(缓存键)里,保持 `public, max-age=300`,可放心交给 CDN 缓存。
- 处理函数未指定 `Cache-Control` 时,私钥请求或请求头公钥的已鉴权响应会补 `private, no-store`;查询参数公钥保持原策略。SSR 场景如需在自己的 CDN 上缓存,建议使用 `?key=` 形式的公钥读请求。
### 错误格式
- 鉴权层错误(401/403/429):`{ "success": false, "error": { "code": "...", "message": "..." } }`(见 `fixtures/headless-v1/error.auth.json`)。
`code` 取值:`missing_key`、`invalid_key`、`secret_key_in_browser`、`origin_not_allowed`、`origin_required`、
`shop_unavailable`、`shop_mismatch`、`rate_limited`。
- 业务处理错误(400/403/404/405/413/429/500 等)沿用现有接口格式:`{ "success": false, "error": "..." }`(见 `error.handler.json`)。
例外:`/featured` 沿用主题店写法 `{ "error": true, "message": "..." }`(400 / 500)。
- 状态码可信:处理逻辑沿用主题店"200 + `{ success: false }`"的软失败(例如评论列表查询异常)在 v1 一律改为 **500**,响应体不变;
v1 的 200 响应不会出现 `success: false`。
- 客户端应同时兼容两种 `error` 形态(字符串或 `{code,message}` 对象)。
## 2. 接口
| 方法 | 路径 | 对应现有接口(处理逻辑相同) | 访问 | 响应示例 |
|---|---|---|---|---|
| GET | `/reviews` | `publicreviews` loader | 读 | `reviews.list.json` |
| POST | `/reviews` | `publicreviews` action | 写 | `review.submit.json` |
| GET | `/rating-summary` | `product-rating-summary` | 读 | `rating-summary.json` |
| GET | `/featured` | `publicfeatured`(忽略 `shopId` 参数,店铺由密钥决定;**文本为 HTML 实体转义后的**,见下文) | 读 | `featured.list.json` |
| GET / POST | `/questions` | `publicquestions` | 读 / 写 | `questions.list.json` |
| GET / POST | `/store-reviews` | `publicstorereviews` | 读 / 写 | GET:`store-reviews.list.json`;POST 见下文 |
| POST | `/review-reactions` | `publicreviewreactions` | 写 | 见下文 |
| POST | `/question-reactions` | `publicquestionreactions` | 写 | 见下文 |
| POST | `/store-review-reactions` | `publicstorereviewreactions` | 写 | 见下文 |
| POST | `/media-upload` | `mediaupload`(查询参数带 `productId`,或缺省时带 `product_handle`) | 写 | 见下文 |
| POST | `/store-media-upload` | `storemediaupload` | 写 | 见下文 |
| GET | `/widget-settings` | `widget-settings` | 读 | — |
| GET | `/json-ld` | 新增:商品 Product + AggregateRating + Review 结构化数据,供 SSR 输出 | 读 | `json-ld.json` |
| GET | `/embed.js`、`/embed.css` | 新增:可嵌入任意站点的评论组件脚本与样式(无需密钥;200 / 304 带 `Access-Control-Allow-Origin: *`、`max-age=300` + `ETag`;503 不带 CORS 头) | 公开 | — |
### 参数要点(读接口)
- 商品(读接口查询参数):`product_id`(纯数字或 `gid://shopify/Product/123`,也接受 `productId`)或 `product_handle`。
- 列表分页:`page`、`limit`(有上限);评论星级筛选用 `rating_filter`(1–5)。**GET `/reviews` 上的 `rating` 参数不用于筛选**。
- `GET /store-reviews`:`page`(默认 1)、`limit`(默认 5,最大 50)、`sortBy`(`recent` 默认 / `oldest` / `highest` / `lowest`)、
`rating`(1–5,只返回该星级;注意这里的星级筛选参数叫 `rating`,与 `/reviews` 的 `rating_filter` 不同)。
响应见 `store-reviews.list.json`:`title`、`user`、`reply` 可能为 `null`;`userReaction` 按访客 IP 匹配(`like` / `dislike` / `null`);
`summary.average` 与 `summary.total` 随 `rating` 筛选变化,`summary.distribution`(键为星级,只含有评论的星级)始终统计全部已发布店铺评论;
`allReviewMedia` 为最近 20 个媒体(供画廊使用)。
- `GET /featured`:`mode`(`featured` / `five-star` / `with-pictures` / `all`)、`limit`(1–50);**忽略 `shopId` 参数**,店铺由密钥决定。
响应见 `featured.list.json`:`title`、`user.country`、`product.mainImageUrl`、`response` 可能为 `null`;`timestamp` 为秒级 Unix 时间。
- **文本是 HTML 实体转义后的,不是纯文本**(与 `/reviews`、`/questions` 不同;主题店渲染依赖此行为,v1 保持不变):
`content`、`title`、`user.nickname`、`product.name`、`response.content` 中的 `<` `>` `"` `'` `/` `` ` `` `\` 分别替换为
`<` `>` `"` `'` `/` ``` `\`(`&` 本身不转义),并删除 `javascript:` 与 `on…=` 子串。
自建 UI 用 React / `textContent` 等按纯文本渲染时,需先把这些实体解码(如 `It's` → `It's`),否则会原样显示实体。
- `reviews[].product.url` 按店铺在后台「Headless」页的设置生成:启用 headless 且配置了店面地址(Storefront base URL)时为绝对 URL
(店面地址 + 商品路径模板,如 `https://shop.example.com/en-us/products/linen-shirt`);否则按商品路径模板(Product URL template,
默认 `/products/{handle}`)生成相对路径;handle 经 URL 编码。商品没有 handle 时不返回该字段。
- `GET /json-ld`:`product_id` 或 `product_handle`,可选 `limit`(最近评论条数 1–10,默认 5,非法值回落默认,超过 10 按 10)。
响应 `{ success, productId, jsonLd }`,`jsonLd` 是完整的 schema.org Product,**自带 `"@context": "https://schema.org"`**,
可直接写进 `<script type="application/ld+json">`;只统计该商品自己的已发布评论,**没有已发布评论时不输出 `aggregateRating` 与 `review`**
(Google 要求评分对应页面可见评论);文本已转纯文本并截断,不含 `<` `>`。
- 公开响应**不回传**任何购买验证结果。
### 写接口请求体
请求体大小上限与超限时的 413 见上文"请求体大小"。所有写接口都可带可选的 `shop`(字符串),只做一致性比对(不一致 403 `Shop mismatch`)。
字段缺失或不合法时返回 400 `{ "success": false, "error": "..." }`(`POST /reviews` 缺必填字段时另带 `fields`,见下)。
#### `POST /reviews`(`multipart/form-data`)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `rating` | 是 | 字符串,整数 `1`–`5` | 缺失或不是严格整数(如 `4.5`、`5abc`)400(`error` 为提示文案,不保证稳定) |
| `email` | 是 | 字符串 | 合法邮箱;格式非法 400 `Invalid email address` |
| `content` | 视店铺表单配置(默认必填) | 字符串 | |
| `nickname` | 视店铺表单配置(默认选填) | 字符串 | 缺省显示为 `Anonymous` |
| `title` | 否 | 字符串 | |
| `productId` / `product_id` | 与 `product_handle` 二选一 | 字符串,纯数字或 Product GID | 不是密钥所属店铺的商品(或不存在)404 `Product not found for this shop` |
| `product_handle` | 与上一项二选一 | 字符串 | 只在没有 `productId` / `product_id` 时使用,在密钥所属店铺内解析;找不到按缺少商品处理:400 `Missing required fields`(`fields.productId` 为 `"required"`) |
| `recommended` | 否 | 字符串 | `"true"` 表示推荐,其它值视为不推荐 |
| `mediaUrls[]` / `mediaTypes[]` / `mediaThumbnails[]` | 否 | 字符串(可重复,按顺序一一对应) | 预上传(`/media-upload`)返回的 `file.url` / `file.type`(`image` / `video`)/ `file.thumbnailUrl`(图片传空串);`mediaUrls[]` 与 `mediaTypes[]` 条数不一致时整体忽略;只接受本应用媒体存储域名的地址,其余丢弃;每条评论最多 6 张图片 + 1 个视频 |
| `media` | 否 | 文件(可重复) | 遗留直传兜底(预上传失败时),校验规则同 `/media-upload`;通常不要使用 |
缺少必填字段:400 `{ "success": false, "error": "Missing required fields", "fields": { "productId", "rating", "content", "nickname", "email" } }`
(`fields` 中缺失的字段为 `"required"`,其余为 `null`;缺 `rating` 会先按上表返回评分错误,因此 `fields.rating` 实际总为 `null`)。同一访客 IP + 邮箱 4 秒内只能提交一次(429)。响应见 `review.submit.json`。
#### `POST /questions`(JSON)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `productId` | 与 `productHandle` 二选一 | 字符串或数字,纯数字或 Product GID | |
| `productHandle` | 与上一项二选一 | 字符串 | 注意 JSON 字段名是 `productHandle`(驼峰) |
| `content` | 是 | 字符串 | 缺失 400 `Question content is required` |
| `email` | 是 | 字符串 | 缺失 400 `Email is required` |
| `nickname` | 否 | 字符串 | 缺省 `Anonymous` |
问题需商家审核后才会出现在列表。响应 `{ "success": true, "message": "Question submitted successfully and is pending approval", "questionId": 55 }`。
同一访客 IP 10 分钟内最多 5 个问题(429);商品找不到 404 `Product not found for this shop`。
#### `POST /store-reviews`(JSON)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `rating` | 是 | 整数 1–5(数字或数字字符串) | 非法 400 `Invalid rating` |
| `content` | 是 | 字符串 | 缺失 400 `Content is required` |
| `user_name` | 是 | 字符串 | 缺失 400 `Nickname is required`(注意字段名与商品评论的 `nickname` 不同) |
| `user_email` | 否 | 字符串 | 注意字段名与商品评论的 `email` 不同 |
| `title` | 否 | 字符串 | |
| `tempIds` | 否 | 字符串数组 | `/store-media-upload` 返回的 `file.tempId`;只接受 `[A-Za-z0-9_-]`、最长 64 的值,去重后最多 7 个(图片 6 + 视频 1),只认领本店铺上传且未被认领的文件 |
是否直接发布取决于店铺的自动发布设置。响应:
`{ "success": true, "review": { "id", "rating", "title", "content", "created_at", "user": { "nickname" }, "media": [{ "id", "url", "thumbnailUrl", "mediaType" }], "likesCount": 0, "dislikesCount": 0, "userReaction": null } }`。
#### `POST /review-reactions`、`POST /question-reactions`、`POST /store-review-reactions`(JSON)
| 接口 | 字段 | 必填 | 类型 / 取值 |
|---|---|---|---|
| `/review-reactions` | `reviewId` | 是 | 正整数(数字或数字字符串),商品评论 ID |
| `/question-reactions` | `questionId` 或 `answerId` | 恰好其一 | 正整数,问题 ID 或商家回复 ID;两者都带 400 |
| `/store-review-reactions` | `reviewId` | 是 | 正整数,店铺评论 ID |
| 三者 | `reaction` | 是 | `like` / `dislike` / `none`(`none` 取消已有反应) |
同一访客对同一条内容只保留一个反应(再次 `like` 不重复计数,`like` 改 `dislike` 会切换)。访客按指纹 `md5("{访客IP}:{UA}")` 识别
(UA 为请求自身的 `User-Agent`;私钥请求带 `X-CustomersSay-Client-UA` 时改用它,见第 1 节),找不到时按访客 IP 兜底;每个访客 IP 每分钟最多 30 次(429)。内容不属于密钥所属店铺时 404。
响应:`/review-reactions`、`/store-review-reactions` 为 `{ "success": true, "message": "...", "likesCount", "dislikesCount" }`
(`message` 为展示用文案,不保证稳定);`/question-reactions` 为 `{ "success": true, "likesCount", "dislikesCount" }`。
#### `POST /media-upload`、`POST /store-media-upload`(`multipart/form-data`)
- `POST /media-upload?productId=…`:商品用查询参数 `productId`(也接受 `product_id`)指定;
缺少时可改用 `product_handle`(也接受 `productHandle`),服务端在密钥所属店铺内解析为商品,找不到 404 `Product not found for this shop`;
两者都缺 400 `Missing productId parameter`。`/store-media-upload` 不需要商品参数。
- 表单字段:
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `type` | 是 | `image` / `video` | 其它值 400 |
| `file` | 是 | 文件 | 图片最大 2 MB、视频最大 20 MB;校验 MIME、扩展名与文件头,文件名含可疑代码 400 |
| `tempId` | 否 | 字符串 | 同一次评论的多个文件共用一个 `tempId`(按它统计每次最多 6 张图片 + 1 个视频、累计 30 MB);只接受 `[A-Za-z0-9_-]`、最长 64,**缺省或不合法时由服务端生成**(16 位十六进制)并在响应里返回,后续文件请沿用响应里的值 |
- 响应 `{ "success": true, "file": { "url", "thumbnailUrl", "type", "tempId" } }`(视频的 `thumbnailUrl` 为截帧地址,图片为 `null`)。
商品评论:提交时把 `file.url` / `file.type` / `file.thumbnailUrl` 放进 `POST /reviews` 的 `mediaUrls[]` / `mediaTypes[]` / `mediaThumbnails[]`;
店铺评论:把 `file.tempId` 放进 `POST /store-reviews` 的 `tempIds`,临时文件按密钥所属店铺隔离。
- 上传限流:每个访客 IP 每 10 秒约 10 次(429)。
## 3. 嵌入脚本(任意 headless 站点)
```html
<link rel="stylesheet" href="https://<应用域名>/api/storefront/v1/embed.css">
<script>
window.CustomersSayConfig = {
apiBase: "https://<应用域名>/api/storefront/v1",
publicKey: "pk_live_...",
shop: "your-store.myshopify.com"
};
</script>
<script src="https://<应用域名>/api/storefront/v1/embed.js" defer></script>
<div data-customerssay-reviews data-product-id="8123456789"></div>
```
单页应用切换商品时调用 `window.CustomersSay.mount(element, { productId })` / `unmount(element)`。
内容安全策略(CSP)需放行应用域名(script/style/connect)及媒体存储域名(img/media)。Swiper 的脚本与样式均由应用域名的 `/api/widget-assets/swiper-bundle.min.js` / `.css` 提供,无需放行 jsDelivr。
嵌入脚本不依赖内联事件处理器或动态注入的 style 标签;配置脚本应带站点 nonce。标记中仍有 style 属性,需要 `style-src-attr 'unsafe-inline'`(旧浏览器可在 style-src 放行内联样式)。React 包默认不输出 style 属性。
星级挂载每次初始化仅请求一次 rating-summary;请求失败时隐藏,不显示成 0 分。商品列表卡片推荐读取第 5 节评分字段。
## 4. React / Hydrogen
见仓库 `packages/customerssay-react/README.md`:服务端取数函数(loader 中调用,SSR 首屏与 JSON-LD)+ 客户端组件。
## 5. 商品评分元字段(Shopify Storefront API 直接读取)
除 v1 接口外,应用还把每个商品的评论汇总写进 Shopify 商品元字段。headless 店可以在自己的 Shopify Storefront API
(GraphQL)查询里直接读取(适合 SSR 首屏、商品列表卡片的星级),不经过 v1、不占用 v1 的限流额度。
评论提交、发布 / 取消发布、删除、导入后由应用自动同步(异步,可能有短暂延迟);只统计该商品自己的已发布评论。
| 元字段 | 类型 | 值 | 何时写入 |
|---|---|---|---|
| `customerssay.reviews_summary` | `json` | `{"average_rating": 4.58, "total_reviews": 12}`(平均分保留两位小数) | 始终写入 |
| `customerssay.recent_reviews` | `json` | 最近 5 条已发布评论的数组:`rating`、`title`、`content`、`author_name`、`created_at`、`verified_purchase` | 始终写入 |
| `reviews.rating` | `rating`(Shopify 标准定义 Product rating) | `{"value":"4.58","scale_min":"1.0","scale_max":"5.0"}` | 标准定义已启用,且有已发布评论(没有时删除) |
| `reviews.rating_count` | `number_integer`(Shopify 标准定义 Product rating count) | 已发布评论数。**没有评论的商品可能没有该元字段(查询为 `null`)**;有过评论、之后全部删除 / 取消发布时同步为 `0` | 标准定义已启用 |
- 元字段只在该商品发生过同步(评论提交、发布 / 取消发布、删除、导入)后才存在:从未有过评论的商品查询这些元字段都为 `null`,按“没有评论”处理。
- `customerssay.*` 两个定义由应用创建并开启 Storefront 只读(`PUBLIC_READ`)。
- `reviews.rating` / `reviews.rating_count` 是 Shopify 的标准评分元字段(Shopify 搜索、Google 等渠道也读取)。
应用在安装 / 重新授权时与定时任务中自动启用这两个标准定义(开启 Storefront 只读,幂等,失败会重试),
**确认启用之后才写入**;未启用期间只写 `customerssay.*` 汇总,不写 `reviews.*`。
若标准定义此前已由商家或其它应用启用,应用直接沿用、不修改其设置,请在 Shopify 后台确认该定义开启了 Storefront 访问。
```graphql
query ProductRating($handle: String!) {
product(handle: $handle) {
rating: metafield(namespace: "reviews", key: "rating") { value }
ratingCount: metafield(namespace: "reviews", key: "rating_count") { value }
reviewsSummary: metafield(namespace: "customerssay", key: "reviews_summary") { value }
}
}
```
建议优先读 `reviews.rating` / `reviews.rating_count`;为 `null`(标准定义尚未启用或商品没有评论)时回落到 `customerssay.reviews_summary`,
仍为 `null` 时按没有评论处理。
### 标准评分元字段未启用(UNSTRUCTURED_ALREADY_EXISTS)
如果店铺的商品上**已有同名但没有定义**的 `reviews.rating` / `reviews.rating_count` 元字段(例如旧版本应用或其它评论应用写过),
Shopify 不允许在其上启用标准定义(返回 `UNSTRUCTURED_ALREADY_EXISTS`),应用会持续只写 `customerssay.*` 汇总,
后台「Headless」页会显示"Shopify standard rating metafields are not enabled"提示。需要商家手动处理:
1. 在 Shopify 后台打开 设置 → 元字段和元对象(Metafields and metaobjects,旧称 Custom data)→ 产品(Products)→
无定义的元字段(Metafields without a definition);
2. 打开 `reviews.rating`,使用标准定义 Product rating 添加定义;`reviews.rating_count` 同样选择 Product rating count。现有值会保留;
3. 回到应用后台「Headless」页点"重新检查"(Check again)。确认启用后,后续同步即开始写入 `reviews.*`。
## 6. 已验证购买规则(摘要)
详见 `app/lib/verification/verificationPolicy.ts`:
- 私钥 + `X-CustomersSay-Customer-Id`:只认该顾客自己的订单;
- 私钥不带顾客 ID、或公钥提交:不自动判定,可由商家手动标记;
- 邀评邮件托管页(带可信 token):按邮箱判定。
## 6. 商家入口与部署
- 公开接入文档:应用域名下 `/headless/docs`;React 包文档:`/headless/docs/react`,无需后台登录。
- 后台 Headless 页管理密钥、可信 Origin、店面 URL,并展示 Google Shopping feed 地址。feed 的币种和库存状态仍有固定值,上线前必须对照实际目录核验。
- 后台 Manage Reviews 的单条评论菜单提供 Mark as verified purchase / Remove verified purchase。人工标记保留来源;取消会清除来源,email / customer_id 策略后续自动检查可能重新标记,操作提示会说明。
- 评论保存提交时的署名;同邮箱的公开提交不能覆盖已有用户资料。历史评论没有快照时沿用原署名,GDPR 删除同时清除快照。
- 新增迁移 `20261104010000_add_review_submitter_name` 仅增加可空列,不回填历史全表;部署前先应用迁移,再启动新代码。
- 按实际代理拓扑配置 `STOREFRONT_TRUSTED_PROXY_HOPS`,并禁止绕过可信代理直连应用。边缘必须覆盖 X-Real-IP,正确追加 X-Forwarded-For。
- 代理需转发 Content-Length 或先缓冲请求体;不要注入 `Access-Control-Allow-Origin: *`;尊重 Vary 和 Cache-Control: private。
- 部署主题扩展资源时运行 `shopify app deploy`,避免主题资源与 embed.js 版本不一致。React 包仍为仓库内交付,不自动发布 npm。
- 邀评托管页的感谢邮件链接不受 emailLinkMode 控制。