{ "swagger": "2.0", "info": { "version": "v1", "title": "Product.EInvoice.Api4Pos", "description": "POSAPI中英文整合合約。先讀 x-integration-guide、x-known-issues、x-open-questions；完整請求情境在 body 的 x-request-examples、回應情境在 x-response-examples。x-*是擴充欄位，通用SDK/UI可能忽略，須額外讀取。所有範例為合成資料，不保證外部條碼存在或可列印；SQL快照未確認部署。本輪只改文件，不改交易行為。 / Bilingual POSAPI integration contract. Read x-integration-guide, x-known-issues and x-open-questions; complete request scenarios are in body x-request-examples and response scenarios in x-response-examples. Generic SDK/UI tools may ignore x-* extensions; read them explicitly. Examples are synthetic, not proof of external barcode validity or printable invoices. SQL snapshot deployment is unverified. Documentation only; transaction behavior is unchanged." }, "host": "jpe-sl-einvoice-posapi-stage.azurewebsites.net", "schemes": [ "https" ], "paths": { "/Append/Order": { "post": { "tags": [ "Append" ], "summary": "開立電子發票並回傳列印資料 / Issue an e-invoice and return print data", "description": "開立電子發票。ModelState與CheckKey先執行，再正規化/決定載具、查重、檢核、取號及寫入。HTTP200不等於業務成功。DUPLICATE_ORDER回0及既有發票，可能另重印和通知，不是唯讀查詢。新開立只有StatusCode=1且ShortCode非空才嘗試列印，欄位可能省略。逾時不可自動重送。完整情境見x-request-examples、錯誤見x-response-examples。 / Issues an invoice: ModelState/CheckKey, normalization/carrier resolution, duplicate lookup, policy checks, allocation and persistence. HTTP200 is not business success. DUPLICATE_ORDER returns 0 and an existing invoice, possibly also reprinting/notifying; not a read-only lookup. New issuance attempts printing only with StatusCode=1 and nonempty ShortCode; output fields may be omitted. Do not auto-retry timeouts. See x-request-examples and x-response-examples.", "operationId": "appendOrder", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "Order", "in": "body", "description": "開立資料 / Invoice issuance request.", "required": true, "schema": { "$ref": "#/definitions/AppendOrderModel" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] }, "x-request-examples": { "consumer": { "description": "一般自然人；無會員資料時依商家設定走代保管或拒絕，P1換成配置用途。 / Consumer; without member data, managed print or rejection depends on merchant settings. Replace P1 with the assigned code.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] } }, "business": { "description": "企業買受人測試例，明細未稅；統編需替換。 / Business-buyer illustration with tax-exclusive lines; replace the test ID.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "87654321", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 95, "SubTotal": 95, "Remark": "" } ] } }, "phoneCarrier": { "description": "手機載具格式示意，不保證此碼存在。 / Mobile-carrier format illustration, not proof of existence.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "3J0002", "CarrierId": "/ABC1234" } }, "citizenCarrier": { "description": "自然人憑證格式示意，顯隱碼相同。 / Citizen-certificate format illustration with equal IDs.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "CQ0001", "CarrierId1": "AB12345678901234", "CarrierId2": "AB12345678901234" } }, "donation": { "description": "捐贈示意，不同送載具；捐贈碼须通過環境查核。 / Donation illustration without carrier fields; the code must pass environment checks.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "NPOBAN": "919" } }, "memberCarrier": { "description": "會員資料示意，功能須開啟，實際載具由資料庫處理。 / Member-data illustration; feature must be enabled and the database resolves the carrier.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "BuyerCustomerNumber": "C0001", "BuyerEmailAddress": "buyer@example.com" } } } } ], "responses": { "200": { "description": "同步開立流程結果；StatusCode=0也可能含既有發票。外部通知/列印/上傳需另外核對。 / Synchronous issuance result; StatusCode=0 may still contain an existing invoice. Reconcile notification/print/upload separately.", "schema": { "$ref": "#/definitions/ResponseAppendOrderModel" }, "examples": { "application/json": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 }, "x-response-examples": { "duplicate": { "description": "既有有效發票，不是新開立成功；Order可能另有重印/通知副作用。 / Existing active invoice, not new issuance success; Order may also reprint/notify.", "value": { "StatusCode": 0, "MessageCode": "DUPLICATE_ORDER", "ResultMessage": "訂單號碼(BillingNo)POS202609030001,BillingNo: POS202609030001 duplicate, InvoiceNumber: AA12345678, InvoiceDate:　2026-09-03", "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678" } }, "authentication": { "description": "金鑰不符示例。 / Credential mismatch example.", "value": { "StatusCode": 0, "ResultMessage": "請確認授權是否正確錯誤" } }, "modelValidation": { "description": "模型驗證失敗，沒有欄位級細節。 / Model validation failure without field details.", "value": { "StatusCode": 0, "ResultMessage": "資料內容錯誤" } }, "issuedNoPrintData": { "description": "開立成功但沒有列印資料；不可因此重新開立。 / Issued successfully without print data; do not issue again for this reason.", "value": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "directPrint": { "description": "Epson初始化片段，不是完整可列印發票。 / Epson initialization fragment, not a complete printable invoice.", "value": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00", "PrintCode": "1B40", "PrintDataString": "電子發票證明聯|115年09-10月|AA-12345678|2026-09-03 16:30:00|隨機碼:9999 總計:100|賣方:12345678|BARCODE_SAMPLE|LEFT_QR_SAMPLE|RIGHT_QR_SAMPLE|RN:POS202609030001" } } } } }, "x-retry-policy": { "automaticRetry": false, "description": "非空RelateNumber複製到BillingNo；缺值則生成時間字串，不能可靠去重。repo查詢找公司+BillingNo最近一張非C/B狀態發票，不保證永久冪等或併發exactly-once。DUPLICATE_ORDER回StatusCode=0與既有InvoiceNumber；Order還可能重印及通知。逾時保留原訂單號/請求/時間，停自動重送並核對結果；核對入口待Q1。 / Nonempty RelateNumber becomes BillingNo; omission generates a timestamp and cannot reliably deduplicate. The repo query finds the latest invoice for seller+BillingNo outside C/B states, without permanent idempotency or concurrent exactly-once guarantees. DUPLICATE_ORDER returns StatusCode=0 and an existing InvoiceNumber; Order may also reprint and notify. Preserve the original ID/request/time after timeout, stop resubmission and reconcile; entry point pending Q1." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "讀取MessageCode/ResultMessage及可選InvoiceNumber。驗證或輸入錯誤先修正；未知業務錯誤人工核對，不以訊息文字自動重試。 / Inspect MessageCode/ResultMessage and optional InvoiceNumber. Correct auth/input problems first; reconcile unknown failures rather than retry by message text." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "保留請求與時間，結果視為未知。不得推定交易回滾或已成功；依核對流程處理。 / Retain request/time and treat outcome as unknown. Do not infer rollback or success; follow reconciliation workflow." } ] } }, "/Append/OrderReturnQKey": { "post": { "tags": [ "Append" ], "summary": "開立電子發票並回傳歸戶資訊 / Issue an e-invoice and return carrier-binding data", "description": "共用開立流程。只有StatusCode=1且ShortCode非空才嘗試QKey/QrCodeUrl，成功不保證有歸戶欄位。URL視為不透明值。Member export SQL快照可能改捐贈/載具狀態，部署待確認；不是純查詢。重複訂單回0與既有發票且可能通知。逾時先核對。 / Uses common issuance. QKey/QrCodeUrl is attempted only with StatusCode=1 and nonempty ShortCode, not guaranteed on every success. Treat URL as opaque. The Member export SQL snapshot may mutate donation/carrier state; verify deployment. Not a pure query. Duplicates return 0/existing invoice and may notify. Reconcile timeouts first.", "operationId": "appendOrderReturnQKey", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "Order", "in": "body", "description": "開立資料 / Invoice issuance request.", "required": true, "schema": { "$ref": "#/definitions/AppendOrderModel" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] }, "x-request-examples": { "consumer": { "description": "一般自然人；無會員資料時依商家設定走代保管或拒絕，P1換成配置用途。 / Consumer; without member data, managed print or rejection depends on merchant settings. Replace P1 with the assigned code.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] } }, "business": { "description": "企業買受人測試例，明細未稅；統編需替換。 / Business-buyer illustration with tax-exclusive lines; replace the test ID.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "87654321", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 95, "SubTotal": 95, "Remark": "" } ] } }, "phoneCarrier": { "description": "手機載具格式示意，不保證此碼存在。 / Mobile-carrier format illustration, not proof of existence.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "3J0002", "CarrierId": "/ABC1234" } }, "citizenCarrier": { "description": "自然人憑證格式示意，顯隱碼相同。 / Citizen-certificate format illustration with equal IDs.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "CQ0001", "CarrierId1": "AB12345678901234", "CarrierId2": "AB12345678901234" } }, "donation": { "description": "捐贈示意，不同送載具；捐贈碼须通過環境查核。 / Donation illustration without carrier fields; the code must pass environment checks.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "NPOBAN": "919" } }, "memberCarrier": { "description": "會員資料示意，功能須開啟，實際載具由資料庫處理。 / Member-data illustration; feature must be enabled and the database resolves the carrier.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "BuyerCustomerNumber": "C0001", "BuyerEmailAddress": "buyer@example.com" } } } } ], "responses": { "200": { "description": "同步開立流程結果；StatusCode=0也可能含既有發票。外部通知/列印/上傳需另外核對。 / Synchronous issuance result; StatusCode=0 may still contain an existing invoice. Reconcile notification/print/upload separately.", "schema": { "$ref": "#/definitions/ResponseAppendOrderModel" }, "examples": { "application/json": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 }, "x-response-examples": { "duplicate": { "description": "既有有效發票，不是新開立成功；Order可能另有重印/通知副作用。 / Existing active invoice, not new issuance success; Order may also reprint/notify.", "value": { "StatusCode": 0, "MessageCode": "DUPLICATE_ORDER", "ResultMessage": "訂單號碼(BillingNo)POS202609030001,BillingNo: POS202609030001 duplicate, InvoiceNumber: AA12345678, InvoiceDate:　2026-09-03", "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678" } }, "authentication": { "description": "金鑰不符示例。 / Credential mismatch example.", "value": { "StatusCode": 0, "ResultMessage": "請確認授權是否正確錯誤" } }, "modelValidation": { "description": "模型驗證失敗，沒有欄位級細節。 / Model validation failure without field details.", "value": { "StatusCode": 0, "ResultMessage": "資料內容錯誤" } }, "issuedNoPrintData": { "description": "開立成功但沒有列印資料；不可因此重新開立。 / Issued successfully without print data; do not issue again for this reason.", "value": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "quickCarrier": { "description": "條件成立才有的合成歸戶範例；不可當真實token。 / Synthetic conditional carrier-binding example, not a real token.", "value": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00", "QKey": "789999", "QrCodeUrl": "https://example.invalid/carrier/SYNTHETIC_TOKEN" } } } } }, "x-retry-policy": { "automaticRetry": false, "description": "非空RelateNumber複製到BillingNo；缺值則生成時間字串，不能可靠去重。repo查詢找公司+BillingNo最近一張非C/B狀態發票，不保證永久冪等或併發exactly-once。DUPLICATE_ORDER回StatusCode=0與既有InvoiceNumber；Order還可能重印及通知。逾時保留原訂單號/請求/時間，停自動重送並核對結果；核對入口待Q1。 / Nonempty RelateNumber becomes BillingNo; omission generates a timestamp and cannot reliably deduplicate. The repo query finds the latest invoice for seller+BillingNo outside C/B states, without permanent idempotency or concurrent exactly-once guarantees. DUPLICATE_ORDER returns StatusCode=0 and an existing InvoiceNumber; Order may also reprint and notify. Preserve the original ID/request/time after timeout, stop resubmission and reconcile; entry point pending Q1." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "讀取MessageCode/ResultMessage及可選InvoiceNumber。驗證或輸入錯誤先修正；未知業務錯誤人工核對，不以訊息文字自動重試。 / Inspect MessageCode/ResultMessage and optional InvoiceNumber. Correct auth/input problems first; reconcile unknown failures rather than retry by message text." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "保留請求與時間，結果視為未知。不得推定交易回滾或已成功；依核對流程處理。 / Retain request/time and treat outcome as unknown. Do not infer rollback or success; follow reconciliation workflow." } ] } }, "/Append/OrderWithoutPrint": { "post": { "tags": [ "Append" ], "summary": "開立電子發票但不回傳列印資料 / Issue an e-invoice without print data", "description": "共用開立流程，但本action不產生列印碼。雖把請求PrintMark設N，GetInvoiceModel沒有映射它，故不保證資料庫註記N或無紙本用途。不要用此endpoint作為禁止紙本的保證。失敗日期不像另外兩個開立action會清除。重複訂單及逾時須核對，可能已有通知。 / Uses common issuance without generating print commands in this action. Although request PrintMark is set to N, GetInvoiceModel does not map it, so database N/no paper disposition is not guaranteed. Do not use this endpoint as a guarantee against paper. Unlike the other two issuance actions, failure dates are not cleared. Reconcile duplicates/timeouts; notifications may already have occurred.", "operationId": "appendOrderWithoutPrint", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "Order", "in": "body", "description": "開立資料 / Invoice issuance request.", "required": true, "schema": { "$ref": "#/definitions/AppendOrderModel" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] }, "x-request-examples": { "consumer": { "description": "一般自然人；無會員資料時依商家設定走代保管或拒絕，P1換成配置用途。 / Consumer; without member data, managed print or rejection depends on merchant settings. Replace P1 with the assigned code.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] } }, "business": { "description": "企業買受人測試例，明細未稅；統編需替換。 / Business-buyer illustration with tax-exclusive lines; replace the test ID.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "87654321", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 95, "SubTotal": 95, "Remark": "" } ] } }, "phoneCarrier": { "description": "手機載具格式示意，不保證此碼存在。 / Mobile-carrier format illustration, not proof of existence.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "3J0002", "CarrierId": "/ABC1234" } }, "citizenCarrier": { "description": "自然人憑證格式示意，顯隱碼相同。 / Citizen-certificate format illustration with equal IDs.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "CarrierType": "CQ0001", "CarrierId1": "AB12345678901234", "CarrierId2": "AB12345678901234" } }, "donation": { "description": "捐贈示意，不同送載具；捐贈碼须通過環境查核。 / Donation illustration without carrier fields; the code must pass environment checks.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "NPOBAN": "919" } }, "memberCarrier": { "description": "會員資料示意，功能須開啟，實際載具由資料庫處理。 / Member-data illustration; feature must be enabled and the database resolves the carrier.", "value": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ], "BuyerCustomerNumber": "C0001", "BuyerEmailAddress": "buyer@example.com" } } } } ], "responses": { "200": { "description": "同步開立流程結果；StatusCode=0也可能含既有發票。外部通知/列印/上傳需另外核對。 / Synchronous issuance result; StatusCode=0 may still contain an existing invoice. Reconcile notification/print/upload separately.", "schema": { "$ref": "#/definitions/ResponseAppendOrderModel" }, "examples": { "application/json": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 }, "x-response-examples": { "duplicate": { "description": "既有有效發票，不是新開立成功；Order可能另有重印/通知副作用。 / Existing active invoice, not new issuance success; Order may also reprint/notify.", "value": { "StatusCode": 0, "MessageCode": "DUPLICATE_ORDER", "ResultMessage": "訂單號碼(BillingNo)POS202609030001,BillingNo: POS202609030001 duplicate, InvoiceNumber: AA12345678, InvoiceDate:　2026-09-03", "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678" } }, "authentication": { "description": "金鑰不符示例。 / Credential mismatch example.", "value": { "StatusCode": 0, "ResultMessage": "請確認授權是否正確錯誤" } }, "modelValidation": { "description": "模型驗證失敗，沒有欄位級細節。 / Model validation failure without field details.", "value": { "StatusCode": 0, "ResultMessage": "資料內容錯誤" } }, "issuedNoPrintData": { "description": "開立成功但沒有列印資料；不可因此重新開立。 / Issued successfully without print data; do not issue again for this reason.", "value": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } } } } }, "x-retry-policy": { "automaticRetry": false, "description": "非空RelateNumber複製到BillingNo；缺值則生成時間字串，不能可靠去重。repo查詢找公司+BillingNo最近一張非C/B狀態發票，不保證永久冪等或併發exactly-once。DUPLICATE_ORDER回StatusCode=0與既有InvoiceNumber；Order還可能重印及通知。逾時保留原訂單號/請求/時間，停自動重送並核對結果；核對入口待Q1。 / Nonempty RelateNumber becomes BillingNo; omission generates a timestamp and cannot reliably deduplicate. The repo query finds the latest invoice for seller+BillingNo outside C/B states, without permanent idempotency or concurrent exactly-once guarantees. DUPLICATE_ORDER returns StatusCode=0 and an existing InvoiceNumber; Order may also reprint and notify. Preserve the original ID/request/time after timeout, stop resubmission and reconcile; entry point pending Q1." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "讀取MessageCode/ResultMessage及可選InvoiceNumber。驗證或輸入錯誤先修正；未知業務錯誤人工核對，不以訊息文字自動重試。 / Inspect MessageCode/ResultMessage and optional InvoiceNumber. Correct auth/input problems first; reconcile unknown failures rather than retry by message text." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "保留請求與時間，結果視為未知。不得推定交易回滾或已成功；依核對流程處理。 / Retain request/time and treat outcome as unknown. Do not infer rollback or success; follow reconciliation workflow." } ] } }, "/AssignNo/UseState": { "post": { "tags": [ "AssignNo" ], "summary": "查詢字軌使用狀態 / Get invoice-number usage status", "description": "查詢指定用途與期別，不保留下一個號碼。有資料才回1與UseStatus；查無資料或被捕捉的DB例外都可能只回0，因此不能解讀成號碼用完。UseFor請用已配置值，省略YearMonth/UseFor的預設和統計算法因程序本體不在repo待確認。 / Queries usage/period without reserving the next number. Data yields 1/UseStatus; no rows or caught DB errors may both return only 0, so do not infer exhausted numbers. Use provisioned UseFor. Omitted filters and aggregation rules remain unconfirmed because the procedure body is absent.", "operationId": "getAssignNoUseState", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "RequestData", "in": "body", "description": "字軌查詢條件與驗證資料 / Query criteria and request credentials.", "required": true, "schema": { "$ref": "#/definitions/RequestAssignNo_UseState_Model" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "UseFor": "P1", "YearMonth": "11510" } } ], "responses": { "200": { "description": "字軌使用狀態 / Invoice-number usage status.", "schema": { "$ref": "#/definitions/ResponseAssignNo_UseState_Model" }, "examples": { "application/json": { "StatusCode": 1, "UseStatus": [ { "CompanyIdentifier": "12345678", "YearMonth": "11510", "UseFor": "P1", "NonUseCount": 800, "UseCount": 200, "NextInvoiceNumber": "AA12345878" } ] } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 }, "x-response-examples": { "data": { "description": "有資料示例。 / Data example.", "value": { "StatusCode": 1, "UseStatus": [ { "CompanyIdentifier": "12345678", "YearMonth": "11510", "UseFor": "P1", "NonUseCount": 800, "UseCount": 200, "NextInvoiceNumber": "AA12345878" } ] } }, "unavailable": { "description": "查無資料或查詢失敗，原因未區分。 / No data or failed query; cause not distinguished.", "value": { "StatusCode": 0 } } } } }, "x-retry-policy": { "automaticRetry": false, "description": "查詢/查核可由呼叫端設定有限次退避；不能保證查核服務每次可用。 / Callers may configure bounded backoff for queries/checks; external availability is not guaranteed." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "有ResultMessage時先查看驗證/授權訊息；沒有訊息時無資料與查詢失敗未區分。核對CompanyIdentifier、UseFor、YearMonth後聯絡維運，不得直接解讀為字軌耗盡。 / Inspect ResultMessage for validation/auth failures when present. Without a message, no data and query failure are conflated. Verify CompanyIdentifier, UseFor and YearMonth, then contact operations; do not infer exhausted allocation." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "狀態查詢未完成；可依呼叫端政策有限次退避重查，結果仍是即時快照，不保留字軌。 / Status lookup is incomplete; bounded backoff may be configured by the caller. Results are snapshots and reserve no invoice numbers." } ] } }, "/Invoice/Cancel": { "post": { "tags": [ "Invoice" ], "summary": "作廢電子發票 / Cancel an e-invoice", "description": "先ModelState再CheckKey。一般業務成功/失敗HTTP200，成功回StatusCode=1、訊息與請求日期；不表示財政部接收完成。失敗CancelDate可能為0001-01-01T00:00:00。SQL快照可拒絕重複、找不到或不符跨期等條件；ReturnTaxDocumentNumber不保證放行。作廢可能已生效才遇到中斷，不可自動重試；先依人工/系統核對流程確認。 / ModelState then CheckKey. Normal business results use HTTP200; success returns StatusCode=1, message and request date, not proof of completed government receipt. Failure CancelDate may be 0001-01-01T00:00:00. SQL snapshot may reject duplicate/missing/late cancellations; ReturnTaxDocumentNumber does not guarantee approval. Cancellation may have taken effect before disconnect; do not auto-retry. Reconcile first.", "operationId": "cancelInvoice", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "RequestData", "in": "body", "description": "作廢資料與驗證資訊 / Cancellation request and credentials.", "required": true, "schema": { "$ref": "#/definitions/RequestCancel_Model" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "InvoiceNumber": "AA12345678", "CancelDate": "2026-09-01T16:30:00", "CancelReason": "消費者退貨", "Remark": "測試作廢", "SalesID": "POS-01", "BlankCancel": "N" } } ], "responses": { "200": { "description": "作廢結果 / Cancellation result.", "schema": { "$ref": "#/definitions/ResponseCancel_Model" }, "examples": { "application/json": { "StatusCode": 1, "ResultMessage": "Invoice AA12345678 Cancel Success", "CancelInvoiceNumber": "AA12345678", "CancelDate": "2026-09-03T16:30:00" } }, "x-business-error-example": { "StatusCode": 0, "ResultMessage": "請確認授權是否正確錯誤", "CancelDate": "0001-01-01T00:00:00" }, "x-response-examples": { "authentication": { "description": "失敗日期為未設定預設值。 / Failure date is the unset default.", "value": { "StatusCode": 0, "ResultMessage": "請確認授權是否正確錯誤", "CancelDate": "0001-01-01T00:00:00" } }, "success": { "description": "同步成功，不是上傳完成。 / Synchronous success, not completed upload.", "value": { "StatusCode": 1, "ResultMessage": "Invoice AA12345678 Cancel Success", "CancelInvoiceNumber": "AA12345678", "CancelDate": "2026-09-03T16:30:00" } } } } }, "x-retry-policy": { "automaticRetry": false, "correlationFields": [ "CompanyIdentifier", "InvoiceNumber" ], "description": "依請求CompanyIdentifier與InvoiceNumber核對作廢結果，保留CancelDate及發送時間。中斷前作廢可能已生效或排入工作；重送可能回已作廢錯誤，不保證重放成功結果。核對入口待Q1，確認前不自動重送。 / Reconcile cancellation using request CompanyIdentifier and InvoiceNumber; retain CancelDate and send time. Changes or queued work may precede disconnect. Resubmission may fail as already cancelled; successful-result replay is not guaranteed. Entry point pending Q1; do not auto-retry before reconciliation." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "查看ResultMessage，以請求InvoiceNumber核對；回應CancelInvoiceNumber可能省略。CancelDate=0001-01-01T00:00:00是未設定值，不是作廢時間。先修正驗證問題，其他失敗循作廢核對流程處理。 / Inspect ResultMessage and reconcile using request InvoiceNumber; response CancelInvoiceNumber may be omitted. Minimum CancelDate is an unset sentinel, not cancellation time. Correct validation issues and reconcile other failures." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "作廢結果未知；保留公司、請求InvoiceNumber、CancelDate及發送時間，由Q1流程確認作廢與後續上傳狀態。 / Cancellation outcome is unknown; retain seller, request InvoiceNumber, CancelDate and send time. Use Q1 to confirm cancellation and downstream upload state." } ] } }, "/Printer/RePrint": { "post": { "tags": [ "Printer" ], "summary": "取得發票重新列印資料 / Get invoice reprint data", "description": "取得命令或排入重印佇列。PrintCode為hex，僅code模式回傳；排隊成功可省略。1B40只是格式片段。SQL快照重印可更改隨機碼/載具/列印狀態，重送可能重印；成功不證明實體列印完成。已知佇列例外可能回1+Error，不可送印、需核對。 / Generates commands or queues a reprint. PrintCode is hex, returned in code mode; queued success may omit it. 1B40 is only a format fragment. SQL snapshot reprint may change random code/carrier/print state; resubmission may print again. Success does not prove physical printing. Known queue exceptions may return 1+Error; never print it, reconcile instead.", "operationId": "reprintInvoice", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "RequestData", "in": "body", "description": "發票號碼與驗證資訊 / Invoice number and request credentials.", "required": true, "schema": { "$ref": "#/definitions/RequestReprintModel" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "InvoiceNumber": "AA12345678" } } ], "responses": { "200": { "description": "重新列印結果 / Reprint result.", "schema": { "$ref": "#/definitions/ResponseReprintModel" }, "examples": { "application/json": { "StatusCode": 1 } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 }, "x-response-examples": { "queued": { "description": "排入列印流程，命令省略，尚非實體完成。 / Queued flow with omitted commands, not physical completion.", "value": { "StatusCode": 1 } }, "direct": { "description": "Epson初始化片段，不是完整可列印發票。 / Epson initialization fragment, not a complete printable invoice.", "value": { "StatusCode": 1, "PrintCode": "1B40" } }, "queueError": { "description": "既有程式缺陷範例，不能將Error送印。 / Existing defect example; never print Error.", "value": { "StatusCode": 1, "PrintCode": "Error" } }, "failed": { "description": "重印失敗示例。 / Reprint failure example.", "value": { "StatusCode": 0, "ResultMessage": "重新列印發生錯誤,請與客服聯絡" } } } } }, "x-retry-policy": { "automaticRetry": false, "correlationFields": [ "CompanyIdentifier", "DeviceNo", "InvoiceNumber" ], "description": "依請求CompanyIdentifier、DeviceNo、InvoiceNumber核對命令/佇列與實體列印結果。重送可能重複列印；SQL快照亦可能改隨機碼、載具、列印註記，不是唯讀或冪等查詢。逾時先走Q1確認，沒有PrintCode或HTTP200都不是重送依據。 / Reconcile commands, queue and physical output using request CompanyIdentifier, DeviceNo and InvoiceNumber. Resubmission may print again; the SQL snapshot may change random code, carrier and print flags. This is not a read-only or idempotent query. Reconcile via Q1 after timeout; missing PrintCode or HTTP200 alone is not grounds to resubmit." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "查看ResultMessage，保留請求InvoiceNumber與裝置；ResponseReprintModel沒有InvoiceNumber欄位。修正驗證問題，其他錯誤核對列印狀態後再決定。 / Inspect ResultMessage and retain request InvoiceNumber and device; ResponseReprintModel has no InvoiceNumber field. Correct validation issues and reconcile print state before further action." }, { "when": "HTTP 200 / StatusCode 1 / PrintCode Error", "action": "已知佇列錯誤仍可能宣告成功；不得解碼或送印Error，請核對佇列與裝置，不自動重送。 / A known queue error may still report success. Never decode or print Error; reconcile queue/device state without automatic resubmission." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "列印結果未知；保留公司、裝置、請求InvoiceNumber與發送時間，由Q1流程核對，不可推定未印出。 / Print outcome is unknown. Retain seller, device, request InvoiceNumber and send time; reconcile via Q1 rather than assuming nothing printed." } ] } }, "/Printer/Status": { "post": { "tags": [ "Printer" ], "summary": "查詢列印伺服器狀態 / Get print-server status", "description": "回傳目前實作的列印服務狀態判斷，1並非某張發票已列印。0可能驗證失败或服務狀態不符；SQL快照欄位與C#比對存在差異，部署待核對。DB/空結果例外可能逸出業務回應。 / Returns current implementation's print-service status; 1 does not prove a particular invoice printed. 0 may mean auth failure or unmatched status. SQL snapshot and C# compare different columns; verify deployment. DB/null-result exceptions may escape business responses.", "operationId": "getPrinterStatus", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "RequestData", "in": "body", "description": "POS 裝置與驗證資訊 / POS device and request credentials.", "required": true, "schema": { "$ref": "#/definitions/RequestAuthBase" }, "x-example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY" } } ], "responses": { "200": { "description": "列印伺服器狀態 / Print-server status.", "schema": { "$ref": "#/definitions/ResponseBase" }, "examples": { "application/json": { "StatusCode": 1 } }, "x-business-error-example": { "ResultMessage": "請確認授權是否正確錯誤", "StatusCode": 0 } } }, "x-retry-policy": { "automaticRetry": false, "description": "查詢/查核可由呼叫端設定有限次退避；不能保證查核服務每次可用。 / Callers may configure bounded backoff for queries/checks; external availability is not guaranteed." }, "x-error-handling": [ { "when": "HTTP 200 / StatusCode 0", "action": "如有ResultMessage先確認驗證資訊；沒有訊息也不能區分實際不可用與已知Status/Light欄位差異。以CompanyIdentifier、DeviceNo核對服務狀態，不當作特定發票列印回執。 / Check ResultMessage for validation issues when present. Without a message, actual unavailability cannot be distinguished from the known Status/Light mismatch. Verify seller/device service state; this is not a receipt for a particular invoice." }, { "when": "timeout / disconnect / unexpected HTTP or non-JSON", "action": "裝置狀態未知；呼叫端可設定有限次退避重查，不因此重新送出開立或重印。 / Device state is unknown; callers may configure bounded backoff for this query, not resubmit issuance or reprint operations." } ] } }, "/PhoneBarCodeCheck": { "post": { "tags": [ "Provide" ], "summary": "驗證手機條碼 / Validate a mobile barcode", "description": "只使用PhoneBarCode，不驗證本文Key或舊Signature。HTTP200/Status字串1表示目前檢查通過，不保證政府已確認存在；HTTP400/Status字串0也可能是外查故障。是否外查依設定而定。手機條碼缺值/空本文可能逸出固定envelope。先確認輸入與環境，不由查核結果推定開立交易結果。 / Uses only PhoneBarCode, without body Key or legacy Signature validation. HTTP200/string Status 1 means the configured check passed, not necessarily government-confirmed existence. HTTP400/string Status 0 may also represent external-check failure. External checking is configuration-dependent. Missing fields/null bodies may escape the fixed envelope. Verify input/environment; check results do not prove an issuance outcome.", "operationId": "checkPhoneBarcode", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "CheckData", "in": "body", "description": "手機條碼驗證資料 / Mobile-barcode validation request.", "required": true, "schema": { "$ref": "#/definitions/EInvServiceCheckModel" }, "x-example": { "PhoneBarCode": "/ABC1234" } } ], "responses": { "200": { "description": "手機條碼有效 / The mobile barcode is valid.", "schema": { "$ref": "#/definitions/EInvServiceCheckResponseModel" }, "examples": { "application/json": { "Status": "1", "ResultMessage": "手機條碼 /ABC1234 有效" } } }, "400": { "description": "手機條碼無效 / The mobile barcode is invalid.", "schema": { "$ref": "#/definitions/EInvServiceCheckResponseModel" }, "examples": { "application/json": { "Status": "0", "ResultMessage": "手機條碼 /INVALID 無效" } } } }, "x-retry-policy": { "automaticRetry": false, "description": "查詢/查核可由呼叫端設定有限次退避；不能保證查核服務每次可用。 / Callers may configure bounded backoff for queries/checks; external availability is not guaranteed." }, "x-error-handling": [ { "when": "HTTP 400 / Status '0'", "action": "檢查格式及查核服務狀態；不能直接判斷該碼不存在。 / Check format and verification-service health; do not conclude the code does not exist." }, { "when": "unexpected HTTP / missing JSON", "action": "視為未完成查核，處理傳輸或未攔截例外。 / Treat as an incomplete check; handle transport or unhandled failures." } ] } }, "/PreservCodeCheck": { "post": { "tags": [ "Provide" ], "summary": "驗證捐贈碼 / Validate a donation code", "description": "只使用PreservCode，不驗證本文Key或舊Signature。HTTP200/Status字串1表示目前檢查通過，不保證政府已確認存在；HTTP400/Status字串0也可能是外查故障。是否外查依設定而定。捐贈碼缺值/空本文可能逸出固定envelope。先確認輸入與環境，不由查核結果推定開立交易結果。 / Uses only PreservCode, without body Key or legacy Signature validation. HTTP200/string Status 1 means the configured check passed, not necessarily government-confirmed existence. HTTP400/string Status 0 may also represent external-check failure. External checking is configuration-dependent. Missing fields/null bodies may escape the fixed envelope. Verify input/environment; check results do not prove an issuance outcome.", "operationId": "checkDonationCode", "consumes": [ "application/json", "text/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "name": "CheckData", "in": "body", "description": "捐贈碼驗證資料 / Donation-code validation request.", "required": true, "schema": { "$ref": "#/definitions/EInvServiceCheckModel" }, "x-example": { "PreservCode": "919" } } ], "responses": { "200": { "description": "捐贈碼有效 / The donation code is valid.", "schema": { "$ref": "#/definitions/EInvServiceCheckResponseModel" }, "examples": { "application/json": { "Status": "1", "ResultMessage": "捐贈碼 919 有效" } } }, "400": { "description": "捐贈碼無效 / The donation code is invalid.", "schema": { "$ref": "#/definitions/EInvServiceCheckResponseModel" }, "examples": { "application/json": { "Status": "0", "ResultMessage": "捐贈碼 INVALID 無效" } } } }, "x-retry-policy": { "automaticRetry": false, "description": "查詢/查核可由呼叫端設定有限次退避；不能保證查核服務每次可用。 / Callers may configure bounded backoff for queries/checks; external availability is not guaranteed." }, "x-error-handling": [ { "when": "HTTP 400 / Status '0'", "action": "檢查格式及查核服務狀態；不能直接判斷該碼不存在。 / Check format and verification-service health; do not conclude the code does not exist." }, { "when": "unexpected HTTP / missing JSON", "action": "視為未完成查核，處理傳輸或未攔截例外。 / Treat as an incomplete check; handle transport or unhandled failures." } ] } } }, "definitions": { "AppendOrderModel": { "description": "開立請求。主檔金額為整數；明細為decimal。請先讀x-integration-guide的驗證、金額、載具與重試規則。Details雖有Required，沒有已證實的最少筆數驗證。 / Issuance request with integer header amounts and decimal lines. Read x-integration-guide for auth, money, carrier and retry rules. Details is Required, without a proven minimum-count validator.", "required": [ "Details" ], "type": "object", "properties": { "ByuerIdentifier": { "description": "已淘汰的買受人統編欄位，請改用 BuyerIdentifier。/ Obsolete buyer tax identifier; use BuyerIdentifier instead.", "type": "string", "example": "0000000000" }, "BuyerIdentifier": { "description": "預設自然人0000000000，8碼企業統編走B類、其他零值走C類；會檢查統編規則。不要同送舊別名ByuerIdentifier。 / Defaults to consumer 0000000000. Business tax IDs use B and zero-valued IDs use C; identifier validation applies. Do not also send legacy ByuerIdentifier.", "default": "0000000000", "type": "string", "example": "0000000000" }, "BuyerCustomerNumber": { "description": "客戶/會員識別資料。SQL快照程序為varchar(20)，並非Model已實作的字元長度驗證。 / Customer/member identifier. SQL snapshot procedure uses varchar(20); not an implemented model character-length validator.", "type": "string", "example": "C0001" }, "BuyerEmailAddress": { "description": "買方電子郵件，最長 80 字元。/ Buyer email address, maximum 80 characters.", "maxLength": 80, "type": "string", "example": "buyer@example.com" }, "BuyerTelNo": { "description": "買方電話，伺服器會正規化並可用於會員識別；SQL快照varchar(26)。 / Buyer phone, normalized and potentially used for member identification; SQL snapshot varchar(26).", "type": "string", "example": "0912345678" }, "RelateNumber": { "description": "建議必填且每筆交易固定。複製到BillingNo供同公司去重；缺值會生成時間字串。SQL快照RelateNumber為varchar(20)、BillingNo為varchar(30)，請勿據後者假設可完整保留30字元。 / Supply a stable ID for each transaction. Copied to BillingNo for seller-scoped duplicate lookup; omission generates a timestamp. SQL snapshot RelateNumber is varchar(20), BillingNo varchar(30); do not assume 30 characters are preserved.", "type": "string", "example": "POS202609010001" }, "TaxAmount": { "format": "int64", "description": "整數稅額。一般檢查SalesAmount+TaxAmount=TotalAmount，存在商家特殊規則，見整合指南。 / Integer tax. Normal checks require SalesAmount+TaxAmount=TotalAmount, with merchant-specific rules; see integration guide.", "type": "integer", "example": 5 }, "SalesAmount": { "format": "int64", "description": "未稅銷售額。/ Sales amount excluding tax.", "type": "integer", "example": 95 }, "TotalAmount": { "format": "int64", "description": "含稅總額。/ Total amount including tax.", "type": "integer", "example": 100 }, "TaxType": { "description": "稅別：1=應稅、2=零稅率、3=免稅、4=特種稅率。/ Tax type: 1=taxable, 2=zero-rated, 3=tax-exempt, 4=special tax rate.", "type": "string", "example": "1" }, "SalesID": { "description": "交易相關人員或 POS 識別碼。/ Related operator or POS identifier.", "type": "string", "example": "POS-01" }, "CarrierType": { "description": "載具類型；允許 3J0002、CQ0001、ER0010、1K0001、2G0001、1H0001、BK0001、EK0002、EJ1520。/ Carrier type. Allowed codes: 3J0002, CQ0001, ER0010, 1K0001, 2G0001, 1H0001, BK0001, EK0002, EJ1520.", "pattern": "^3J0002|CQ0001|ER0010|1K0001|2G0001|1H0001|BK0001|EK0002|EJ1520$", "type": "string", "example": "3J0002" }, "CarrierId": { "description": "相容載具欄位；CarrierId1空值時沿用此值，之後正規化大小寫與全半形。 / Compatibility carrier ID used when CarrierId1 is empty, then normalized for case/character width.", "type": "string", "example": "/ABC1234" }, "CarrierId1": { "description": "載具顯碼。手機條碼為/加7碼[0-9A-Z+-.]；自然人憑證為2個大寫字母+14位數字；適用規則見整合指南。 / Visible ID. Mobile barcode is / plus seven [0-9A-Z+-.] characters; citizen certificate is two uppercase letters plus fourteen digits. See guide for conditional rules.", "type": "string", "example": "/ABC1234" }, "CarrierId2": { "description": "載具隱碼，最長64；缺值沿用顯碼。手機/自然人憑證顯隱碼須相同。 / Hidden ID, at most 64 characters; defaults to visible ID if empty. Mobile/citizen IDs must match.", "maxLength": 64, "type": "string", "example": "/ABC1234" }, "NPOBAN": { "description": "捐贈碼；一般格式3–7位數字。有效捐贈優先於載具，但外查失敗或零元可能先被清除。 / Donation code, normally 3–7 digits. Valid donation takes precedence over carriers, but failed external precheck or zero amounts may clear it.", "type": "string", "example": "919" }, "PrintMark": { "description": "相容欄位，GetInvoiceModel未映射到內部發票。OrderWithoutPrint雖將請求設N，最终用途仍由內部流程決定，不保證落庫N或不走紙本；待另案修正。 / Compatibility field not mapped by GetInvoiceModel. OrderWithoutPrint sets request N but internal disposition still decides the result; persisted N or no paper is not guaranteed. Pending separate fix.", "type": "string", "example": "Y", "x-runtime-mapped": false }, "Details": { "description": "必須提供的明細集合。客戶應至少1筆；程式僅Required，未發現空陣列檢核，不宣稱空陣列為受支援業務用法。 / Required line collection. Clients should supply at least one item; only Required is implemented, without a found empty-array check. Empty arrays are not promised as a supported business use.", "type": "array", "items": { "$ref": "#/definitions/AppendOrderDetailModel" }, "example": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] }, "UseFor": { "description": "服務端配置的取號/切本用途，並非固定業務enum。P開頭另寫入DeptID。示意P1須換成商家配置；SQL快照用途為2字元，省略/空值取號行為須核對環境。 / Server-configured allocation/split code, not a fixed business enum. A P prefix also sets DeptID. Replace illustrative P1 with merchant configuration; SQL snapshot codes are two characters. Verify omitted/empty allocation behavior per environment.", "default": "", "type": "string", "example": "P1" }, "CompanyIdentifier": { "description": "已配置的賣方統編；與DeviceNo/Key一起驗證。可用舊別名CompanyID，勿兩者同送。 / Provisioned seller ID validated with DeviceNo/Key. CompanyID is a legacy alias; do not send both.", "default": "", "type": "string", "example": "12345678" }, "DeviceNo": { "description": "已配置於該公司的POS裝置編號；使用測試環境配置值。 / POS device provisioned under the seller; use the test-environment value.", "type": "string", "example": "0001" }, "Key": { "description": "該公司/装置的驗證金鑰；範例僅佔位，不可將正式金鑰寫入文件或程式碼。 / Credential for the seller/device; sample is a placeholder. Never put production keys in documentation or source.", "type": "string", "example": "YOUR_TEST_KEY" }, "CompanyID": { "description": "CompanyIdentifier的讀寫別名；後反序列化的欄位可能覆蓋前者。請只傳其中一個。 / Read/write alias of CompanyIdentifier; deserialization order can overwrite the value. Send only one.", "type": "string", "example": "12345678" }, "Timestamp": { "description": "保留舊欄位；目前POSAPI受驗證操作不呼叫簽章驗證，不能替代Key。 / Retained legacy field; protected POSAPI actions do not call signature verification. Not a replacement for Key.", "type": "string", "example": "1788251400" }, "Signature": { "description": "保留舊欄位，這些POSAPI操作不驗證此簽章。 / Retained legacy field; these POSAPI operations do not validate this signature.", "type": "string", "example": "YOUR_TEST_SIGNATURE" } }, "example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "BuyerIdentifier": "0000000000", "RelateNumber": "POS202609030001", "TaxAmount": 5, "SalesAmount": 95, "TotalAmount": 100, "TaxType": "1", "UseFor": "P1", "Details": [ { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } ] }, "x-authentication-fields": [ "CompanyIdentifier", "DeviceNo", "Key" ] }, "AppendOrderDetailModel": { "description": "開立明細；數量、單價與小計為decimal，SQL快照儲存decimal(20,7)，未實作對應API精度驗證。 / Invoice line; quantity/unit price/subtotal are decimal. SQL snapshot stores decimal(20,7), without corresponding API precision validation.", "required": [ "ProductName", "Quantity", "UnitPrice", "SubTotal" ], "type": "object", "properties": { "DetailID": { "description": "選填，提供時最多3字元且符合3位數字；000可通過Model。SQL快照對缺值/000可補序號，部署待確認。 / Optional; when supplied, at most three characters matching three digits. Model accepts 000. SQL snapshot can assign sequence for omitted/000 values; deployment unverified.", "maxLength": 3, "pattern": "^[0-9]{3}", "type": "string", "example": "001" }, "ProductID": { "description": "商品或關聯編號，最長 20 字元。/ Product or related identifier, maximum 20 characters.", "maxLength": 20, "type": "string", "example": "P001" }, "ProductName": { "description": "商品名稱，最長 256 字元。/ Product name, maximum 256 characters.", "maxLength": 256, "type": "string", "example": "測試商品" }, "Quantity": { "format": "double", "description": "decimal數量；Required屬性存在，但沒有正數範圍驗證。 / Decimal quantity; Required exists but no positive-range validator.", "type": "number", "example": 1 }, "Unit": { "description": "單位，最長 6 字元。/ Unit, maximum 6 characters.", "maxLength": 6, "type": "string", "example": "個" }, "UnitPrice": { "format": "double", "description": "decimal單價；沒有統一的小數位/捨入Model驗證。 / Decimal unit price; no uniform model-scale or rounding validator.", "type": "number", "example": 100 }, "SubTotal": { "format": "double", "description": "由呼叫端計算並提供的小計；本路徑不重算或逐筆驗證Quantity×UnitPrice。企業買受人通常使用未稅明細，見金額規則。 / Client-calculated subtotal; this path neither recalculates nor validates Quantity*UnitPrice per line. Business buyers normally use tax-exclusive lines; see money rules.", "type": "number", "example": 100 }, "Remark": { "description": "明細備註，最長 40 字元。/ Line remark, maximum 40 characters.", "maxLength": 40, "type": "string", "example": "" } }, "example": { "DetailID": "001", "ProductID": "P001", "ProductName": "測試商品", "Quantity": 1, "Unit": "個", "UnitPrice": 100, "SubTotal": 100, "Remark": "" } }, "ResponseAppendOrderModel": { "description": "電子發票開立結果。/ E-invoice issuance result.", "type": "object", "properties": { "RelateNumber": { "description": "原 POS 訂單或交易識別碼。/ Original POS order or transaction identifier.", "type": "string", "example": "POS202609010001" }, "InvoiceNumber": { "description": "電子發票號碼，格式為兩碼英文字母加八碼數字。/ E-invoice number: two letters followed by eight digits.", "type": "string", "example": "AA12345678" }, "InvoiceDateTime": { "format": "date-time", "description": "內部發票建立時取台北時間，POS請求不能指定；通常無offset。Order與OrderReturnQKey會清除失敗時日期，WithoutPrint不做這項清除；不要把無offset當UTC。 / Internal invoice creation uses Taipei time, not a POS-supplied field; normally no offset. Order/OrderReturnQKey clear it on failure, WithoutPrint does not. Do not interpret offsetless values as UTC.", "type": "string", "example": "2026-09-01T16:30:00" }, "PrintCode": { "description": "PrintCode通常為無分隔大寫hex，每2字元解1byte再送符合裝置的通道，不是Base64/UTF-8文字。MachineType含code回碼，否則排印且可能省略碼；wp選WinPos，其餘Epson。1B40僅初始化片段，不是完整發票。PrintCode=Error不可送印；成功不證明實體完成。PrintDataString為10段|分隔文字/條碼資料，須保留空白，非命令或QR圖片。 / PrintCode is normally separator-free uppercase hex: decode pairs to bytes for the configured printer channel, not Base64/UTF-8 text. MachineType containing code returns commands, otherwise queues and may omit them; wp selects WinPos, otherwise Epson. 1B40 is only an initialization fragment, not a complete invoice. Never print Error; success does not prove physical completion. PrintDataString is ten pipe-delimited text/barcode sections; preserve spaces. It is not commands or a QR image.", "type": "string", "example": "1B40", "x-example-purpose": "Epson初始化片段，不是完整可列印發票。 / Epson initialization fragment, not a complete printable invoice." }, "PrintDataString": { "description": "10段以|分隔的顯示/條碼資料，詳見x-integration-guide.printing.printDataSections；保留所有空白，不作PrintCode解碼。範例QR段為佔位，不能列印正式發票。 / Ten pipe-delimited display/barcode sections; see x-integration-guide.printing.printDataSections. Preserve spaces; do not decode as PrintCode. Sample QR segments are placeholders, not a printable invoice.", "type": "string", "example": "電子發票證明聯|115年09-10月|AA-12345678|2026-09-03 16:30:00|隨機碼:9999 總計:100|賣方:12345678|BARCODE_SAMPLE|LEFT_QR_SAMPLE|RIGHT_QR_SAMPLE|RN:POS202609030001" }, "ShortCode": { "description": "LINE 歸戶短碼；部分流程成功後會清空。/ LINE carrier-binding short code; some flows clear it after success.", "type": "string", "example": "AB12CD" }, "AuthCode": { "description": "發票連結授權碼。/ Invoice-link authorization code.", "type": "string", "example": "AUTH1234" }, "QrCodeUrl": { "description": "條件性產生的歸戶URL，視為不透明字串使用，不自行組合或解密。Member export可能有資料副作用，見整合指南。 / Conditionally generated opaque carrier URL; do not construct or decrypt it. Member export may mutate data; see integration guide.", "type": "string", "example": "https://example.invalid/carrier/QR123" }, "QKey": { "description": "只有成功且ShortCode非空才嘗試產生；格式為發票末2碼+檢查碼。示例789999不能代替實際回應。 / Only attempted on success with nonempty ShortCode; final two invoice digits plus check number. Sample 789999 is not an actual response token.", "type": "string", "example": "789999" }, "ShowMessage": { "description": "顯示給使用者的訊息。/ Message intended for display to the user.", "type": "string", "example": "發票開立成功" }, "MessageCode": { "description": "可選的業務代碼；開立重複已確認DUPLICATE_ORDER。沒有完整固定錯誤碼表，不假定成功固定回SUCCESS。 / Optional business code; issuance duplicate is confirmed as DUPLICATE_ORDER. No complete fixed error catalog; do not assume SUCCESS is emitted.", "type": "string", "example": "DUPLICATE_ORDER" }, "ResultMessage": { "description": "中文執行結果或錯誤訊息。/ Chinese result or error message.", "type": "string", "example": "執行成功" }, "EnglishResultMessage": { "description": "英文執行結果或錯誤訊息；部分流程可能不回傳。/ English result or error message; some flows may omit it.", "type": "string", "example": "Success" }, "StatusCode": { "format": "int32", "description": "數字0=未成功、1=同步流程回報成功，不是HTTP狀態或外部上傳/實體列印完成證明；留意已知列印Error例外。 / Numeric 0=not successful, 1=synchronous flow reports success; not HTTP status or proof of external upload/physical print. Note the known print Error exception.", "type": "integer", "example": 1 } }, "example": { "StatusCode": 1, "RelateNumber": "POS202609030001", "InvoiceNumber": "AA12345678", "InvoiceDateTime": "2026-09-03T16:30:00" } }, "RequestAssignNo_UseState_Model": { "description": "字軌使用狀態查詢。/ Invoice-number usage query.", "type": "object", "properties": { "UseFor": { "description": "服務端配置的取號/切本用途，並非固定業務enum。P開頭另寫入DeptID。示意P1須換成商家配置；SQL快照用途為2字元，省略/空值取號行為須核對環境。 / Server-configured allocation/split code, not a fixed business enum. A P prefix also sets DeptID. Replace illustrative P1 with merchant configuration; SQL snapshot codes are two characters. Verify omitted/empty allocation behavior per environment.", "default": "", "type": "string", "example": "P1" }, "YearMonth": { "description": "五字元民國年+雙月末月(02/04/06/08/10/12)，11510=2026年9–10月。沒有Required；省略不保證當期。既有regex問題另列。 / Five-character ROC year plus period-ending month (02/04/06/08/10/12); 11510 means Sep–Oct 2026. Not Required; omission does not guarantee current period. Existing regex issue is listed separately.", "maxLength": 5, "pattern": "1[0-9][0-9]0[2|4|6|8]|1[0-9][0-9]1[0|2]", "type": "string", "example": "11510" }, "CompanyIdentifier": { "description": "已配置的賣方統編；與DeviceNo/Key一起驗證。可用舊別名CompanyID，勿兩者同送。 / Provisioned seller ID validated with DeviceNo/Key. CompanyID is a legacy alias; do not send both.", "default": "", "type": "string", "example": "12345678" }, "DeviceNo": { "description": "已配置於該公司的POS裝置編號；使用測試環境配置值。 / POS device provisioned under the seller; use the test-environment value.", "type": "string", "example": "0001" }, "Key": { "description": "該公司/装置的驗證金鑰；範例僅佔位，不可將正式金鑰寫入文件或程式碼。 / Credential for the seller/device; sample is a placeholder. Never put production keys in documentation or source.", "type": "string", "example": "YOUR_TEST_KEY" }, "CompanyID": { "description": "CompanyIdentifier的讀寫別名；後反序列化的欄位可能覆蓋前者。請只傳其中一個。 / Read/write alias of CompanyIdentifier; deserialization order can overwrite the value. Send only one.", "type": "string", "example": "12345678" }, "Timestamp": { "description": "保留舊欄位；目前POSAPI受驗證操作不呼叫簽章驗證，不能替代Key。 / Retained legacy field; protected POSAPI actions do not call signature verification. Not a replacement for Key.", "type": "string", "example": "1788251400" }, "Signature": { "description": "保留舊欄位，這些POSAPI操作不驗證此簽章。 / Retained legacy field; these POSAPI operations do not validate this signature.", "type": "string", "example": "YOUR_TEST_SIGNATURE" } }, "example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "UseFor": "P1", "YearMonth": "11510" }, "x-authentication-fields": [ "CompanyIdentifier", "DeviceNo", "Key" ] }, "ResponseAssignNo_UseState_Model": { "description": "字軌使用狀態查詢結果。/ Invoice-number usage query result.", "type": "object", "properties": { "UseStatus": { "description": "各用途的字軌使用統計。/ Invoice-number usage statistics by usage code.", "type": "array", "items": { "$ref": "#/definitions/proc_EInv_AssignNoGetUseState_Result" }, "example": [ { "CompanyIdentifier": "12345678", "YearMonth": "11510", "UseFor": "P1", "NonUseCount": 800, "UseCount": 200, "NextInvoiceNumber": "AA12345878" } ] }, "MessageCode": { "description": "可選的業務代碼；開立重複已確認DUPLICATE_ORDER。沒有完整固定錯誤碼表，不假定成功固定回SUCCESS。 / Optional business code; issuance duplicate is confirmed as DUPLICATE_ORDER. No complete fixed error catalog; do not assume SUCCESS is emitted.", "type": "string", "example": "DUPLICATE_ORDER" }, "ResultMessage": { "description": "中文執行結果或錯誤訊息。/ Chinese result or error message.", "type": "string", "example": "執行成功" }, "EnglishResultMessage": { "description": "英文執行結果或錯誤訊息；部分流程可能不回傳。/ English result or error message; some flows may omit it.", "type": "string", "example": "Success" }, "StatusCode": { "format": "int32", "description": "數字0=未成功、1=同步流程回報成功，不是HTTP狀態或外部上傳/實體列印完成證明；留意已知列印Error例外。 / Numeric 0=not successful, 1=synchronous flow reports success; not HTTP status or proof of external upload/physical print. Note the known print Error exception.", "type": "integer", "example": 1 } }, "example": { "StatusCode": 1, "UseStatus": [ { "CompanyIdentifier": "12345678", "YearMonth": "11510", "UseFor": "P1", "NonUseCount": 800, "UseCount": 200, "NextInvoiceNumber": "AA12345878" } ] } }, "proc_EInv_AssignNoGetUseState_Result": { "description": "單一字軌用途的使用統計。/ Usage statistics for one invoice-number usage code.", "type": "object", "properties": { "CompanyIdentifier": { "description": "賣方統一編號。/ Seller tax identifier.", "type": "string", "example": "12345678" }, "YearMonth": { "description": "民國年月 yyyMM。/ ROC year and month in yyyMM format.", "type": "string", "example": "11510" }, "UseFor": { "description": "服務端配置的取號/切本用途，並非固定業務enum。P開頭另寫入DeptID。示意P1須換成商家配置；SQL快照用途為2字元，省略/空值取號行為須核對環境。 / Server-configured allocation/split code, not a fixed business enum. A P prefix also sets DeptID. Replace illustrative P1 with merchant configuration; SQL snapshot codes are two characters. Verify omitted/empty allocation behavior per environment.", "type": "string", "example": "P1" }, "NonUseCount": { "format": "int32", "description": "尚未使用的發票號碼數量；可能為 null。/ Count of unused invoice numbers; may be null.", "type": "integer", "example": 800 }, "UseCount": { "format": "int32", "description": "已使用的發票號碼數量。/ Count of used invoice numbers.", "type": "integer", "example": 200 }, "NextInvoiceNumber": { "description": "查詢時的下一號資訊，可能省略；查詢不保留號碼，不可當成可自行開立的保證。 / Next-number information at query time, possibly omitted. Query does not reserve it or guarantee client-controlled issuance.", "type": "string", "example": "AA12345878" } }, "example": { "CompanyIdentifier": "12345678", "YearMonth": "11510", "UseFor": "P1", "NonUseCount": 800, "UseCount": 200, "NextInvoiceNumber": "AA12345878" } }, "RequestCancel_Model": { "description": "電子發票作廢請求。/ E-invoice cancellation request.", "required": [ "InvoiceNumber" ], "type": "object", "properties": { "InvoiceNumber": { "description": "發票號碼：兩碼英文字母加八碼數字。/ Invoice number: two letters followed by eight digits.", "pattern": "^[a-zA-Z]{2}[0-9]{8}$", "type": "string", "example": "AA12345678" }, "CancelDate": { "format": "date-time", "description": "建立請求模型時預設UTC+08時間，輸出通常沒有offset，不是作廢完成時間。若自行提供時區/offset請先與環境驗證。 / Defaults to UTC+08 local time when the request model is created, normally serialized without offset; not cancellation-completion time. Verify explicitly supplied offsets with the environment.", "type": "string", "example": "2026-09-01T16:30:00" }, "CancelReason": { "description": "最長20字元。C#不填預設；SQL 2026-05-11快照對空值/空字串使用「訂單作廢」，部署版本待確認。 / At most 20 characters. C# sets no default; the 2026-05-11 SQL snapshot substitutes 訂單作廢 for null/empty. Verify deployed version.", "maxLength": 20, "minLength": 0, "type": "string", "example": "消費者退貨" }, "ReturnTaxDocumentNumber": { "description": "最長60的作廢核准文號。僅提供此欄不保證可跨期作廢；正式流程及部署SQL需確認。 / Cancellation approval number up to 60 characters. Supplying it alone does not guarantee late cancellation; confirm workflow and deployed SQL.", "maxLength": 60, "minLength": 0, "type": "string", "example": "APPROVAL-20260901" }, "Remark": { "description": "備註，最長 200 字元。/ Remark, maximum 200 characters.", "maxLength": 200, "minLength": 0, "type": "string", "example": "測試作廢" }, "SalesID": { "description": "相關使用者、業務或會計識別碼。/ Related user, salesperson, or accountant identifier.", "type": "string", "example": "POS-01" }, "BlankCancel": { "description": "預設N，客戶僅應傳Y/N。既有regex也接受|，不代表|有定義的業務意義。 / Defaults to N; clients should send Y/N. Existing regex also accepts |, without defined business meaning.", "default": "N", "pattern": "^[Y|N]$", "type": "string", "example": "N" }, "CompanyIdentifier": { "description": "已配置的賣方統編；與DeviceNo/Key一起驗證。可用舊別名CompanyID，勿兩者同送。 / Provisioned seller ID validated with DeviceNo/Key. CompanyID is a legacy alias; do not send both.", "default": "", "type": "string", "example": "12345678" }, "DeviceNo": { "description": "已配置於該公司的POS裝置編號；使用測試環境配置值。 / POS device provisioned under the seller; use the test-environment value.", "type": "string", "example": "0001" }, "Key": { "description": "該公司/装置的驗證金鑰；範例僅佔位，不可將正式金鑰寫入文件或程式碼。 / Credential for the seller/device; sample is a placeholder. Never put production keys in documentation or source.", "type": "string", "example": "YOUR_TEST_KEY" }, "CompanyID": { "description": "CompanyIdentifier的讀寫別名；後反序列化的欄位可能覆蓋前者。請只傳其中一個。 / Read/write alias of CompanyIdentifier; deserialization order can overwrite the value. Send only one.", "type": "string", "example": "12345678" }, "Timestamp": { "description": "保留舊欄位；目前POSAPI受驗證操作不呼叫簽章驗證，不能替代Key。 / Retained legacy field; protected POSAPI actions do not call signature verification. Not a replacement for Key.", "type": "string", "example": "1788251400" }, "Signature": { "description": "保留舊欄位，這些POSAPI操作不驗證此簽章。 / Retained legacy field; these POSAPI operations do not validate this signature.", "type": "string", "example": "YOUR_TEST_SIGNATURE" } }, "example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "InvoiceNumber": "AA12345678", "CancelDate": "2026-09-01T16:30:00", "CancelReason": "消費者退貨", "Remark": "測試作廢", "SalesID": "POS-01", "BlankCancel": "N" }, "x-authentication-fields": [ "CompanyIdentifier", "DeviceNo", "Key" ] }, "ResponseCancel_Model": { "description": "電子發票作廢結果。/ E-invoice cancellation result.", "type": "object", "properties": { "CancelInvoiceNumber": { "description": "已作廢的發票號碼。/ Cancelled invoice number.", "type": "string", "example": "AA12345678" }, "CancelDate": { "format": "date-time", "description": "成功時回傳請求模型的日期；部分失敗未設定時為0001-01-01T00:00:00，不代表有效作廢日期。 / Echoes request-model date on success; some failures leave 0001-01-01T00:00:00, which is not a valid cancellation time.", "type": "string", "example": "2026-09-01T16:30:00" }, "MessageCode": { "description": "可選的業務代碼；開立重複已確認DUPLICATE_ORDER。沒有完整固定錯誤碼表，不假定成功固定回SUCCESS。 / Optional business code; issuance duplicate is confirmed as DUPLICATE_ORDER. No complete fixed error catalog; do not assume SUCCESS is emitted.", "type": "string", "example": "DUPLICATE_ORDER" }, "ResultMessage": { "description": "中文執行結果或錯誤訊息。/ Chinese result or error message.", "type": "string", "example": "執行成功" }, "EnglishResultMessage": { "description": "英文執行結果或錯誤訊息；部分流程可能不回傳。/ English result or error message; some flows may omit it.", "type": "string", "example": "Success" }, "StatusCode": { "format": "int32", "description": "數字0=未成功、1=同步流程回報成功，不是HTTP狀態或外部上傳/實體列印完成證明；留意已知列印Error例外。 / Numeric 0=not successful, 1=synchronous flow reports success; not HTTP status or proof of external upload/physical print. Note the known print Error exception.", "type": "integer", "example": 1 } }, "example": { "StatusCode": 1, "ResultMessage": "Invoice AA12345678 Cancel Success", "CancelInvoiceNumber": "AA12345678", "CancelDate": "2026-09-03T16:30:00" } }, "RequestReprintModel": { "description": "發票重新列印請求。/ Invoice reprint request.", "required": [ "InvoiceNumber" ], "type": "object", "properties": { "InvoiceNumber": { "description": "發票號碼：兩碼英文字母加八碼數字。/ Invoice number: two letters followed by eight digits.", "pattern": "^[a-zA-Z]{2}[0-9]{8}$", "type": "string", "example": "AA12345678" }, "CompanyIdentifier": { "description": "已配置的賣方統編；與DeviceNo/Key一起驗證。可用舊別名CompanyID，勿兩者同送。 / Provisioned seller ID validated with DeviceNo/Key. CompanyID is a legacy alias; do not send both.", "default": "", "type": "string", "example": "12345678" }, "DeviceNo": { "description": "已配置於該公司的POS裝置編號；使用測試環境配置值。 / POS device provisioned under the seller; use the test-environment value.", "type": "string", "example": "0001" }, "Key": { "description": "該公司/装置的驗證金鑰；範例僅佔位，不可將正式金鑰寫入文件或程式碼。 / Credential for the seller/device; sample is a placeholder. Never put production keys in documentation or source.", "type": "string", "example": "YOUR_TEST_KEY" }, "CompanyID": { "description": "CompanyIdentifier的讀寫別名；後反序列化的欄位可能覆蓋前者。請只傳其中一個。 / Read/write alias of CompanyIdentifier; deserialization order can overwrite the value. Send only one.", "type": "string", "example": "12345678" }, "Timestamp": { "description": "保留舊欄位；目前POSAPI受驗證操作不呼叫簽章驗證，不能替代Key。 / Retained legacy field; protected POSAPI actions do not call signature verification. Not a replacement for Key.", "type": "string", "example": "1788251400" }, "Signature": { "description": "保留舊欄位，這些POSAPI操作不驗證此簽章。 / Retained legacy field; these POSAPI operations do not validate this signature.", "type": "string", "example": "YOUR_TEST_SIGNATURE" } }, "example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY", "InvoiceNumber": "AA12345678" }, "x-authentication-fields": [ "CompanyIdentifier", "DeviceNo", "Key" ] }, "ResponseReprintModel": { "description": "發票重新列印結果。/ Invoice reprint result.", "type": "object", "properties": { "PrintCode": { "description": "PrintCode通常為無分隔大寫hex，每2字元解1byte再送符合裝置的通道，不是Base64/UTF-8文字。MachineType含code回碼，否則排印且可能省略碼；wp選WinPos，其餘Epson。1B40僅初始化片段，不是完整發票。PrintCode=Error不可送印；成功不證明實體完成。PrintDataString為10段|分隔文字/條碼資料，須保留空白，非命令或QR圖片。 / PrintCode is normally separator-free uppercase hex: decode pairs to bytes for the configured printer channel, not Base64/UTF-8 text. MachineType containing code returns commands, otherwise queues and may omit them; wp selects WinPos, otherwise Epson. 1B40 is only an initialization fragment, not a complete invoice. Never print Error; success does not prove physical completion. PrintDataString is ten pipe-delimited text/barcode sections; preserve spaces. It is not commands or a QR image.", "type": "string", "example": "1B40", "x-example-purpose": "Epson初始化片段，不是完整可列印發票。 / Epson initialization fragment, not a complete printable invoice." }, "MessageCode": { "description": "可選的業務代碼；開立重複已確認DUPLICATE_ORDER。沒有完整固定錯誤碼表，不假定成功固定回SUCCESS。 / Optional business code; issuance duplicate is confirmed as DUPLICATE_ORDER. No complete fixed error catalog; do not assume SUCCESS is emitted.", "type": "string", "example": "DUPLICATE_ORDER" }, "ResultMessage": { "description": "中文執行結果或錯誤訊息。/ Chinese result or error message.", "type": "string", "example": "執行成功" }, "EnglishResultMessage": { "description": "英文執行結果或錯誤訊息；部分流程可能不回傳。/ English result or error message; some flows may omit it.", "type": "string", "example": "Success" }, "StatusCode": { "format": "int32", "description": "數字0=未成功、1=同步流程回報成功，不是HTTP狀態或外部上傳/實體列印完成證明；留意已知列印Error例外。 / Numeric 0=not successful, 1=synchronous flow reports success; not HTTP status or proof of external upload/physical print. Note the known print Error exception.", "type": "integer", "example": 1 } }, "example": { "StatusCode": 1 } }, "RequestAuthBase": { "description": "本文公司/裝置/金鑰驗證；CompanyID為別名。舊簽章欄位存在但此專案操作未使用。 / Body seller/device/key authentication; CompanyID is an alias. Legacy signature fields exist but are unused by these operations.", "type": "object", "properties": { "CompanyIdentifier": { "description": "已配置的賣方統編；與DeviceNo/Key一起驗證。可用舊別名CompanyID，勿兩者同送。 / Provisioned seller ID validated with DeviceNo/Key. CompanyID is a legacy alias; do not send both.", "default": "", "type": "string", "example": "12345678" }, "DeviceNo": { "description": "已配置於該公司的POS裝置編號；使用測試環境配置值。 / POS device provisioned under the seller; use the test-environment value.", "type": "string", "example": "0001" }, "Key": { "description": "該公司/装置的驗證金鑰；範例僅佔位，不可將正式金鑰寫入文件或程式碼。 / Credential for the seller/device; sample is a placeholder. Never put production keys in documentation or source.", "type": "string", "example": "YOUR_TEST_KEY" }, "CompanyID": { "description": "CompanyIdentifier的讀寫別名；後反序列化的欄位可能覆蓋前者。請只傳其中一個。 / Read/write alias of CompanyIdentifier; deserialization order can overwrite the value. Send only one.", "type": "string", "example": "12345678" }, "Timestamp": { "description": "保留舊欄位；目前POSAPI受驗證操作不呼叫簽章驗證，不能替代Key。 / Retained legacy field; protected POSAPI actions do not call signature verification. Not a replacement for Key.", "type": "string", "example": "1788251400" }, "Signature": { "description": "保留舊欄位，這些POSAPI操作不驗證此簽章。 / Retained legacy field; these POSAPI operations do not validate this signature.", "type": "string", "example": "YOUR_TEST_SIGNATURE" } }, "example": { "CompanyIdentifier": "12345678", "DeviceNo": "0001", "Key": "YOUR_TEST_KEY" }, "x-authentication-fields": [ "CompanyIdentifier", "DeviceNo", "Key" ] }, "ResponseBase": { "description": "POS API 共用回應欄位。/ Common POS API response fields.", "type": "object", "properties": { "MessageCode": { "description": "可選的業務代碼；開立重複已確認DUPLICATE_ORDER。沒有完整固定錯誤碼表，不假定成功固定回SUCCESS。 / Optional business code; issuance duplicate is confirmed as DUPLICATE_ORDER. No complete fixed error catalog; do not assume SUCCESS is emitted.", "type": "string", "example": "DUPLICATE_ORDER" }, "ResultMessage": { "description": "中文執行結果或錯誤訊息。/ Chinese result or error message.", "type": "string", "example": "執行成功" }, "EnglishResultMessage": { "description": "英文執行結果或錯誤訊息；部分流程可能不回傳。/ English result or error message; some flows may omit it.", "type": "string", "example": "Success" }, "StatusCode": { "format": "int32", "description": "數字0=未成功、1=同步流程回報成功，不是HTTP狀態或外部上傳/實體列印完成證明；留意已知列印Error例外。 / Numeric 0=not successful, 1=synchronous flow reports success; not HTTP status or proof of external upload/physical print. Note the known print Error exception.", "type": "integer", "example": 1 } }, "example": { "StatusCode": 1 } }, "EInvServiceCheckModel": { "description": "手機條碼或捐贈碼驗證資料。兩個 endpoint 共用此 Model，請只填入該 endpoint 使用的欄位。/ Mobile-barcode or donation-code validation data. Both endpoints share this model; supply only the field used by the selected endpoint.", "type": "object", "properties": { "PhoneBarCode": { "description": "手機條碼；PhoneBarCodeCheck 使用。/ Mobile barcode used by PhoneBarCodeCheck.", "type": "string", "example": "/ABC1234" }, "PreservCode": { "description": "捐贈碼；PreservCodeCheck 使用。/ Donation code used by PreservCodeCheck.", "type": "string", "example": "919" }, "CompanyIdentifier": { "description": "此兩個驗證 endpoint 目前未使用的公司統編欄位。/ Company identifier currently unused by these two validation endpoints.", "type": "string", "example": "12345678" }, "Signature": { "description": "此兩個驗證 endpoint 目前未使用的簽章欄位。/ Signature currently unused by these two validation endpoints.", "type": "string", "example": "YOUR_TEST_SIGNATURE" }, "InvoiceStartDate": { "format": "date-time", "description": "此兩個驗證 endpoint 目前未使用的發票起始日期。/ Invoice start date currently unused by these two validation endpoints.", "type": "string", "example": "2026-08-31T00:00:00" }, "DayRange": { "format": "int32", "description": "此兩個驗證 endpoint 目前未使用的查詢天數。/ Query-day range currently unused by these two validation endpoints.", "type": "integer", "example": 1 } }, "example": { "PhoneBarCode": "/ABC1234" } }, "EInvServiceCheckResponseModel": { "description": "手機條碼或捐贈碼驗證結果。/ Mobile-barcode or donation-code validation result.", "type": "object", "properties": { "Status": { "description": "驗證狀態字串：0=失敗、1=成功。/ Validation status string: 0=failure, 1=success.", "type": "string", "example": "1" }, "ResultMessage": { "description": "中文驗證結果。/ Chinese validation result message.", "type": "string", "example": "驗證成功" } }, "example": { "Status": "1", "ResultMessage": "驗證成功" } } }, "securityDefinitions": { "apiKey": { "type": "apiKey", "description": "選用的 x-api-key Header / Optional x-api-key header. 使用 RequestAuthBase 的 endpoint 仍會驗證 request body 中的 CompanyIdentifier、DeviceNo 與 Key。/ Endpoints using RequestAuthBase also validate CompanyIdentifier, DeviceNo, and Key in the request body.", "name": "x-api-key", "in": "header" } }, "x-contract-revision": "2026-09-03", "x-integration-guide": { "authentication": { "bodyFields": [ "CompanyIdentifier", "DeviceNo", "Key" ], "description": "受驗證操作呼叫 CheckKey，比對資料庫公司/裝置/金鑰，回1才通過。CompanyID 是公司欄位別名，請勿兩者同送；Timestamp/Signature不參與本專案這些操作的驗證。Header不替代本文憑證。三欄沒有Required驗證，不保證缺值回欄位錯誤。部署層額外驗證待確認。 / Protected operations call CheckKey and require database result 1 for seller/device/key. CompanyID aliases CompanyIdentifier; do not send both. Timestamp/Signature are not checked by these operations. Headers do not replace body credentials. The three fields lack Required validators; missing values do not guarantee field errors. Deployment-layer auth remains unverified." }, "retry": { "automaticRetry": false, "duplicateKey": [ "CompanyIdentifier", "BillingNo" ], "description": "非空RelateNumber複製到BillingNo；缺值則生成時間字串，不能可靠去重。repo查詢找公司+BillingNo最近一張非C/B狀態發票，不保證永久冪等或併發exactly-once。DUPLICATE_ORDER回StatusCode=0與既有InvoiceNumber；Order還可能重印及通知。逾時保留原訂單號/請求/時間，停自動重送並核對結果；核對入口待Q1。 / Nonempty RelateNumber becomes BillingNo; omission generates a timestamp and cannot reliably deduplicate. The repo query finds the latest invoice for seller+BillingNo outside C/B states, without permanent idempotency or concurrent exactly-once guarantees. DUPLICATE_ORDER returns StatusCode=0 and an existing InvoiceNumber; Order may also reprint and notify. Preserve the original ID/request/time after timeout, stop resubmission and reconcile; entry point pending Q1." }, "money": { "description": "主檔金額為int64整數；明細數量/單價/小計為decimal，SubTotal由客戶填入、不會重算。通常檢查SalesAmount+TaxAmount=TotalAmount；B/E類明細總和與銷售額差不得超過2，應稅時明細總和×0.05與稅額差不得超過2，存在商家豁免/覆寫。SQL快照明細為decimal(20,7)，不是API精度驗證；通用捨入政策待確認。 / Header amounts are int64 integers; line quantity/unit price/subtotal are decimal. Clients supply SubTotal, which is not recalculated. Normal checks require SalesAmount+TaxAmount=TotalAmount; B/E allow at most 2 difference between line sum and sales, and taxable line sum*0.05 and tax, with merchant exemptions/overrides. SQL snapshot storage is decimal(20,7), not an API precision validator; general rounding policy remains unconfirmed.", "sources": [ "Product.EInvoice.BPL/Invoice/InvoiceDataCheck.cs", "Product.EInvoice.BPL/Invoice/InvoiceDataReplace.cs", "docs/EInvoice_20260511_Export.sql:55841" ] }, "carrier": { "description": "先正規化再決定用途。企業買受人清除載具/捐贈；自然人有效捐贈優先。缺公用載具時依會員資料及商家開關走會員、代保管或拒絕。無效手機條碼可能轉會員或預設捐贈080088；外查不可用可按本地格式接受。自然人憑證格式/顯隱碼不一致會拒絕。捐贈前置外查失敗或零元可清除捐贈碼，故不保證保留請求用途。 / Normalize before disposition. Business buyers clear carrier/donation; valid consumer donation takes precedence. Missing public carrier may resolve to member, managed print or rejection based on member data/settings. Invalid mobile barcodes may fall back to member/default donation 080088; unavailable checks may be accepted by local format. Invalid citizen-certificate format/mismatched IDs is rejected. Donation precheck failure or zero amount may clear donation, so requested disposition is not guaranteed.", "sources": [ "Product.EInvoice.BPL/Invoice/InvoiceDataReplace.cs", "Product.EInvoice.CommonLib/Invoice/Carrier/InvoiceCarrierProcessor.cs" ] }, "printing": { "description": "PrintCode通常為無分隔大寫hex，每2字元解1byte再送符合裝置的通道，不是Base64/UTF-8文字。MachineType含code回碼，否則排印且可能省略碼；wp選WinPos，其餘Epson。1B40僅初始化片段，不是完整發票。PrintCode=Error不可送印；成功不證明實體完成。PrintDataString為10段|分隔文字/條碼資料，須保留空白，非命令或QR圖片。 / PrintCode is normally separator-free uppercase hex: decode pairs to bytes for the configured printer channel, not Base64/UTF-8 text. MachineType containing code returns commands, otherwise queues and may omit them; wp selects WinPos, otherwise Epson. 1B40 is only an initialization fragment, not a complete invoice. Never print Error; success does not prove physical completion. PrintDataString is ten pipe-delimited text/barcode sections; preserve spaces. It is not commands or a QR image.", "printDataSections": [ "title", "period", "invoiceNumber", "displayDateTime", "randomCodeAndAmount", "sellerBuyerText", "barcode", "leftQrPayload", "rightQrPayload", "RN:RelateNumber or PD:timestamp" ], "sources": [ "Product.EInvoice.BPL/Print/PrintProcess.cs", "Product.EInvoice.CommonLib/Helper/BytesConverterHelper.cs", "Product.EInvoice.Printer/EpsonTMT70II/Invoice.cs:519" ] }, "sqlSnapshot": "SQL證據來自2026-05-11快照與repo獨立SQL，不是部署證明。RePrint可能改隨機碼/載具/列印註記；Member export可能改捐贈/載具；作廢可排Turnkey工作。同步成功不代表財政部接收完成，以上非唯讀流程。 / SQL evidence comes from the 2026-05-11 snapshot and standalone repo SQL, not deployment verification. RePrint may change random code/carrier/print flags; Member export may change donation/carrier state; cancellation may enqueue Turnkey work. Synchronous success is not completed government receipt; these are not read-only flows." }, "x-known-issues": [ { "id": "printmark-not-mapped", "description": "GetInvoiceModel未映射PrintMark。OrderWithoutPrint只改請求物件，不保證最終註記N或不走紙本。 / GetInvoiceModel does not map PrintMark. OrderWithoutPrint only changes the request, not guaranteeing final N or no paper disposition.", "source": "Product.EInvoice.Model/Api/Invoice/AppendOrderModel.cs:GetInvoiceModel" }, { "id": "blankcancel-pattern", "description": "BlankCancel regex也接受|；客戶僅應傳Y/N，本次不改runtime。 / BlankCancel regex also accepts |; clients should send only Y/N. Runtime unchanged.", "source": "Product.EInvoice.Model/Api/Invoice/RequestCancel_Model.cs" }, { "id": "yearmonth-pattern", "description": "YearMonth regex字元集合含|；客戶須傳有效期別，本次不改驗證。 / YearMonth regex character classes include |; clients must send valid periods. Validation unchanged.", "source": "Product.EInvoice.Model/Api/AssignNo/RequestAssignNo_UseState_Model.cs" }, { "id": "print-error-sentinel", "description": "排隊寫入失敗可能仍回StatusCode=1、PrintCode=Error，不可解碼/送印，需人工核對。 / Queue-write failure may return StatusCode=1 with PrintCode=Error. Do not decode/print it; reconcile manually.", "source": "Product.EInvoice.BPL/Print/PrintProcess.cs:GetPrintCode" }, { "id": "printer-status-column", "description": "C#比對Status=Green，SQL快照卻用Light傳Green；可能誤報不可用，部署程序待確認。 / C# compares Status to Green while the SQL snapshot uses Light, potentially misreporting availability. Verify deployed procedure.", "source": "Product.EInvoice.BPL/Print/PrinterStatus.cs; docs/EInvoice_20260511_Export.sql:71459" }, { "id": "unhandled-input", "description": "部分空本文、缺手機條碼及DB例外未統一攔截，可能不回宣告的業務envelope。 / Some null bodies, missing mobile barcodes and DB exceptions escape handling and may not return the documented business envelope.", "source": "Product.EInvoice.Api4Pos/Controllers; Product.EInvoice.CommonLib/Helper/EInvServiceHelper.cs" }, { "id": "empty-details", "description": "Details有Required但未找到最小筆數檢核。客戶應至少傳1筆；不宣稱runtime有minItems保證。 / Details is Required but no minimum-count validation was found. Clients should send at least one item; no runtime minItems guarantee.", "source": "Product.EInvoice.Model/Api/Invoice/AppendOrderModel.cs" } ], "x-open-questions": [ { "id": "Q1", "priority": "high", "question": "逾時後用哪個系統/客服流程核對訂單、作廢與列印結果？ / Which system/support workflow reconciles order, cancellation and print outcomes after timeout?", "needed": "查詢入口與負責人；9個endpoint沒有依RelateNumber查開立狀態的專用操作。 / Reconciliation entry point and owner; the nine endpoints have no dedicated issuance-status lookup by RelateNumber." }, { "id": "Q2", "priority": "high", "question": "部署SQL是否與快照一致，尤其字軌、重印、Member export、PrinterStatus與跨期作廢？ / Does deployed SQL match the snapshot, especially allocation, reprint, Member export, PrinterStatus and late cancellation?", "needed": "去敏感程序定義；UseState程序本體不在repo。 / Sanitized procedure definitions; the UseState procedure body is absent from the repo." }, { "id": "Q3", "priority": "high", "question": "各商家POS的UseFor、列印模式、會員載具及外部查核設定？ / What UseFor, printer mode, member-carrier and external-check settings apply per merchant POS?", "needed": "測試商家設定表，不提供正式金鑰。 / Test-merchant configuration table without production secrets." }, { "id": "Q4", "priority": "medium", "question": "商家特殊金額規則、捨入及超過7位小數的對外政策？ / What merchant-specific amount, rounding and excess-precision policy should clients follow?", "needed": "代表性算例與期望值；既有容差不是新的稅務承諾。 / Representative calculations with expected values; existing tolerance is not a new tax guarantee." }, { "id": "Q5", "priority": "high", "question": "PrintMark映射、Error成功回應及狀態欄位差異是否另案修正？ / Should PrintMark mapping, Error success responses and the status-column mismatch be fixed separately?", "needed": "另核准runtime變更，本輪只揭露。 / Separate runtime-change approval; this pass only documents them." }, { "id": "Q6", "priority": "medium", "question": "測試公司/裝置、憑證配置、印表機型號與驗收案例？ / Which test seller/device, credential setup, printer model and acceptance cases should be used?", "needed": "透過本機安全設定提供測試憑證；實體列印與外部上傳未驗證。 / Provide test credentials through secure local settings; physical printing and external upload remain unverified." } ] }