ewoooc/docs/API_DOCUMENTATION.md

MOMO Pro System - API 文件

最後更新：2026-01-29

---

📌 概述

Base URL

• 生產環境: https://mo.wooo.work
• 開發環境: http://localhost:5000

認證方式

• Session Cookie: 透過 /login 取得
• Bot API Token: Header Authorization: Bearer <token>

回應格式

{
    "success": true,
    "data": { ... },
    "message": "操作成功"
}

錯誤回應

{
    "success": false,
    "error": "錯誤訊息",
    "code": "ERROR_CODE"
}

---

🔐 認證 API

登入

POST /login
Content-Type: application/x-www-form-urlencoded

參數	類型	必填	說明
username	string	✓	帳號
password	string	✓	密碼

回應: 302 Redirect 或 401

登出

GET /logout

修改密碼

POST /api/user/change_password
Content-Type: application/json

{
    "current_password": "舊密碼",
    "new_password": "新密碼"
}

---

📊 商品看板 API

取得商品列表

GET /api/products

參數	類型	說明
page	int	頁碼 (default: 1)
per_page	int	每頁筆數 (default: 50)
category	string	分類篩選
filter	string	狀態篩選 (all/increase/decrease/delisted)
q	string	搜尋關鍵字
sort_by	string	排序欄位
order	string	排序方向 (asc/desc)

回應:

{
    "items": [...],
    "total": 5576,
    "page": 1,
    "per_page": 50,
    "total_pages": 112
}

取得商品價格歷史

GET /api/history/{product_id}

回應:

[
    {"t": "2026-01-29 14:00", "p": 3280},
    {"t": "2026-01-28 14:00", "p": 3180}
]

手動執行爬蟲

POST /api/run_task

發送價格通知

POST /api/trigger_momo_notification

---

📈 業績分析 API

取得每日業績

GET /api/daily_sales

參數	類型	說明
date	string	日期 (YYYY-MM-DD)
pm	string	PM 篩選
brand	string	品牌篩選

取得月份總表

GET /api/monthly_summary

參數	類型	說明
year	int	年份
month	int	月份

取得銷售趨勢

GET /api/sales/trend

參數	類型	說明
start_date	string	開始日期
end_date	string	結束日期
dimension	string	維度 (brand/pm/category)

---

📦 廠商缺貨 API

匯入缺貨資料

POST /api/vendor/stockout/import
Content-Type: multipart/form-data

參數	類型	說明
file	file	Excel 檔案

取得缺貨列表

GET /api/vendor/stockout

參數	類型	說明
batch_id	string	批次篩選
vendor_code	string	廠商篩選
status	string	狀態篩選

發送通知郵件

POST /api/vendor/stockout/send
Content-Type: application/json

{
    "stockout_ids": [1, 2, 3]
}

廠商清單 CRUD

GET /api/vendor/list                      # 取得廠商列表
POST /api/vendor/list                     # 新增廠商
PUT /api/vendor/list/{vendor_id}          # 更新廠商
DELETE /api/vendor/list/{vendor_id}       # 刪除廠商

廠商郵件 CRUD

GET /api/vendor/{vendor_id}/emails        # 取得郵件列表
POST /api/vendor/{vendor_id}/emails       # 新增郵件
DELETE /api/vendor/email/{email_id}       # 刪除郵件

---

🤖 AI API

生成文案

POST /api/ai/generate
Content-Type: application/json

{
    "product_name": "商品名稱",
    "style": "吸睛",
    "keywords": ["保濕", "抗老"],
    "provider": "ollama"
}

回應:

{
    "content": "生成的文案內容",
    "model": "llama3:70b",
    "duration": 5.2,
    "input_tokens": 120,
    "output_tokens": 85
}

取得熱門推薦

GET /api/ai/trending

參數	類型	說明
source	string	來源 (mybest/cosme/youtube)
category	string	分類

網路搜尋 (Gemini)

POST /api/ai/search
Content-Type: application/json

{
    "query": "搜尋關鍵字"
}

AI 歷史記錄

GET /api/ai/history                       # 取得歷史列表
GET /api/ai/history/{id}                  # 取得單筆記錄
PUT /api/ai/history/{id}/favorite         # 切換收藏
DELETE /api/ai/history/{id}               # 刪除記錄

AI 使用統計

GET /api/ai/usage/stats

參數	類型	說明
start_date	string	開始日期
end_date	string	結束日期

---

👤 用戶管理 API

取得用戶列表 (Admin)

GET /api/users

新增用戶 (Admin)

POST /api/users
Content-Type: application/json

{
    "username": "帳號",
    "email": "郵箱",
    "password": "密碼",
    "role": "user",
    "display_name": "顯示名稱"
}

更新用戶 (Admin)

PUT /api/users/{user_id}

刪除用戶 (Admin)

DELETE /api/users/{user_id}

重設密碼 (Admin)

POST /api/users/{user_id}/reset_password

取得登入歷史

GET /api/users/login_history

---

⚙️ 系統 API

取得系統狀態

GET /api/system/status

回應:

{
    "cpu_percent": 25.5,
    "memory_percent": 68.2,
    "disk_percent": 45.0,
    "uptime": "5 days"
}

取得爬蟲狀態

GET /api/system/crawler/status

系統清理

POST /api/system/cleanup

K8s Pod 重啟

POST /api/system/k8s/restart
Content-Type: application/json

{
    "deployment": "momo-app"
}

健康檢查

GET /health

回應: 200 OK

Prometheus 指標

GET /metrics

---

📥 匯入 API

列出 Google Drive 檔案

GET /api/import/drive/files

匯入 Drive 檔案

POST /api/import/drive/import
Content-Type: application/json

{
    "file_id": "Google Drive 檔案 ID",
    "job_type": "daily_sales"
}

取得匯入進度

GET /api/import/jobs/{job_id}

---

📤 匯出 API

匯出商品報表

GET /api/export/excel/all
GET /api/export/excel/changes
GET /api/export/excel/delisted

匯出業績報表

GET /api/export/daily_sales

參數	類型	說明
date	string	日期
format	string	格式 (excel/csv)

---

🔔 通知 API

發送 Telegram 通知

POST /api/notification/telegram
Content-Type: application/json

{
    "message": "通知內容"
}

渲染通知模板 (供 n8n 呼叫)

POST /api/notification/render
Content-Type: application/json

{
    "code": "disk_warning",
    "variables": {
        "usage_percent": 85
    }
}

取得通知模板

GET /api/notification/templates
GET /api/notification/templates/{code}
PUT /api/notification/templates/{code}

---

🤖 Bot API

Telegram Webhook

POST /api/bot/telegram/webhook

Bot 指令處理

POST /api/bot/command
Content-Type: application/json

{
    "command": "/sales",
    "args": ["today"]
}

---

📝 錯誤代碼

代碼	HTTP	說明
AUTH_REQUIRED	401	需要登入
AUTH_FAILED	401	登入失敗
PERMISSION_DENIED	403	權限不足
NOT_FOUND	404	資源不存在
VALIDATION_ERROR	400	參數驗證錯誤
RATE_LIMITED	429	請求過於頻繁
SERVER_ERROR	500	伺服器錯誤