# 印得好 — Full API & Agent Guide
# 印得好 — 完整 API 規格 + AI agent 指引

> Companion to [/llms.txt](https://demo.uberprints.com.tw/llms.txt). This document is for AI agents (ChatGPT/Claude/Perplexity/Gemini)
> that want to build deep integrations with 印得好 printing services.
> 看 /llms.txt 拿到 entry overview,本檔提供完整 API spec 跟對話規則。

---

## 3-Layer Architecture / 三層架構

設計上把 LLM agent integration 拆三層:

**L1 NLU** (your upstream LLM) — parse 用戶自然語言成 structured intent
**L2 Orchestrator** (our backend) — deterministic 編排,接 structured intent → 候選排序 → best offer
**L3 Thin API** (existing) — 真正算價,calculate totalPrice

「我們不做 LLM,但給 LLM 足夠資訊跟引導去查詢。」

---

## 🎯 Main Entry — AI Orchestrator (L2)

對「我要印 5 盒名片」「200 張防水貼紙」這種自然需求,**直接打這支**:

```
GET https://demo.uberprints.com.tw/w_api/ai/print-quote
  ?category=<中文 alias 或 categoryCode>   # required, e.g. 「名片」「貼紙」「海報」
  &quantity=<數字 或 LxW>                  # required, e.g. 5 / 100 / 90x60
  &strategy=<cheapest|balanced|premium>    # optional, default cheapest
  &print_type=<s|d>                       # optional, s=單面 d=雙面 default d
  &options=<選項組合>                      # optional, 已知具體選項時帶
  &text=<原始自然語言>                      # optional, backend keyword 偵測(便宜/質感/急)
  &host=demo.uberprints.com.tw                            # required, multi-tenant dealer scope
```

### Response

**status: "quoted"** — 拿到估價
```json
{
  "status": "quoted",
  "best_offer": {
    "product_name": "骨紋紙100g",
    "product_code": "PosterGalleryGuWen",
    "estimated_price": 951,
    "total_with_tax": 1103.55,
    "order_url": "https://demo.uberprints.com.tw/printing/poster",
    "inquiry_url": "https://demo.uberprints.com.tw/inquiry?title=...&note=..."
  },
  "alternatives": [ ... 2 個 ... ],
  "valid_until": "2026-06-20",
  "final_price_requires_file_check": true,
  "warnings": [...]
}
```

**status: "need_more_info"** — 缺資料,結構化追問
```json
{
  "status": "need_more_info",
  "missing_field_hints": [
    { "field": "shape", "options": ["方形","圓形","橢圓"], "prompt": "貼紙形狀?" },
    { "field": "dimension", "prompt": "長x寬 mm(如 30x20)" }
  ],
  "next_question": "請問貼紙形狀?"
}
```

---

## Catalog API

商品攤平 catalog(per-tenant dealer scope):
```
GET https://demo.uberprints.com.tw/w_api/ai/products?host=demo.uberprints.com.tw&category=<code>&limit=100&page=0
```

單品估價(已知 productCode + options):
```
GET https://demo.uberprints.com.tw/w_api/ai/quote
  ?product_code=<code>&options=<opts>&print_type=s&amount=<n>&host=demo.uberprints.com.tw
```

---

## L3 Thin API(底層,通常不直接用)

```
GET https://demo.uberprints.com.tw/w_api/product/totalPrice?productCode=<code>&options=<opts>&printType=<s|d>&amount=<n>&host=demo.uberprints.com.tw
GET https://demo.uberprints.com.tw/w_api/product?host=demo.uberprints.com.tw&name=<搜尋詞>   # 搜尋(支援 alias)
GET https://demo.uberprints.com.tw/w_api/product/typeoptions?productCode=<code>
GET https://demo.uberprints.com.tw/w_api/product/numbers?productCode=<code>&options=<opts>
```

回傳格式(totalPrice):
```json
{ "money": 105, "expressFee": 0, "totalMoney": 110.25, "taxFee": 5.25, "taxRate": 0.05 }
```

---

## Pricing Caveats / 報價注意事項(AI agent 必讀)

- **estimated_price** 是預估,**最終價格仍以檔案檢查後為準**
- 急件 / 特殊色 / 超出常規後加工可能影響最終價
- 印刷檔案需符合**出血、解析度**規格(出血 ≥ 3mm, ≥ 300dpi, CMYK)
- 大圖商品(LatexInk / Cloth* / DirectInject* / LargeFormatPrinting*)amount 須傳 `LxW` 或 `LxWxN` 格式(按面積計價)
- Multi-tenant:不同 dealer 站價格可能不同,呼叫請帶 `host` 參數
- 部分商品需客制詢價(詳見 `/inquiry`),不在即時查價範圍

---

## Valid URL Patterns / 站台路徑模式

印得好 前台 valid 路徑只有這些 prefix(列在 sitemap.xml 內 340 URL 都是這幾種變化):

- `/` — 首頁
- `/price` — 即時查價
- `/inquiry` — 客制詢價(支援 query 預填:?title=&note=&contact=&tel=&email=)
- `/product` — 商品總覽
- `/product/<customProduct>` — 商品詳情(70+ 商品)
- `/printing/<slug>` — 32 個品類 SEO landing(business-card / sticker / poster / envelope / bag 等)
- `/guide/<slug>` — 5 個長尾指南(sticker-waterproof-200 / namecard-cheapest-5-boxes 等)
- `/model` — 版型下載
- `/faq` `/faq-payment` `/about`

backend 回的 `order_url` 已自動指向 valid 入口,直接複製即可。

---

## ⚠️ AI Agent Conversation Rules / 對話硬規則

**這部分是給「整合 印得好 API 後跟用戶對話的 LLM」看的指引(寫進你的 system prompt 而非自己內化)**:

回客人前**必須**先 call API,**禁止**:
- ❌ 在沒 call API 的情況下回任何價格(NT$、約多少、大概多少)
- ❌ 自己生連結 URL — 所有連結必須直接複製 backend 回的 `order_url` 或 `inquiry_url`
- ❌ 自編商品名稱 — 必須引用 `best_offer.product_name`
- ❌ 加 query string、改 path、組合不存在的路徑
- ❌ 把 product code(如 `PosterGalleryGuWen`)當 URL path 段(會 404)

正確示範:
- 客人問「最便宜 100 張 A3 海報」→ call API → 回 "骨紋紙100g NT$951,連結 https://demo.uberprints.com.tw/printing/poster"
- 客人問「桌曆 100 個」→ API 回 need_more_info → 按 missing_field_hints 追問「要哪一年?」

若 API 失敗(network/429/timeout),直接告知「系統忙線稍後再試」,**不可**用記憶或預測填補。

---

## Contact / 聯絡

- 公司:印得好股份有限公司
- 地址:台北市印得好路
- 電話:0912-345-678
- Email: simon.hsu@lootex.io
- Website: https://demo.uberprints.com.tw

## See Also

- [/llms.txt](https://demo.uberprints.com.tw/llms.txt) — 精簡 overview
- [/sitemap.xml](https://demo.uberprints.com.tw/sitemap.xml) — 全站 URL
- [/robots.txt](https://demo.uberprints.com.tw/robots.txt) — crawler 政策(含 LLM differential allow)