新增 APP

• 串接第 0 步：到 https://partner.cyberbiz.io/account/signUp 註冊開發者帳號，並在該開發者帳號建立 app ，建立的流程可參考此文件。

  • 建立好 APP 後，即可在 APP 設定頁中看到測試店，透過後台提供的連結可直接進到測試店後台進行測試

    

• 在 CYBERBIZ Partner 後台，partners 可以自行設定上架內容 (例如 App Icon、App 說明、… )，並可從後台取得 Client ID 與 Client Secret。

• App 需設定的資料

  | scopes | must | 空白分隔，預設為 public

  scope 列表參考 ‣ (預設只會先給 public 這個 scope) | | | --- | --- | --- | --- | | authorize_url | optional | 安裝流程第一步跳轉的 URL，讓 app 知道有誰來安裝，app自己紀錄最終安裝結果 資安考量，僅支援 https

  商家安裝 APP 時，瀏覽器會跳轉到這個頁面，為 GET request

  點擊開發者後台，該 APP 頁面的的「安裝測試」按鈕，即可開始測試整個安裝流程 | | | redirect_url | must | oauth redirect url，會帶 code 過去 資安考量，僅支援 https | | | webhook_url | optional | 事件列表 資安考量，僅支援 https

  Webhook 為 POST requests | |

APP 安裝流程

1. 驗證登入店家，此步驟會將下方資訊使用跳轉 (redirect) 方式導到 App 的 Authorization URL。

   hmac = OpenSSL::HMAC.hexdigest(
   	OpenSSL::Digest.new('sha256'),
   	your_oauth_application.secret,
   	Base64.strict_encode64(domain)
   )
   url = "app-authorization-url?shop=#{cyberbiz_domain}&hmac=#{hmac}"
   
   # EX: <https://partner-domain.com/?shop=demo.cyberbiz.co&hmac=47532a9c63a83037603d6b16d4a44e551c28e6e560804e179c6e2b62cf38f248>
   # GET <https://partner-domain.com/?shop=demo.cyberbiz.co&hmac=47532a9c63a83037603d6b16d4a44e551c28e6e560804e179c6e2b62cf38f248>
   

2. APP 從開發商驗證頁面跳轉回 CYBERBIZ https://{cyberbiz_domain}/admin/oauth/authorize (GET request)

   <aside> 🚨 務必實做 state 參數，避免遭受 CSRF 攻擊，造成資料外洩

   </aside>

   client_id	your oauth app client_id
   redirect_uri	your oauth app redirect_url
   response_type	code
   scope	(optional)
   your oauth app scopes split by whitespace. e.g: scope=public read_customers read_products ****
   state	random string to prevent CSRF

3. CYBERBIZ APP 授權安裝

   1. 進到這畫面後，勾選並按下確認

      

4. 安裝完成跳轉至 App 的 Redirect URL (redirect_url)跳到 Redirect URL 時會帶的參數有

   code	oauth grant code (Valid within 10 minutes
   shop	shop.domain
   hmac	同第 1 點，可拿兩者做比對驗證（不用特別解開）
   state	state

到這步安裝流程就完成了 🎉 APP 即可用取得的 code 跟 CYBERBIZ 要 token。

→ 通常這一步後，就是跳到自己的 APP 設定畫面，或符合條件的話也可以進行「設定頁面自動代入設定」。

取得 token

• 用 code 可以跟 EC 取得 access token 與 refresh token：

  • code 的有效期限為 10 分鐘。
  • code 為一次性有效。使用過一次後，就不能再用第二次。
  • access token 時效可以從 access token (JWT) 中的 exp 欄位知道何時過期，目前有效期限是 2 小時，但有可能更動。
  • access token 過期後，就會需要用 refresh token 重新要一個新的。

• 商家反安裝 APP 後，access token 與 refresh token 會同時失效。

  • 需再走重新走一次安裝流程 → 拿到 grant code → 才能再次要到 refresh token、access token。

  grant_type	authorization_code
  code	your grant code from app installation step 4
  redirect_uri	your oauth app redirect_url
  client_id	your oauth app client id
  client_secret	your oauth app client secret

  curl -XPOST <https://your-shop.cyberbiz.co/admin/oauth/token> \\
      -H "Content-Type:application/json" \\
      -d '{"grant_type":"authorization_code", "code":"從APP安裝流程第四步拿到的code", "redirect_uri":"APP申請時，提供的redirect_url", "client_id":"APP上架第二步取得的 Client ID", "client_secret": "APP上架第二步取得的 Client Secret"}' 
  

  • 範例 response：

    {
      "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODkxMjk1OTUsImV4cCI6MTY4OTEzNjc5NSwic2hvcF9pZCI6NzEwOSwic2NvcGVzIjoicHVibGljIHNob3BfYXBpIiwic2hvcF9kb21haW4iOiJkZW1vLmN5YmVyYml6LmNvIn0.uewT_eFkXO-kxYHELAarPvur7Ep7M8Z1WzNtwPCr9GU",
      "token_type": "Bearer",
      "expires_in": 7199,
      "refresh_token": "x_FqF3ZKbDbDm5t96p4Mktq-e30aQYeIhfkB-4vEc90",
      "scope": "public read_customers",
      "created_at": 1689129595
    }
    

• 如果 access token 過期，需再用 refresh token 重新要一次 access token。

  • refresh token 不會過期 ⇒ 但用 refresh token 重新要一次 access token 後，refresh token 也會更新。

  • 商家反安裝 APP 後，access token 與 refresh token 會同時失效。

    • 這種情況需再請商家走重新走一次安裝流程，拿到 grant code、再要到 refresh token、access token。

    grant_type	refresh_token
    refresh_token	your-refresh-token
    client_id	your oauth app client id
    client_secret	your oauth app client secret

    curl -XPOST <https://your-shop.cyberbiz.co/admin/oauth/token> \\
        -H "Content-Type:application/json" \\
        -d '{"grant_type":"refresh_token", "refresh_token":"x_FqF3ZKbDbDm5t96p4Mktq-e30aQYeIhfkB-4vEc90","client_id":"APP上架第二步取得的 Client ID","client_secret":"APP上架第二步取得的 Client Secret"}'
    

  • 範例 response

    {
      "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODkxMzAyMjMsImV4cCI6MTY4OTEzNzQyMywic2hvcF9pZCI6NzEwOSwic2NvcGVzIjoicHVibGljIHNob3BfYXBpIiwic2hvcF9kb21haW4iOiJkZW1vLmN5YmVyYml6LmNvIn0.xpcKBoLtIpVREr07s1cSUKafhgwd-EgzqrbuIJefzXo",
      "token_type": "Bearer",
      "expires_in": 7200,
      "refresh_token": "6WzmFu1CebHJUIxH3VCRHARtyGZ4ndYKodPdyMaHo6Q",
      "scope": "public read_customers",
      "created_at": 1689130223
    }
    

設定頁面