商家 API 指南
让客户通过你的 API 查询订单状态
Ouviro 可以在会话中调用你的只读 API。你的服务端必须判断访客提供的订单号和邮箱是否允许查询该订单。
Ouviro · 发布于
1. 准备只读查询接口
准备店主或管理员账号、网站渠道，以及返回 JSON 且不会修改订单、支付或履约状态的接口。使用虚构数据测试，例如 DEMO-1042 和 ana@example.com。
安装聊天组件或嵌入管理后台均不授予订单访问权限。这是自定义 API 集成，不是原生 Shopify 或 WooCommerce 连接器。
2. 使用固定的公网 HTTPS 主机
配置使用默认端口的完整 HTTPS URL。Ouviro 发送 GET 请求，不跟随重定向。访客值只能填入路径或查询参数，不能改变主机名。
localhost、IP 字面量、内网形式的主机名、ouviro.com、workers.dev 和 pages.dev 均会被拒绝。如果 API 托管于 Cloudflare Workers，请配置自己的公网自定义域名，不要尝试绕过主机限制。
3. 同时要求订单号和邮箱
至少将 order_id 和 email 设为必填参数，两者都必须出现在 URL 模板中，其中 email 放在查询字符串内。示例将 order_id 限为 64 个字符，email 限为 200 个字符；任何参数都不能超过 200 个字符。
商家服务端必须联合核验这两个值，再返回订单字段。Ouviro 的格式校验不能证明订单归属。请实施自己的授权校验和防滥用控制。
4. 将服务凭证保留在服务端
在工具设置中配置允许使用的请求头名称和服务密钥，Ouviro 会在服务端请求中添加它。不要把密钥放进组件、HTML、URL 或知识库文件。
该凭证用于授权调用方；你的 API 仍须核验访客提供的订单号和邮箱。
5. 为渠道配置工具
创建工具，选择对应渠道，并按实际接口调整下方定义。超时时间必须在 1 至 5 秒之间。
示例中的主机名和客户数据均为虚构。请替换为自己的接口，并单独保存密钥；此示例不是可直接使用的商家服务。
这段 JSON 用于说明配置字段。请逐项填写后台表单，表单不支持整段粘贴 JSON。参数长度上限属于 API 定义，无法在该表单中编辑。
{
"name": "get_order",
"description": "Look up order status and shipping details using the order number and the email used at checkout.",
"urlTemplate": "https://api.example.com/verified-orders/{order_id}?email={email}",
"params": [
{
"name": "order_id",
"description": "The order number provided by the visitor.",
"required": true,
"pattern": null,
"maxLength": 64
},
{
"name": "email",
"description": "The email used at checkout, provided by the visitor.",
"required": true,
"pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$",
"maxLength": 200
}
],
"responseMap": [
{
"path": "order.status",
"label": "Order status"
},
{
"path": "shipping.carrier",
"label": "Carrier"
},
{
"path": "shipping.eta",
"label": "Estimated arrival"
}
],
"authHeaderName": "Authorization",
"timeoutMs": 5000
}JSON · 说明示例
{
"order": {
"status": "shipped"
},
"shipping": {
"carrier": "Example Carrier",
"eta": "3–5 business days"
}
}6. 仅映射客户需要的字段
使用 order.status 或 order.shipment.status 这样的点分路径，不要添加 $. 前缀。路径必须匹配服务端实际返回的 JSON。
只有已映射的标量字段会提供给回答模型；缺失字段和对象不会成为订单事实。响应中不要包含内部备注、地址、支付凭证或无关客户记录。
7. 核对第一条有效查询回答
在后台使用相互匹配的虚构订单号和邮箱测试，检查请求、返回字段和状态。然后在组件内提供这两个值，查询同一订单。
将回答与 API 响应对照，并查看会话的工具调用记录。仅通过接口测试，不能证明实际会话行为正确。
8. 测试拒绝、未找到和超时
测试错误邮箱、未知订单、缺少参数、无效 JSON 和慢接口。邮箱不匹配时，接口不得泄露任何订单字段。未找到、HTTP 错误和超时结果，不能被转述成虚构的发货或支付详情。
查询失败时，应请客户修正信息或转人工处理。超时不代表订单不存在、已取消或尚未付款。