尋找產品
使用此技能將「藍色小工具」或掃描的條碼轉換為具體的 SKU.io 產品 —
其 id、sku、名稱和詳細資訊 — 以便下游技能擁有明確的參考。
選擇正確的查找方式
| 您擁有… | 呼叫 | 原因 |
|---|---|---|
| 精確的 SKU | GET /api/products/by-sku?sku=WIDGET-BLUE-01 | 直接,單一結果 |
| 掃描的條碼 (UPC/EAN/GTIN) | GET /api/products/barcode-lookup?code=0123456789012 | 將條碼解析為其產品(參數為 code) |
| 部分名稱或 SKU | GET /api/products/search?query=blue widget | 模糊搜尋,可能返回多個匹配 |
| 數位產品 ID | GET /api/products/{id} | 當您已有 ID 時取得完整記錄 |
始終優先選擇您能進行的最具體查找。僅在您沒有精確 SKU 或條碼時使用 search — 它可能返回多個候選項,您需要進行區分。
步驟
-
根據您擁有的資訊選擇上述查找方式。
-
使用您的 Bearer token(範圍
products:read)發送請求:curl -sS "https://$SKU_TENANT.sku.io/api/products/by-sku?sku=WIDGET-BLUE-01" \ -H "Authorization: Bearer $SKU_PAT" -H "Accept: application/json" -
處理結果:
- 完全匹配一個 → 擷取其
id和sku;完成。 - 搜尋返回多個 → 透過匹配精確的
sku來縮小範圍,或向使用者顯示前幾個候選項(名稱 + sku)並詢問選擇哪一個。請不要默默地選擇第一個。 - 無匹配 → 產品可能不存在或已歸檔。報告此情況,而不是憑空捏造一個 ID。在放棄之前,考慮使用更廣泛的
search查詢。
- 完全匹配一個 → 擷取其
備註
search支援分頁 — 請參閱shared/pagination.md。最佳匹配位於第一頁;在查找時您很少需要翻頁。- 產品
id是其他技能期望的穩定鍵(例如銷售訂單行中的product_id)。建議將id傳遞給下游,而不是每次重新透過 SKU 解析。
API 操作
| 方法 | 路徑 | 功能 |
|---|---|---|
GET | /api/products/search | 依名稱或 SKU 片段模糊搜尋產品。 |
GET | /api/products/by-sku | 依精確 SKU 擷取單一產品。 |
GET | /api/products/barcode-lookup | 將掃描的條碼 (UPC/EAN/GTIN) 解析為產品。 |
GET | /api/products/{id} | 依數位 ID 擷取完整產品記錄。 |
驗證
每個請求都使用 SKU.io 個人存取令牌,以 Bearer 令牌形式發送:
Authorization: Bearer <YOUR_SKU_PAT>
- 基礎 URL:
https://{tenant}.sku.io(將{tenant}替換為您的帳戶子域名) - 所需範圍:
products:read
在 SKU.io 網頁應用程式的 設定 → 開發者 → 個人存取令牌 下建立一個令牌。
完整流程請參閱 shared/authentication.md。
改進此技能
此技能是否不足 — 步驟不明確、端點錯誤或無法完成?請不要繞過它:記錄問題所在並開啟拉取請求,以便下一個代理能做得更好。
- 倉庫:https://github.com/skuio/sku-skills
- 編輯
skills/<domain>/<name>/下的規範技能(而非此生成的檔案),然後執行npm run build並開啟 PR。外部貢獻者:請 fork 倉庫並從 fork 發起 PR。 - 完整的代理工作流程請參閱
AGENTS.md。
您的代理可以端到端完成此操作。每次有人發送修正,此函式庫都會變得更好。