JOP Gateway

簡介

JOP Gateway 作為 ISV 業者訪問街口開放平台之網關，當 ISV 業者發送請求至街口 JOP Gateway 時需要帶入相關資訊，細節請見下方說明。

簽章規則

當 ISV 業者申請街口開放平台的使用權限時，將會獲得一組可存取街口服務之 Credential (client_id) 與密鑰 (secret_key)。在街口開放平台發起請求時，皆須提供透過該 Credential 與密鑰對該筆請求進行簽章之 signature 給街口開放平台進行驗證。

下列步驟說明簽章產生規則：

取得簽章內容

初始化一個 json 物件 (or map)，下稱 signBody
將指定資料依序放入物件中
- a. client_id
- b. access_token (若請求的 api 需要帶入 access token)
- c. 業務參數：依照參數名稱 ASCII Code 排序
- d. timestamp
將 json 轉換為 String，下稱 jsonBody

// 1. init a map 
Map<String, Object> signBody = new LinkedHashMap<>();

// 2.a put the client_id in the signBody
signBody.put(ParamNames.CLIENT_ID_NAME, apiParam.fetchClientId());

// 2.b if the access token is required in the requested api
if (Objects.nonNull(apiParam.fetchAccessToken())) {
  signBody.put(ParamNames.APP_AUTH_TOKEN_NAME, apiParam.fetchAccessToken());
}

// 2.c sort the params by name and put all in the signBody
List<String> keyList = new ArrayList<>();
apiParam.forEach(
    (k, v) -> {
      if (ignoredKey.containsKey(k)) {
        return;
      }
      keyList.add(k);
    });
Collections.sort(keyList);
keyList.forEach(
    key -> {
      signBody.put(key, apiParam.get(key));
    });

// 2.d put timestamp into the signBody
// *timestamp's type is String here
signBody.put(ParamNames.TIMESTAMP_NAME, apiParam.fetchTimestamp());

簽章

根據上述取得簽章 String 後，以 {secret}, {jsonBody}, {timestamp/1000/86400} 的順序組裝，取得 SHA256 Hash 值。

StringBuilder sb = new StringBuilder();
sb.append(secret).append(jsonBody).append(timestamp / 1000 / 86400);
String body = sb.toString();
return getSHA256(body.toLowerCase()).toUpperCase();

公共參數

呼叫任何 API 都需要帶入的參數

Name	Type	Required	Description
client_id	string	true	表示 ISV 業者之身份，需帶入於開放平台取得之 Credential
method	string	true	欲呼叫之 API 名稱
sign	string	true	該請求之簽章。簽章規則如上
sign_method	string	true	簽名方法，目前支援的值為 JKOS_SIGN
timestamp	string	true	傳送該請求的 Unix Timestamp（毫秒）街口金科 Gateway 允許請求最大時間誤差為一小時
access_token	string	false	訪問令牌

業務參數

Request

API 呼叫除了包含公共參數，如果 API 本身有業務級的參數也必須傳入。

Name	Type	Required	Description
grant_type	string	true	授權類型，其值可能為 authorization_code 或 refresh_token。其值為 authorization_code 時，代表使用 auth_code 換取；其值為 refresh_token 時，代表用 refresh_token 換取。
code	string	false	授權碼。使用者對應用授權後得到，即第一步中開發者獲取到的 auth_code 值。如開發者選擇傳入 refresh_token，則無需傳入 code。
refresh_token	string	false	Refresh token 。刷新 access_token 時使用，若請求已傳入 code 後無需傳入。

Response

Name	Type	Description
code	string	服務代碼
msg	string	服務訊息
result	object	終端服務回傳內容

API Documentation

BaseURL

UAT：https://uat-gw-jop.jkos.app
PROD：https://gw-jop.jkos.com

Request URL

POST https://{BaseUrl}/api

Content-Type

application/x-www-form-urlencoded

1. 取得 access token (by auth code or refresh token)

Description

第三方服務欲調用用戶許可之資料或是服務時，需要先使用 authcode 換取訪問令牌 access token。

Request Body (x-www-form-urlencoded)

Name	Type	Required	Description
client_id	string	true	表示 ISV 業者之身份，需帶入於開放平台取得之 Credential
method	string	true	欲呼叫之 API 名稱
sign	string	true	該請求之簽章
sign_method	string	true	簽名摘要算法，目前支援的值為 JKOS_SIGN
timestamp	string	true	傳送該請求的 Unix 時間戳（粒度：毫秒）街口金科 Gateway 允許請求最大時間誤差為一小時。
grant_type	string	true	授權類型，其值可能為 authorization_code 或 refresh_token。其值為 authorization_code 時，代表使用 auth_code 換取；其值為 refresh_token 時，代表用 refresh_token 換取。
code	string	false	授權碼。使用者對應用授權後得到，即第一步中開發者獲取到的 auth_code 值。如開發者選擇傳入 refresh_token，則無需傳入 code
refresh_token	string	false	Refresh token 。刷新 access_token 時使用，若請求已傳入 code 後無需傳入

Request Example

curl --location --request POST 'https://{BaseUrl}/api' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=935165030d357d7e2aab0a0d1e7f58bb' \
--data-urlencode 'client_id=80938078' \
--data-urlencode 'method=jkopay.system.oauth.token' \
--data-urlencode 'sign=testsign' \
--data-urlencode 'timestamp=1648201714000' \
--data-urlencode 'sign_method=JKOS_SIGN'

# 如開發者選擇傳入 refresh_token，則無需傳入 code
# -d ‘refresh_token=thisisrefreshtoken’
# 刷新 access_token時使用，傳入 code後無需傳入

Response Body

Name	Type	Description
code	string	服務代碼
msg	string	服務訊息
result	object	終端服務回傳內容
result.user_id	string	用戶於街口的 user_id
result.access_token	string	開發者接下來使用街口開放平台時所需要的 access token
result.expires_in	number	access_token 有效期，單位為秒
result.refresh_token	string	用於取得新 access token 的 token
result.refresh_expires_in	number	refresh_token 有效期，單位為秒

Response Example

{
    "code": "OA-001",
    "msg": "Success",
    "result": {
        "user_id": "780a7306-0ef0-11ec-90a0-00505684fd45",
        "access_token": "21c71e5cbffe6ed8749c6be78fe7d727",
        "expires_in": 2592000,
        "refresh_token": "38a600e7b9e4cb89ccc043a2af0f285c",
        "refresh_expires_in": 7776000
    }
}

Error Code

Error Code	Message	備註
205	無效或錯誤參數，請參考 msg 回覆
999	網關服務異常
OA-001	成功
OA-205	Auth Code 已被使用
OA-360	Auth Code 過期
OA-999	系統異常

2. 調用用戶授權資料 (by access token)