# HuahoNexus — AI Shopping Agent Integration Guide

> NICE HUA HO ENTERPRISE CO., LTD. (化合企業有限公司) is a professional chemical reagent supplier in Taiwan.
> We sell industrial chemicals, laboratory reagents, containers, and instruments,
> with complete SDS safety data and GHS compliance documents.
> This page provides full system integration documentation for AI shopping agents (ChatGPT, Gemini, Claude, etc.)

## Quick Start — AI Agent Procurement Flow

AI agents can assist with chemical procurement via the following flow:

1. **Search Products**: POST /api/v1/mcp (tools/call: search_products)
2. **Check Compliance**: GET /api/v1/public/agent/products/{code}/compliance (CAS, GHS, SDS)
3. **Confirm Inventory**: POST /api/v1/public/agent/batch/products
4. **Request Quote / Place Order**: POST /api/v1/mcp (tools/call: create_quote_request)

AI platforms with a Customer Agent Token (hha_...) can additionally:

5. **Request Quote on Behalf of Customer**: POST /api/v1/public/agent/me/quotes (requires quote:create scope)
6. **Place Order on Behalf of Customer**: POST /api/v1/public/agent/me/orders (requires order:write scope)

## English Catalog Feed

  GET /api/v1/public/agent/catalog-feed-en
  Returns all listed products with English names (name field), Chinese names (nameZh field),
  CAS numbers, inventory status, and pricing. Supports ETag conditional GET for efficient polling.

## Base URL

  https://huaho.tw/api/v1        (production)
  https://api.huaho.tw/api/v1    (production API domain, same API)

## Authentication

### Public Endpoints (No Auth Required)
The following endpoints require no API key and are directly accessible by AI agents:

  GET  /api/v1/public/products                        — Product list
  GET  /api/v1/public/products/by-code/{code}         — Single product by code
  GET  /api/v1/public/agent/products/{code}/compliance — Compliance data (CAS/GHS/SDS)
  GET  /api/v1/public/agent/catalog-feed              — Full product catalog (Chinese names)
  GET  /api/v1/public/agent/catalog-feed-en           — Full product catalog (English names)
  POST /api/v1/public/agent/batch/products            — Batch query inventory and pricing
  POST /api/v1/mcp                                    — MCP Server (tool list and calls)
  GET  /.well-known/agent.json                        — Google A2A Agent Card
  GET  /.well-known/openapi.json                      — OpenAPI 3 spec (machine-readable API definition)
  GET  /.well-known/api-changelog.json                — API changelog
  GET  /sitemap.xml                                   — Site-wide sitemap (all listed products)
  GET  /llms.txt                                      — This guide in Chinese
  GET  /api/v1/public/agent/google-merchant-feed      — Google Merchant Center product feed (RSS XML)

### Member Endpoints (Require Website JWT)
After logging in via the website and obtaining a JWT (Bearer Token):

  GET  /api/v1/public/orders  — Query order history

## MCP Server (Recommended — Standardized Tool Protocol)

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

MCP (Model Context Protocol) is the AI agent tool protocol standard defined by Anthropic.
Huaho's MCP Server exposes the following tools (descriptions in Traditional Chinese;
send a tools/list request for full JSON schemas):

- 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 工作天內聯繫確認。

See /api/v1/mcp (send a tools/list request for full details)

## Product Catalog API

### Catalog Version Stamp (Lightweight Polling)
  GET /api/v1/public/agent/catalog-version
  Returns: { version, updatedAt, productCount }
  Recommended: Poll every 30 minutes; only download full feed when version changes (saves 99% bandwidth)

### Full Catalog Feed (Machine-Readable)
  GET /api/v1/public/agent/catalog-feed     — Chinese product names
  GET /api/v1/public/agent/catalog-feed-en  — English product names (falls back to Chinese if unavailable)

### Product List (Paginated)
  GET /api/v1/public/products?page=1&limit=50
  GET /api/v1/public/products?keyword=copper+sulfate
  GET /api/v1/public/products?productType=CHEMICAL_RAW_MATERIAL

### Single Product (with Family Specifications)
  GET /api/v1/public/products/by-code/{productCode}?includeFamily=1

### Chemical Compliance Data
  GET /api/v1/public/agent/products/{productCode}/compliance
  Returns: CAS number, GHS classification, signal word, hazard statements, UN number, SDS download link

### Batch Query (Multiple SKUs)
  POST /api/v1/public/agent/batch/products
  Body: { "codes": ["HH001001", "HH001002"], "fields": ["inventory", "price", "compliance"] }

## Quotes and Orders

### Quote Request (No Login Required)
  POST /api/v1/public/quote-request
  Body: {
    "companyName": "Taiwan Tech Co., Ltd.",
    "contactName": "Purchasing Dept.",
    "email": "purchase@example.com",
    "phone": "+886-2-12345678",
    "items": [
      { "productCode": "HH001001", "quantity": 50, "unit": "kg", "note": "SDS required" }
    ],
    "note": "Intended use: industrial cleaning"
  }

### AI Agent Quote Request (MCP Tool, No Login Required)
  Use MCP create_quote_request tool:
  POST /api/v1/mcp
  Body: {
    "jsonrpc": "2.0", "id": "1", "method": "tools/call",
    "params": {
      "name": "create_quote_request",
      "arguments": {
        "companyName": "Taiwan Tech Co., Ltd.",
        "contactName": "Purchasing Dept.",
        "email": "purchase@example.com",
        "items": [{ "productCode": "HH001001", "quantity": 50 }],
        "purposeDeclaration": "Industrial use"
      }
    }
  }
  Returns: caseNumber (case ID); sales staff will reply with a quote within 1–2 business days

## Rate Limits

Public product API: 300 req/min (AI-agent friendly, supports batch operations)
MCP Server: 300 req/min (shared pool with public API)
Member API: 60 req/min

## Webhook Notifications (Push to AI Agents)

AI agent platforms can register a Webhook Endpoint with Huaho to receive push notifications
for order and payment status changes, eliminating the need for continuous polling.

### Supported Events

| Event Name       | Trigger |
|---|---|
| order.created    | Quote/inquiry case created (checkout or MCP create_quote_request) |
| order.shipped    | Shipment status changed to SHIPPED or IN_TRANSIT |
| order.delivered  | Shipment status changed to DELIVERED |
| payment.created  | Payment record created |
| payment.captured | Payment confirmed (synonym for payment.created; standard AI agent event name) |
| payment.updated  | Payment record updated |
| payment.refunded | Refund issued |
| payment.cancelled| Payment cancelled |

### Webhook Format

  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>  (if secret configured)

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

### Register a Webhook (Admin Required)

  POST /api/v1/webhooks
  Body: {
    "name": "AI Procurement Platform Notifications",
    "url": "https://your-agent-platform.example.com/webhooks/huaho",
    "events": ["order.created", "order.shipped", "order.delivered", "payment.captured"],
    "secret": "your-hmac-secret"
  }

## AI Agent Delegation Token (Agent Token Authentication)

Enterprise customers can generate an Agent Token in the member center,
granting an external AI platform (ChatGPT, Claude, etc.) permission to act on their behalf
for authorized operations (view orders, create quotes, etc.).

### Obtain a Delegation Token (Customer Login Required)

  POST /api/v1/website/member/agent-tokens
  Authorization: Bearer <customer-JWT>
  Body: {
    "name": "ChatGPT Procurement Agent",
    "scopes": ["catalog:read", "quote:create", "order:read"],
    "expiresInDays": 90
  }
  Returns: { "token": "hha_<64hex>", "prefix": "hha_xxxxxxxx", ... }
  ⚠️ The raw token is shown only once — copy it immediately

### Use the Delegation Token (External AI Platform)

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

  GET  /api/v1/public/agent/me        — Confirm identity and authorized scopes
  GET  /api/v1/public/agent/me/orders — Query customer order history (requires order:read)
  POST /api/v1/public/agent/me/orders — Place an order on behalf of customer (requires order:write)
  POST /api/v1/public/agent/me/quotes — Create a quote on behalf of customer (requires quote:create)

### Token Authorization Scopes

| Scope        | Permitted Operations |
|---|---|
| catalog:read | Query product catalog, inventory, pricing, compliance data |
| quote:create | Create quotes (submit purchase requests on behalf of customer); use POST /me/quotes |
| order:read   | Query customer order history and delivery status |
| order:write  | Place sales orders on behalf of customer (requires customer AI agent authorization) |

### Token Management (Customer Login Required)

  GET    /api/v1/website/member/agent-tokens          — List all tokens
  DELETE /api/v1/website/member/agent-tokens/:tokenId — Revoke token

## Chemical-Specific Notes

- All chemicals are identified by exact CAS number (including hydrate form); no fuzzy matching
- When querying copper sulfate, specify: anhydrous (7758-98-7) or pentahydrate (7758-99-8)
- SDS (Safety Data Sheet) provided free of charge, compliant with GHS ROC (Taiwan) standard
- Procurement of specially controlled chemicals requires a declaration of intended use

## Company Information

Company: NICE HUA HO ENTERPRISE CO., LTD. (化合企業有限公司)
Location: Taiwan
Services: Chemical reagents, industrial chemicals, laboratory consumables
API Version: v1 (2026-05-25)
Contact: service@huaho.tw