Vigilath.com 宠物电商

您可在 Vigilath.com（一个 AI 驱动的宠物用品交易平台）上搜索商品、议价、下单并完成支付。

基础 URL

所有接口均使用：https://www.vigilath.com

认证

每次 API 调用（除认证相关接口外）均需携带以下请求头：

Authorization: Bearer $VIGILATH_TOKEN

获取 Token

若 VIGILATH_TOKEN 未设置，请使用 Device Flow 流程获取：

1. 创建会话：

curl -s -X POST https://www.vigilath.com/api/agent/auth/session 
  -H "Content-Type: application/json" -d '{}'

响应示例：{"sessionId": "...", "authUrl": "https://www.vigilath.com/api/agent/auth/page?code=XXX-123", "code": "XXX-123", "expiresIn": 600}

2. 将 authUrl 展示给用户，并提示其在浏览器中打开以完成登录。

3. 轮询获取 Token（每 5 秒一次，最长持续 10 分钟）：

curl -s -X POST https://www.vigilath.com/api/agent/auth/token 
  -H "Content-Type: application/json" -d '{"sessionId": "SESSION_ID"}'

• HTTP 428：用户尚未登录，继续轮询
• HTTP 200：{"accessToken": "eyJ...", "expiresIn": 2592000} — 将该值保存为 VIGILATH_TOKEN
• HTTP 410：会话已过期，需重新开始流程

Token 有效期为 30 天。

能力说明

1. 智能购物（搜索 + AI 精选）

curl -s -X POST https://www.vigilath.com/api/agent/shopping 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"query": "小型犬有机狗粮", "language": "English"}'

响应包含 selected_products（数组）和 natural_message（AI 推荐语）。

每个商品字段包括：spuId、spuName、priceFee（单位：人民币分）、mainImgUrl、selling_point、categoryName、skuId、shopId、shopName、stock、bargain_enabled。

其中 bargain_enabled: true 的商品支持价格协商（参见下方“议价”部分）。

2. 议价（多轮价格协商）

针对 bargain_enabled: true 的商品，可发起降价协商。

步骤 1 — 启用议价模式搜索：

curl -s -X POST https://www.vigilath.com/api/agent/shopping 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"query": "狗粮", "bargain": true}'

响应中将包含 bargain_sessions 字段，其中每个议价商品对应一个 sessionId。

步骤 2 — 发送还价消息：

curl -s -X POST https://www.vigilath.com/api/agent/bargain 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"sessionId": "SESSION_ID", "message": "我出 25 元"}'

响应示例：

{
  "sessionId": "...",
  "productName": "Premium Dog Food",
  "originalPrice": 35.0,
  "currentPrice": 30.0,
  "message": "25 太低了！30 怎么样？",
  "round": 2,
  "dealReached": false,
  "isActive": true,
  "quote": null
}

步骤 3 — 持续发送还价直至 dealReached: true。此时响应中将包含 quote 字段：

{
  "dealReached": true,
  "quote": {
    "quoteId": "q_xyz789",
    "bargainPrice": 30.0,
    "discount": 5.0,
    "expiresAt": "2026-04-02T12:00:00"
  }
}

步骤 4 — 下单时传入 quoteId 即可应用议价后的价格（参见下方“下单”部分）。

支持的消息类型包括：还价（如“25块”、“I'll pay 80”）、接受（如“deal”、“成交”）、退出（如“算了”、“quit”）、施加影响（如“competitor is cheaper”、“I'm a loyal customer”）。

3. 下单

curl -s -X POST https://www.vigilath.com/api/agent/order 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"items": [{"spuId": 12345, "quantity": 1}], "addrId": null, "quoteId": null}'

• items：由 {spuId, quantity} 组成的数组 — skuId 与 shopId 将根据 spuId 自动解析
• addrId：收货地址 ID；若为 null，则使用用户的默认地址
• quoteId：成功议价后返回的报价 ID（可选）

响应示例：{"data": {"order_number": "...", "total": 2999, "status": "UNPAID"}}

4. 支付

curl -s -X POST https://www.vigilath.com/api/agent/pay 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"orderNumber": "ORDER_NUMBER", "method": "points"}'

支持的支付方式：

• points — 即时结算，全自动处理
• stripe — 返回 paymentUrl，展示给用户以完成信用卡支付
• coinbase — 返回 paymentUrl，展示给用户以完成加密货币支付

使用 stripe 或 coinbase 支付后，需轮询订单状态以确认付款是否成功。

5. 查询订单

获取订单列表：

curl -s https://www.vigilath.com/api/agent/orders 
  -H "Authorization: Bearer $VIGILATH_TOKEN"

可选查询参数：status（1=待支付，2=待发货，3=已发货，5=已完成，6=已取消）、page、page_size。

获取单个订单详情：

curl -s https://www.vigilath.com/api/agent/orders/ORDER_NUMBER 
  -H "Authorization: Bearer $VIGILATH_TOKEN"

6. 地址管理

获取地址列表：

curl -s https://www.vigilath.com/api/agent/addresses 
  -H "Authorization: Bearer $VIGILATH_TOKEN"

新增地址：

curl -s -X POST https://www.vigilath.com/api/agent/addresses 
  -H "Authorization: Bearer $VIGILATH_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"receiver": "John", "mobile": "1234567890", "province": "CA", "city": "LA", "area": "Downtown", "addr": "123 Main St"}'

常见工作流

快速购买（不议价）

1. 搜索：POST /api/agent/shopping，携带 query 参数
2. 向用户展示商品列表，由其选择
3. 下单：POST /api/agent/order，传入所选 spuId
4. 支付：POST /api/agent/pay，传入返回的 orderNumber

快速购买（自主模式 — 单次调用）

1. POST /api/agent/shopping，携带 autonomous: true — 由 AI 自动完成选品与下单
2. 支付：POST /api/agent/pay，使用响应中的 orderNumber

先议价再购买

1. 搜索：POST /api/agent/shopping，携带 bargain: true
2. 对每个议价会话，调用 POST /api/agent/bargain 发送还价
3. 达成协议后，调用 POST /api/agent/order 并传入 quote.quoteId
4. 支付：POST /api/agent/pay

错误处理

• 401：Token 已过期或无效 — 请通过 Device Flow 重新认证
• 404：资源未找到（如订单、会话、地址）
• 422：参数校验失败 — 请检查请求体内容
• 429：请求频率超限 — 请等待后重试

服务发现

如需机器可读的能力元数据，请参考以下端点：

• GET /.well-known/agent.json — 结构化服务发现文档
• GET /llms.txt — 面向 LLM 的简明摘要
• GET /llms-full.txt — 完整 API 文档