# 化合企業 HuahoNexus — AI Shopping Agent Integration Guide

> 化合企業有限公司（NICE HUA HO ENTERPRISE CO., LTD.）是台灣專業化學試劑供應商。
> 我們銷售工業化學品、實驗室試劑、容器與儀器，並提供完整的 SDS 安全資料與 GHS 合規文件。
> 本頁面為 AI 購物代理（ChatGPT、Gemini、Claude 等）提供完整的系統整合說明。

## 快速入門 — AI 代理購物流程

AI 代理可透過以下流程協助採購化學品：

1. **搜尋商品**：POST /api/v1/mcp（tools/call: search_products）
2. **查詢合規**：GET /api/v1/public/agent/products/{code}/compliance（CAS、GHS、SDS）
3. **確認庫存**：POST /api/v1/public/agent/batch/products
4. **詢價下單**：POST /api/v1/mcp（tools/call: create_quote_request）

持有客戶 Agent Token（hha_...）的 AI 平台可額外使用：

5. **代理詢價**：POST /api/v1/public/agent/me/quotes（需 quote:create scope）
6. **代理下單**：POST /api/v1/public/agent/me/orders（需 order:write scope）

## Base URL

  https://huaho.tw/api/v1        (production)
  https://api.huaho.tw/api/v1    (production API domain, 同一套 API)

## Authentication

### 公開端點（無需認證）
以下端點無需任何 API 金鑰，AI 代理可直接存取：

  GET  /api/v1/public/products              — 商品列表
  GET  /api/v1/public/products/by-code/{code}  — 依編號取單一商品
  GET  /api/v1/public/agent/products/{code}/compliance  — 合規資料（CAS/GHS/SDS）
  GET  /api/v1/public/agent/catalog-feed    — 完整商品目錄（機器可讀 JSON）
  GET  /api/v1/public/agent/catalog-feed-en — 英文版商品目錄
  POST /api/v1/public/agent/batch/products  — 批次查詢多 SKU 庫存與定價
  POST /api/v1/mcp                          — MCP Server（工具列表與呼叫）
  GET  /.well-known/agent.json              — Google A2A Agent Card
  GET  /.well-known/openapi.json            — OpenAPI 3 規格（機器可讀 API 定義）
  GET  /.well-known/api-changelog.json      — API 版本變更紀錄
  GET  /sitemap.xml                         — 官網全站 Sitemap（含全部上架商品）
  GET  /llms-en.txt                         — 本指南英文版
  GET  /api/v1/public/agent/google-merchant-feed  — Google Merchant Center 商品 Feed（RSS XML）

### 會員端點（需官網 JWT）
通過官網登入取得 JWT（Bearer Token）後可存取：

  GET  /api/v1/public/orders                — 查詢訂單歷史

## MCP Server（推薦 — 標準化工具協議）

  POST /api/v1/mcp
  Content-Type: application/json

MCP（Model Context Protocol）是 Anthropic 制定的 AI 代理工具協議標準。
化合的 MCP Server 暴露以下工具：

- search_products — 搜尋化合化學試劑商品目錄。支援自然語言、CAS 號、中英文品名。回傳商品列表含 SKU、品名、庫存狀態、官網售價、CAS 號。
- get_product_detail — 依商品編號（productCode）取得完整商品資料，含規格、包裝、庫存量、價格、圖片。
- get_compliance_data — 取得化學品安全合規資料：CAS 號、GHS 危害分類、信號詞（危險/警告）、危害聲明（H codes）、UN 號碼（危險品運輸）、SDS 安全資料表下載連結。
- check_inventory — 批次查詢多個 SKU 的庫存狀態（現貨量、安全庫存、是否有貨）。
- get_pricing — 查詢商品定價（含官網售價，未來支援數量階梯報價）。
- check_agent_permissions — （B2B 企業客戶專用）在建立詢價單前，驗證 AI 代理是否有授權代表此客戶進行採購，以及申請金額是否在允許範圍內。建議在 create_quote_request 前呼叫此工具。
- get_inquiry_status — 查詢詢價單或訂單狀態。建立詢價單後，AI 代理可用此工具追蹤案件處理進度。
- create_quote_request — 建立詢價單（B2B 採購詢價，無需登入）。適合大量採購、特殊規格或需報出口報價的情境。
- place_order — 代理客戶直接建立銷售訂單（需客戶已在化合設定 AI 代理授權）。系統自動依 CustomerAiAgentConfig 檢查金額授權上限：在上限內自動確認訂單；超出審批門檻則建立待審訂單由業務確認後出貨。呼叫前請先執行 check_agent_permissions 確認授權範圍。
- get_sds_summary — 取得化學品的安全資料摘要（SDS 重點）。回傳信號詞、GHS 危害聲明、預防措施重點、危險物品運送資訊、SDS 下載連結。比下載 PDF 更快，適合 AI 代理在採購前快速確認安全性。如需完整 SDS 文件，請使用回傳的 sdsUrl 下載 PDF。
- get_tier_pricing — 查詢商品的現行定價及近期價格歷史，並提供大量採購階梯折扣資訊。B2B 採購 Agent 最常問「買 N kg 多少錢」時使用此工具。回傳當前官網定價、內部定價、近 5 筆定價歷史，以及如何取得數量折扣報價的指引。化合的正式數量折扣需透過 create_quote_request 工具提交需求，業務人員將回覆含折扣的報價。
- get_alternatives — 當商品缺貨或需要比較規格時，查詢同 CAS 號的替代品。回傳相同化學物質但不同規格（包裝量、純度等）的在架商品清單及庫存狀態。注意：不同水合形態有不同 CAS 號（如硫酸銅無水 7758-98-7 vs 五水合物 7758-99-8），此工具使用精確 CAS 比對，不做模糊配對，請確認您查詢的是正確的化學形態。
- get_restock_estimate — 查詢商品的補貨預計到貨日期。根據進行中的採購訂單（PENDING/APPROVED/PROCESSING/PARTIAL 狀態）估算最早補貨時間。適合 AI 代理在商品暫時缺貨時告知客戶「預計 N 天後有貨」，避免客戶流失。若無進行中採購單，回傳 null 並建議提交採購詢價。
- accept_quote — 接受報價單並自動轉成銷售訂單（一步完成 SENT→ACCEPTED→CONVERTED）。客戶或採購 AI 代理在收到報價後確認接受時呼叫，系統自動建立訂單並回傳訂單編號。需提供報價單編號（QT-YYYYMMDD-NNN 格式）及客戶 email 以驗證身份。
- get_invoice — 查詢發票資訊。可依訂單編號或發票號碼查詢。回傳發票狀態（待開立/已開立/已作廢）、金額、買受人資訊及 PDF 路徑。適合 AI 代理協助客戶確認發票是否已開立、金額是否正確。
- create_return_request — 建立退換貨申請。客戶對已成立訂單的商品提出退換貨時呼叫。需提供訂單編號、客戶 email（驗證身份）、退換原因與品項清單。系統自動生成退換單號，業務將於 1-2 工作天內聯繫確認。

詳見 /api/v1/mcp（發送 tools/list 請求取得完整 schema）

## 商品目錄 API

### 目錄版本戳記（輕量輪詢）
  GET /api/v1/public/agent/catalog-version
  返回：{ version, updatedAt, productCount }
  建議：每 30 分鐘輪詢，version 有變化再下載完整 Feed，可省 99% 流量

### 完整目錄 Feed（機器可讀）
  GET /api/v1/public/agent/catalog-feed
  返回：所有上架商品的完整資料（含 CAS、庫存狀態、價格、SDS 連結）

### 商品列表（分頁）
  GET /api/v1/public/products?page=1&limit=50
  GET /api/v1/public/products?keyword=硫酸銅
  GET /api/v1/public/products?productType=CHEMICAL_RAW_MATERIAL

### 單一商品（含家族規格）
  GET /api/v1/public/products/by-code/{productCode}?includeFamily=1

### 化學品合規資料
  GET /api/v1/public/agent/products/{productCode}/compliance
  返回：CAS 號、GHS 分類、信號詞、危害聲明、UN 號碼、SDS 下載連結

### 批次查詢（多 SKU）
  POST /api/v1/public/agent/batch/products
  Body: { "codes": ["HH001001", "HH001002"], "fields": ["inventory", "price", "compliance"] }

## 詢價與下單

### 詢價單（無需登入）
  POST /api/v1/public/quote-request
  Body: {
    "companyName": "台灣科技股份有限公司",
    "contactName": "採購部",
    "email": "purchase@example.com",
    "phone": "02-12345678",
    "items": [
      { "productCode": "HH001001", "quantity": 50, "unit": "kg", "note": "需附 SDS" }
    ],
    "note": "採購用途：工業清洗"
  }

### AI 代理建立詢價單（MCP 工具，無需登入）
  使用 MCP create_quote_request 工具：
  POST /api/v1/mcp
  Body: {
    "jsonrpc": "2.0", "id": "1", "method": "tools/call",
    "params": {
      "name": "create_quote_request",
      "arguments": {
        "companyName": "台灣科技股份有限公司",
        "contactName": "採購部",
        "email": "purchase@example.com",
        "items": [{ "productCode": "HH001001", "quantity": 50 }],
        "purposeDeclaration": "工業用途"
      }
    }
  }
  回傳：caseNumber（案號），業務 1–2 工作天回覆報價

## 速率限制

公開商品 API：300 req/min（AI 代理友善，支援批次操作）
MCP Server：300 req/min（與公開 API 共用池）
會員 API：60 req/min

## Webhook 通知（AI 代理主動推送）

AI 代理平台可向化合系統登錄 Webhook Endpoint，接收訂單與付款狀態的主動推送，
無需持續輪詢。適用於：訂單成立後自動通知採購系統、付款完成後觸發進一步流程。

### 支援的事件

| 事件名稱 | 觸發時機 |
|---|---|
| order.created | 採購詢價單建立時（checkout/MCP create_quote_request） |
| order.shipped | 出貨單狀態變更為 SHIPPED 或 IN_TRANSIT |
| order.delivered | 出貨單狀態變更為 DELIVERED |
| payment.created | 付款記錄建立時 |
| payment.captured | 付款確認時（與 payment.created 同義，標準 AI 代理事件名稱）|
| payment.updated | 付款記錄更新時 |
| payment.refunded | 退款時 |
| payment.cancelled | 付款取消時 |

### Webhook 格式

  POST <your-endpoint-url>
  Headers:
    Content-Type: application/json
    X-Webhook-Event: <event-name>
    X-Webhook-Delivery: <delivery-uuid>
    X-Webhook-Signature: sha256=<hmac-sha256-signature>  (若設定 secret)

  Body: { "event": "<event-name>", "payload": { ... }, "timestamp": "<ISO8601>" }

### 設定 Webhook（需管理員權限）

  POST /api/v1/webhooks
  Body: {
    "name": "AI 採購平台通知",
    "url": "https://your-agent-platform.example.com/webhooks/huaho",
    "events": ["order.created", "order.shipped", "order.delivered", "payment.captured"],
    "secret": "your-hmac-secret"
  }

## AI 代理委派令牌（Agent Token 認證）

企業客戶可在會員中心產生 Agent Token，授予外部 AI 平台（ChatGPT、Claude 等）
代理其帳號執行被授權的操作（查閱訂單、建立詢價單等）。

### 取得委派令牌（客戶登入後操作）

  POST /api/v1/website/member/agent-tokens
  Authorization: Bearer <customer-JWT>
  Body: {
    "name": "ChatGPT 採購代理",
    "scopes": ["catalog:read", "quote:create", "order:read"],
    "expiresInDays": 90
  }
  回傳：{ "token": "hha_<64hex>", "prefix": "hha_xxxxxxxx", ... }
  ⚠️ token 原始值僅顯示一次，請立即複製

### 使用委派令牌（外部 AI 平台）

  Authorization: Bearer hha_<64hex>
  或
  X-Agent-Token: hha_<64hex>

  GET  /api/v1/public/agent/me            — 確認身份與授權範圍
  GET  /api/v1/public/agent/me/orders     — 查詢客戶訂單歷史（需 order:read）
  POST /api/v1/public/agent/me/orders     — 代理客戶直接下訂單（需 order:write）
  POST /api/v1/public/agent/me/quotes     — 代理客戶建立詢價單（需 quote:create）

### 令牌授權範圍

| Scope | 允許操作 |
|---|---|
| catalog:read | 查詢商品目錄、庫存、定價、合規資料 |
| quote:create | 建立詢價單（代理客戶提交採購請求）；使用 POST /me/quotes |
| order:read | 查詢客戶訂單歷史與配送狀態 |
| order:write | 代理客戶直接建立銷售訂單（需客戶已設定 AI 代理授權）|

### 令牌管理（客戶登入後）

  GET    /api/v1/website/member/agent-tokens          — 列出所有令牌
  DELETE /api/v1/website/member/agent-tokens/:tokenId — 撤銷令牌

## 化學品特殊說明

- 所有化學品均依精確 CAS 號（含水合物形態）識別，不做模糊比對
- 查詢硫酸銅時請指定：無水（7758-98-7）或五水合物（7758-99-8）
- SDS（安全資料表）免費提供，符合 GHS 中華民國標準
- 特殊管制化學品之採購需提供用途申報

## 公司資訊

公司：化合企業有限公司（NICE HUA HO ENTERPRISE CO., LTD.）
地址：台灣
服務：化學試劑、工業化學品、實驗耗材
API 版本：v1（2026-05-23）
聯絡：service@huaho.tw