Reference

Condensed from 行動自然人憑證應用程式介面規格書 v2.9 §參.三 and §伍 — see SPEC.md for the full write-up this app was built from.

transaction_id

UUIDv4 (or another identifier), ≤100 characters. A fresh one is generated per request unless you override it in a page's form.

sp_checksum / idp_checksum

Both use AES_GCM_HEX( SHA256_HEX( Payload ) ):

Concatenate the interface's specified fields into one string (empty string for unused optional fields).
hex = SHA256(payload.getBytes("UTF-8")) → lowercase 64-char hex string.
AES-256-GCM encrypt the hex string's UTF-8 bytes (not the raw 32-byte digest) with an all-zero 12-byte IV and a 128-bit auth tag.
Result = hex(iv) + hex(ciphertext + tag).

This app's implementation is verified via an encrypt→decrypt round-trip self-test (lib/moica/crypto.selftest.ts) rather than the Spec's own worked hex examples, which had text-extraction artifacts across a PDF page break — see SPEC.md §6.2/§11.

sp_ticket

BASE64URL(payloadJson) + "." + BASE64URL(SHA256(BASE64URL(payloadJson)))

A two-segment (not three-segment / not a real JWT) token. The digest is an integrity check on the ticket itself — anyone can recompute it, so it does not prove the ticket came from MOICA, only that the two segments weren't corrupted in transit.

Interfaces implemented

介面編號 → this app's route

Spec ID	English name	Page
SP-API-WEB-01	fidoRedirect (web)	/redirect
SP-API-ATH-01	getSpTicket	/ticket
SP-API-ATH-02	getAthOrSignResult	/result
SP-API-ATH-03	requestAthOrSignPush	/push
SP-API-ATH-04	doBatchSigning	/batch
SP-API-LF-01	checkDeviceStatus	/device-status
APP-API-01	verifySign (deep link)	/app-link

Error codes

錯誤代碼為：介面編號 || '-' || 系統錯誤代碼 (e.g. SP-API-ATH-01-INV_SP_CHECKSUM)

系統錯誤代碼	詳細敘述	處理建議
DB_CONN_ERR	資料庫連線失敗	[1021] 系統維護中，請稍後再試。
DB_SQL_EXP	資料庫操作失敗	[1022] 系統維護中，請稍後再試。
DB_ROOLBACK	資料庫批次操作失敗，已回復到操作前狀態	[1023] 系統維護中，請稍後再試。
DB_CLOSE_ERR	資料庫連線關閉失敗	[1024] 系統維護中，請稍後再試。
DB_JNDI_ERR	資料庫設定錯誤	[1025] 系統維護中，請稍後再試。
UNDEFINED	未定義錯誤	[1026] 系統維護中，請稍後再試。
NFCNONCE_INS_ERR	NFC NONCE 於DB 資料表寫入失敗	[1027] 系統維護中，請稍後再試。
OTP_INS_ERR	OTP 於DB 資料表寫入失敗	[1028] 系統維護中，請稍後再試。
NFCNONCE_DBSQL	NFC_NONCE 查詢時發生DB 錯誤	[1029] 系統維護中，請稍後再試。
NFCNONCE_DEL_ERR	NFC_NONCE 刪除時發生DB 錯誤	[1030] 系統維護中，請稍後再試。
OTP_EXPIRED	OTP 認證碼逾期	[1031] 驗證碼逾時，請重新再試一次。
OTP_IDNUM_MISMATCH	身分證字號與OTP 比對不符合	[1032] 驗證碼與身分證號不符，請重新再試一次。
OTP_NF	找不到OTP（通常是用戶跑到測試官網註冊，然後用正式APP 綁定造成；或是用測試APP 跑到正式官網綁定造成）	[1033] 未取得驗證碼，請按照流程重新再試一次。
OTP_DBSQL	OTP 查詢時發生DB 錯誤	[1034] 驗證碼與身分證號不符，請重新再試一次。
NFCNONCE_NF	找不到 NFC NONCE	[1035] 未取得驗證碼，請按照流程重新再試一次。
NFCNONCE_IDNUM_MISMATCH	身分證字號與 NFC NONCE 比對不符合	[1036] 驗證碼與身分證號不符，請重新再試一次。
IDNUM_USERPROF_NF	身分證字號未找到對應之使用者資訊（新用戶或過去完成註銷之用戶）	[1051] 您尚未註冊綁定裝置，請先綁定裝置並申請行動自然人憑證。
IDNUM_USERPROF_DBSQL	身分證字號查詢使用者資訊時發生DB 錯誤	[1052] 查詢使用者資訊不成功，請洽客服人員處理。
IDNUM_DEVPROF_NF	身分證字號未找到對應之裝置資訊	[1053] 您尚未註冊綁定裝置，請先綁定裝置並申請行動自然人憑證。
IDNUM_DEVPROF_DBSQL	身分證字號查詢裝置資訊時發生DB 錯誤	[1054] 查詢使用者資訊不成功，請洽客服人員處理。
DEV_LIM_REACHED	裝置綁定數量到達上限	[1055] 裝置綁定已達上限，請至行動自然人憑證網站註銷後，再重新申請。
DEVID_DEVPROF_NF	Device_id 未找到對應之裝置資訊（憑證被廢止後會出現，出現後會清除裝置金鑰，恢復初始狀態）	[1061] 查詢裝置資訊不成功，請至行動自然人憑證官方網站確認該裝置名稱是否一致。
DEVID_DEVPROF_DBSQL	Device_id 查詢裝置資訊時發生DB 錯誤	[1062] 查詢裝置資訊不成功，請洽客服人員處理。
DEV_DESC_MISMATCH	未找到對應之自訂裝置名稱	[1063] 查詢裝置資訊不成功，請至行動自然人憑證官方網站確認該裝置名稱是否一致。
DEVID_SPTKT_MISMATCH	Device_id 與sp ticket 中對應之身份證字號雜湊值不符合	[1064] 裝置資訊驗證不成功，請確定使用合法裝置進行認證/簽章。
USERPROF_INS_ERR	使用者資訊DB 資料表寫入失敗	[1071] 系統維護中，請稍後再試。
DEVPROF_INS_ERR	裝置資訊DB 資料表寫入失敗	[1072] 系統維護中，請稍後再試。
SPTKT_INS_ERR	Sp_ticket DB 資料表寫入失敗（身分證字號驗證不符）	[1073] 系統維護中，請稍後再試。
TXNLOG_INS_ERR	認證簽署紀錄DB 資料表寫入失敗（常見真實問題：機關使用相同的transaction_id 送出）	[1074] 系統維護中，請稍後再試。
USERPROF_DEL_ERR	使用者資訊DB 資料表刪除失敗	[1075] 系統維護中，請稍後再試。
DEVPROF_DEL_ERR	裝置資訊DB 資料表刪除失敗	[1076] 系統維護中，請稍後再試。
SPTKT_DEL_ERR	Sp_ticket DB 資料表刪除失敗	[1077] 系統維護中，請稍後再試。
USERPROF_UPD_ERR	使用者資訊DB 資料表更新失敗	[1078] 系統維護中，請稍後再試。
DEVPROF_UPD_ERR	裝置資訊DB 資料表更新失敗	[1079] 系統維護中，請稍後再試。
IDNUM_DEVID_MISMATCH	身分證字號與 Device_id 比對不符合	[1080] 裝置名稱與使用者身分證號不符，請重新再試一次。
CERT_SIGNDATA_MISMATCH	輸入參數與簽章內容不符合	[1081] 簽章資料不成功，請洽客服人員。
CERT_SIGNDATA_ERR	簽章格式分析發生錯誤	[1082] 簽章資料不成功，請洽客服人員。
SPTKT_OVD	Sp_ticket 逾期	[1101] 驗證碼已過期，請重新執行驗證流程。
SPTKTID_SPTKT_NF	Sp_ticket_id 未找到對應之Sp_ticket（相容TWFIDO）	[1102] 驗證碼不存在，請重新執行驗證流程。
SPTKTID_SPTKT_RDM	Sp_ticket_id 對應之Sp_ticket 已經被使用過	[1103] 驗證碼已被使用過，請重新執行驗證流程。
SPTKTID_SPTKT_DBSQL	Sp_ticket_id 查詢Sp_ticket 時發生DB 錯誤	[1104] 驗證碼查詢有誤，請稍後再試。
NFCNONCE_EXPIRED	NFC NONCE 逾期	[1105] 驗證碼已過期，請重新執行註冊流程。
SIGRESP_CNT_MISMATCH	連續簽章回傳內容數量與Sp_ticket 中數量不符合	[1106] 連續簽章資料有誤，請重新執行或洽客服人員。
PS_CONNECT_404	推播模組PS 回應404	[3002] 系統維護中，請稍後再試。
PS_CONNECT_500	推播模組PS 回應500	[3003] 系統維護中，請稍後再試。
PS_JSON_FMT_ERR	推播模組PS 回應非JSON格式內容	[3004] 系統維護中，請稍後再試。
PS_JSON_TYPE_ERR	推播模組PS 回應JSON中部份型態不符合	[3005] 系統維護中，請稍後再試。
PS_JSON_MISS_KEY	推播模組PS 回應JSON中缺少必要欄位	[3006] 系統維護中，請稍後再試。
PS_CONNECT_IOEXC	推播模組PS 連線失敗	[3007] 系統維護中，請稍後再試。
PS_1001	訊息推播模組JSON 參數輸入錯誤	[3008] 系統維護中，請稍後再試。
PS_5000	訊息推播模組push_data JSON 解析錯誤	[3009] 系統維護中，請稍後再試。
PS_FCM_UNKNOWN	未知的錯誤，通常是伺服器問題	[3101] 系統維護中，請稍後再試。
PS_FCM_ABORTED	推播中止，推播過程發生衝突	[3102] 系統維護中，請稍後再試。
PS_FCM_ALREADY_EXISTS	資源已重複存在，無法建立推播資源	[3103] 系統維護中，請稍後再試。
PS_FCM_CANCELLED	推播操作已取消	[3104] 系統維護中，請稍後再試。
PS_FCM_CONFLICT	資源讀寫衝突	[3105] 系統維護中，請稍後再試。
PS_FCM_DATA_LOSS	資料遺失或資料毀損、接收不完全	[3106] 系統維護中，請稍後再試。
PS_FCM_DEADLINE_EXCEEDED	推播逾時	[3107] 系統維護中，請稍後再試。
PS_FCM_FAILED_PRECONDITION	推播失敗，請檢查系統程式完整性	[3108] 系統維護中，請稍後再試。
PS_FCM_INTERNAL	推播系統內部發生錯誤	[3109] 系統維護中，請稍後再試。
PS_FCM_INVALID_ARGUMENT	參數錯誤	[3110] 系統維護中，請稍後再試。
PS_FCM_NOT_FOUND	APP 推播資源失效，常見原因為用戶過久未開啟行動自然人憑證APP 導致推播資源未更新	[3111] 請重新開啟APP 後再試。
PS_FCM_OUT_OF_RANGE	超出推播範圍	[3112] 系統維護中，請稍後再試。
PS_FCM_PERMISSION_DENIED	API 無存取權限或尚未啟用	[3113] 系統維護中，請稍後再試。
PS_FCM_RESOURCE_EXHAUSTED	推播資源忙碌中，超出系統負荷範圍	[3114] 系統維護中，請稍後再試。
PS_FCM_UNAUTHENTICATED	未認證的名稱	[3115] 系統維護中，請稍後再試。
PS_FCM_UNAVAILABLE	資源目前無法存取	[3116] 系統維護中，請稍後再試。
(iOS fingerprint 完成按鈕)	只會發生在iOS，用戶進入指紋畫面直接點下左上角的完成按鈕造成，請用戶按照正確程序操作即可。	[10002] 操作不成功，請稍後再操作一次。
(WebAuthn credentials.create)	WebAuthn API: navigator.credentials.create 錯誤	[32001] 操作不成功，請稍後再操作一次。
(WebAuthn credentials.get)	WebAuthn API: navigator.credentials.get 錯誤	[32002] 操作不成功，請稍後再操作一次。
(WebAuthn Cancel by User)	只會發生在iOS，用戶進入指紋畫面，點下指紋後按了取消造成，請用戶按照正確程序操作即可。	[32003] 操作不成功，請稍後再操作一次。
(WebAuthn CredentialID missing)	只會發生在iOS，原因是用戶把Safari 重置或是清除瀏覽資料，造成FIDO 金鑰消失所致，需要請用戶上官方網站註銷原有裝置，再重新安裝APP 綁定。	[32004] 操作不成功，請稍後再操作一次。
(WebAuthn SecurityError)	WebAuthn API: SecurityError	[32005] 操作不成功，請稍後再操作一次。
(WebAuthn TimeoutError)	iOS 網頁，點下指紋icon 以後，等待超過30 秒會發生。	[32006] 操作不成功，請稍後再操作一次。
PM_INV_NF	缺少參數或者格式不正確	[5002] 簽章不成功，請洽客服人員處理。
PM_SIGDATA_ERR	APP 端簽章內容格式不正確	[5003] 簽章不成功，請洽客服人員處理。
PM_INV_SG	APP 端簽章驗證失敗	[5004] 驗證不成功，請確認憑證有效性。
PM_SIGNDATA_NULL	APP 端簽章明文為空值	[5005] 簽章不成功，請洽客服人員處理。
SPTKT_PLD_FT_ERR	Sp_ticket 格式錯誤	[9002] 資料格式有誤，請洽該應用服務之管理員。
SPTKT_DIG_FT_ERR	Sp_ticket 簽章驗證失敗	[9003] 資料驗證不成功，請洽該應用服務之管理員。
INV_SP_CHECKSUM	SP CHECKSUM 檢驗失敗	[9004] 資料驗證不成功，請洽該應用服務之管理員。
TGT_INV	無效的操作對象代碼	[9005] 資料驗證不成功，請洽該應用服務之管理員。
PM_IDN_FT_ERR	身份證字號格式錯誤	[9006] 身分證號格式錯誤，請確認輸入資訊。
SPTKTID_TXNLOG_NF	查無使用者認證/簽署結果	[9007] 使用者認證/簽署作業尚未完成，請稍後再試。
SIGNDATA_LEN_LIMIT	簽章資料長度到達上限（上限1024 個字元）	[9008] 簽章資料長度到達上限（上限1024 個字元）。
SPTKT_TIME_FT_ERR	自訂 Sp_ticket 逾期時間格式錯誤	[9009] 資料驗證不成功，請洽該應用服務之管理員。
SPTKT_TIME_ORV	自訂 Sp_ticket 逾期時間超過範圍(out of range value)	[9010] 資料驗證不成功，請洽該應用服務之管理員。
SPSVCID_NF	Sp service id 未找到對應之 SP 資訊	[9011] 資料驗證不成功，請洽該應用服務之管理員。
SPSVCID_DBSQL	Sp service id 查詢 SP 資訊時發生DB 錯誤	[9012] 資料驗證不成功，請洽該應用服務之管理員。
BATSIGN_CNT_LIMIT	連續簽章文件數量達到上限	[9013] 資料驗證不成功，請洽該應用服務之管理員。
APP_SIGN_FAILURE	APP 簽章失敗	[9014] APP 回報簽章失敗，簽章作業終止。
APP_USER_CANCEL	APP 簽章時使用者取消	[9015] APP 回報使用者取消簽章，簽章作業終止。
APP_DECODE_FAIL	APP 簽章資料解碼失敗	[9016] APP 回報簽章資料解碼失敗，簽章作業終止。
APP_DATA_NULL	APP 簽章資料為空	[9017] APP 回報簽章資料為空，簽章作業終止。