SYM APP 系統介接 API 規劃書

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

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

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

資料範圍

點數由 App 後端管理並通知 SYM，其餘資料以 SYM 系統為主檔。

SYM APPiOS／Android

HTTPS

App 後端Google Cloud 台灣區域

HA VPN
REST／JSON

SYM 系統本文件 API

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

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

API 索引

編號	方法	路徑	用途
會員帳戶7 支
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	POST	`/points/transactions`	通知點數異動
車輛與服務10 支
S-08	GET	`/vehicles`	車輛列表
S-09	GET	`/vehicles/{vehicleId}`	取得車輛
S-10	POST	`/verifications`	車主驗證
S-11	GET	`/models`	車型列表
S-12	GET	`/models/{modelId}`	取得車型
S-13	GET	`/models/{modelId}/maintenance`	車型保養規則列表
S-14	GET	`/dealers`	據點列表
S-15	GET	`/dealers/{dealerId}`	取得據點
S-16	GET	`/services`	保養記錄列表
S-17	GET	`/services/{recordId}`	取得保養記錄
客服與資料回傳4 支
S-18	GET	`/feedbacks`	意見反應列表
S-19	GET	`/feedbacks/{feedbackId}`	取得意見反應
S-20	POST	`/feedbacks`	建立意見反應
S-21	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": "PHONE_IN_USE",
    "message": "手機號碼已屬其他會員"
  }
}

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

API 規格

會員帳戶

S-01～S-07｜7 支

簡訊發送、會員、點數異動。

簡訊發送

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

點數異動

點數由 App 後端計算與記帳，每筆異動後通知 SYM。

POST/points/transactions通知點數異動S-07

以 transactionId 去除重複。同一會員的異動依發生順序逐筆送出；SYM 端餘額加 amount 不等於 balanceAfter 時不入帳，回 BALANCE_MISMATCH，該筆可用同一 transactionId 重送。更正、到期失效也以異動通知，reasonCode 分別為 REVERSAL、EXPIRED。

請求

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
`balanceAfter` *	integer	異動後餘額，須等於 SYM 端目前餘額加 `amount`
`reasonCode` *	string	`RIDE_DISTANCE`騎乘里程`ACTIVITY_CHECK_IN`活動簽到`TASK_COMPLETED`完成任務`ACHIEVEMENT_UNLOCKED`解鎖成就`VOUCHER_REDEEM`兌換`PARTNER_GRANT`合作方發放`MANUAL_ADJUST`人工調整`REVERSAL`更正`EXPIRED`到期失效
`description`	string	異動說明
`occurredAt` *	datetime	異動時間

JSON{
  "transactionId": "pt_20270415_7f3a91c2",
  "memberId": "100245",
  "amount": 200,
  "balanceAfter": 1450,
  "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",
  "createdAt": "2027-04-15T10:12:01+08:00"
}

200

transactionId 重複，回傳原紀錄

Schema：PointTransaction

409

BALANCE_MISMATCH details.currentBalance 帶 SYM 端目前餘額

404

MEMBER_NOT_FOUND

車輛與服務

S-08～S-17｜10 支

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

車輛

SYM 銷售資料中的車輛。

GET/vehicles車輛列表S-08

請求

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-09

請求

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-10

兩種方式擇一：
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-11

請求

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-12

請求

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-13

請求

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-14

請求

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-15

請求

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-16

請求

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-17

請求

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-18～S-21｜4 支

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

客服意見反應

寫入 SYM 客服系統。

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

請求

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-19

請求

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-20

附件以下載連結提供，連結有效 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-21

每批最多 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	同意或拒絕的時間

PointTransaction9 個欄位

會員點數的一筆異動。

欄位	型別	說明
`id` *	string	SYM 異動紀錄 ID
`transactionId` *	string	App 後端交易 ID
`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	異動時間
`createdAt` *	datetime	SYM 接收時間

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	附加資訊

介接時程

SYM 於各批時間前提供測試環境。

批次	API	測試環境需求時間
第一批	會員帳戶 S-01～S-07；認證機制	待議定
第二批	車輛與服務 S-08～S-17	待議定
第三批	客服與資料回傳 S-18～S-21	待議定
第二階段	S-21 車端資料集（`vehicle-telemetry`、`dtc-events`）	2027/01/29 前確認格式

待 SYM 確認事項

認證方式：API 金鑰搭配 VPN 與 IP 白名單是否符合 SYM 資安規範；SYM 若已有 API Gateway 或 OAuth 2.0 機制，可改用既有機制。
簡訊發送：簡訊商與發送者名稱；每則內容上限；OTP 簡訊能否 10 秒內送達；SYM 端流量上限；簡訊費用歸屬。
既有欄位與代碼：SYM 系統既有欄位或代碼可沿用者，標註對應。
會員 ID 與既有會員：會員 ID 與會員編號格式；既有會員是否都有手機號碼；同一手機號碼是否可能對應多筆會員，若有如何處理。
會員欄位：必填欄位、欄位長度，以及同意條款的版本由哪一方管理。
帳號刪除：刪除後個人資料的保存方式、保存期限；是否需要非同步處理。
車主驗證：PLATE_CONTACT 比對的聯絡資訊欄位（車主手機、使用人手機或其他）；車主與實際使用人不同時的處理方式。
保養記錄：是否包含零件與金額；可提供的歷史記錄年限；保養項目代碼能否與保養規則一致。
母廠回傳：可接收的資料集與欄位、頻率、保存期限。
客服系統：意見分類代碼、附件的接收方式；案件狀態與 SYM 客服系統狀態的對應。
事件通知：SYM 系統能否於會員、據點、保養記錄異動時主動通知 App 後端；不能時可接受的輪詢頻率。
連線環境：測試與正式環境的主機、VPN 設定，以及雙方技術窗口。