API 文件

AnonMail REST API 完整端點參考

Base URL: https://vetmail.vercel.app格式: JSON認證: Cookie (jwt)

v1 REST API（外部整合）

以下 /api/v1 端點是提供給外部整合（嵌入式 widget、合作夥伴後台、自動化流程）使用的正式契約，採 Bearer API Key 認證（Authorization: Bearer ak_<40 位 hex>）。 Key 具備 read（GET）與 write（POST/PATCH）兩種 scope。有金鑰的端點回應會帶上 X-RateLimit-Limit / Remaining / Reset 速率限制標頭；超限時回傳 429 並附 Retry-After。

完整 OpenAPI 3.1 規格： /openapi.json （可匯入 Swagger UI、Postman、Insomnia 等工具）。

POST/api/v1/submit— 提交案件（widget 用，無需金鑰）公開scope: 無— 提交案件（widget 用，無需金鑰）

GET/api/v1/cases— 案件列表（分頁、可篩選）Bearer API Keyscope: read— 案件列表（分頁、可篩選）

GET/api/v1/cases/{id}— 案件詳情（不含內部備註）Bearer API Keyscope: read— 案件詳情（不含內部備註）

PATCH/api/v1/cases/{id}— 更新案件狀態 / 指派Bearer API Keyscope: write— 更新案件狀態 / 指派

POST/api/v1/cases/{id}/reply— 回覆案件（一律對外可見）Bearer API Keyscope: write— 回覆案件（一律對外可見）

GET/api/v1/stats— 案件統計數據Bearer API Keyscope: read— 案件統計數據

GET/api/v1/audit-logs— 稽核日誌查詢（分頁、可篩選）Bearer API Keyscope: read— 稽核日誌查詢（分頁、可篩選）

GET/api/v1/form-config— 表單欄位設定（無需金鑰）公開scope: 無— 表單欄位設定（無需金鑰）

⚠️ 兩個 submit 端點不要搞混

POST /api/submit（內部 / 舊版）：必填 agree_policy: true，回應為扁平結構 { tracking_code, message }。
POST /api/v1/submit（widget / 整合）：不需 agree_policy， tracking code 巢狀於 data 之下 { data: { tracking_code, case_id } }。

外部整合請一律使用 /api/v1/submit。下方「公開端點」「認證端點」「案件管理端點」等區段為內部 cookie-session 端點，不屬於 v1 契約，僅供管理後台自身使用。

公開端點（無需認證）

POST/api/submit— 提交匿名陳情（JSON 或 multipart/form-data 夾帶附件）公開

提交匿名陳情（JSON 或 multipart/form-data 夾帶附件）

Request Body

{
  "category": "harassment",   // safety | harassment | discrimination | ethics | labor | management | environment | other
  "priority": "high",         // low | medium | high | urgent
  "title": "主旨文字（1-100 字）",
  "department": "行銷部",      // 選填，0-50 字
  "content": "詳細陳情內容...（1-10000 字）",
  "agree_policy": true        // 必須為 true
}

Response

{
  "success": true,
  "tracking_code": "TRK-A3B7-KN2Q-WE",
  "message": "陳情已成功提交"
}

Status Codes

201 Created — 提交成功
400 Bad Request — 欄位驗證失敗 / 附件驗證失敗
429 Too Many Requests — 已達本月案件上限或頻率限制
500 Internal Server Error

POST/api/track— 以追蹤碼查詢案件進度公開

以追蹤碼查詢案件進度

Request Body

{
  "tracking_code": "TRK-A3B7-KN2Q-WE"
}

Response

{
  "success": true,
  "case": {
    "tracking_code": "TRK-A3B7-KN2Q-WE",
    "category": "harassment",
    "priority": "high",
    "status": "investigating",
    "title": "主旨",
    "content": "陳情內容...",
    "submitted_at": "2026-03-20T08:00:00Z",
    "messages": [
      { "author_type": "hr", "content": "已收到您的陳情...", "created_at": "..." }
    ]
  },
  "retaliation_checkin": null  // 或 { "id": "...", "cohort": "3m", "prompt": "..." }
}

Status Codes

200 OK — 查詢成功
400 Bad Request — 追蹤碼格式不正確
404 Not Found — 追蹤碼不存在
429 Too Many Requests — 查詢過於頻繁

POST/api/reply-anon— 匿名追問（員工端）公開

匿名追問（員工端）

Request Body

{
  "tracking_code": "TRK-A3B7-KN2Q-WE",
  "content": "補充說明...（1-10000 字）"
}

Response

{
  "success": true,
  "message": {
    "content": "補充說明...",
    "author_type": "employee",
    "created_at": "2026-03-21T09:00:00Z"
  }
}

Status Codes

201 Created — 追問成功
400 Bad Request — 驗證失敗 / 案件已結案或凍結
404 Not Found — 追蹤碼不存在
429 Too Many Requests

GET/api/tenant/config— 取得目前租戶的公開設定公開

取得目前租戶的公開設定

Response

{
  "success": true,
  "tenant": {
    "slug": "my-company",
    "company_name": "範例企業",
    "logo_url": null,
    "primary_color": "#2DD4BF"
  }
}

Status Codes

200 OK
500 Internal Server Error

POST/api/onboarding— 自助租戶註冊（需先 GET /api/captcha/challenge 取得驗證題）公開

自助租戶註冊（需先 GET /api/captcha/challenge 取得驗證題）

Request Body

{
  "slug": "my-company",            // 2-50 字，小寫英數與連字號
  "company_name": "新公司名稱",
  "admin_email": "admin@example.com",
  "admin_password": "securePassword123",  // 8-256 字
  "admin_name": "管理員姓名",
  "plan": "free",                  // free | pro | enterprise（選填，預設 free）
  "captcha_token": "<來自 /api/captcha/challenge>",
  "captcha_answer": 12
}

Response

{
  "success": true,
  "requires_payment": false,
  "plan": "free",
  "tenant": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "my-company",
    "company_name": "新公司名稱",
    "subdomain_url": "https://vetmail.vercel.app"
  }
}

Status Codes

201 Created — 註冊成功（Set-Cookie 自動登入）
400 Bad Request — 欄位驗證失敗 / 驗證碼錯誤或過期
409 Conflict — 子網域已被使用
429 Too Many Requests — 註冊過於頻繁

認證端點

POST/api/auth/login— 管理員登入公開

管理員登入

Request Body

{
  "email": "admin@example.com",
  "password": "yourPassword"
}

Response

{
  "success": true,
  "message": "登入成功",
  "user": { "email": "admin@example.com", "full_name": "Admin", "role": "admin" }
}

Status Codes

200 OK — 登入成功（Set-Cookie httpOnly）
400 Bad Request — 欄位驗證失敗
401 Unauthorized — 帳號或密碼錯誤
403 Forbidden — 帳號已停用

GET/api/auth/session— 驗證目前 session 是否有效需登入

驗證目前 session 是否有效

Response

{
  "authenticated": true,
  "user": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@example.com",
    "full_name": "Admin",
    "role": "admin",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Status Codes

200 OK — session 有效
401 Unauthorized — 未登入或 token 過期

POST/api/auth/logout— 登出並清除 session需登入

登出並清除 session

Response

{
  "success": true
}

Status Codes

200 OK — 已登出

案件管理端點（需登入）

GET/api/cases— 取得案件列表（query：status / priority / category / search / page / per_page）需登入

取得案件列表（query：status / priority / category / search / page / per_page）

Response

{
  "success": true,
  "cases": [
    {
      "id": "550e8400-...", "category": "harassment", "priority": "high",
      "status": "submitted", "title": "主旨", "department": null,
      "assigned_to": null, "submitted_at": "2026-03-20T08:00:00Z",
      "ai_risk_score": null, "ai_risk_level": null, "ai_summary": null
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Status Codes

200 OK
401 Unauthorized

GET/api/cases/[id]— 取得單一案件詳情（含訊息與附件）需登入

取得單一案件詳情（含訊息與附件）

Response

{
  "success": true,
  "case": {
    "id": "550e8400-...",
    "category": "harassment", "priority": "high", "status": "investigating",
    "title": "主旨", "content": "內容...", "department": null,
    "assigned_to": null, "submitted_at": "2026-03-20T08:00:00Z",
    "sla_ack_deadline": "2026-03-27T08:00:00Z",
    "sla_resolution_deadline": "2026-06-18T08:00:00Z",
    "ai_risk_score": null, "ai_risk_level": null, "ai_summary": null,
    "case_messages": [ { "id": "...", "author_type": "hr", "content": "...", "is_internal": false, "created_at": "..." } ],
    "case_attachments": [ { "id": "...", "file_name": "...", "file_size": 1024, "mime_type": "image/png", "created_at": "..." } ]
  }
}

Status Codes

200 OK
400 Bad Request — ID 格式錯誤
401 Unauthorized
404 Not Found

PATCH/api/cases/[id]— 更新案件狀態、指派或標籤需登入

更新案件狀態、指派或標籤

Request Body

{
  "status": "investigating",   // submitted | acknowledged | investigating | pending_decision | resolved | escalated | closed
  "assigned_to": "處理人名稱",  // 選填
  "tags": ["騷擾", "重複申訴"]  // 選填，最多 20 個
}

Response

{
  "success": true,
  "case": {
    "id": "...", "status": "investigating", "assigned_to": "處理人名稱",
    "tags": ["騷擾"], "acknowledged_at": "...", "resolved_at": null,
    "closed_at": null, "retention_deletion_at": null
  }
}

Status Codes

200 OK
400 Bad Request — 驗證失敗或不允許的狀態轉換
401 Unauthorized
404 Not Found
423 Locked — 案件處於法律保留（legal hold）

POST/api/cases/[id]/reply— 管理員回覆案件（is_internal 為內部備註）需登入

管理員回覆案件（is_internal 為內部備註）

Request Body

{
  "content": "感謝您的反映，我們已開始調查...",
  "is_internal": false
}

Response

{
  "success": true,
  "message": { "id": "...", "content": "...", "author_type": "hr", "is_internal": false, "created_at": "..." }
}

Status Codes

200 OK
400 Bad Request
401 Unauthorized
404 Not Found
423 Locked — 案件處於法律保留

POST/api/cases/[id]/analyze— AI 分析案件內容（需租戶開啟 AI 分析並簽署同意書）需登入

AI 分析案件內容（需租戶開啟 AI 分析並簽署同意書）

Response

{
  "success": true,
  "analysis": {
    "ai_category_suggestion": "harassment",
    "ai_risk_score": 78,
    "ai_risk_level": "high",
    "ai_summary": "案件摘要...",
    "ai_tags": ["騷擾", "主管"],
    "ai_analyzed_at": "2026-03-20T10:00:00Z"
  }
}

Status Codes

200 OK
401 Unauthorized
403 Forbidden
404 Not Found
503 Service Unavailable — AI 分析未啟用

PATCH/api/cases/batch— 批次更新案件狀態（最多 50 件）需登入

批次更新案件狀態（最多 50 件）

Request Body

{
  "case_ids": ["550e8400-...", "550e8401-..."],
  "status": "acknowledged"
}

Response

{
  "success": true,
  "updated": 2,
  "errors": []   // 失敗項目：[{ "id": "...", "error": "原因" }]
}

Status Codes

200 OK
400 Bad Request
401 Unauthorized

GET/api/cases/report— 取得報告資料（query：type=single&case_id=… 或 type=monthly&month=YYYY-MM）需登入

取得報告資料（query：type=single&case_id=… 或 type=monthly&month=YYYY-MM）

Response

{
  "success": true,
  "report": {
    "type": "monthly",
    "month": "2026-03",
    "generated_at": "2026-03-31T12:00:00Z",
    "stats": {
      "total": 12,
      "by_status": { "submitted": 2, "investigating": 4 },
      "by_category": { "harassment": 5, "discrimination": 3 },
      "by_priority": { "high": 4, "medium": 6 },
      "avg_response_hours": 18.5,
      "risk_distribution": {}
    },
    "cases": [ { "id": "...", "title": "..." } ]
  }
}

Status Codes

200 OK
400 Bad Request — type / case_id / month 參數錯誤
401 Unauthorized
404 Not Found

儀表板與稽核（需登入）

GET/api/dashboard/stats— 總覽統計數據需登入

總覽統計數據

Response

{
  "success": true,
  "stats": {
    "total": 42,
    "by_status": { "submitted": 5, "investigating": 8 },
    "by_category": { "harassment": 12 },
    "by_priority": { "high": 9 },
    "trend": [ { "date": "2026-03-01", "count": 3 } ],
    "avg_response_hours": 16.2,
    "avg_resolution_hours": 96.8
  }
}

Status Codes

200 OK
401 Unauthorized

GET/api/dashboard/analytics— 進階分析資料（趨勢圖表）需登入

進階分析資料（趨勢圖表）

Response

{
  "success": true,
  "analytics": {
    "priorityDistribution": { "low": 3, "medium": 12, "high": 8, "urgent": 2 },
    "departmentBreakdown": [ { "department": "行銷部", "count": 6 } ],
    "weeklyTrend": [ { "week": "2026-W12", "count": 5, "resolved": 3 } ],
    "avgResolutionDays": 4.2,
    "responseRate": 0.92,
    "topCategories": [ { "category": "harassment", "count": 12, "percentage": 35 } ]
  }
}

Status Codes

200 OK
401 Unauthorized

GET/api/audit— 取得稽核日誌（query：page / per_page / action / actor / from / to）需登入

取得稽核日誌（query：page / per_page / action / actor / from / to）

Response

{
  "success": true,
  "logs": [
    {
      "id": "...",
      "action": "status_change",
      "actor": "admin@example.com",
      "target": "CASE-550E8400",
      "details": { "from": "submitted", "to": "acknowledged" },
      "ip_address": null,
      "created_at": "2026-03-20T10:00:00Z"
    }
  ],
  "total": 128,
  "page": 1,
  "per_page": 50
}

Status Codes

200 OK
401 Unauthorized

通知設定（需登入）

GET/api/notifications/preferences— 取得通知偏好設定需登入

取得通知偏好設定

Response

{
  "success": true,
  "preferences": {
    "notification_email": "hr@example.com",
    "contact_email": null,
    "line_notify_token": null
  }
}

Status Codes

200 OK
401 Unauthorized

PATCH/api/notifications/preferences— 更新通知偏好設定（需 admin 角色）需登入

更新通知偏好設定（需 admin 角色）

Request Body

{
  "notification_email": "hr@example.com"   // 或 null 表示停用
}

Response

{
  "success": true
}

Status Codes

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden — 非 admin 角色

租戶與帳單（需登入）

PATCH/api/tenant/config— 更新租戶設定（需 admin 角色）需登入

更新租戶設定（需 admin 角色）

Request Body

{
  "company_name": "新名稱",            // 選填，1-100 字
  "primary_color": "#2DD4BF",         // 選填，#RRGGBB
  "notification_email": "hr@example.com",  // 選填，可為 null
  "contact_email": null,              // 選填
  "line_notify_token": null           // 選填
}

Response

{
  "success": true,
  "tenant": {
    "slug": "my-company", "company_name": "新名稱", "primary_color": "#2DD4BF",
    "notification_email": "hr@example.com", "contact_email": null,
    "line_notify_token": null, "plan": "free"
  }
}

Status Codes

200 OK
400 Bad Request — 驗證失敗或未提供任何欄位
401 Unauthorized
403 Forbidden — 非 admin 角色

GET/api/billing/status— 取得目前帳單與方案狀態需登入

取得目前帳單與方案狀態

Response

{
  "success": true,
  "billing": {
    "plan": "pro",
    "plan_name": "Pro",
    "max_admins": 5,
    "max_cases_per_month": 500,
    "has_subscription": true,
    "usage": { "month": "2026-03", "cases_count": 18, "admins_count": 2 }
  }
}

Status Codes

200 OK
401 Unauthorized
404 Not Found — 找不到租戶

POST/api/billing/checkout— 建立 Stripe Checkout Session（需 admin 角色）需登入

建立 Stripe Checkout Session（需 admin 角色）

Request Body

{
  "plan": "pro"   // pro | enterprise
}

Response

{
  "success": true,
  "checkout_url": "https://checkout.stripe.com/..."
}

Status Codes

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden — 非 admin 角色
503 Service Unavailable — 帳單系統尚未設定

POST/api/billing/portal— 建立 Stripe 客戶管理入口（需 admin 角色）需登入

建立 Stripe 客戶管理入口（需 admin 角色）

Response

{
  "success": true,
  "portal_url": "https://billing.stripe.com/..."
}

Status Codes

200 OK
401 Unauthorized
403 Forbidden — 非 admin 角色
404 Not Found — 尚無 Stripe 客戶
503 Service Unavailable — 帳單系統尚未設定

管理員管理（需 admin 角色）

GET/api/admin/admins— 取得管理員列表需登入

取得管理員列表

Response

{
  "success": true,
  "admins": [
    {
      "id": "550e8400-...", "email": "admin@example.com", "full_name": "Admin",
      "role": "admin", "is_active": true, "last_login_at": "...", "created_at": "..."
    }
  ]
}

Status Codes

200 OK
401 Unauthorized
403 Forbidden — 非 admin 角色

GET/api/admin/export— 匯出租戶完整資料（JSON 檔案下載）需登入

匯出租戶完整資料（JSON 檔案下載）

Response

{
  "exported_at": "2026-03-20T12:00:00Z",
  "tenant_id": "550e8400-...",
  "cases": [ { "id": "...", "category": "...", "status": "...", "legal_hold": false } ],
  "messages": [ { "id": "...", "case_id": "...", "author_type": "hr" } ],
  "audit_logs": [ { "id": "...", "action": "..." } ],
  "admins": [ { "id": "...", "email": "..." } ]
}

Status Codes

200 OK — Content-Disposition: attachment
401 Unauthorized
403 Forbidden — 非 admin 角色

返回首頁

載入中...