Manual API 使用說明

🕒 最後更新：2026-09-18 18:50

NEXPOS Manual API · 建立 / 更新說明書 HTTP 介面

版本 1.0 api.php JSON Token 認證

外部系統、自動化腳本或者 AI 可以用呢個入口直接建立或更新 manuals，唔使經後台 TinyMCE 人手輸入。讀取已發佈內容仍然可以用現有 ai_feed.php。

把 api.php 放喺網站根目錄，即同 config.php、ai_feed.php 同一層。資料庫連線沿用 config.php。

1. 基本資料

Endpoint	`https://manual.nexposhk.com/api.php`
Protocol	HTTPS · JSON
寫入方法	POST（create / update / upsert）
讀取方法	GET 或 POST（get / list / categories）
Content-Type	application/json（建議）或 form-urlencoded
字元編碼	UTF-8
CORS	允許 *（方便內部工具呼叫）

2. 認證

同 ai_feed.php 共用同一把 AI Token。三種傳法擇一即可，優先次序由上至下：

方式	例子
HTTP Header X-API-Token	`X-API-Token: nexpos_ai_access_2026_secure`
Authorization Bearer	`Authorization: Bearer nexpos_ai_access_2026_secure`
Query / JSON 欄位 token	`?token=nexpos_ai_access_2026_secure`

Token 值
nexpos_ai_access_2026_secure
與 ai_feed.php 內 $ai_token 相同。如要更換，兩邊要一齊改。

Token 錯誤會回 HTTP 403：

{"ok": false, "error": "Access Denied: Invalid Token"}

3. Action 一覽

action	方法	用途
`upsert`（預設）	POST	有 id / slug / 完全相同 title 就更新，否則新增
`create`	POST	強制新增，即使 title 已存在都會再開一篇
`update`	POST	只更新。必須提供 id、slug 或精確 title，找不到就 404
`get`	GET / POST	讀取單篇完整內容（含 HTML content）
`list`	GET / POST	列出文章摘要，可 filter
`categories`	GET / POST	列出全部分類

對文章的查找順序
id → slug → title（精確全名、取最新一筆）。title 唔會做模糊比對，避免改錯文。

4. 欄位說明

欄位	必填	說明
`action`	否	預設 upsert
`token`	視乎	若無 Header 就要喺 body / query 帶
`id`	update 時	現有 manuals.id
`slug`	否	網址用短碼。新增時如不傳會由 title 自動產生
`title`	新增時必填	標題。upsert 亦可用精確 title 對到現有文章
`content`	否	HTML 正文，格式同後台 TinyMCE
`status`	否	draft 或 published。新增預設 draft
`category_id`	否	現有分類 ID。不存在會 400
`category_name` 或 `category`	否	用名稱對分類；沒有就自動建立一個公開分類
`sort_order`	否	排序。新增時預設為目前最大值 + 1
`q`	list	標題關鍵字搜尋
`limit`	list	回傳筆數，1–200，預設 50

5. 使用例子

5.1 建立或更新（最常用）

同一 title 再打一次就會 update，唔會重複開新篇。分類名稱冇就自動開。

curl -X POST https://manual.nexposhk.com/api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Token: nexpos_ai_access_2026_secure" \
  -d '{
    "action": "upsert",
    "title": "POS 開機流程",
    "content": "<h2>步驟</h2><ol><li>開電源</li></ol>",
    "status": "published",
    "category_name": "操作教學"
  }'

成功新增回 HTTP 201，"action": "created"。成功更新回 HTTP 200，"action": "updated"。

5.2 用 ID 更新指定一篇

curl -X POST https://manual.nexposhk.com/api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Token: nexpos_ai_access_2026_secure" \
  -d '{
    "action": "update",
    "id": 88,
    "content": "<p>已修正步驟 3。</p>",
    "status": "published"
  }'

update 時只傳想改嘅欄位即可，其餘保留原值。

5.3 強制新增

curl -X POST https://manual.nexposhk.com/api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Token: nexpos_ai_access_2026_secure" \
  -d '{
    "action": "create",
    "title": "週末促銷設定",
    "content": "<p>...</p>",
    "status": "draft",
    "category_id": 3
  }'

5.4 讀取

curl "https://manual.nexposhk.com/api.php?action=get&id=88&token=nexpos_ai_access_2026_secure"
curl "https://manual.nexposhk.com/api.php?action=get&slug=pos-xxxx&token=nexpos_ai_access_2026_secure"
curl "https://manual.nexposhk.com/api.php?action=list&status=published&limit=50&token=nexpos_ai_access_2026_secure"
curl "https://manual.nexposhk.com/api.php?action=categories&token=nexpos_ai_access_2026_secure"

5.5 用 PHP 呼叫

$payload = [
  'action' => 'upsert',
  'title'  => 'POS 開機流程',
  'content'=> '<p>第一步……</p>',
  'status' => 'published',
  'category_name' => '操作教學',
];
$ch = curl_init('https://manual.nexposhk.com/api.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Token: nexpos_ai_access_2026_secure',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

6. HTTP 狀態碼

200	更新成功、讀取成功
201	新增成功
204	OPTIONS preflight
400	缺 title、status 不合法、category_id 不存在、未知 action
403	Token 錯誤或缺失
404	update / get 搵唔到文章
405	用 GET 去做 create / update / upsert
500	伺服器或資料庫例外，error 欄會有訊息

7. 同現有系統的關係

config.php	PDO 連線。API 直接 require，唔使重複寫帳密
ai_feed.php	只讀：匯出已 published 文章給 AI（純文字）
api.php	讀寫：JSON 建立 / 更新 / 查詢
admin/add.php、edit.php	人手後台，寫入同一張 manuals 表
upload.php	TinyMCE 上圖。本 API 唔處理檔案上傳

資料表欄位與後台一致：title、slug、content、category_id、status、sort_order、public_token、created_at、updated_at。API 新增時會自動產生 slug 同 public_token，updated_at 用 NOW()。

8. 注意事項

Token 等同後台寫入權限，唔好公開喺前端 JS 或公開 Git repo。
content 接受 HTML。外部來源要自己過濾 XSS，先至寫入。
upsert 用精確 title 對文章。標題改咗之後要用 id 或 slug 先對到舊篇。
category_name 會自動開分類，分類名打錯就會開多一個，建議優先用 category_id。
本 API 暫時冇刪除、冇上圖。刪文繼續用後台；圖片可先 call upload.php 再把 URL 寫入 content。
更換 Token 時，api.php 同 ai_feed.php 必須同步修改。

9. 快速檢查清單

步驟	預期
把 api.php 上傳到網站根目錄	`https://manual.nexposhk.com/api.php` 可訪問
無 token 打一次	403 + Invalid Token
action=categories 加 token	200 + categories 陣列
upsert 一篇 draft	201 created，後台 Dashboard 見到
同一 title 再 upsert	200 updated，id 不變
改 status=published	前台 / ai_feed.php 見到新內容

NEXPOS 說明書