在進行串接前，首先需要有定義串接的規格，例如：串接的協定 (HTTP、或走 FTP 檔案交換等等)、需要傳送的欄位等等資料。國內比較少像國外服務通常有 Web 版的開放文件網頁可以查詢，反而常見交付的文件有 PDF 文件、Google Doc、Word... 還有看過用 Excel 寫的...@@。

不論是那種文件類型，只要寫的夠清楚，就很棒。而豐支付提供的為 PDF 版的文件手冊。

由於要開始介紹裡頭的重點及串接方法，如果沒有完整版可以閱讀，只靠截取片段圖片，比較難跳躍式閱讀找重點比對，因此把文件放到 GitHub，可以在這裡閱讀豐支付API文件。

圖 2-1: 使用 Google Chrome 閱讀 PDF 文件

關於閱讀此份文檔的工具，在此推薦直接使用 Google Chrome 打開即可。在左側會有邊欄的頁面預覽，很方便跳躍式的選擇頁面閱讀。

API 文件條目

這份文件一共 55 頁，我們快速看一下文件條目，先瞭解一下一共有幾支 API 構成這整個刷卡流程，大概花個 10 分鐘快速瀏覽，找到第 10 頁，有提供 API 接口的資訊。

*圖 2-2: 文件條目，第四章節。

在第 10 頁我們得知，一共有兩支 API，在第 11 頁則有測試卡號的資訊及注意事項。

各項 API 服務

https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/Order

取得 Nonce

https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/Nonce

測試資訊

*圖 2-3: 文件條目，第七章節。

文件裡的第七章節，是 Order 這支 API 提供的四種功能。

*圖 2-4: 文件條目，第四章節。

Nonce 是一串驗證 Request 來源有效性的雜湊值，依文件描述，它的效期為 60 秒。由於我們的伺服器主機的 IP 位址是固定的，因此取得該 IP 位址的 Nonce 值，並使用 Nonce 值作為向 Order API 發送請求時的其中一個欄位，可以驗證 IP 位址的有效性。

Postman 測試

先不管刷卡流程間的商業邏輯，光從以上資料可得知，沒有 Nonce 是不行的，因此先從取得 Nonce 值的 API 作為切入點。

這個時候，還沒有寫任何程式碼，我們可以先用像是 Postman 這類的工具快速測試一下 API 接受的是什麼樣的請求，確定可以成功取得 Nonce 之後，再繼續下一步。

*圖 2-5: 使用 Postman 測試 Nonce API。

一開始選擇預設的 Content-Type 為 application/x-www-form-urlencoded 是不行的，改為 application/json 即可接通取得 Nonce 值。

第一個，也是唯一一個

Postman 在測試一般的 API 很好用，可以在測試時把每一條 API 文件化後分享給團隊。不過在金融類型的 API 需要的欄位會有效期，且需要加密的簽章欄位，無法那麼簡單地使用 Postman 測試 Order API，不過我們經由這個簡單測試得知: Content-Type 為 application/json，發送的資料欄位字串為 JSON 格式，可以成功拿到 Nonce，下一步就直接進入 Coding 了。

拿到 Nonce 後，接著呢？

你會發現整段串接流程會花最多時間在第 17 頁「產生安全簽章 Sign」的方法，需要算出 HashId 及產生 JSON 訊息內文。接下來的文章，會開始對這方面開始著墨。

本文更新於筆者的 TerryL 部落格，Day 2 - API 文件導覽、 Postman 測試取得 Nonce，有興趣可前往閱讀及討論。