NaraForm

所有端點的 Base URL：https://your-domain.com/api

認證方式請參閱 API 認證。

表單（Forms）

列出所有表單

GET /api/forms
Authorization: Bearer nf_xxx

回應範例

{
  "forms": [
    {
      "id": "clx1234",
      "title": "客戶滿意度調查",
      "slug": "customer-satisfaction",
      "status": "published",
      "responseCount": 42,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-02T00:00:00.000Z"
    }
  ]
}

建立表單

POST /api/forms
Authorization: Bearer nf_xxx
Content-Type: application/json

請求 body

欄位	型別	必填	說明
`title`	string	✓	表單標題（最多 120 字）
`slug`	string		URL slug，只允許小寫英數和 `-`
`templateId`	string		套用範本的 ID

回應範例（201）

{
  "form": {
    "id": "clx5678",
    "title": "新表單",
    "slug": null,
    "status": "draft"
  }
}

取得表單詳情

GET /api/forms/:id
Authorization: Bearer nf_xxx

回傳表單完整資訊，包含 draft schema 和最新 published schema。

更新表單設定

PATCH /api/forms/:id
Authorization: Bearer nf_xxx
Content-Type: application/json

可更新欄位：title、slug、status、startAt、endAt、maxResponses、limitOnePerPerson。

刪除表單

DELETE /api/forms/:id
Authorization: Bearer nf_xxx

發布表單

POST /api/forms/:id/publish
Authorization: Bearer nf_xxx

將 draft 版本設為 published，自動指派 slug（如未設定）。

取消發布

POST /api/forms/:id/unpublish
Authorization: Bearer nf_xxx

回覆（Responses）

列出回覆

GET /api/forms/:id/responses
Authorization: Bearer nf_xxx

Query 參數

參數	說明	預設
`limit`	每頁筆數（最大 50）	20
`page`	頁碼	1
`from`	開始日期（ISO 8601）
`to`	結束日期（ISO 8601）
`search`	搜尋答案內容
`metadata[<hidden_key>]`	依表單 hidden 題目 metadata 篩選

匯出回覆（CSV）

GET /api/forms/:id/responses/export
Authorization: Bearer nf_xxx

回傳 text/csv 格式的回覆資料。支援 from、to、search 與 metadata[<hidden_key>] filters。

參數	說明	預設
`includeMetadata`	設為 `1` 時加入表單 hidden 題目的 `metadata.*` 欄位

分析（Analytics）

分析摘要

GET /api/forms/:id/analytics/summary
Authorization: Bearer nf_xxx

支援 metadata[<hidden_key>]，篩選會在 aggregation 前套用。

回應範例

{
  "formId": "clx1234",
  "totalResponses": 42,
  "todayResponses": 3,
  "weekResponses": 15,
  "completionRate": 0.88,
  "questions": [
    {
      "key": "satisfaction",
      "title": "整體滿意度",
      "type": "rating",
      "responses": 40,
      "summary": {
        "avg": 4.2,
        "count": 40,
        "distribution": { "5": 18, "4": 12, "3": 7, "2": 2, "1": 1 }
      }
    }
  ]
}

趨勢資料

GET /api/forms/:id/analytics/trend
Authorization: Bearer nf_xxx

回傳過去 30 天每日回覆數量趨勢。

API 金鑰管理（Keys）

列出 API 金鑰

GET /api/keys
Authorization: Bearer nf_xxx  (或 session 認證)

建立 API 金鑰

POST /api/keys
Authorization: Bearer nf_xxx  (或 session 認證)
Content-Type: application/json