pricewatcha

Pricewatcha API

Pricewatcha API 是面向开发者、自动化和 AI Agent 的结构化产品价格情报平台。

Pricewatcha API 源自 pricewatcha.com 应用。除 Pricewatcha 控制面板提供的功能外，它还提供价格跟踪、提醒和产品情报。本仓库记录了公共 HTTP API、OpenAPI 架构、官方 SDK、MCP 服务和示例。它不包含生产环境中的 Web 应用或抓取工具。

状态： 可用 · 版本： v1 · 基础 URL： https://pricewatcha.com/api/v1

交互式 API 密钥（浏览器）： 个人资料与 API 密钥

---

可选：使用 GET https://pricewatcha.com/api/v1/health 验证连接。然后从以下三种方式中选择一种。

快速入门

方式 1：浏览价格（无需身份验证）

使用演示目录中的演示产品 ID，或搜索目录：

curl -s "https://pricewatcha.com/api/v1/products/demo_iphone_15_pro"
curl -s "https://pricewatcha.com/api/v1/search?q=iphone+15&limit=10"

搜索采用不区分大小写的词元 AND（必须包含所有词条，词序不限）。结果包含完整的 Pricewatcha 目录，而不仅仅是通过 POST /track 提交的 URL。使用搜索结果中的 product_id 调用产品和价格历史端点（prod_* 或 demo_*）。

方式 2：跟踪产品并获取价格历史

curl -s -X POST "https://pricewatcha.com/api/v1/track" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.backmarket.de/de-de/p/example-product"}'

curl -s "https://pricewatcha.com/api/v1/products/{productId}/price-history"

POST /track 会返回 HTTP 200，并进行有时限的服务端长轮询（约 25 秒）。使用响应中的 product_id 获取价格历史。可选：发送 Authorization: Bearer pwk_live_…，以使用更高的跟踪、搜索和产品读取配额。

响应迅速的商店会在一次调用中返回 status: "completed" 和完整的 product。响应较慢的商店会返回 status: "running" 和 job_id。轮询 GET https://pricewatcha.com/api/v1/jobs/{jobId}，直到任务状态变为 completed 或 failed。更多详情：异步跟踪与轮询。

方式 3：使用 Webhook 发送价格提醒（需要 API 密钥）

在个人资料与 API 密钥中创建密钥，然后：

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4e5",
    "notify_on_drop": true,
    "min_threshold_price": 500.00,
    "webhook_url": "https://your-n8n-instance.com/webhook/abc",
    "notify_email": true
  }'

有关身份验证和数据边界，请参阅身份验证和数据边界。

---

身份验证

目录搜索、产品详情、价格历史和异步跟踪/轮询无需凭据。未提供密钥时，这些端点使用匿名速率限制。发送 API 密钥即可使用更高的账户级跟踪、搜索和产品读取配额。

受保护的 API v1 端点（提醒、Webhook、经过身份验证的跟踪回调）使用：

Authorization: Bearer pwk_live_…

凭据	格式	使用场景
API 密钥	pwk_live_…	脚本、Agent、n8n 和服务器集成的推荐方式。在个人资料与 API 密钥中创建。
登录会话令牌	来自 POST https://pricewatcha.com/api/auth/login 的 JWT	仅用于网站 UI 和无头密钥引导

拥有 API 密钥后，请勿使用登录会话令牌调用提醒、Webhook 或其他 API v1 接口。

有关哪些路由为公开接口、哪些需要身份验证，请参阅访问模型。

---

API 密钥（浏览器）

登录并打开个人资料与 API 密钥，即可在浏览器中创建和管理 API 密钥。完整密钥只会在创建时显示一次。

对于无法使用浏览器的 Agent，请使用下方的无头密钥引导。

在受保护的端点上使用密钥：

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_a1b2c3d4e5", "notify_on_drop": true}'

---

无头密钥引导（面向 Agent）

如果 Agent 必须在没有浏览器的情况下获取 API 凭据，请使用与网站相同的电子邮件地址和密码进行一次身份验证，创建 API 密钥，然后在后续所有调用中使用 pwk_live_…。这并非单独的 Agent 登录方式，而是通过 HTTP 端点公开的常规 Pricewatcha 账户登录方式。

如何通过 API 登录

POST https://pricewatcha.com/api/auth/login 接受包含 email 和 password 的 JSON，并返回一个短期有效的 access_token（登录会话令牌）。开发者页面中的登录弹窗会调用同一端点；在脚本或 Agent 中，你可以直接使用 curl 或 HTTP 客户端调用它。

• 你需要已有账户（在网站上注册，或通过 POST https://pricewatcha.com/api/auth/register 注册）。
• 邮箱必须经过验证，否则 API 会返回 403。
• 凭据错误会返回 401。
• 仅使用 access_token 创建密钥；对于提醒和 Webhook，请使用第 2 步中的 pwk_live_… 密钥。

第 1 步：登录

curl -s -X POST "https://pricewatcha.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "YOUR_PASSWORD"}'

响应（HTTP 200），AuthResponse：

• access_token（字符串）：登录会话令牌（JWT）
• token_type（字符串）：始终为 "bearer"
• user（对象）：id（字符串，UUID）、email（字符串）、email_verified（布尔值）

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "email_verified": true
  }
}

在第 2 步中，将令牌作为 Authorization: Bearer <access_token> 发送。会话令牌会过期；不要将其存储为 Agent 的长期凭据。

第 2 步：创建 API 密钥

curl -s -X POST "https://pricewatcha.com/api/keys" \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent bootstrap"}'

响应（HTTP 200），CreateApiKeyResponse：

• id（整数）：密钥 ID
• name（字符串）：请求中的标签
• key_prefix（字符串）：密钥的前 12 个字符（用于显示）
• key（字符串）：完整密钥；仅在创建时返回，不会在列表中返回
• is_active（布尔值）
• created_at（字符串，ISO 8601 日期时间）
• last_used_at（字符串或 null）
• revoked_at（字符串或 null）

{
  "id": 42,
  "name": "agent bootstrap",
  "key_prefix": "pwk_live_ab",
  "key": "pwk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "is_active": true,
  "created_at": "2026-05-27T14:30:00.123456",
  "last_used_at": null,
  "revoked_at": null
}

安全存储 key。在提醒、Webhook 和其他受保护的 API v1 端点中使用它，而不要使用第 1 步中的会话令牌。

---

API 端点（概览）

方法	路径	身份验证	描述
GET	/api/v1/health	-	健康检查
GET	/api/v1	-	发现信息和免责声明
POST	/api/v1/track	-	URL 导入（长轮询）
GET	/api/v1/jobs/{jobId}	-	任务状态
GET	/api/v1/products/{productId}	-	商品情报
GET	/api/v1/products/{productId}/price-history	-	历史记录和趋势
GET	/api/v1/search?q=	-	关键词搜索（limit 最大为 200）
GET	/api/v1/openapi.json	-	实时 OpenAPI 3.1
POST	/api/auth/login	-	登录（短期有效的会话令牌）
POST	/api/keys	会话令牌	创建 API 密钥
GET / DELETE	/api/keys …	会话令牌或密钥	列出／撤销密钥
*	/api/v1/alerts …	API 密钥	价格提醒
*	/api/v1/watchlist / …/watch	API 密钥	持续价格监控清单
*	/api/v1/webhooks …	API 密钥	Webhook 订阅

机器可读的规范：openapi/openapi.yaml · 实时版本：GET https://pricewatcha.com/api/v1/openapi.json

---

速率限制

当前限制（仅供参考）

以下限制当前适用，且可能随时变更，恕不另行通知。

类别	端点	匿名	已认证（API 密钥）
跟踪（并发）	POST /track	约 2 个正在处理的作业	约 4 个正在处理的作业
跟踪（突发）	POST /track	约 10 个作业 / 60s	约 20 个作业 / 60s
跟踪（每小时）	POST /track	约 40 个作业 / 小时	约 120 个作业 / 小时
跟踪（每日）	POST /track	约 80 个作业 / 天	约 400 个作业 / 天
作业轮询	GET /jobs/{id}	每个客户端约 40 req/min	相同
搜索（突发）	GET /search	约 20 req / 60s	约 40 req / 60s
搜索（每小时）	GET /search	约 60 req / 小时	约 180 req / 小时
搜索（每日）	GET /search	约 200 req / 天	约 1000 req / 天
读取（突发）	/products、/price-history	每个客户端约 60–120 req/min	约 240 req / 60s
读取（每小时）	/products、/price-history	约 180 req / 小时	约 540 req / 小时
读取（每日）	/products、/price-history	约 600 req / 天	约 3000 req / 天
健康检查	/health 和 /	不限	不限

在 POST /track、GET /search 或读取产品时，发送 Authorization: Bearer pwk_live_… 即可使用已认证档位。这些端点也可在匿名限制内无密钥访问。

客户端身份： 匿名限制按客户端 IP 计算。在 Cloudflare 后方时，API 优先使用 CF-Connecting-IP 而非 X-Forwarded-For，以免将边缘代理 IP 视为不同客户端。托管的 MCP 服务会通过共享代理密钥转发稳定的 X-Pricewatcha-Client-Id（OAuth 令牌哈希，否则为连接 IP 哈希），避免 MCP 调用方全部被计入同一个出口 IP。已认证的跟踪、搜索和产品读取配额按账户（owner_id）而非 IP 计算。

监控 X-RateLimit-Remaining，并在收到 429 时遵循指数退避策略。X-RateLimit-Policy 会标明响应头所指的时间窗口（track、track_hourly、track_daily、track_concurrent、job_read、search、search_hourly、search_daily、read、read_hourly 或 read_daily）。

跟踪配额根据已持久化的作业计算（按客户端密钥或账户查询 api_track_jobs），因此多个应用实例共用该配额。即使长轮询使 HTTP 连接保持约 25s，创建时仍只计为 一个 跟踪作业；如果连续跟踪的间隔超过 60s，就不会触发突发窗口限制，但每小时、每日及并发上限仍然适用。

Agent 应优先采用以下方式：启动跟踪 → 通过退避策略轮询 GET /jobs/{id}（而非每隔 1–2s 轮询一次）→ 完成后读取一次产品信息 / 历史记录。在作业仍处于 queued/processing 状态时，使用相同 URL 重试 POST /track 会复用现有作业，不会占用额外的并发名额。若作业处于 queued/processing 状态的时间超过抓取超时时间（默认 600s），则会被标记为失败，以免部署期间名额被占用不放。

搜索和产品读取配额按应用实例保存在内存中（不会像跟踪作业那样在 Railway 副本之间共享）。已认证的调用方仍可获得更高的账户级时间窗口。短间隔重复轮询相同的目录查询仍会触发每小时 / 每日搜索时间窗口限制。

确切数值可能随时变更，恕不另行通知（环境变量覆盖项：API_V1_TRACK_*、API_V1_TRACK_AUTH_*、API_V1_JOB_READ_*、API_V1_READ_*、API_V1_READ_AUTH_*、API_V1_SEARCH_*、API_V1_SEARCH_AUTH_*）。

响应头

启用速率限制时，响应可能包含以下内容：

响应头	说明
X-RateLimit-Limit	此时间窗口内的最大请求数
X-RateLimit-Remaining	此时间窗口内剩余的请求数
X-RateLimit-Reset	时间窗口重置时的 Unix 时间戳
X-RateLimit-Policy	响应头所描述的时间窗口

HTTP 429

达到限制时，API 会返回 429 Too Many Requests，并附带 JSON 正文：

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (track daily). Try again later.",
    "http_status": 429,
    "retry_recommended": true,
    "retry_after_seconds": 3600
  }
}

**Agent 指引：**遵守 429，等待 retry_after_seconds / X-RateLimit-Reset 指定的时间，并降低作业状态端点的轮询频率。与其在每小时／每日上限临近时突发请求，不如将跟踪请求分散到一段时间内。匿名 429 响应会提示，API 密钥可以提高配额。

当每小时／每日／并发跟踪限制，或每小时／每日搜索和商品读取限制触发时，运营人员可以收到电子邮件（每个客户端有冷却时间；参见 API_V1_RATE_LIMIT_ALERT_*）。

滥用和 IP 限制

持续滥用匿名每日配额（跟踪、搜索或商品读取——例如，连续多天从同一 IP 耗尽每日限额）可能触发应用内限制，而不仅仅是 429。

1. **通知（宽限期）。**API 调用仍会成功。响应包含 X-Pricewatcha-Restriction: notice 和 X-Pricewatcha-Restriction-Message，其中附有即将封禁的警告。速率限制仍然适用。
2. **封禁。**如果没有收到回复，IP 将被封禁。后续调用会返回 HTTP 403，且 error.code 为 access_restricted。

请发送电子邮件至 [email protected]，讨论相关条款或恢复访问权限。在访问权限恢复前，请勿重试。重试不会解除限制。

---

异步跟踪和轮询

POST /api/v1/track 会提交商品 URL，并最多等待 约 25 秒（长轮询）。无需 API 密钥。发送 Authorization: Bearer pwk_live_…，即可使用更高的每账户跟踪配额。

• 快速商店：响应中包含 status: "completed" 和完整的 product
• 慢速商店：响应中包含 status: "running" 和 job_id：轮询 GET /api/v1/jobs/{jobId}，直到状态变为 completed 或 failed
• 当某个作业仍在运行时，对同一 URL 重复执行 POST /track 会返回该作业，而不会启动另一个作业（也不会触发并发 429）
• 使用 API 密钥时：watch: true 会将商品加入持续调度更新；即使 URL 已在目录中，refresh: true 也会强制重新抓取

作业会保留 72 小时。过期后，GET /jobs/{jobId} 会返回 404：请改用 GET /products/{productId}。

典型流程

快速商店（一次调用）

POST /api/v1/track → { "status": "completed", "product": { ... } }

慢速商店

POST /api/v1/track → { "status": "running", "job_id": "job_xxx", "hint": "..." }
GET  /api/v1/jobs/{jobId} → poll until terminal state
GET  /api/v1/products/{productId} and .../price-history

跟踪商品

curl -s -X POST "https://pricewatcha.com/api/v1/track" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.backmarket.de/de-de/p/example-product"}'

抓取在长轮询时间窗口内完成时的响应（200）：

{
  "job_id": "job_xxxxxxxx",
  "status": "completed",
  "product": {
    "product_id": "prod_xxxxxxxx",
    "name": "Example product",
    "shop": "Back Market",
    "current_price": 563,
    "currency": "EUR"
  },
  "error": null
}

长轮询超时后仍在运行时的响应（200）：

{
  "job_id": "job_xxxxxxxx",
  "status": "running",
  "product": null,
  "error": null,
  "hint": "Job still running. Call the get_job_status tool with this job_id to poll for the result."
}

轮询作业状态

curl -s "https://pricewatcha.com/api/v1/jobs/job_xxxxxxxx"

已完成响应

{
  "job_id": "job_xxxxxxxx",
  "status": "completed",
  "product": {
    "product_id": "prod_xxxxxxxx",
    "name": "Example product",
    "shop": "Back Market",
    "current_price": 563,
    "currency": "EUR"
  }
}

作业状态

状态	含义
queued	作业已接受，正在等待启动
running	正在进行数据摄取
completed	product 中包含商品智能信息
failed	抓取失败：读取结构化的 error（HTTP 200 作业查询）

推荐的客户端流程

1. 使用 { "url": "..." } 执行 POST /track → 200
2. 如果状态为 running 或 queued，每 2–5 秒轮询一次 GET /jobs/{jobId}
3. 状态变为 completed 后，从作业中读取 product，或调用 GET /products/{productId}
4. 状态变为 failed 后，显示 error.code；在重试前进行退避

作业查询与抓取失败

轮询 GET /jobs/{jobId} 时，请结合 HTTP 状态和正文进行判断：

响应	含义	处理方式
HTTP 404	没有此 job_id 的作业（ID 错误或作业在 72 小时后过期）	停止轮询；如果仍需要此商品，请发起新的 POST /track
HTTP 200 且 "status": "failed"	作业存在，但抓取失败	读取 JSON 正文中的 error.code（例如 scrape_target_not_found）

404 表示查询问题。状态为 failed 的 200 表示作业已完成，但抓取未成功。

跟踪任务 Webhook（推送）

通过身份验证的客户端可以在跟踪任务完成时接收推送：使用 callback_url（一次性）或 webhook_id（现有订阅）。两者不能同时使用。除经过身份验证的跟踪任务本身外，回调不会消耗额外配额。

curl -s -X POST "https://pricewatcha.com/api/v1/track" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.backmarket.de/de-de/p/example-product",
    "callback_url": "https://n8n.example.com/webhook/track-done"
  }'

使用 callback_url 时，跟踪响应可能会返回一次 callback_secret（whsec_…）：其签名方式与订阅 Webhook 相同。

任务完成时，Pricewatcha 会发送事件类型为 track_job_completed 或 track_job_failed 的 Webhook（负载结构与其他 Webhook 相同）。如果不使用推送方式，你仍可以等待 POST /track（长轮询），或轮询 GET /jobs/{jobId}，直到任务进入终止状态。

注意： 匿名调用 POST /track 并提供 callback_url 或 webhook_id 时，会返回 400 auth_required_for_callback。MCP 工具使用跟踪 → 轮询（v1 中不使用 callback_url）。

SDK 便捷方法

官方 Python 和 TypeScript SDK 可能会提供 track_and_wait() / trackAndWait()：这是一个辅助方法，会调用 POST /track，然后轮询 GET /jobs/{jobId}，直到任务状态变为 completed 或 failed，并返回结果。HTTP API 仍以异步为主；该辅助方法只是省去你自行编写轮询循环的工作。请参阅 SDK。

去重

对同一 URL 重复调用 POST /track，可能会基于已有情报快速返回 completed。

超时

长轮询的默认时长约为 25 秒。对于处理较慢的商店，请轮询 GET /jobs/{jobId}，而不是延长跟踪超时时间。

---

搜索

关键词搜索不区分大小写。查询会拆分为多个词元；当每个词元都出现在规范化后的商品名称、URL、平台/商店或相关字段中时，商品才会匹配。词元顺序无关紧要，连字符和斜杠等标点会视为空格（Darth-Vader 可匹配 Darth Vader）。搜索结果涵盖 Pricewatcha 的全部商品目录，而不仅是通过 POST /track 提交的 URL。

如果连续短语与其他词元匹配结果都符合条件，连续短语的排名仍会更高。

端点

GET https://pricewatcha.com/api/v1/search?q=…&limit=…

可选参数 limit：默认值为 50，最大值为 200。此参数在排除词过滤后应用。

搜索的速率限制与商品读取分开计算。匿名调用者每 60 秒约可请求 20 次、每小时约 60 次、每天约 200 次；使用 API 密钥后，每个账户每 60 秒约可请求 40 次、每小时约 180 次、每天约 1000 次。请遵守 HTTP 429 和 X-RateLimit-Policy；请参阅速率限制。

q 支持 Google 风格的减号前缀排除词。q=iPhone+15+-cover+-case 会返回在可搜索字段中同时包含 "iPhone" 和 "15"、但不包含 "cover" 或 "case" 的商品（不区分大小写）。单独的 - 会被忽略。

curl -s "https://pricewatcha.com/api/v1/search?q=iphone&limit=10"
curl -s "https://pricewatcha.com/api/v1/search?q=iPhone+15+-cover+-case"
curl -s "https://pricewatcha.com/api/v1/search?q=Darth+Vader+DX27"

响应示例

[
  {
    "product_id": "demo_iphone_15_pro",
    "name": "Apple iPhone 15 Pro 128GB (Refurbished)",
    "shop": "Back Market",
    "product_url": "https://www.backmarket.de/de-de/p/example-iphone-15-pro",
    "current_price": 563,
    "currency": "EUR",
    "status": "active",
    "preview": true,
    "google_product_category_id": null,
    "google_product_category_name": null
  },
  {
    "product_id": "prod_a1b2c3d4e5",
    "name": "iPhone 15 Pro",
    "shop": "Swappie",
    "product_url": "https://swappie.com/de/p/iphone-15-pro/",
    "current_price": 505,
    "currency": "EUR",
    "status": "active",
    "google_product_category_id": null,
    "google_product_category_name": null
  }
]

无需额外调用 GET /products/{id}，即可使用 product_url 直接链接商品。

结果始终包含 google_product_category_id 和 google_product_category_name（未设置时为 null）。无需添加额外的查询参数。

演示目录（无需抓取）

预览演示商品始终可用于集成测试：

curl -s "https://pricewatcha.com/api/v1/products/demo_iphone_15_pro"
curl -s "https://pricewatcha.com/api/v1/products/demo_iphone_15_pro/price-history"
curl -s "https://pricewatcha.com/api/v1/search?q=iphone+15+pro"

请在 GitHub 上查看演示目录。

---

数据边界

目录中的价格情报（当前价格、历史记录、商品元数据）无需身份验证即可访问。用户专属数据（账户、电子邮件、提醒设置）绝不会通过公共读取端点公开。

通过身份验证的客户端可以通过 /api/v1/watchlist 和 /api/v1/products/{id}/watch 管理自己的监视列表（需要 API 密钥）。绝不会返回其他用户的监视列表。

可读取字段

• product_id、名称、商店／平台、商品 URL
• 当前价格、货币、上次检查时间、状态
• 价格历史、历史最低价／最高价、平均价、趋势
• 当价格数据直接来自商家 Feed 时，提供 data_source 和 data_source_label（merchant_feed → "Direct merchant data"）
• 商品详情和搜索结果中的 google_product_category_id 和 google_product_category_name（未设置时为 null）。搜索无需额外的查询参数。
• 示例条目可能包含 "preview": true

无论商品是通过控制面板、API、MCP 还是示例数据添加的，搜索、商品详情和价格历史都会返回相同的字段。

持续更新

价格调度器只会刷新账户监控列表中的商品（通过控制面板或 API 监控／提醒／商品级价格 webhook 添加）。不带 watch 的一次性 POST /track 不会将商品加入持续更新。

商品 ID

前缀	含义
demo_*	静态预览示例（例如 demo_iphone_15_pro）
prod_*	每个目录商品对应的稳定不透明 ID（每个 URL 实体一个）

使用搜索结果或已完成的跟踪任务中的 product_id 调用 GET /products/{productId} 和 .../price-history。

Webhook 载荷

推送内容仅包含商品级事件数据（价格、商品 ID、事件类型），不包含用户邮箱或账户详情。使用订阅签名密钥（whsec_...）验证真实性；请参阅 Webhooks。

合规性

如果你基于此 API 构建产品，请向用户说明价格仅供参考，商家网站上的信息具有权威性。

---

错误与错误代码

非成功响应会使用结构化的 error 对象。检查 error.code；不要解析自由文本 message 的值。

结构

{
  "error": {
    "code": "invalid_url_type",
    "message": "url looks like a search or listing page (query parameter 'k')",
    "http_status": 400,
    "retry_recommended": false,
    "retry_after_seconds": null
  }
}

字段	说明
code	稳定的机器可读标识符
message	供人阅读的详细信息（不用于分支逻辑）
http_status	响应正文中回显的 HTTP 状态码
retry_recommended	是否可能通过重试解决问题
retry_after_seconds	触发速率限制时的等待提示（可能为 null）

公共／跟踪／目录错误代码

代码	常见 HTTP 状态	情况
invalid_input_format	400	JSON 或参数格式错误
invalid_url_type	400	URL 指向搜索／列表页面、不受支持的商店等
job_not_found	404	未知或已过期的 job_id（任务在 72h 后过期）
product_not_found	404	未知的 product_id
scrape_target_not_found	404	在商店中找不到商品页面
scrape_chain_exhausted	502	所有抓取策略均失败
scrape_timeout	200（任务失败）	跟踪任务超出抓取超时时间，或排队中／处理中的任务在工作进程丢失后被回收
rate_limited	429	跟踪／搜索／读取配额已超限：遵循 retry_after_seconds。匿名流量按客户端 IP 限制；API 密钥按账户提供更高的跟踪、搜索和商品读取配额。
access_restricted	403	客户端 IP 在收到滥用通知后被封锁。请发送邮件至 [email protected]。访问恢复前请勿重试。在此前的宽限期内，API 仍可使用，并会发送 X-Pricewatcha-Restriction: notice。
internal_error	500	意外的服务器错误

身份验证与 API 密钥

代码	常见 HTTP 状态	情况
unauthenticated	401	缺少或无效的 bearer token
invalid_session_token	401	登录会话已过期或无效（不是 API 密钥）
invalid_api_key	401	API 密钥已撤销或未知
api_key_limit_reached	403	账户密钥配额已超限
api_key_not_found	404	找不到密钥 ID

警报与 Webhook

代码	常见 HTTP 状态码	适用情况
alert_already_exists	409	每位用户针对每个产品只能有一个警报：请使用 PATCH
alert_not_found	404	未知的 alert_id
webhook_not_found	404	未知的订阅
webhook_limit_reached	403	超出订阅配额
auth_required_for_callback	400	未进行身份验证时，在 POST /track 中使用了 callback_url / webhook_id
callback_conflict	400	同时设置了 callback_url 和 webhook_id
invalid_callback_url	400	回调 URL 不是 HTTPS，或目标被阻止

Agent 使用指南

• 根据 error.code 而非 message 进行分支处理。
• 当 retry_recommended 为 true 时，请使用指数退避，并遵守 retry_after_seconds。
• GET /jobs/{jobId} 返回 HTTP 200 且 status: "failed"，表示作业失败，而非传输错误。

完整架构：实时 GET https://pricewatcha.com/api/v1/openapi.json，以及 GitHub 上的 OpenAPI 规范。

---

价格提醒 API

创建价格提醒，在价格变动时发送电子邮件通知和/或触发 Webhook。

每个受追踪产品对每位用户只有一条提醒记录。可组合使用以下任意设置：

• notify_on_drop：价格有任何下降时通知（无需设置阈值）
• notify_on_rise：价格有任何上涨时通知（无需设置阈值）
• min_threshold_price：价格降至或低于此值时通知
• max_threshold_price：价格升至或高于此值时通知

以上四项设置中至少需要设置一项。

创建提醒也会为你的账户关注该产品，以便价格调度器持续更新价格（参见关注列表）。

所有端点都需要在 Authorization: Bearer … 中提供 API 密钥。完整架构：GET https://pricewatcha.com/api/v1/openapi.json（标签 alerts）。

端点

方法	路径	说明
GET	/api/v1/alerts	列出你的提醒。可选：?product_id=prod_…
POST	/api/v1/alerts	创建提醒。如果提醒已存在，则返回 409 alert_already_exists：请使用 PATCH
GET	/api/v1/alerts/{alertId}	获取一条提醒
PATCH	/api/v1/alerts/{alertId}	更新阈值、方向标记、Webhook URL、电子邮件、名称、is_active
DELETE	/api/v1/alerts/{alertId}	删除（204）

创建方向提醒（无阈值）

价格下跌时通知——效果与控制面板中的 Cheaper 开关相同：

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4e5",
    "notify_on_drop": true,
    "notify_email": true,
    "name": "Any drop"
  }'

创建阈值提醒

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4e5",
    "min_threshold_price": 499.00,
    "max_threshold_price": 599.00,
    "webhook_url": "https://n8n.example.com/webhook/alert",
    "notify_email": true,
    "name": "Deal range"
  }'

响应示例（201）：

{
  "alert_id": 76,
  "product_id": "prod_a1b2c3d4e5",
  "min_threshold_price": 499.00,
  "max_threshold_price": 599.00,
  "notify_on_drop": false,
  "notify_on_rise": false,
  "currency": "EUR",
  "webhook_url": "https://n8n.example.com/webhook/alert",
  "notify_email": true,
  "name": "Deal range",
  "is_active": true,
  "created_at": "2026-05-24T12:00:00Z",
  "updated_at": "2026-05-24T12:00:00Z",
  "last_triggered_at": null
}

列出与获取

curl -s "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

curl -s "https://pricewatcha.com/api/v1/alerts?product_id=prod_a1b2c3d4e5" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

curl -s "https://pricewatcha.com/api/v1/alerts/76" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

更新与删除

curl -s -X PATCH "https://pricewatcha.com/api/v1/alerts/76" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"notify_on_drop": true, "min_threshold_price": null}'

curl -s -X PATCH "https://pricewatcha.com/api/v1/alerts/76" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

curl -s -X DELETE "https://pricewatcha.com/api/v1/alerts/76" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

---

关注列表 API

选择对你关注的产品进行持续价格更新。已关注的产品使用与控制面板关注列表相同的调度器流程（user_products）。

匿名 POST /track 仍仅用于一次性目录数据录入。如果没有关注该产品（或未创建提醒 / 产品范围的价格 Webhook），价格不会按计划刷新。

端点

方法	路径	说明
GET	/api/v1/watchlist	列出你关注的产品（limit、offset）
GET	/api/v1/products/{productId}/watch	查看单个产品的关注状态
POST	/api/v1/products/{productId}/watch	开始关注（幂等）
DELETE	/api/v1/products/{productId}/watch	停止关注

所有端点都需要在 Authorization: Bearer … 中提供 API 密钥。上限：每个账户可关注 200 个产品（403 watch_limit_reached）。

关注产品

curl -s -X POST "https://pricewatcha.com/api/v1/products/prod_a1b2c3d4e5/watch" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

响应示例（200）：

{
  "product_id": "prod_a1b2c3d4e5",
  "watching": true,
  "watched_at": "2026-09-07T18:00:00Z"
}

一次调用即可追踪并关注

经过身份验证的 POST /track 接受以下参数：

• watch: true — 作业关联到产品时，将该产品添加到你的关注列表
• refresh: true — 即使 URL 已在目录中，也强制重新抓取

curl -s -X POST "https://pricewatcha.com/api/v1/track" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.backmarket.de/de-de/p/example",
    "watch": true,
    "refresh": true
  }'

自动监控

以下操作也会为你的账户监控商品：

• 创建价格提醒（POST /alerts）
• 创建/更新包含价格事件（price_dropped、price_changed 等）的商品范围 Webhook

取消监控

如果该商品仍有有效提醒，DELETE /products/{productId}/watch 会失败并返回 409 alert_requires_watch。请先删除或停用该提醒。

---

Webhook

当价格发生变化、达到提醒阈值或经过身份验证的跟踪任务完成时，Webhook 会推送经过签名的 HTTP POST 请求。

可全局订阅事件类型，也可针对单个 product_id 订阅。每种事件类型都会作为独立请求发送。

范围	行为
全局（省略 product_id）	仅限你正在跟踪（关注列表）或设有有效价格提醒的商品的价格事件。不会包含完整商品目录。
指定范围（设置 product_id）	仅限该商品的价格事件。创建/更新包含价格事件的商品范围订阅，也会为计划任务更新监控该商品。
测试（POST /webhooks/{id}/test）	发送 webhook_test 负载以验证你的端点；不指定商品范围。

不支持全商品目录范围的价格流。请使用测试端点验证投递，然后跟踪商品或创建提醒，以接收你关注的事件。

通过 POST https://pricewatcha.com/api/v1/webhooks 管理订阅。完整的架构定义：GET https://pricewatcha.com/api/v1/openapi.json（标签 webhooks、alerts）。

注意： 目标 URL 必须使用 HTTPS，且不得解析到专用或内部 IP 地址。

事件类型

事件类型	触发条件
price_changed	价格变动超过 €0.01
price_dropped	价格下降超过 €0.01
price_increased	价格上涨超过 €0.01
new_historical_low	新价格严格低于此前的任何一次观测价格
price_alert_triggered	用户提醒触发（最低/最高阈值或定向降价/涨价）
track_job_completed	经过身份验证的 POST /track 成功完成
track_job_failed	经过身份验证的 POST /track 失败
webhook_test	仅来自 POST /api/v1/webhooks/{webhook_id}/test

负载格式

price_dropped

{
  "event_id": "evt_a1b2c3d4e5",
  "event_type": "price_dropped",
  "occurred_at": "2026-05-24T14:00:00Z",
  "product": {
    "product_id": "prod_a1b2c3d4e5",
    "name": "Apple iPhone 15 Pro 128GB (Refurbished)",
    "shop": "Back Market",
    "product_url": "https://www.backmarket.de/...",
    "currency": "EUR"
  },
  "price": {
    "old_price": 599.00,
    "new_price": 536.00,
    "historical_low": 536.00,
    "historical_high": 729.00,
    "average_price": 612.50
  },
  "metadata": {
    "source": "pricewatcha",
    "api_version": "v1"
  }
}

price_alert_triggered

包含相同的 product 和 price 区块，以及一个 alert 对象：

{
  "event_id": "evt_b2c3d4e5f6",
  "event_type": "price_alert_triggered",
  "occurred_at": "2026-05-24T14:00:00Z",
  "alert": {
    "alert_id": "76",
    "min_threshold_price": 549.00,
    "max_threshold_price": 599.00,
    "threshold_reached": "min",
    "name": "Under €550"
  },
  "metadata": {
    "source": "pricewatcha",
    "api_version": "v1"
  }
}

签名与验证

每次投递都会包含：

• X-Pricewatcha-Event-Id
• X-Pricewatcha-Event-Type
• X-Pricewatcha-Timestamp（Unix 秒）
• X-Pricewatcha-Signature（sha256=<hex>）

签名字符串："{timestamp}.{raw_body}"，使用 HMAC-SHA256 和你的 Webhook 密钥（whsec_…，仅在创建订阅时显示一次）。

**警告：****Webhook 密钥仅显示一次。**请妥善保管：之后只会显示 secret_prefix。

Python

import hmac
import hashlib

def verify_pricewatcha_webhook(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{raw_body.decode('utf-8')}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature or "")

JavaScript（Node.js）

import crypto from "node:crypto";

function verifyPricewatchaWebhook(secret, timestamp, rawBody, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const expectedHeader = `sha256=${expected}`;
  return crypto.timingSafeEqual(
    Buffer.from(expectedHeader),
    Buffer.from(signature || "")
  );
}

投递与重试

投递失败最多重试 5 次：1 分钟 → 5 分钟 → 30 分钟 → 2 小时 → 12 小时。

连续失败 10 次后，订阅会自动停用。

投递日志

curl -s "https://pricewatcha.com/api/v1/webhooks/{webhook_id}/deliveries" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

示例

创建订阅

curl -s -X POST "https://pricewatcha.com/api/v1/webhooks" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://n8n.example.com/webhook/abc123",
    "event_types": ["price_dropped", "new_historical_low"],
    "product_id": "prod_a1b2c3d4e5"
  }'

发送测试 Webhook

curl -s -X POST "https://pricewatcha.com/api/v1/webhooks/42/test" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY_HERE"

---

AI Agents 与 MCP

Pricewatcha 提供远程 MCP 端点：无需本地安装。使用下方 URL 连接 AI 客户端。可用工具包括目录读取（get_api_status、search_products、track_product、get_job_status、get_product、get_price_history）、持续监测（watch_product、unwatch_product、list_watchlist、get_watch_status）和价格提醒（create_price_alert、list_price_alerts、get_price_alert、update_price_alert、delete_price_alert）。提醒和监测列表工具需要 Pricewatcha API 密钥。提醒可以在价格下跌或上涨时通知，无需设置数值阈值；创建提醒也会监测该商品，以便通过调度器持续更新。

https://mcp.pricewatcha.com

分步设置说明请参见下方的 Claude、ChatGPT、n8n 和 Make。

---

Claude

功能： 直接在 Claude.ai 或 Claude 桌面应用中，用自然语言让 Claude 搜索商品、跟踪价格、查看价格历史、持续监测商品、设置提醒和管理 Webhook。

连接方式：Claude.ai（网页）

第 1 步：打开自定义面板
点击 Claude.ai 左侧边栏中的 Customize（滑块图标），或前往 claude.ai/settings/connectors。

第 2 步：添加自定义连接器
在 Connectors 下，点击 + 添加新的连接器。

第 3 步：输入 MCP 服务 URL
输入名称（例如“Pricewatcha”）并粘贴：

https://mcp.pricewatcha.com

点击 Add。

第 4 步：完成
Pricewatcha 将显示在连接器列表中，其中包含只读工具（get_api_status、get_job_status、get_product、get_price_history、search_products、list_price_alerts、get_price_alert、list_watchlist、get_watch_status）和写入工具（track_product、create_price_alert、update_price_alert、delete_price_alert、watch_product、unwatch_product）。现在，你可以在任何 Claude 对话中使用 Pricewatcha。

第 5 步：配置工具权限（可选）
在连接器列表中打开该连接器（或返回 claude.ai/settings/connectors），然后展开 Tool permissions。

对于每个工具，或整个 Read-only / Write 组，选择 Claude 可以在何时调用它：

设置	含义
Always allow	Claude 无需每次询问即可调用该工具
Require approval	Claude 每次调用前都会询问（新连接器的默认设置）
Never allow	禁止使用该工具

对于日常价格查询和搜索，将只读工具（或整个只读组）设为 Always allow。对于 track_product、提醒和监测列表工具，如果希望写入操作无需确认，请选择 Always allow；如果希望先确认，则保留 Require approval。提醒和监测列表工具需要 Pricewatcha API 密钥（pwk_live_...）。

连接方式：Claude 桌面应用

步骤相同：Customize → Connectors → Add custom connector → 粘贴 https://mcp.pricewatcha.com。工具权限的配置方式相同，可在连接器设置中的 Tool permissions 下进行配置。

试试：

• “帮我找一部 €550 以下的翻新 iPhone 15 Pro”
• “跟踪此商品 URL，并显示价格历史”
• “监测此商品以便持续更新价格，然后列出我的监测列表”
• “当此商品价格降至 €500 以下时提醒我”
• “无论何时此商品降价都通知我——无需设置价格目标”

注意： track_product 是写入工具，因为它会在后台创建跟踪任务。它不会修改或删除现有数据。提醒工具（create_price_alert、update_price_alert、delete_price_alert）和监测列表工具（watch_product、unwatch_product、list_watchlist、get_watch_status）需要 API 密钥。创建提醒也会持续监测该商品，以便通过调度器更新。

ChatGPT

功能： 直接在 ChatGPT 中通过 MCP 搜索商品、跟踪价格、查看价格历史、持续监控商品更新、设置价格提醒并管理 Webhook。

Pricewatcha 已获批准，并作为 ChatGPT 插件在官方插件商店中提供。

步骤 1： 在 ChatGPT 侧边栏中打开 Plugins，然后搜索 Pricewatcha。

步骤 2： 打开插件页面，然后点击 Install plugin。

步骤 3： 在授权页面确认 Connect Pricewatcha。ChatGPT 可能会短暂打开 Pricewatcha 登录页面，以完成 OAuth。

步骤 4：完成。 示例提示词：

• “搜索售价低于 €550 的翻新 iPhone 15 Pro”
• “跟踪此商品 URL 并显示价格历史”
• “监控此商品以持续更新价格，然后列出我的监控清单”
• “此商品降价时通知我——无需设定目标价格”

提醒和监控清单工具（create_price_alert、watch_product、list_watchlist 等）需要 Pricewatcha API 密钥（pwk_live_...）。创建提醒后，也会监控该商品，以便调度程序持续更新。

其他 MCP 客户端的可选配置： 远程 MCP URL 为 https://mcp.pricewatcha.com。连接器徽标（PNG，最大 10 KB）：从 https://pricewatcha.com/static/img/mcp/chatgpt-logo.png 下载。

---

n8n

功能： 构建自动化价格监控工作流。价格变动或达到提醒阈值时触发操作：无需编写代码。

典型用例： 跟踪的商品价格低于设定阈值时 → 发送 Telegram、Slack 或电子邮件通知，包含商品名称、商店、当前价格和提醒名称。

注意： 只有在本地运行 n8n（在自己的计算机上自托管）时，才需要可公开访问的 URL。如果使用 n8n Cloud 或托管在服务器上的实例，n8n Webhook URL 已可公开访问：跳过隧道步骤。

路径 A：n8n Cloud 或托管在服务器上（无需隧道）

1. 在 n8n 中创建一个 Webhook 节点 → 复制 Production URL。
2. 创建 Pricewatcha 提醒，将 webhook_url 设置为 n8n URL（见下文）。
3. 完成：达到阈值时会收到 price_alert_triggered 事件。

路径 B：在本地自托管 n8n（需要隧道）

1. 启动 Cloudflare Tunnel：cloudflared tunnel --url http://localhost:5678（在 macOS 上使用 brew install cloudflared 安装）。
2. 复制隧道 URL（例如 https://abc123.trycloudflare.com）。
3. 在 n8n 中创建一个 Webhook 节点 → 记下路径（例如 /webhook-test/abc123）。
4. 拼接 URL：https://abc123.trycloudflare.com/webhook-test/abc123。
5. 在 Pricewatcha 提醒中将其用作 webhook_url。

创建价格提醒并通过 Webhook 发送通知

需要 API 密钥：

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "min_threshold_price": 600.00,
    "webhook_url": "https://YOUR_N8N_URL/webhook/YOUR_PATH",
    "notify_email": false,
    "name": "Price drop alert"
  }'

当当前价格等于或低于 min_threshold_price 时，Pricewatcha 会发送 price_alert_triggered 事件，载荷格式如下：

{
  "event_id": "evt_...",
  "event_type": "price_alert_triggered",
  "occurred_at": "2026-05-26T20:32:07Z",
  "product": {
    "product_id": "prod_...",
    "name": "iPhone 15 Pro",
    "shop": "Swappie",
    "current_price": 559.00,
    "currency": "EUR"
  },
  "price": {
    "old_price": 559.00,
    "new_price": 559.00,
    "historical_low": 7.99,
    "historical_high": 649.00,
    "average_price": 570.44
  },
  "alert": {
    "alert_id": "77",
    "min_threshold_price": 600.00,
    "threshold_reached": "min",
    "name": "Price drop alert"
  },
  "metadata": {
    "source": "pricewatcha",
    "api_version": "v1"
  }
}

推荐的 n8n 工作流

1. Webhook 节点（触发器）：接收 price_alert_triggered 事件。
2. IF 节点：筛选条件：{{ $json.body.event_type }} 等于 price_alert_triggered。
3. 通知节点：电子邮件 / Telegram / Slack，包含：
   • 商品：{{ $json.body.product.name }}
   • 商店：{{ $json.body.product.shop }}
   • 当前价格：{{ $json.body.price.new_price }} {{ $json.body.product.currency }}
   • 提醒名称：{{ $json.body.alert.name }}

测试连接

curl -s -X POST "https://pricewatcha.com/api/v1/webhooks/YOUR_WEBHOOK_ID/test" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY"

注意： 测试端点需要 Webhook 订阅（POST https://pricewatcha.com/api/v1/webhooks），而不是提醒。

签名验证： 在生产环境中验证 X-Pricewatcha-Signature（HMAC-SHA256）：参见 Webhook 签名。

替代方案： 使用 HTTP Request 节点：GET https://pricewatcha.com/api/v1/search?q=… 或 GET https://pricewatcha.com/api/v1/products/PRODUCT_ID/price-history。

---

Make

**它能实现什么：**与 n8n 相同的基于 webhook 的自动化：无需编写代码即可创建可视化工作流。

n8n	Make 对应项
Webhook Trigger	Webhooks → Custom webhook
IF node	Router 或 Filter
HTTP Request	HTTP → Make a request
Notification nodes	Email / Telegram / Slack

1. 创建一个以 Custom webhook 为触发器的场景；复制 URL。
2. 创建 Pricewatcha webhook 订阅（使用与 n8n 指南相同的 curl，并将你的 Make URL 用作 target_url）。
3. 添加一个基于 event_type 的 Router。
4. 使用 POST https://pricewatcha.com/api/v1/webhooks/{id}/test 进行测试。

**Make 免费套餐：**每月最多 1,000 次操作，包括 webhook，足以满足个人价格监控需求。

---

智能家居

使用价格提醒 webhook驱动自动化：当已跟踪商品达到目标价格时，触发场景、通知或灯光。

请参阅下文的 Home Assistant 和 Loxone。

---

Home Assistant

**它能实现什么：**在 Pricewatcha 触发价格提醒时运行自动化。

**典型用例：**价格低于阈值 → 发送移动通知、切换 input_boolean.good_deal 或运行脚本。

路径 A：Webhook 触发器（推荐）

1. 添加 Webhook 触发器（例如，webhook ID 为 pricewatcha_price_drop → https://YOUR_HA_HOST/api/webhook/pricewatcha_price_drop）。
2. 确保该 URL 可从互联网访问（通过 Nabu Casa、反向代理或隧道）。
3. 创建一个带有该 webhook_url 的 Pricewatcha 提醒（n8n 指南中提供了 curl 示例）。
4. 在操作中使用 trigger.json.product.name、trigger.json.price.new_price 等。

自动化示例（YAML）：

automation:
  - alias: "Pricewatcha price drop"
    trigger:
      - platform: webhook
        webhook_id: pricewatcha_price_drop
        allowed_methods: [POST]
        local_only: false
    action:
      - service: notify.notify
        data:
          title: "Price alert: {{ trigger.json.product.name }}"
          message: >-
            {{ trigger.json.product.shop }} ·
            {{ trigger.json.price.new_price }}
            {{ trigger.json.product.currency }}

路径 B：REST 传感器（轮询）

rest:
  - resource: "https://pricewatcha.com/api/v1/products/prod_YOUR_PRODUCT_ID"
    scan_interval: 3600
    sensor:
      - name: "Tracked product price"
        value_template: "{{ value_json.current_price }}"
        unit_of_measurement: "EUR"

读取端点无需 API 密钥。轮询方式更简单，但实时性不如 webhook。

**签名验证：**在生产环境中验证 X-Pricewatcha-Signature：请参阅 Webhook 签名。

---

Loxone

**它能实现什么：**按计划从 Pricewatcha 轮询当前价格，并在达到价格阈值时触发 Loxone 程序。兼容 Miniserver Generation 1 和 Generation 2。

路径 A — 轮询当前价格（Virtueller HTTP Eingang）

Loxone 的 Virtueller HTTP Eingang（虚拟 HTTP 输入）会按可配置的时间间隔获取 URL，并通过 Command Recognition 提取数值。每个提取出的数值都会成为一个 Loxone 输入，可用于你的程序中。

Gen2 — 直接使用 HTTPS（无需中间件）

Miniserver Gen2 原生支持 HTTPS，可以直接调用 Pricewatcha API。

Gen1 — 通过 LoxBerry https2http Plugin

Miniserver Gen1 不支持 HTTPS。在 LoxBerry 上安装 https2http Plugin。它充当 HTTPS 代理：LoxBerry 获取 Pricewatcha 的 HTTPS 响应，再通过 HTTP 将其提供给 Loxone。

步骤 1 — 查找产品 ID

搜索你的产品并记下 product_id（格式为 prod_...，也可以使用演示产品，例如 demo_iphone_15_pro）：

GET https://pricewatcha.com/api/v1/search?q=YOUR+PRODUCT

步骤 2 — 在 Loxone Config 中创建 Virtueller HTTP Eingang

在 Loxone Config 中，前往 Periphery → Virtual Inputs → Virtual HTTP Input。

根据 Miniserver 的代际设置 URL：

代际	要输入的 URL
Gen2（直连）	https://pricewatcha.com/api/v1/products/prod_YOUR_PRODUCT_ID
Gen1（通过 LoxBerry）	http://YOUR_LOXBERRY_IP/plugins/https2http/?url=https://pricewatcha.com/api/v1/products/prod_YOUR_PRODUCT_ID

设置轮询间隔（Abfragezyklus），例如 3600 秒（每小时一次）。

无需 API 密钥或身份验证 — 产品端点是公开的。

步骤 3 — 添加 Virtueller HTTP Eingang Befehle（Command Recognition）

为每个要提取的数值，向输入添加一个 Virtueller HTTP Eingang Befehl（虚拟 HTTP 输入命令）。Command Recognition 会在原始 JSON 响应中搜索匹配模式并提取数值。

Pricewatcha 产品 API 返回的 JSON 如下：

{
  "product_id":"prod_...",
  "name":"Apple iPhone 15 Pro 128GB (Refurbished)",
  "shop":"Back Market",
  "current_price":563.0,
  "currency":"EUR",
  "status":"active"
}

每个需要的数值添加一个 Befehl：

数值	Command Recognition 模式
当前价格（数值）	"current_price":\v
产品名称（文本）	"name":"\a
商店名称（文本）	"shop":"\a
货币（文本）	"currency":"\a

模式语法参考：

• \v — 提取此位置的数值
• \a — 提取文本（读取至下一个 "）
• \i...\i — 跳过／忽略标记之间的文本（用于在 JSON 中定位到正确位置）

注意： 提示： Loxone Config 内置了模式测试器。输入 Command Recognition 模式时，点击输入框右侧的 > 按钮。此时会打开 Edit Command Recognition 对话框 — 输入 Pricewatcha 产品 URL，点击 "Daten abfragen"，Loxone Config 会获取实时响应，并以绿色高亮显示匹配的数值。这样，你就可以在保存前验证每个模式。

步骤 4 — 连接到你的程序

每个 Befehl 的输出都是一个数值或文本，可直接用于 Loxone 程序：

• 将 current_price 连接到 Threshold Switch（带阈值的开关）→ 价格低于目标值时触发
• 将阈值开关的输出连接到 Push Notification、灯光场景或任何其他 Loxone 操作

注意： 无需 API 密钥 — 产品详情端点是公开的。只有在使用提醒和 Webhook（路径 B）时才需要 API 密钥。

路径 B —— 通过 LoxBerry 实现实时价格提醒

Loxone 无法直接接收 Pricewatcha Webhook，因为 Pricewatcha 要求使用可从公网访问的 HTTPS 端点，而 Miniserver 通常位于 NAT 后且没有公网 IP。Gen1 和 Gen2 均如此。

LoxBerry 充当中间件：接收 Pricewatcha Webhook，并通过 MQTT 将数据转发到 Miniserver。

接收器 URL 取决于你的 LoxBerry 版本：

LoxBerry 版本	接收器 URL
3.0+（内置 MQTT，无需插件）	http://YOUR_LOXBERRY_IP/system/tools/mqtt/receive.php
2.x（需先安装 MQTT Gateway Plugin）	http://YOUR_LOXBERRY_IP/plugins/mqttgateway/receive.php

步骤 1 —— 创建 Pricewatcha API 密钥

在个人资料中创建一个 API 密钥（需要登录）。提醒和 Webhook 需要身份验证。

步骤 2 —— 创建指向 LoxBerry 的 Pricewatcha 价格提醒

curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_YOUR_PRODUCT_ID",
    "min_threshold_price": 500.00,
    "webhook_url": "http://YOUR_LOXBERRY_IP/system/tools/mqtt/receive.php",
    "notify_email": false,
    "name": "Price drop alert"
  }'

步骤 3 —— 配置 LoxBerry MQTT 订阅

在 LoxBerry MQTT 配置中，订阅主题 rcvr/#。传入的 JSON 载荷会自动解析。将相关字段（例如 event_type、price/new_price）映射到 Loxone 虚拟输入，通过 MQTT 订阅接收。

步骤 4 —— 在 Loxone Config 中

将虚拟输入（由 MQTT 订阅触发）连接到通知或自动化程序。

警告： 需要可从公网访问： Pricewatcha 必须能够通过互联网访问你的 LoxBerry Webhook URL。请使用 Loxone Remote Connect，或在路由器上配置端口转发。若要在不暴露到互联网的情况下进行本地测试，可使用 Pricewatcha 测试端点触发手动投递：POST https://pricewatcha.com/api/v1/webhooks/{id}/test

注意： 替代中间件： ioBroker 及其 Loxone 适配器也可用作接收 Pricewatcha Webhook 的中间件。有关设置详情，请参阅 ioBroker 文档。

---

SDK

官方 Python 和 TypeScript 客户端库位于 GitHub 上的 sdks/。

它们支持异步的 跟踪 → 轮询 → 读取 工作流。其他语言可使用 OpenAPI 架构或普通 HTTP。

Python

from pricewatcha import Pricewatcha

client = Pricewatcha()  # public endpoints, no key needed

## With an API key (alerts, webhooks, …)
client = Pricewatcha(api_key="pwk_live_YOUR_KEY")

从 GitHub 上的 Python SDK 安装。设置说明：sdks/python/README.md。

TypeScript

import { PricewatchaClient } from "@pricewatcha/sdk";

const client = new PricewatchaClient();  // public endpoints, no key needed

const authedClient = new PricewatchaClient({ apiKey: "pwk_live_YOUR_KEY" });

从 GitHub 上的 TypeScript SDK 安装。设置说明：sdks/typescript/README.md。

客户端生成

可使用 OpenAPI 规范 或实时接口 GET https://pricewatcha.com/api/v1/openapi.json，通过 OpenAPI Generator、Speakeasy、Kiota 等工具生成其他语言的客户端。

---

更新日志

本仓库中公开 API 契约、SDK 和 MCP 服务的所有重要变更。

软件包／发行版本采用 0.1.x。HTTP API 路径仍为 /api/v1。

0.1.7 - 2026-09-07

新增

• 监控列表 API： GET /api/v1/watchlist、GET|POST|DELETE /api/v1/products/{productId}/watch（需要 API 密钥）。监控的产品会纳入价格调度器（与仪表盘使用相同的 user_products 路径）。
• POST /track 选项（需要身份验证）： watch: true 会将产品加入持续更新；refresh: true 会强制重新抓取，即使该 URL 已在目录中也是如此。
• 自动监控： 创建价格提醒，或创建包含价格事件的产品级 webhook，会为该账户监控相应产品。
• MCP / SDK： watch_product、unwatch_product、list_watchlist、get_watch_status；track 接受 watch / refresh。
• Claude / ChatGPT 指南： 连接器设置页面现已记录监控列表工具和示例提示词。
• SDK / MCP 软件包： 升级至 0.1.7。

0.1.6 - 2026-08-26

变更

• 搜索速率限制： GET /api/v1/search 现在有独立的分层配额，与常规目录读取分开：匿名用户约为每 60 秒 20 次、每小时 60 次、每天 200 次；已验证身份的用户（API 密钥）约为每 60 秒 40 次、每小时 180 次、每天 1000 次，按账户分别计算。在短时间间隔内重复轮询相同查询会返回 HTTP 429，并附带 X-RateLimit-Policy 值 search、search_hourly 或 search_daily。
• 产品读取速率限制： GET /products/{id} 和 /price-history 保留每分钟突发配额，并新增每小时／每天上限：匿名用户约为每 60 秒 120 次、每小时 180 次、每天 600 次；已验证身份的用户约为每 60 秒 240 次、每小时 540 次、每天 3000 次。
• 滥用通知： 耗尽匿名用户的每日搜索或产品读取配额（search_daily / read_daily）会计入与 track_daily 相同的 IP 违规次数阈值。经过若干个不同的 UTC 日期后，客户端会收到联系 [email protected] 的提示（X-Pricewatcha-Restriction: notice）；如果未收到回复，该 IP 将被封禁。默认限制范围为 /api/v1 下的所有端点，健康检查／发现端点除外。

0.1.5 - 2026-08-24

变更

• 搜索匹配： GET /api/v1/search?q= 采用不区分大小写的词元 AND匹配（所有词都必须出现，顺序不限），不再要求完整查询作为一个连续子串出现。连字符、斜线及类似标点会规范化为空格（Darth-Vader ≡ Darth Vader，1/6 ≡ 1 6）。连续短语匹配的排名仍然更高。以减号开头的排除词保持不变。

0.1.4 - 2026-08-23

新增

• 方向性价格提醒： POST／PATCH／GET /api/v1/alerts 支持 notify_on_drop 和 notify_on_rise。设置任一标记即可，不再要求数值阈值。
• MCP 提醒工具： create_price_alert、list_price_alerts、get_price_alert、update_price_alert、delete_price_alert（需要 API 密钥）。方向性标记与 HTTP API 相同。
• Google 产品类别： GET /api/v1/products/{id}、GET /api/v1/search（以及 MCP get_product / search_products / 已完成的 track 任务）支持 google_product_category_id 和 google_product_category_name。响应中始终包含这两个字段（未设置时为 null）；搜索无需额外查询参数。
• 搜索排除词： GET /api/v1/search?q= 接受以减号开头的词元（例如 iPhone 15 -cover -hülle），以排除名称、商店或 URL 包含这些词的产品。不区分大小写。排除后再应用 limit。
• 滥用／IP 限制： 多次触发匿名用户每日限制可能会启动宽限／通知期（API 仍可使用，X-Pricewatcha-Restriction: notice），之后会封禁（403 access_restricted）。请联系 [email protected]。

0.1.3 - 2026-08-17

变更

• Track 并发名额： 抓取超时后仍处于 queued／processing 状态的任务会自动失败（启动时及 POST /track 时），因此部署或卡住的工作进程不会永远阻塞客户端。
• 相同 URL 重试： 对该客户端已有进行中任务的 URL 再次发送 POST /track 时，会返回已有的 job_id，而不是 HTTP 429。

0.1.2 - 2026-08-13

更改

• **跟踪速率限制：**匿名配额保持在每分钟约 2 个并发请求 / 10 次 / 每小时 40 次 / 每天 80 次。客户端身份优先使用 CF-Connecting-IP（然后是 True-Client-IP，再然后是 X-Forwarded-For），以避免将 Cloudflare 边缘 IP 视为不同的配额桶。
• 已认证的跟踪配额：在 POST /track 中使用 API 密钥或登录会话，可获得更高的每账户限制（每分钟约 4 个并发请求 / 20 次 / 每小时 120 次 / 每天 400 次）。即使没有回调，账户也会关联到跟踪任务。
• MCP 调用方可以根据稳定的转发客户端 ID（而不是共享的出口 IP）进行速率限制。

0.1.1 - 2026-06-28

更改

• 从 API 文档、OpenAPI 规范和 SDK 中移除了 Public Preview 品牌标识。发现状态为可用。

0.1.0 - 2026-06-03

公开 API、官方 SDK 和远程 MCP 服务的初始版本。

新增

• GET /api/v1/health
• GET /api/v1：发现文档
• POST /api/v1/track：异步接收数据（200，有界长轮询约 25 秒）
• GET /api/v1/jobs/{jobId}
• GET /api/v1/products/{productId}
• GET /api/v1/products/{productId}/price-history
• GET /api/v1/search?q=
• GET /api/v1/openapi.json
• 演示目录：demo_iphone_15_pro、demo_galaxy_s24
• v1 端点的速率限制响应标头
• API 密钥：POST /api/keys、GET /api/keys、DELETE /api/keys/{id}（pwk_live_...）
• 提醒：POST/GET/PATCH/DELETE /api/v1/alerts（需要 API 密钥）
• Webhooks：/api/v1/webhooks 上提供完整的 CRUD 操作、测试投递和投递日志（需要 API 密钥）
• 官方 MCP 服务：远程 HTTP 服务，地址为 https://mcp.pricewatcha.com（MCP 连接无需 API 密钥）
• 文档：默认凭据为 API 密钥；登录会话令牌仅用于无头密钥初始化

说明

• 读取端点无需身份验证即可使用；提醒和 Webhooks 需要 API 密钥
• 端点和字段可能随时更改，恕不另行通知

---

仓库布局

openapi/              OpenAPI 3.1 specification
docs/                 API guides (source for README and Developer page)
examples/             curl and SDK samples
sdks/python/          Official Python package
sdks/typescript/      Official TypeScript package
mcp/                  MCP tool schema (reference)
mcp-server/           MCP server (TypeScript)
public-demo/          Demo product IDs

示例： examples/

MCP： mcp/README.md · mcp-server/

---

免责声明

• API 稳定性：端点、字段和速率限制可能会更改。
• 价格为快照：请务必在商家网站上核实。
• 不构成财务建议：趋势仅根据历史数据得出。

许可证

Apache License 2.0：参见 LICENSE。

安全

请负责任地报告漏洞：SECURITY.md。

---

支持

有关 API 的问题、集成问题或异常行为，请联系：[email protected]。

如果你的 IP 收到 HTTP 403 响应并带有 access_restricted，或收到通知标头（X-Pricewatcha-Restriction: notice），请联系 [email protected]。请参阅滥用行为与 IP 限制。

如要报告此仓库中的错误或文档问题，请提交 GitHub issue。