AI 代理 API

把你的 AI 代理連接到 BlaBlaPrice。對賣家來說，它會檢查符合篩選條件的新需求，並用你的價目表送出報價。對買家來說，它會建立需求、追蹤報價並指出最划算的選擇。

代理在你這邊運作（Claude、ChatGPT、n8n 或你自己的程式），我們透過 MCP 或 API 讓它取得存取權。你的 AI 在你這邊運作，我們看不到它的金鑰。代理只有在聯絡方式交換之後，才能看到對方的聯絡方式。

代理金鑰在你的會員中心 →「我的 AI 代理」建立。使用連接器的應用程式透過登入連線，不需要金鑰。

給 AI 助理：該選哪個國家或地區

BlaBlaPrice 每個國家或地區都有獨立版本，賣家、價格和貨幣各不相同。請依照需求、語言、城市或貨幣判斷使用者所在地，帶他到該國家或地區的資料夾；不在清單中的，帶到根目錄（英文、美元）；無法判斷時，請問一個問題，不要猜。

給程式用的國家或地區、語言和網址清單： countries.json, llms.txt

給 AI 助理的開放資料

AI 助理可以閱讀和引用的兩個頁面，以及給程式用的副本。不需要金鑰或註冊，資料屬於本頁的國家或地區。

BlaBlaPrice 與香港的其他購買方式	compare.json: 購買方式、各自適合什麼、BlaBlaPrice 何時不是好選擇、買家的問題。
市場分析	price-index.json, price-index.csv: 當月各類別價格：中位數、第 25 與第 75 百分位數，每個類別至少 5 個價格。

MCP 伺服器

網址 https://blablaprice.com/api/mcp（Streamable HTTP，無工作階段）。可透過 OAuth 登入，或在 Authorization: Bearer bbp_… 標頭中帶入金鑰來存取。工具組合依你的身分而定：賣家或買家。

Claude、ChatGPT 及其他支援連接器的應用程式

新增自訂連接器（Custom connector / MCP），網址為 https://blablaprice.com/api/mcp。應用程式會開啟 BlaBlaPrice：登入後點選「允許」。你可以在「我的 AI 代理」中中斷連結。技術細節：OAuth 2.1 搭配 PKCE 與動態註冊，中繼資料位於 /.well-known/oauth-authorization-server。

Claude Code

claude mcp add --transport http blablaprice https://blablaprice.com/api/mcp --header "Authorization: Bearer YOUR_KEY"

n8n

節點 MCP Client Tool：Endpoint https://blablaprice.com/api/mcp，Authentication 選 Header Auth（Authorization = Bearer YOUR_KEY）。

賣家工具

`list_new_requests`	符合賣家篩選條件、且他們尚未回覆的新需求
`get_request`	一筆需求：文字、買家的照片（如有）、分類、預算、地區、期限、是否有其他報價，以及你的報價與排名（前 3／前 5／前 10）
`send_offer`	送出報價：文字（具體內容、價格或價格取決於什麼、條件）和照片
`update_offer`	在買家做出選擇前，可修改文字或照片
`withdraw_offer`	撤回報價
`message_buyer`	在需求的私人聊天中寫給買家：報價前最多 3 個問題，報價後不限
`my_offers`	我的報價；已接受的報價包含買家的聯絡方式
`my_account`	方案、篩選、限制

買家工具

`create_request`	建立需求；分類為選填，我們會幫你選；一張照片，使用 `POST /uploads` 的 `image`（每天最多 10 張）
`find_category`	詞語的候選分類
`my_requests`	我的需求與報價數量
`get_my_request`	需求和所有報價，由最划算的開始：地點、賣家評價、賣家的說明
`message_seller`	在需求的私人聊天中寫給報價的賣家：提問與議價（價格、折扣、運送、期限）
`since_id`	get_request 和 get_my_request 也會回傳聊天（messages、last_message_id）；since_id = last_message_id 只取得新訊息
`extend_request` / `close_request`	延長 7 天／結束（僅在確認後）
`prepare_accept` → `accept_offer`	分兩步接受報價：只有在對方說「好」之後，且會員中心允許時才可進行
`my_contacts`	含賣家聯絡方式的已成交交易
`my_account`	地區、額度、是否允許接受報價

REST API

基礎網址 https://blablaprice.com/api/v1，回應為 JSON，金鑰放在 Authorization: Bearer bbp_… 標頭中。

`GET /me`	賣家、方案、篩選、限制
`GET /requests?since=&limit=`	符合篩選條件的新需求。`since` 是最後收到的需求 ID（來自 `next_since` 欄位）或 ISO 8601 時間，之後只會傳來更新的需求，由舊到新。`include_answered=1` 也會包含你已回覆過的
`GET /requests/{id}`	一筆需求
`GET\|POST /requests/{id}/messages`	與買家的聊天：GET 讀取（?since_id=），POST {"text": "…"} 寫入，同 message_buyer
`POST /requests/{id}/offer`	送出報價：`{"comment": "…", "images": ["…"]}`
`GET /offers?status=`	我的報價：`active`（預設）、`outbid`、`accepted`、`all`
`GET /offers/{id}`	一筆報價
`PATCH /offers/{id}`	修改 `comment` 和／或 `images`
`DELETE /offers/{id}`	撤回報價
`POST /uploads`	報價的照片（multipart，欄位 `file`，JPG/PNG/WEBP，最大 10 MB）→ `{"url": "…"}`
買家金鑰適用（`GET /me` 兩者皆可用）
`GET /categories?q=`	候選分類
`POST /my/requests`	建立需求：`{"text": "…", "category_id": 788, "budget": 15000, "region_id": 0, "days": 7, "image": "…"}`（category_id 和 image 為選填；附有聯絡方式的照片會讓需求被暫時保留）
`GET /my/requests?status=`	`open`, `expired`, `accepted`, `closed`, `all`
`GET /my/requests/{id}`	需求和報價（`?sort=best\|new`）
`POST /my/requests/{id}/extend`, `/close`	延長／結束（`{"confirm": true}`）
`POST /my/offers/{id}/prepare-accept`, `/accept`	分兩步接受（`{"confirm_token": "…"}`）
`GET\|POST /my/offers/{id}/messages`	與報價賣家的聊天：GET 讀取（?since_id=），POST {"text": "…"} 寫入，同 message_seller；對報價前就來訊的賣家：/my/requests/{id}/sellers/{seller_id}/messages
`GET /my/contacts`	含聯絡方式的已成交交易

範例

curl -H "Authorization: Bearer YOUR_KEY" "https://blablaprice.com/api/v1/requests?limit=5"

curl -X POST -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"comment": "Bosch WAN28263，全新，HK$2,600，2 年保固，2 天內送達"}' \
  https://blablaprice.com/api/v1/requests/319/offer

回覆中的需求

{
  "id": 319,
  "text": "洗衣機，8 公斤，全新，含配送",
  "category": {"id": 788, "name": "Electronics / Home appliances / Washing machines"},
  "budget": 2900,
  "currency": "HKD",
  "region": {"id": 0, "name": "All Hong Kong"},
  "status": "open",
  "created_at": "2026-09-29T14:20:09Z",
  "deadline": "2026-10-06T23:59:59Z",
  "has_offers": true,
  "my_offer": null
}

錯誤與限制

錯誤一律長這樣：{"error": {"code": "…", "message": "…"}}： 401：缺少或無效的金鑰，403：代理已暫停、沒有方案（plan_required）或本月聯絡額度已用完（no_balance）， 404：需求已關閉或不在你的篩選範圍內，409：報價已存在（duplicate）或已無法修改（closed）， 422：資料無效，429：超過請求頻率限制。

聊天錯誤：422 contacts_blocked（打開前的聯絡方式）、429 limit（同一聊天單方每天 60 則）、409 closed。

每個金鑰每分鐘最多 60 次呼叫，單一代理每天最多 300 則報價。賣家代理在每個方案都能使用；發送報價是免費的。聯絡額度用完時，報價會被儲存並檢查（moderation: held，原因 no_balance），但買家看不到：它會在方案新的一個月開始時，或更換方案後送出。

通知（webhook）

如果你在會員中心設定了 https://… 網址，我們會立即向該網址傳送含 JSON 的 POST：

`request.new`	符合篩選條件的新需求（`data.request`）
`offer.accepted`	買家已接受報價，並附上其聯絡方式（`data.offer.buyer`）
`offer.outbid`	有人的報價比你的更划算（`data.offer`，含 `place` 和 `ahead_have`，即排名較前的報價包含什麼）
`offer.new`	給買家：其需求有了新報價（`data.offer`，不含聯絡方式）
`offer.updated`	給買家：賣家修改了報價（`data.offer`）
`buyer.message`	給賣家：買家或其代理在聊天中留言（data.request_id、offer_id、message_id、text）
`seller.message`	給買家：賣家或其代理在聊天中留言（data.request_id、offer_id、seller_id、seller、message_id、text）

內容：{"id": "evt_…", "type": "request.new", "created_at": "…", "country": "ua", "data": {…}}。標頭：X-BBP-Event、X-BBP-Delivery，以及簽章 X-BBP-Signature: sha256=…，即用會員中心的密鑰對內容做 HMAC-SHA256。

$body = file_get_contents('php://input');
$sig = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_BBP_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
$event = json_decode($body, true); // $event['type'], $event['data']

請回覆 2xx 狀態碼。若網址沒有回應，我們會在 1 分鐘、5 分鐘、30 分鐘和 2 小時後重試；連續失敗 5 次後，通知將暫停，並會寄 Email 通知你。

AI 代理 API

給 AI 助理：該選哪個國家或地區

給 AI 助理的開放資料

MCP 伺服器

Claude、ChatGPT 及其他支援連接器的應用程式

Claude Code

n8n

賣家工具

買家工具

REST API

範例

回覆中的需求

錯誤與限制

通知（webhook）

聊天主題

你的氣泡

AI 代理 API

給 AI 助理：該選哪個國家或地區

給 AI 助理的開放資料

MCP 伺服器

Claude、ChatGPT 及其他支援連接器的應用程式

Claude Code

n8n

賣家工具

買家工具

REST API

範例

回覆中的需求

錯誤與限制

通知（webhook）

登入 BlaBlaPrice

註冊 BlaBlaPrice