SYM APP 系統介接 API 規劃書

v1.0｜2026 年 11 月 13 日｜Rytass｜REST／JSON｜共 23 支 API

本文件定義由 SYM 系統實作、供 SYM APP 後端（以下稱 App 後端）呼叫的 API。

Base URLhttps://{SYM 主機}/v1測試與正式環境主機待 SYM 提供

資料範圍

以下資料以 SYM 系統為主檔。

SYM APPiOS／Android

HTTPS

App 後端Google Cloud 台灣區域

HA VPN
REST／JSON

SYM 系統本文件 API

SYM 主檔資料	App 後端使用方式	API
簡訊發送通道	App 後端產生 OTP 後經 SYM 發送簡訊	S-01
會員基本資料（以手機號碼識別）	查詢、建立、修改、刪除	S-02～S-06
點數交易、餘額與效期	App 後端依規則加減點；SYM 計算餘額與到期	S-07～S-09
車輛銷售資料與車主	綁車時驗證車主；後台查詢	S-10～S-12
車型主檔、配備、保養規則	增量同步	S-13～S-15
經銷商據點	增量同步	S-16、S-17
保養與維修記錄	增量同步；依車輛查詢	S-18、S-19
客服意見反應	建立案件；查詢處理狀態	S-20～S-22
App 端使用紀錄	App 後端批次回傳，SYM 接收	S-23

OTP 產生與驗證、第三方登入、經驗值、會員等級、點數取得規則、活動、任務、兌換券由 App 後端負責。

API 索引

編號	方法	路徑	用途
會員帳戶9 支
S-01	POST	`/sms`	發送簡訊
S-02	GET	`/members`	會員列表
S-03	GET	`/members/{memberId}`	取得會員
S-04	POST	`/members`	建立會員
S-05	PATCH	`/members/{memberId}`	修改會員
S-06	DELETE	`/members/{memberId}`	刪除會員
S-07	GET	`/points/transactions`	點數交易列表
S-08	GET	`/members/{memberId}/points`	取得會員點數
S-09	POST	`/points/transactions`	建立點數交易
車輛與服務10 支
S-10	GET	`/vehicles`	車輛列表
S-11	GET	`/vehicles/{vehicleId}`	取得車輛
S-12	POST	`/verifications`	車主驗證
S-13	GET	`/models`	車型列表
S-14	GET	`/models/{modelId}`	取得車型
S-15	GET	`/models/{modelId}/maintenance`	車型保養規則列表
S-16	GET	`/dealers`	據點列表
S-17	GET	`/dealers/{dealerId}`	取得據點
S-18	GET	`/services`	保養記錄列表
S-19	GET	`/services/{recordId}`	取得保養記錄
客服與資料回傳4 支
S-20	GET	`/feedbacks`	意見反應列表
S-21	GET	`/feedbacks/{feedbackId}`	取得意見反應
S-22	POST	`/feedbacks`	建立意見反應
S-23	POST	`/datasets/{dataset}/records`	批次寫入資料

共通規範

連線與認證	HA VPN、HTTPS、API 金鑰，見認證。測試與正式環境各一組。
格式	JSON、UTF-8；欄位名稱 camelCase；接收端須忽略未定義的欄位。
時間	ISO 8601 含時區，例 `2027-01-15T09:30:00+08:00`；日期 `2027-01-15`。
ID	所有物件（含巢狀物件）帶 `id`，字串。SYM 產生的物件由 SYM 定義格式；App 傳入的物件（來源、附件、操作人員、回傳記錄）為 App 後端 ID。建立時請求不帶 SYM 物件的 `id`；修改既有巢狀物件時帶 `id`。列表外層與錯誤外層除外。
手機號碼	E.164，例 `+886912345678`。
數值	點數、里程以整數表示；里程單位公里。
重複請求	建立會員以手機號碼、點數交易以 `transactionId`、意見反應以 `externalId`、資料回傳以記錄 `id` 去除重複。發送簡訊不去除重複。
追蹤	每個請求帶 `X-Request-Id`（UUID），雙方記錄於日誌，供查詢與對帳。
列表	查詢參數 `page`（從 1 開始）、`pageSize`（預設 20，上限 500）、`sort`（前置 `-` 為遞減）與各 API 的篩選欄位；多個篩選條件為 AND。回應為 `{ items, total, page, pageSize }`。
增量同步	列表帶 `updatedSince` 與 `sort=updatedAt`；已刪除或停用的資料仍須回傳並標記 `deleted: true`。
效能	單筆查詢與寫入在 1 秒內回應；App 後端逾時設定 10 秒，遇逾時或 5xx 以指數退避重試，最多 5 次（發送簡訊除外）。
版本	路徑帶主版本 `/v1`。新增欄位不升版；移除或變更欄位意義時升版，舊版並行至少 3 個月。

請求範例

HTTPPOST https://{SYM 主機}/v1/members HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: 6f1c2a9e-4d1b-4f3e-9a51-0c2e8b7d1f40
Content-Type: application/json; charset=utf-8

認證

層級	做法
網路	HA VPN，SYM 端只允許 App 後端的固定出口 IP。
傳輸	HTTPS，TLS 1.2 以上。
請求	每個請求帶 `Authorization: Bearer {API 金鑰}`，金鑰由 SYM 發行。請求不帶會員憑證，會員身分由 App 後端驗證。

驗證失敗

HTTP	error.code	說明
401	`AUTH_MISSING_KEY`	缺少 `Authorization` 標頭
401	`AUTH_INVALID_KEY`	金鑰不存在或已停用
403	`AUTH_IP_NOT_ALLOWED`	來源 IP 不在此金鑰的允許清單

錯誤處理

所有 4xx、5xx 回應使用同一格式（Schema：Error）。

JSON{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "點數餘額不足",
    "details": {
      "balance": 120
    }
  }
}

HTTP 狀態	用途	App 後端處理
400	欄位缺漏或格式錯誤	不重試
401／403	認證失敗，見認證錯誤代碼	不重試，通報
404	資料不存在	不重試
409	資料衝突（手機號碼已存在等）	依 `error.code` 處理
422	業務規則不允許（點數餘額不足等）	依 `error.code` 處理
429	超過流量限制，回應帶 `Retry-After`	依秒數後重試
5xx	系統錯誤或暫停服務	退避重試

API 規格

會員帳戶

S-01～S-09｜9 支

簡訊發送、會員、點數。

簡訊發送

OTP 由 App 後端產生與驗證，經此 API 由 SYM 簡訊通道發送。SYM 系統不保存、不驗證驗證碼。

POST/sms發送簡訊S-01

內容原樣發送，10 秒內送達。

請求

HTTPPOST https://{SYM 主機}/v1/sms HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

Request body application/json

欄位	型別	說明
`phone` *	string	E.164
`content` *	string	簡訊內容

JSON{
  "phone": "+886912345678",
  "content": "【SYM APP】您的驗證碼為 382915，5 分鐘內有效。請勿將驗證碼提供給他人。"
}

回應

202

已受理，排入發送

422

SMS_PHONE_INVALID 號碼格式不支援或無法發送

422

SMS_CONTENT_TOO_LONG 超過內容上限

429

SMS_RATE_LIMITED 超過 SYM 端流量上限

會員

會員以手機號碼識別，第三方登入帳號一律綁定手機號碼。手機號碼已存在於 SYM 系統時沿用該會員。

GET/members會員列表S-02

註冊與登入時以 phone 查詢，查無會員時 items 為空陣列。

請求

HTTPGET https://{SYM 主機}/v1/members HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`phone` query	string	E.164，完全相符
`keyword` query	string	姓名、會員編號、手機號碼部分相符
`status` query	string	`ACTIVE`正常`SUSPENDED`停權`DELETED`已刪除
`createdFrom` query	datetime
`createdTo` query	datetime
`updatedSince` query	datetime	只回傳此時間之後異動的資料，含 `deleted: true` 者
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`createdAt`、`updatedAt`、`memberNo`

回應

200

Schema：Member[]

JSON{
  "items": [
    {
      "id": "100245",
      "memberNo": "M00012345",
      "phone": "+886912345678",
      "name": "王小明",
      "gender": "M",
      "birthday": "1990-05-01",
      "email": "user@example.com",
      "address": {
        "id": "810033",
        "zipCode": "300",
        "city": "新竹市",
        "district": "東區",
        "line": "光復路一段 1 號"
      },
      "status": "ACTIVE",
      "consents": [
        {
          "id": "820101",
          "type": "TERMS",
          "version": "2027-01",
          "agreed": true,
          "at": "2027-03-19T10:00:00+08:00"
        },
        {
          "id": "820103",
          "type": "MARKETING",
          "version": "2027-01",
          "agreed": false,
          "at": "2027-03-19T10:00:00+08:00"
        }
      ],
      "createdAt": "2027-03-19T10:00:01+08:00",
      "updatedAt": "2027-04-02T00:10:00+08:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/members/{memberId}取得會員S-03

請求

HTTPGET https://{SYM 主機}/v1/members/{memberId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`memberId` * path	string

回應

200

Schema：Member

JSON{
  "id": "100245",
  "memberNo": "M00012345",
  "phone": "+886912345678",
  "name": "王小明",
  "gender": "M",
  "birthday": "1990-05-01",
  "email": "user@example.com",
  "address": {
    "id": "810033",
    "zipCode": "300",
    "city": "新竹市",
    "district": "東區",
    "line": "光復路一段 1 號"
  },
  "status": "ACTIVE",
  "consents": [
    {
      "id": "820101",
      "type": "TERMS",
      "version": "2027-01",
      "agreed": true,
      "at": "2027-03-19T10:00:00+08:00"
    },
    {
      "id": "820103",
      "type": "MARKETING",
      "version": "2027-01",
      "agreed": false,
      "at": "2027-03-19T10:00:00+08:00"
    }
  ],
  "createdAt": "2027-03-19T10:00:01+08:00",
  "updatedAt": "2027-04-02T00:10:00+08:00"
}

404

MEMBER_NOT_FOUND

POST/members建立會員S-04

請求

HTTPPOST https://{SYM 主機}/v1/members HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

Request body application/json

欄位	型別	說明
`phone` *	string	已由 App 後端完成 OTP 驗證
`name` *	string
`gender`	string
`birthday`	date
`email`	string
`address`	Address
`consents` *	Consent[]	至少含 `TERMS`、`PRIVACY`

JSON{
  "phone": "+886912345678",
  "name": "王小明",
  "gender": "M",
  "birthday": "1990-05-01",
  "email": "user@example.com",
  "consents": [
    {
      "type": "TERMS",
      "version": "2027-01",
      "agreed": true,
      "at": "2027-03-19T10:00:00+08:00"
    },
    {
      "type": "PRIVACY",
      "version": "2027-01",
      "agreed": true,
      "at": "2027-03-19T10:00:00+08:00"
    },
    {
      "type": "MARKETING",
      "version": "2027-01",
      "agreed": false,
      "at": "2027-03-19T10:00:00+08:00"
    }
  ]
}

回應

201

建立成功

Schema：Member

JSON{
  "id": "100245",
  "memberNo": "M00012345",
  "phone": "+886912345678",
  "name": "王小明",
  "gender": "M",
  "birthday": "1990-05-01",
  "email": "user@example.com",
  "address": {
    "id": "810033",
    "zipCode": "300",
    "city": "新竹市",
    "district": "東區",
    "line": "光復路一段 1 號"
  },
  "status": "ACTIVE",
  "consents": [
    {
      "id": "820101",
      "type": "TERMS",
      "version": "2027-01",
      "agreed": true,
      "at": "2027-03-19T10:00:00+08:00"
    },
    {
      "id": "820103",
      "type": "MARKETING",
      "version": "2027-01",
      "agreed": false,
      "at": "2027-03-19T10:00:00+08:00"
    }
  ],
  "createdAt": "2027-03-19T10:00:01+08:00",
  "updatedAt": "2027-04-02T00:10:00+08:00"
}

409

PHONE_IN_USE 手機號碼已屬其他會員，details.memberId 帶既有會員 ID

PATCH/members/{memberId}修改會員S-05

只送有變更的欄位。

請求

HTTPPATCH https://{SYM 主機}/v1/members/{memberId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

參數

名稱	型別	說明
`memberId` * path	string

Request body application/json

欄位	型別	說明
`phone`	string	新手機號碼
`name`	string
`gender`	string
`birthday`	date
`email`	string
`address`	Address
`consents`	Consent[]	新增的同意紀錄

JSON{
  "email": "new@example.com",
  "address": {
    "id": "810033",
    "zipCode": "300",
    "city": "新竹市",
    "district": "東區",
    "line": "光復路一段 100 號"
  }
}

回應

200

修改後的會員

Schema：Member

409

PHONE_IN_USE 新號碼已屬其他會員

404

MEMBER_NOT_FOUND

DELETE/members/{memberId}刪除會員S-06

個人資料依 SYM 個資政策保存。刪除後同一手機號碼可重新註冊為新會員。

請求

HTTPDELETE https://{SYM 主機}/v1/members/{memberId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`memberId` * path	string

回應

204

已刪除

202

已受理，非同步處理；完成後以事件通知 MEMBER_DELETED 告知 App 後端

404

MEMBER_NOT_FOUND

點數

點數交易與餘額以 SYM 系統為主檔。SYM 計算餘額、點數效期與到期失效；餘額不可直接修改，更正以反向交易處理。

GET/points/transactions點數交易列表S-07

到期失效由 SYM 系統產生 reasonCode: EXPIRED 的交易。

請求

HTTPGET https://{SYM 主機}/v1/points/transactions HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`memberId` query	string
`transactionId` query	string	App 後端交易 ID
`reasonCode` query	string	`RIDE_DISTANCE`騎乘里程`ACTIVITY_CHECK_IN`活動簽到`TASK_COMPLETED`完成任務`ACHIEVEMENT_UNLOCKED`解鎖成就`VOUCHER_REDEEM`兌換`PARTNER_GRANT`合作方發放`MANUAL_ADJUST`人工調整`REVERSAL`更正`EXPIRED`到期失效
`from` query	datetime	起始時間
`to` query	datetime	結束時間
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`occurredAt`、`createdAt`，預設 `-occurredAt`

回應

200

Schema：PointTransaction[]

JSON{
  "items": [
    {
      "id": "PT202704150001",
      "transactionId": "pt_20270415_7f3a91c2",
      "memberId": "100245",
      "amount": 200,
      "balanceAfter": 1450,
      "reasonCode": "ACTIVITY_CHECK_IN",
      "description": "2027 春季騎乘活動簽到",
      "occurredAt": "2027-04-15T10:12:00+08:00",
      "expiresAt": "2028-04-30T23:59:59+08:00",
      "reversalOf": null,
      "createdAt": "2027-04-15T10:12:01+08:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/members/{memberId}/points取得會員點數S-08

請求

HTTPGET https://{SYM 主機}/v1/members/{memberId}/points HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`memberId` * path	string

回應

200

Schema：PointBalance

JSON{
  "id": "100245",
  "balance": 1450,
  "expiringPoints": [
    {
      "id": "PB20270630001",
      "amount": 300,
      "expiresAt": "2027-06-30T23:59:59+08:00"
    }
  ]
}

404

MEMBER_NOT_FOUND

POST/points/transactions建立點數交易S-09

以 transactionId 去除重複。扣點時優先扣除最早到期的點數。

請求

HTTPPOST https://{SYM 主機}/v1/points/transactions HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

Request body application/json

欄位	型別	說明
`transactionId` *	string	App 後端交易 ID，唯一
`memberId` *	string
`amount` *	integer	正數增加，負數扣除，不可為 0
`reasonCode` *	string	`RIDE_DISTANCE`騎乘里程`ACTIVITY_CHECK_IN`活動簽到`TASK_COMPLETED`完成任務`ACHIEVEMENT_UNLOCKED`解鎖成就`VOUCHER_REDEEM`兌換`PARTNER_GRANT`合作方發放`MANUAL_ADJUST`人工調整`REVERSAL`更正`EXPIRED`到期失效
`description`	string	顯示於會員明細
`occurredAt` *	datetime	行為發生時間
`reversalOf`	string	`REVERSAL` 時必填，原交易 ID

JSON{
  "transactionId": "pt_20270415_7f3a91c2",
  "memberId": "100245",
  "amount": 200,
  "reasonCode": "ACTIVITY_CHECK_IN",
  "description": "2027 春季騎乘活動簽到",
  "occurredAt": "2027-04-15T10:12:00+08:00"
}

回應

201

已入帳

Schema：PointTransaction

JSON{
  "id": "PT202704150001",
  "transactionId": "pt_20270415_7f3a91c2",
  "memberId": "100245",
  "amount": 200,
  "balanceAfter": 1450,
  "reasonCode": "ACTIVITY_CHECK_IN",
  "description": "2027 春季騎乘活動簽到",
  "occurredAt": "2027-04-15T10:12:00+08:00",
  "expiresAt": "2028-04-30T23:59:59+08:00",
  "reversalOf": null,
  "createdAt": "2027-04-15T10:12:01+08:00"
}

200

transactionId 重複，回傳原交易

Schema：PointTransaction

422

INSUFFICIENT_BALANCE 扣除超過餘額，details.balance 帶目前餘額

409

ALREADY_REVERSED reversalOf 指定的交易已被更正

404

MEMBER_NOT_FOUND

車輛與服務

S-10～S-19｜10 支

車輛、車型與保養規則、經銷商據點、保養與維修記錄。

車輛

SYM 銷售資料中的車輛。

GET/vehicles車輛列表S-10

請求

HTTPGET https://{SYM 主機}/v1/vehicles HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`vin` query	string	完全相符
`plateNo` query	string	完全相符
`modelId` query	string
`dealerId` query	string	銷售據點
`salesFrom` query	date
`salesTo` query	date
`updatedSince` query	datetime	只回傳此時間之後異動的資料，含 `deleted: true` 者
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`salesDate`、`updatedAt`

回應

200

Schema：Vehicle[]

JSON{
  "items": [
    {
      "id": "200871",
      "vin": "RFGBS1EF0RX000001",
      "plateNo": "ABC-1234",
      "modelId": "4012",
      "modelYear": 2027,
      "color": "消光黑",
      "salesDate": "2027-03-02",
      "dealerId": "301"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/vehicles/{vehicleId}取得車輛S-11

請求

HTTPGET https://{SYM 主機}/v1/vehicles/{vehicleId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`vehicleId` * path	string

回應

200

Schema：Vehicle

JSON{
  "id": "200871",
  "vin": "RFGBS1EF0RX000001",
  "plateNo": "ABC-1234",
  "modelId": "4012",
  "modelYear": 2027,
  "color": "消光黑",
  "salesDate": "2027-03-02",
  "dealerId": "301"
}

404

VEHICLE_NOT_FOUND

POST/verifications車主驗證S-12

兩種方式擇一：
PLATE_VIN：車牌與車身號碼屬同一車輛。
PLATE_CONTACT：車牌對應車輛的車主聯絡電話與輸入的電話相符。
只有 MATCHED 時回傳 vehicle。

請求

HTTPPOST https://{SYM 主機}/v1/verifications HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

Request body application/json

欄位	型別	說明
`method` *	string	`PLATE_VIN`車牌＋車身號碼`PLATE_CONTACT`車牌＋車主聯絡電話
`plateNo` *	string
`vin`	string	`PLATE_VIN` 時必填
`phone`	string	車主聯絡電話，`PLATE_CONTACT` 時必填
`memberId` *	string	發起驗證的會員

JSON{
  "method": "PLATE_VIN",
  "plateNo": "ABC-1234",
  "vin": "RFGBS1EF0RX000001",
  "memberId": "100245"
}

回應

200

Schema：VehicleVerification

JSON{
  "id": "VV202704150088",
  "result": "MATCHED",
  "vehicle": {
    "id": "200871",
    "vin": "RFGBS1EF0RX000001",
    "plateNo": "ABC-1234",
    "modelId": "4012",
    "modelYear": 2027,
    "color": "消光黑",
    "salesDate": "2027-03-02",
    "dealerId": "301"
  }
}

429

TOO_MANY_ATTEMPTS 同一會員每小時驗證失敗超過 10 次

車型與保養規則

車型、配備或保養規則異動時以事件通知 VEHICLE_MODEL_UPDATED 告知 App 後端。

GET/models車型列表S-13

請求

HTTPGET https://{SYM 主機}/v1/models HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`keyword` query	string	車型代碼、名稱部分相符
`series` query	string
`powertrain` query	string	`ICE`燃油`EV`電動
`updatedSince` query	datetime	只回傳此時間之後異動的資料，含 `deleted: true` 者
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`modelCode`、`modelYear`、`updatedAt`

回應

200

Schema：VehicleModel[]

JSON{
  "items": [
    {
      "id": "4012",
      "modelCode": "JET-SL-158",
      "name": "JET SL+ 158",
      "series": "JET",
      "modelYear": 2027,
      "displacementCc": 158,
      "powertrain": "ICE",
      "equipment": [
        {
          "id": "31",
          "code": "ABS",
          "name": "ABS 防鎖死煞車"
        },
        {
          "id": "35",
          "code": "TBOX",
          "name": "車聯網模組"
        }
      ],
      "updatedAt": "2027-01-10T08:00:00+08:00",
      "deleted": false
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/models/{modelId}取得車型S-14

請求

HTTPGET https://{SYM 主機}/v1/models/{modelId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`modelId` * path	string

回應

200

Schema：VehicleModel

404

MODEL_NOT_FOUND

GET/models/{modelId}/maintenance車型保養規則列表S-15

請求

HTTPGET https://{SYM 主機}/v1/models/{modelId}/maintenance HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`modelId` * path	string

回應

200

Schema：MaintenanceRule[]

JSON{
  "items": [
    {
      "id": "9001",
      "itemCode": "ENGINE_OIL",
      "name": "機油",
      "firstKm": 300,
      "firstMonths": 1,
      "intervalKm": 1000,
      "intervalMonths": 3
    },
    {
      "id": "9002",
      "itemCode": "GEAR_OIL",
      "name": "齒輪油",
      "firstKm": null,
      "firstMonths": null,
      "intervalKm": 3000,
      "intervalMonths": 6
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}

404

MODEL_NOT_FOUND

經銷商據點

據點異動時以事件通知 DEALER_UPDATED 告知 App 後端。

GET/dealers據點列表S-16

請求

HTTPGET https://{SYM 主機}/v1/dealers HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`keyword` query	string	據點代碼、名稱、地址部分相符
`city` query	string
`service` query	string	`SALES`銷售`MAINTENANCE`保養維修`PARTS`零件`EV_SERVICE`電動車服務
`updatedSince` query	datetime	只回傳此時間之後異動的資料，含 `deleted: true` 者
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`dealerCode`、`updatedAt`

回應

200

Schema：Dealer[]

JSON{
  "items": [
    {
      "id": "301",
      "dealerCode": "D0123",
      "name": "三陽機車 新竹光復店",
      "phone": "+88635551234",
      "address": {
        "id": "830301",
        "zipCode": "300",
        "city": "新竹市",
        "district": "東區",
        "line": "光復路一段 100 號"
      },
      "latitude": 24.7889,
      "longitude": 121.0123,
      "openingHours": [
        {
          "id": "6001",
          "weekday": 1,
          "open": "09:00",
          "close": "21:00"
        }
      ],
      "services": [
        "SALES",
        "MAINTENANCE",
        "PARTS"
      ],
      "roadsideAssistance": true,
      "status": "OPEN",
      "updatedAt": "2027-01-10T08:00:00+08:00",
      "deleted": false
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/dealers/{dealerId}取得據點S-17

請求

HTTPGET https://{SYM 主機}/v1/dealers/{dealerId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`dealerId` * path	string

回應

200

Schema：Dealer

404

DEALER_NOT_FOUND

保養與維修記錄

保養或維修完成時以事件通知 SERVICE_RECORD_CREATED 告知 App 後端。itemCode 使用保養規則的項目代碼。

GET/services保養記錄列表S-18

請求

HTTPGET https://{SYM 主機}/v1/services HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`vehicleId` query	string
`dealerId` query	string
`serviceType` query	string	`PERIODIC`定期保養`REPAIR`維修`WARRANTY`保固`RECALL`召回
`from` query	date	保養日期起
`to` query	date	保養日期迄
`updatedSince` query	datetime	只回傳此時間之後異動的資料，含 `deleted: true` 者
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`serviceDate`、`updatedAt`，預設 `-serviceDate`

回應

200

Schema：ServiceRecord[]

JSON{
  "items": [
    {
      "id": "500913",
      "recordNo": "SR20270420000123",
      "vehicleId": "200871",
      "dealerId": "301",
      "serviceType": "PERIODIC",
      "serviceDate": "2027-04-20",
      "mileageKm": 1012,
      "items": [
        {
          "id": "510027",
          "itemCode": "ENGINE_OIL",
          "name": "機油更換",
          "partNo": "OIL-10W40-1L",
          "quantity": 1
        }
      ],
      "completedAt": "2027-04-20T15:40:00+08:00",
      "updatedAt": "2027-04-20T15:41:00+08:00",
      "deleted": false
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/services/{recordId}取得保養記錄S-19

請求

HTTPGET https://{SYM 主機}/v1/services/{recordId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`recordId` * path	string

回應

200

Schema：ServiceRecord

404

RECORD_NOT_FOUND

客服與資料回傳

S-20～S-23｜4 支

客服意見反應、App 端資料回傳。

客服意見反應

寫入 SYM 客服系統。

GET/feedbacks意見反應列表S-20

請求

HTTPGET https://{SYM 主機}/v1/feedbacks HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`memberId` query	string
`status` query	string	`OPEN`已受理`PROCESSING`處理中`CLOSED`已結案
`category` query	string
`from` query	datetime	起始時間
`to` query	datetime	結束時間
`page` query	integer	頁碼，從 1 開始，預設 1
`pageSize` query	integer	每頁筆數，預設 20，上限 500
`sort` query	string	排序欄位，前置 `-` 為遞減。可用：`createdAt`、`updatedAt`，預設 `-createdAt`

回應

200

Schema：Feedback[]

JSON{
  "items": [
    {
      "id": "700056",
      "caseNo": "CS2027042000056",
      "externalId": "fb_20270420_0031",
      "memberId": "100245",
      "category": "PRODUCT",
      "subject": "儀表亮起機油燈",
      "content": "行駛約 20 分鐘後亮起…",
      "vehicleId": "200871",
      "dealerId": null,
      "status": "PROCESSING",
      "closedAt": null,
      "createdAt": "2027-04-20T10:00:02+08:00",
      "updatedAt": "2027-04-21T09:30:00+08:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

GET/feedbacks/{feedbackId}取得意見反應S-21

請求

HTTPGET https://{SYM 主機}/v1/feedbacks/{feedbackId} HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}

參數

名稱	型別	說明
`feedbackId` * path	string

回應

200

Schema：Feedback

404

FEEDBACK_NOT_FOUND

POST/feedbacks建立意見反應S-22

附件以下載連結提供，連結有效 7 天。

請求

HTTPPOST https://{SYM 主機}/v1/feedbacks HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

Request body application/json

欄位	型別	說明
`externalId` *	string	App 後端意見編號，唯一
`memberId` *	string
`category` *	string	SYM 客服系統分類代碼
`subject` *	string
`content` *	string
`vehicleId`	string	相關車輛
`dealerId`	string	相關據點
`attachments`	Attachment[]

JSON{
  "externalId": "fb_20270420_0031",
  "memberId": "100245",
  "category": "PRODUCT",
  "subject": "儀表亮起機油燈",
  "content": "行駛約 20 分鐘後亮起…",
  "vehicleId": "200871",
  "dealerId": null,
  "attachments": [
    {
      "id": "file_3c91a0",
      "fileName": "photo1.jpg",
      "contentType": "image/jpeg",
      "url": "https://files.example.com/fb/photo1.jpg",
      "expiresAt": "2027-04-27T10:00:00+08:00"
    }
  ]
}

回應

201

已建立

Schema：Feedback

JSON{
  "id": "700056",
  "caseNo": "CS2027042000056",
  "externalId": "fb_20270420_0031",
  "memberId": "100245",
  "category": "PRODUCT",
  "subject": "儀表亮起機油燈",
  "content": "行駛約 20 分鐘後亮起…",
  "vehicleId": "200871",
  "dealerId": null,
  "status": "PROCESSING",
  "closedAt": null,
  "createdAt": "2027-04-20T10:00:02+08:00",
  "updatedAt": "2027-04-21T09:30:00+08:00"
}

200

externalId 重複，回傳既有案件

Schema：Feedback

母廠資料回傳

App 後端每小時批次送出 App 端產生的資料。

POST/datasets/{dataset}/records批次寫入資料S-23

每批最多 500 筆，以記錄 id 去除重複。部分筆數失敗仍回 200，rejected 列出失敗記錄。

dataset	內容	階段
`vehicle-bindings`	會員與車輛的綁定、解除、共享	一
`manual-records`	加油、洗車、保養等手動記錄與里程（含非三陽體系保養）	一
`ride-summaries`	騎乘行程摘要：起訖時間、距離、平均速度（不含完整軌跡）	一
`behavior-events`	功能使用、活動參與、兌換等行為事件	一
`vehicle-telemetry`	車機回報之里程與騎乘統計	二
`dtc-events`	車機回報之故障碼	二

請求

HTTPPOST https://{SYM 主機}/v1/datasets/{dataset}/records HTTP/1.1
Authorization: Bearer {API 金鑰}
X-Request-Id: {UUID}
Content-Type: application/json

參數

名稱	型別	說明
`dataset` * path	string	見上表

Request body application/json

欄位	型別	說明
`records` *	DatasetRecord[]

JSON{
  "records": [
    {
      "id": "mr_8f2c41",
      "memberId": "100245",
      "vehicleId": "200871",
      "type": "FUEL",
      "date": "2027-04-19",
      "mileageKm": 1210,
      "liters": 4.2,
      "amountTwd": 130,
      "action": "UPSERT",
      "updatedAt": "2027-04-19T18:00:00+08:00"
    }
  ]
}

回應

200

已處理

Schema：IngestResult

JSON{
  "id": "IB202704200100",
  "accepted": 499,
  "rejected": [
    {
      "id": "mr_91aa07",
      "code": "INVALID_VEHICLE",
      "message": "查無車輛"
    }
  ]
}

Schemas

* 表示必填或必定回傳。

Member12 個欄位

欄位	型別	說明
`id` *	string	會員 ID
`memberNo` *	string	會員編號，供顯示
`phone` *	string	手機號碼，E.164，唯一
`name` *	string	姓名
`gender`	string	`M`男`F`女`O`其他
`birthday`	date
`email`	string
`address`	Address	地址
`status` *	string	`ACTIVE`正常`SUSPENDED`停權`DELETED`已刪除
`consents` *	Consent[]	條款同意紀錄
`createdAt` *	datetime
`updatedAt` *	datetime

Address5 個欄位

欄位	型別	說明
`id` *	string	地址 ID
`zipCode`	string	郵遞區號
`city`	string	縣市
`district`	string	鄉鎮市區
`line`	string	其餘地址

Consent5 個欄位

欄位	型別	說明
`id` *	string	同意紀錄 ID
`type` *	string	`TERMS`服務條款`PRIVACY`隱私權政策`MARKETING`行銷訊息
`version` *	string	條款版本
`agreed` *	boolean
`at` *	datetime	同意或拒絕的時間

PointTransaction11 個欄位

會員點數的一筆交易。

欄位	型別	說明
`id` *	string	交易 ID
`transactionId`	string	App 後端交易 ID；SYM 產生的交易（到期失效等）為 null
`memberId` *	string
`amount` *	integer	正數增加，負數扣除
`balanceAfter` *	integer	交易後餘額
`reasonCode` *	string	`RIDE_DISTANCE`騎乘里程`ACTIVITY_CHECK_IN`活動簽到`TASK_COMPLETED`完成任務`ACHIEVEMENT_UNLOCKED`解鎖成就`VOUCHER_REDEEM`兌換`PARTNER_GRANT`合作方發放`MANUAL_ADJUST`人工調整`REVERSAL`更正`EXPIRED`到期失效
`description`	string	顯示於會員明細的說明
`occurredAt` *	datetime	行為發生時間
`expiresAt`	datetime	增加的點數到期時間
`reversalOf`	string	被更正的原交易 ID
`createdAt` *	datetime	入帳時間

PointBalance3 個欄位

欄位	型別	說明
`id` *	string	會員 ID
`balance` *	integer	點數餘額
`expiringPoints` *	ExpiringPoint[]	即將到期點數，依到期時間遞增

ExpiringPoint3 個欄位

欄位	型別	說明
`id` *	string	點數批次 ID
`amount` *	integer
`expiresAt` *	datetime

Vehicle8 個欄位

SYM 銷售資料中的車輛。

欄位	型別	說明
`id` *	string	車輛 ID
`vin` *	string	車身號碼
`plateNo`	string	車牌，未領牌時為 null
`modelId` *	string	車型 ID
`modelYear` *	integer	年份
`color`	string	顏色
`salesDate` *	date	銷售日期
`dealerId` *	string	銷售據點 ID

VehicleModel10 個欄位

欄位	型別	說明
`id` *	string	車型 ID
`modelCode` *	string	車型代碼
`name` *	string	車型名稱
`series` *	string	車系
`modelYear` *	integer	年份
`displacementCc`	integer	排氣量，電動車為 null
`powertrain` *	string	`ICE`燃油`EV`電動
`equipment` *	Equipment[]	配備，項目清單請 SYM 提供
`updatedAt` *	datetime
`deleted` *	boolean	已停用

MaintenanceRule7 個欄位

里程與月份先到者觸發。

欄位	型別	說明
`id` *	string	規則 ID
`itemCode` *	string	保養項目代碼，與 ServiceRecord 一致
`name` *	string	項目名稱
`firstKm`	integer	首次保養里程
`firstMonths`	integer	首次保養月數
`intervalKm`	integer	之後每隔幾公里
`intervalMonths`	integer	之後每隔幾個月

Dealer13 個欄位

經銷商據點。

欄位	型別	說明
`id` *	string	據點 ID
`dealerCode` *	string	據點代碼
`name` *	string	據點名稱
`phone` *	string	E.164
`address` *	Address
`latitude` *	number	WGS84
`longitude` *	number	WGS84
`openingHours` *	OpeningHour[]
`services` *	string[]	`SALES`銷售`MAINTENANCE`保養維修`PARTS`零件`EV_SERVICE`電動車服務
`roadsideAssistance` *	boolean	是否提供道路救援
`status` *	string	停業以 `deleted: true` 表示 `OPEN`營業中`TEMP_CLOSED`暫停營業
`updatedAt` *	datetime
`deleted` *	boolean	停業

ServiceRecord11 個欄位

經銷商的保養或維修記錄。

欄位	型別	說明
`id` *	string	記錄 ID
`recordNo` *	string	工單編號
`vehicleId` *	string	車輛 ID
`dealerId` *	string	據點 ID
`serviceType` *	string	`PERIODIC`定期保養`REPAIR`維修`WARRANTY`保固`RECALL`召回
`serviceDate` *	date
`mileageKm` *	integer	進廠里程
`items` *	ServiceItem[]
`completedAt` *	datetime
`updatedAt` *	datetime
`deleted` *	boolean

Feedback13 個欄位

SYM 客服案件。

欄位	型別	說明
`id` *	string	案件 ID
`caseNo` *	string	案件編號，供顯示
`externalId` *	string	App 後端意見編號
`memberId` *	string
`category` *	string
`subject` *	string
`content` *	string
`vehicleId`	string
`dealerId`	string
`status` *	string	`OPEN`已受理`PROCESSING`處理中`CLOSED`已結案
`closedAt`	datetime
`createdAt` *	datetime
`updatedAt` *	datetime

Equipment3 個欄位

欄位	型別	說明
`id` *	string	配備 ID
`code` *	string	配備代碼
`name` *	string

OpeningHour4 個欄位

欄位	型別	說明
`id` *	string	營業時段 ID
`weekday` *	integer	1 週一～7 週日
`open` *	string	`HH:mm`
`close` *	string	`HH:mm`

ServiceItem5 個欄位

欄位	型別	說明
`id` *	string	工單項目 ID
`itemCode` *	string	保養項目代碼
`name` *	string
`partNo`	string	零件料號
`quantity` *	integer

Attachment5 個欄位

欄位	型別	說明
`id` *	string	App 後端檔案 ID
`fileName` *	string
`contentType` *	string
`url` *	string	下載連結
`expiresAt` *	datetime	連結到期時間

VehicleVerification3 個欄位

欄位	型別	說明
`id` *	string	驗證紀錄 ID
`result` *	string	`MATCHED`相符`NOT_MATCHED`不相符`NOT_FOUND`查無車牌
`vehicle`	Vehicle	`MATCHED` 時回傳

DatasetRecord4 個欄位

欄位	型別	說明
`id` *	string	App 後端記錄 ID，唯一
`action` *	string	`UPSERT` 新增或更新、`DELETE` 刪除
`updatedAt` *	datetime
`…`		資料集欄位

IngestResult3 個欄位

欄位	型別	說明
`id` *	string	批次 ID
`accepted` *	integer	成功筆數
`rejected` *	RejectedRecord[]	失敗記錄

RejectedRecord3 個欄位

欄位	型別	說明
`id` *	string	失敗記錄的 ID
`code` *	string	錯誤代碼
`message` *	string

Error3 個欄位

所有 4xx、5xx 回應的格式。

欄位	型別	說明
`error.code` *	string	錯誤代碼，呼叫端依此判斷
`error.message` *	string	可讀訊息，不顯示給會員
`error.details`	object	附加資訊