HARUKI Agent — BYOA entry for harukibox proxy-shopping SaaS

harukibox Agent is the Bring-Your-Own-Agent gateway to the harukibox proxy-shopping inventory platform. It exposes the products / orders / buyers / shipping / confirmation / dashboard surfaces through OAuth 2.1 PKCE plus an OpenAPI 3.1 specification and an MCP (Model Context Protocol) server. The primary way to connect, and the one that covers most users, takes about one minute: paste https://harukibox.com/api/agent/mcp into the connector settings of Claude (web, desktop or mobile), ChatGPT (Plus or above), Claude Code or Cursor, then approve the authorization screen once. No API key is requested, no token is issued by hand, and no Custom GPT has to be built — clients register themselves through CIMD (Client ID Metadata Documents) and obtain tokens over OAuth 2.1 PKCE. Alternative paths for tools that cannot use a remote connector: local stdio MCP via the @harukibox/mcp package, or direct REST calls from Python / Node / curl / n8n HTTP request / Zapier Webhook against the OpenAPI 3.1 endpoints with a Bearer hrk_* token. Not yet provided as turnkey: dedicated iOS Shortcut template, dedicated n8n / Zapier node — both possible to build yourself with the HTTPS API. Security: OAuth 2.1 PKCE, 90-day access + 365-day refresh tokens (rotation + reuse detection), granular scopes (products:read/write, registrations:read/write, buyers:read/write, shippings:read/write, search, me), per-token IP allowlist and rate limit, full audit log, instant revoke, strict per-token organization scoping. Buyer email and phone are always masked before leaving the system. Forty-one MCP tools are exposed. Reading works on every plan including the free one; writing requires a paid plan and returns HTTP 402 with an upgrade hint otherwise. Available writes: create products and their items, create and update orders (single or batches of up to 50, with automatic price binding), fully edit existing products and items in place — including selling prices, which re-sync the price snapshot on every existing order — upload images, generate confirmation links, record prepaid balance movements, create shipment batches, manage series and characters, keep buyer memos, advance shipping status, allocate freight across orders, merge buyer aliases, assign items into warehouse boxes, and publish a shop link (賣場連結) to every buyer with an order on the products that just landed. Not exposed to agents: deleting any record, and creating the warehouse structure itself. Free plan available, no credit card. Spec: https://harukibox.com/api/agent/openapi.json · MCP HTTP: https://harukibox.com/api/agent/mcp · llms.txt: https://harukibox.com/llms.txt.

讓你的 AI
直接操作 harukibox。

在 Claude 或 ChatGPT 貼上一個網址、按一次授權，就能直接對它說 「這個月哪個 IP 賣最好」。不用申請 API key，不用寫程式。 Claude Code、Cursor 與任何能打 HTTPS 的工具也同樣接得上。

免費開始→ 看 30 秒入門
OAuth 2.1 PKCE · 90 天 tokenOpenAPI 3.1 + MCP 2026-07-28@harukibox/mcp · @harukibox/cli
三步驟接入

貼一個網址，按一次授權。
一分鐘就能開始用。

不用申請 API key、不用手動發 token、不用寫程式。

1

註冊 harukibox

免費版就能讓 AI 讀你的商品、訂單、買家。要讓它直接幫你建訂單、改狀態則需付費方案。

2

在你的 AI 貼上一個網址

Claude、ChatGPT、Claude Code、Cursor 都是同一個網址。不用先申請 API key。

3

按下授權，開始用人話操作

授權頁會列出這個 AI 要的權限，你可以只給讀取。授權後直接對它說「這個月哪個 IP 賣最好」。

你只需要這一個網址

https://harukibox.com/api/agent/mcp

不用先申請 API key、不用手動發 token。貼上網址 → 按授權 → 完成。

  1. 1

    開啟 Claude → 左下角你的名字 → 設定（Settings）

  2. 2

    選「連接器」（Connectors）→ 新增自訂連接器（Add custom connector）

  3. 3

    網址貼上：

    https://harukibox.com/api/agent/mcp
  4. 4

    按「連接」→ 會跳到 harukibox 的授權頁，用你的帳號登入

  5. 5

    確認要開放的權限後按「授權」，就完成了

授權頁會顯示「Claude 想要存取你的帳號」與資料會送去 claude.ai——看到別的網域請立刻取消。

其他接入方式

不走連接器的話，還有兩條路。

上面那條路涵蓋絕大多數人。如果你的工具不支援遠端連接器，或你本來就想自己寫程式，走這兩條。

範例對話

你跟 AI 講話，
AI 跟 harukibox 講話。

以下是真實 API call — AI 透過 OpenAPI 即時讀寫你的資料，不是預先寫好的 Q&A。

AIChatGPT
列出我這個月銷售前 4 個商品
GET /api/agent/search

本月銷售排行，依營收排序：

#1海賊王 SD 路飛12 件NT$ 36,000
#2ChiiKawa 抱枕8 件NT$ 24,800
#3Re:ZERO 雷姆 Wedding6 件NT$ 22,176
#4SPY×FAMILY 安妮亞 黏土人5 件NT$ 18,000
CClaude Desktop · MCP
幫我找陳小玲所有訂單，列出狀態
GET /api/agent/buyers?search=陳小玲

陳小玲（買家 ID by_8f3a1c）共 3 筆訂單，合計 NT$ 12,500：

REG-2026-0512待出貨 · NT$ 4,500
REG-2026-0508已寄出 · NT$ 5,200
REG-2026-0501已完成 · NT$ 2,800
>_curl / @harukibox/cli
harukibox products create --name "火影 鳴人徽章" --price 1500
POST /api/agent/products
✓
已新建：火影 鳴人徽章SKU NRT-0512-A · NT$ 1,500 · 預購

透過 @harukibox/cli + OAuth scope products:write

先講清楚

ChatGPT 可以幫我管代購訂單嗎？

可以，但要分成兩件事：整理一次性的資料，和持續管理一門生意。 純 ChatGPT 做得到前者，做不到後者——差別不在模型聰不聰明，在於它沒有地方存你的資料。

純 ChatGPT 現在就做得到的事

不用接任何系統，把喊單留言整段貼進 ChatGPT，它就能整理成表格； 也能幫你換匯、算單筆成本、草擬要發給買家的訊息。 這些是真的有用，而且已經有不少代購賣家每天在這樣做。

  • 把一批雜亂的留言整理成「誰要什麼、幾個」
  • 日幣換台幣、算這一筆的成本與毛利
  • 草擬對帳訊息、到貨通知的文案
  • 解釋你不熟的日文商品名或角色名

純 ChatGPT 做不到的事

它沒有你的資料庫。整理完的結果只存在那個對話視窗裡， 關掉就沒了，下次要重貼一次；而代購真正花時間的部分，恰好都在「下一次」。

  • 資料不會留下——這批整理完，下批要重來，兩批之間對不起來
  • 算不了跨批運費分攤——要同一批所有包裹的重量與總運費，而且事後補一件就得全部重算
  • 買家查不到自己的單——你還是得一個一個回訊息
  • 多人一起做會各做各的——沒有共同的一份資料
  • 對話一長就會忘記前面——你以為它記得上個月那個買家，它不記得
  • 沒有紀錄——誰在什麼時候改了什麼，查不到

所以「把 AI 接上後台」是什麼意思？

就是讓 AI 讀寫一份會留下來的資料，而不是每次都從貼上開始。 harukibox 提供兩條路，需求不同、門檻也差很多——大部分人需要的是第一條。

兩條路你要做的事需要什麼適合誰
站內 AI
（快速登記）		登入 harukibox，把喊單貼進「快速登記」，它自動解析成訂單讓你確認。免費版就能用，每月 30 次 AI 呼叫； 專業版以上無限。
不需要 ChatGPT Plus。		只是想把喊單變成訂單、不想再多學一個工具的人。多數人在這一列。
接你自己的 AI
（MCP 連接器）		在 ChatGPT / Claude 貼上一個網址授權，之後在你原本的對話裡直接問資料、下指令。讀取：所有方案（含免費版）。
讓 AI 直接寫入：專業版以上。
ChatGPT 那側需 Plus 以上才有連接器。		本來就整天待在 ChatGPT / Claude 裡、希望不要再切換視窗的人。

harukibox 的 AI 不做的事

寫出來是因為這些界線會直接影響你要不要用它， 而且其中幾條是刻意設計的，不是還沒做完。

不猜

解析喊單時，角色、尺寸、數量只要判讀不出來，那幾列不會被寫進系統， 而是列成具體問題回報給你。因為猜錯的那一項會變成真的從日本寄來的貨， 你要到貨才會發現，那時已經退不掉。

不替你決定倉位

AI 可以幫你記錄「這批放 3 號箱」，但箱子一定要你講。 它不會因為箱子名稱看起來跟商品有關就自己選一個—— 放錯箱比沒標位置更糟，因為你會相信系統而去翻錯的那一箱。

看不到買家的聯絡方式

買家的 email 與電話一律遮蔽後才送出去（co***@gmail.com、****5678）。 AI 拿得到「這個買家收不收得到通知」，但拿不到完整聯絡方式—— 那是買家的個資，不該由賣家單方面決定要不要交給外部 AI。

不做的還有

不幫你決定要進什麼貨（它只告訴你賣得如何，判斷是你的）； 不代收款、不介入金流；不會刪除任何資料。 另外 Gemini 目前沒有 MCP 連接器，接不上—— 要用 Gemini 的話走站內 AI 那條路。

為什麼 BYOA

為什麼 harukibox
開放 agent 入口？

我們專心做後台與 API。AI，交給你已經在用的那一個。

你的工具，你的 AI

你已經付錢買 ChatGPT Plus、Claude Pro、Gemini Advanced。為什麼還要學另一個產品的內建 chatbot？

標準介面，不綁特定 AI

OpenAPI 3.1 + MCP 2026-07-28 都是業界標準。AI 透過 HTTPS 即時讀寫你的資料，不是預寫 Q&A。讀取所有方案都能用；讓 AI 直接寫入需要付費方案。

跟 web 後台同一套 auth

OAuth 2.1 PKCE + 90 天 access token + 365 天 refresh + 隨時撤銷 + 每次 call 寫 audit log。Token 有 scope 限制，AI 拿到的權限是你 web 後台權限的子集。

安全與權限

你 AI 拿到的權限，
你完全控制。

每個 token 獨立設定 scope，每次 API call 寫進 audit log，隨時可撤銷。

  • ✓OAuth 2.1 PKCE flow · 業界標準，跟 Google / Microsoft 同 spec。
  • ✓你選 scope · 只給「讀商品」或「讀寫全部」，granular 到單一資源。
  • ✓90 天 access · 365 天 refresh · token 自動續期，過期即作廢。
  • ✓任何時候 harukibox tokens revoke 撤銷。
  • ✓每次 API call 寫進 audit log，你可查看誰、何時、做了什麼。
  • ✓多租戶嚴格隔離 · 你的 token 只能讀你自己的資料。
完整安全規範見 Agent 安全文檔 →
Ttoken: hrk_live_8f3a1c…b9e2active · 89d 12h
Permissions · 可即時切換
商品 — 讀取
products:read
商品 — 修改
products:write
訂單 — 讀取
registrations:read
訂單 — 修改
registrations:write
買家資料 — 讀取
buyers:read
3/5已授權↑ 點點看 toggle
完整支援列表

你在用的那個 AI，多半已經接得上。

只要支援 OAuth + OpenAPI 的 agent 工具，幾乎都接得上。挑你最熟的那一個。

工具接入方式設定時間狀態教學
CClaude（網頁 / 桌面 / 手機）
貼網址 + 一鍵授權 · /api/agent/mcp約 1 分鐘可用查看 →
AIChatGPT（Plus 以上）
貼網址 + 一鍵授權 · /api/agent/mcp約 1 分鐘可用查看 →
>_Claude Code
一行指令 · claude mcp add約 1 分鐘可用查看 →
<>Cursor / Cline
MCP 設定檔 · /api/agent/mcp約 3 分鐘可用查看 →
{}Python / Node / curl
REST + Bearer · @harukibox/cli看你需求可用查看 →
n8nn8n / Make / Zapier
HTTP Request 節點
無官方 node / Zap，用內建 HTTP request + Bearer header 自接
看你需求可用（自架）查看 →
所有 client 的完整教學在 docs 站。看 GitHub 範例 cosmopig/harukibox-agent →
常見問題

常見問題

不確定的事先看這裡，沒答案就 mail support@harukibox.com。

可以，但要分成兩件事。純 ChatGPT 做得到「整理一次性的資料」——把喊單留言貼進去變成表格、換匯算成本、草擬給買家的訊息，這些是真的有用。它做不到的是「持續管理」：資料不會留下，關掉視窗就沒了，下次要重貼；算不了跨批運費分攤（要同批所有包裹的重量與總運費，事後補一件就得全部重算）；買家自己查不到單；多人會各做各的；對話一長它就忘記前面。差別不在模型聰不聰明，在於它沒有地方存你的資料。
不用。harukibox 站內就有 AI 快速登記——登入後把喊單貼進「快速登記」，它自動解析成訂單讓你確認，走的是站內 Gemini，免費版每月 30 次就能用，專業版以上無限。這條路不需要 ChatGPT Plus，也不需要付費方案。要接自己的 ChatGPT / Claude 當作連接器是另一條路，那條 ChatGPT 那側才需要 Plus 以上。
不用寫程式也能用。在 Claude 或 ChatGPT 的「連接器」設定貼上 https://harukibox.com/api/agent/mcp，按一次授權就完成，全程約一分鐘——不用申請 API key，也不用自建 Custom GPT。接好之後直接用講的問「這個月哪個 IP 賣最好」「還有誰沒付款」。（ChatGPT 需 Plus 以上方案才有連接器功能。）
只有你授權的 scope 才會，而且授權時讀取與寫入是分開勾選的——你可以只給「讀」，AI 就只能查不能改。買家的 email 與電話一律遮蔽後才送出（你會拿到「收不收得到通知」的標記，但看不到完整聯絡方式），因為那是買家的個資，不該由賣家單方面決定要不要交給外部 AI。權限隨時可單獨撤回，每次 API 呼叫都寫進你查得到的 audit log。
harukibox 沒有內建 AI，短期內也不打算做。我們把資源用在後台與 API 規範上，模型由你選——你已經在付的那一個就好。目前 Claude（網頁／桌面／手機）、ChatGPT（需 Plus 以上）、Claude Code、Cursor 都接得上；Gemini 目前還沒有 MCP 連接器，接不上。
只要支援 OAuth + OpenAPI 或 MCP 的工具都能接。換 AI 就在新的那一個貼一次同樣的網址、再授權一次，舊的直接撤銷——資料一直在 harukibox，沒有東西被綁在單一 AI 廠商。
token 用 OAuth 2.1 PKCE 發給（與 Google / Microsoft 同 spec），90 天到期、refresh rotation + reuse detection、隨時撤銷、每次 call 有 audit log。但任何 long-lived credential 都有風險 — 我們建議用 scope 最小化 + 短期 token + IP allowlist 一起降低暴露面。
Agent 介面本身不另外收費，依你訂閱方案的 quota 走。讀取（查商品、訂單、買家）所有方案都能用，包含免費版；讓 AI 直接寫入資料需要付費方案（專業版 NT$129 以上）。但如果你要的只是「把喊單貼上去自動建成訂單」，系統內建的 AI 快速登記免費版每月 30 次就能用，不需要付費方案、也不需要 ChatGPT Plus——那條路和這頁講的連接器是兩件事。

把你的 AI 接上
harukibox。

14 天免費試用 · 不需信用卡 · OpenAPI + MCP 全開放。

免費開始→ 看 GitHub
// or: 完整接入文檔