Hướng Dẫn Tạo App Kết Nối API

Các mục liên quan

Bước 1: Tạo app

- Vào link https://developers.haravan.com
(nếu chưa đăng nhập trước đó thì hệ thống sẽ chuyển sang page login https://accounts.haravan.com, tại page này bạn có thể đang nhập hoặc click tạo mới tài khoản.)

Tạo App Kết Nối API

- Sau khi đăng nhập/đăng ký thành công hệ thống sẽ hiển thị ra màn hình listing các ứng dụng đã tạo, Click “Create App” để tạo ứng dụng mới.

Tạo App Kết Nối API

- Giao diện tạo mới ứng dụng.

Tạo App Kết Nối API

  • Name: Tên ứng dụng.
  • Description: Mô tả ứng dụng.
  • Redirect Url: Là đường dẫn đến app của bạn
    • Cần khai báo ít nhất 2 url: login và install
      • Login url với cú pháp khuyến khích: https://{domain_app}/install/login
      • Install url với cú pháp khuyến khích: https://{domain_app}/install/grandservice
    • Các url này do bạn cấu hình trong config của app

- Tạo ứng dụng thành công, cần lưu lại App ID, App Secret, Redirect Url vào config của app

Tạo App Kết Nối API

Bước 2: Chọn scope cho app

- Scope là quyền chỉnh sửa hoặc đọc dữ liệu được chia theo từng phần của shop và website, bạn có thể yêu cầu các scope dưới đây.

- Lưu ý: Khi chọn scope nào thì phải lưu scope đó vào config của app để truyền đi lúc cài app.

2.1 Haraweb scopes

- Scope dành cho các api dùng ngoài website bán hàng.

- Các khai báo scope ở mục Haraweb : web.{tên_scope}
VD : web.read_script_tags

- Tham khảo tên scope và các đầu api liên quan ở file hướng dẫn scope

Chọn scope cho app

2.2 Commerce scopes

- Scope dành cho các api dùng trong trang quản trị bán hàng.

- Các khai báo scope ở mục Commerce : com.{tên_scope}
VD : com.write_products

- Tham khảo tên scope và các đầu api liên quan ở file hướng dẫn scope

Chọn scope cho app

Bước 3: Đăng ký webhook

- Vào mục Webhooks, chọn nút Register để đăng kí Webhooks.

Đăng ký webhook

3.1 Tạo ngrok để đăng kí webhoo :

- Ngrok (https://ngrok.com/) là tool giúp bạn test webhook, nếu bạn chưa có tên miền online.

- Ngrok sẽ tạo ra cổng kết nối từ public internet đến port máy tính local của bạn.

- Sau khi tải ngrok về , chạy file ngrok.exe.

- Chạy lệnh ngrok http 3000 (port tùy ý, ví dụ ở đây là port 3000)

- Lưu ý:

  • 1 tên miền ngrok có thể tồn 8h, sau đó phải chạy lệnh lại để lấy tên miên mới
  • Và tên miền để đăng kí webhook bắt buộc phải là https://

Đăng ký webhook

3.2 Đăng kí webhook:

- Nhập vào CallBack URL : là đường dẫn được cấu hình trong app để hứng response webhook.

- Nhập vào Verify Token : là một chuỗi random bất kì tối thiểu 1 kí tự, vì dùng để chứng thực với app nên lưu lại chuỗi này vào config của app.

Đăng ký webhook

- Khi đăng kí thành công , reload lại page để thấy những mục có thể Subscribe.

- Những mục đã subscribe sẽ được webhook trả dữ liệu về tương ứng.

Đăng ký webhook

- Tìm hiểu thêm ở phần Kết nối Webhooks

Bước 4 : Cấu hình cho app

- Sau khi cấu hình cơ bản trên https://developers.haravan.com/apps

- Bạn sẽ có các thông tin như App id, App secret, scope, webhook…

- Lưu các thông tin đó vào app, Vd ở đây lưu vào một object tên là config.

STT

Thuộc tính

Mô tả

1

response_mode

Form method responses

2

url_authorize

Url Login vào của hệ thống

3

url_connect_token

Url lấy token cho app

4

grant_type

Loại code cấp.
Luôn là “authorization_code”

5

nonce

Mã random tối thiếu 1 kí tự

6

response_type

Chọn các field cần responses

7

app_id

App ID lấy được sau khi cài app ở bước 1

8

app_secret

App Secret lấy được sau khi cài app ở bước 1

9

scope_login

Là các scope bắt buộc truyền vào khi login vào hệ thống
Gồm : openid, profile, email, org, userinfo

10

scope

- Là các scope bao gồm cả bắt buộc và tùy chọn để tiến hành install app

+ Các scope bắt buộc : openid, profile, email, org, userinfo, grant_service
+ Scope dùng webhook : wh_api
+ Các scope khác phải tương ứng phải các scope đã chọn ở bước 2

11

login_callback_url

Là Url redirect đã khai báo ở bước 1, có vai trò login vào hệ thống

12

install_callback_url

Là Url redirect đã khai báo ở bước 1, có vai trò cài app

13

webhook

13.1

hrVerifyToken

Mã xác thực webhook, đã khai báo ở bước 1
Có thể lấy ở https://randomkeygen.com/ (CodeIgniter Encryption Keys)

13.2

subscribe

url post subscribe webhook

	const config = {
		response_mode: 'form_post',
		url_authorize: 'https://accounts.haravan.com/connect/authorize',
		url_connect_token: 'https://accounts.haravan.com/connect/token',
		grant_type: 'authorization_code',
		nonce: 'asdfasdgd',
		response_type: 'code id_token',
		app_id: '0e86d3653f580f07358865a0b6cda6de',
		app_secret: '24302376155dd82a92f4d9d0b1d573c5a232d30ab5fe4a79069e4435bad7e200',
		scope_login: 'openid profile email org userinfo',
		scope: 'openid profile email org userinfo com.write_products  web.write_script_tags  grant_service',
		login_callback_url: 'http://localhost:3000/install/login',
		install_callback_url: 'http://localhost:3000/install/grandservice',
		webhook: {
			hrVerifyToken: 'bOL3XFfZabhKe6dnJfCJuTAfi37dFchQ',  
			subscribe: 'https://webhook.haravan.com/api/subscribe'
		},
	};

	

Bước 5: Login Lấy authorization code

- Đầu tiên phải login vào hệ thống để kiểm tra thông tin shop và user

- Vào login_callback_url, app sẽ redirect đến url_authorize với phương thức get để đăng nhập.

- Sau khi redirect tới url_authorize nếu chưa đăng nhập tài khoản haravan_account thì hệ thống sẽ yêu cầu đăng nhập để lấy thông tin user, nếu đã đăng nhập trước đó rồi thì hệ thống sẽ bỏ qua bước đăng nhập và lấy thông tin user đã đăng nhập trước đó.

- Khi user đăng nhập thành công sẽ redirect lại link redirect_uri mà bạn đã khai báo trước đó với method là POST, kèm theo codeid_toke.

5.1 Request get code

Method

URL  

GET

https://accounts.haravan.com/connect/authorize

Request params:
    response_mode
    response_type
    scope_login
    client_id (app_id)
    redirect_uri (login_callback_url)
    nonce 
//Tất cả đều đã lưu lại trong config

Truyền params theo cú pháp sau:
https://accounts.haravan.com/connect/authorize?response_mode={response_mode}& response_type={response_type}&scope={scope_login}&client_id={app_id}&redirect_uri={ login_callback_url}&nonce={nonce}
VD: 
https://accounts.haravan.com/connect/authorize?response_mode=form_post&response_type=code id_token&scope=openid profile email org userinfo&client_id=0e86d3653f580f07358865a0b6cda6de&redirect_uri=http://locahost:3000/install/login&nonce=asdfasdgd

STT

Thuộc tính

Mô tả

1

response_mode

Form method responses

2

response_type

Chọn các field cần responses

3

scope

Quyền truy cập của token
Lưu ý: các scope này phải giống với scope đã chọn trong phần cấu hình.
(Xem các scope hiện có)

4

client_id

App ID trong ứng dụng sau khi cài sẽ có

5

redirect_uri

login_callback_url ở config

6

nonce

Mã ramdom

5.2 Response get code

Status

Response

200

{
"code": "c309cc6a97e7da821975d2440645892a95f13ce8e06af81ecffe5ed9db8fe7a3",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NzA3Njk4MjAsImV4cCI6MTU3MDc3MDEyMCwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOGJkOWExNDc1NTI4NTJlNTFlYTU3MTExMDQ3NGZlNjMiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU3MDc2OTgyMCwiY19oYXNoIjoiRm9XSFRLUU50SWFRVndFSlg5bVBMQSIsInNpZCI6Ijc5NDgyZGExZGE5ZmZlZjJmMjY2NjVjOWE2Yjc4MmIzIiwic3ViIjoiMjAwMDAwMDIwMzMyIiwiYXV0aF90aW1lIjoxNTcwNjgwMDU2LCJpZHAiOiJsb2NhbCIsInJvbGUiOiJhZG1pbiIsIm9yZ2lkIjoiMTAwMDExMzc2MyIsIm1pZGRsZV9uYW1lIjoidGVzdCIsIm5hbWUiOiJ0ZXN0IiwiZW1haWwiOiI4YmQ5YTE0NzU1Mjg1MmU1MWVhNTcxMTEwNDc0ZmU2MyIsIm9yZ25hbWUiOiJob2FpbmFtMDlfMTExIiwib3JnY2F0IjoiT3RoZXIiLCJhbXIiOlsicHdkIl19.Q8I9ezKY6r22exDkqBjXbHHirFFg7HRc33DFRHP0ID6E1XyPsry2zgsyVpP4EVtOs0jl0fEzaLvpKLabFDlqNAwMnnRbPqECazMJ5OTDKGTJsEO9Xj-v-TwqMDWPEwV_Abemj8_deovPCw_3wAxxB3mta1GLqz12iBD7m9jlIWFEzqEvIULhdrQ_isMQwjBaxA2r8oQHqQlxVuUAOPKOgP-mCCUa8kGGAFPtd3dfl4C7EezgNE2xtdjv1ItE4_SCdvaF6-hTMrE5smildtgRp3gGv2_QmgGnU1IV8rPGcT3OyaOtywaaQDBSyGcCkF6OXT30-Ez1guJvllVYJ9AIqg",
"scope":"openid profile email org userinfo",
"session_state": "cE63E1b725ke5g329GmRQLnEydXpuQanSCG_DF8AbKM.15223afbde03d10d258e85b1be797e41"
}

401

Unauthorized

422

{"error": "Unprocessable Entity"}

500

Something went wrong. Please try again later.

Bước 6: Kiểm tra thông tin

- Lúc này app sẽ lấy được codeid_token.

- Trên môi trường nodejs sử dụng thư viện dùng thư viện jsonwebtoken: https://www.npmjs.com/package/jsonwebtoken để render id_token ra thông tin user và role.

- Tiến hành kiểm tra trước khi cài app.

  • Đầu tiên, dùng thông tin user để tìm shop trong database.
  • Nếu shop đã có cài app, cấp token cho user đang login vào app
  • Nếu chưa cài app, sẽ xét tới role, sẽ có 2 trường hợp xảy ra:
    a. Trường hợp 1 : nếu user đang login là admin thì tiến hành cài app.
    b. Trường hợp 2: nếu user đang login không phải admin thì thông báo không có quyền.

Bước 7: Install Lấy authorization code

- Sau khi kiểm tra , nếu các thông tin thỏa điều kiện thì tiến hành cài app

- Vào install_callback_url, app sẽ redirect đến url_authorize với phương thức get.

- Khi user đồng ý cài đặt sẽ redirect lại link redirect_uri mà bạn đã khai báo trước đó với method là POST, kèm theo codeid_token.

- Giống như login , cùng redirect đến url_authorize nhưng sẽ khác redirect_uriscope.

- Dùng code được trả về để lấy access_token cho app.

7.1 Request get code

Method

URL  

GET

https://accounts.haravan.com/connect/authorize

Request params:
    response_mode
    response_type
    scope
    client_id (app_id)
    redirect_uri (install_callback_url)
    nonce 
//Tất cả đều đã lưu lại trong config


Truyền params theo cú pháp sau:
https://accounts.haravan.com/connect/authorize?response_mode={response_mode}& response_type={response_type}&scope={scope}&client_id={app_id}&redirect_uri={install_callback_url}&nonce={nonce}
VD: 
https://accounts.haravan.com/connect/authorize?response_mode=form_post&response_type=code id_token&scope=openid profile email org userinfo&client_id=0e86d3653f580f07358865a0b6cda6de&redirect_uri=http://locahost:3000/install/login&nonce=asdfasdgd

STT

Thuộc tính

Mô tả

1

response_mode

Form method responses

2

response_type

Chọn các field cần responses

3

scope

Quyền truy cập của token
Lưu ý: các scope này phải giống với scope đã chọn trong phần cấu hình.
(Xem các scope hiện có)

4

client_id

App ID trong ứng dụng sau khi cài sẽ có

5

redirect_uri

login_callback_url ở config

6

nonce

Mã ramdom

7.2 Response get code

Status

Response

200

{
"code": "c309cc6a97e7da821975ecffe5ed9db8fe7a3d2440645892a95f13ce8e06af81",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NzA3Njk4MjAsImV4cCI6MTU3MDc3MDEyMCwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOGJkOWExNDc1NTI4NTJlNTFlYTU3MTExMDQ3NGZlNjMiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU3MDc2OTgyMCwiY19oYXNoIjoiRm9XSFRLUU50SWFRVndFSlg5bVBMQSIsInNpZCI6Ijc5NDgyZGExZGE5ZmZlZjJmMjY2NjVjOWE2Yjc4MmIzIiwic3ViIjoiMjAwMDAwMDIwMzMyIiwiYXV0aF90aW1lIjoxNTcwNjgwMDU2LCJpZHAiOiJsb2NhbCIsInJvbGUiOiJhZG1pbiIsIm9yZ2lkIjoiMTAwMDExMzc2MyIsIm1pZGRsZV9uYW1lIjoidGVzdCIsIm5hbWUiOiJ0ZXN0IiwiZW1haWwiOiI4YmQ5YTE0NzU1Mjg1MmU1MWVhNTcxMTEwNDc0ZmU2MyIsIm9yZ25hbWUiOiJob2FpbmFtMDlfMTExIiwib3JnY2F0IjoiT3RoZXIiLCJhbXIiOlsicHdkIl19.Q8I9ezKY6r22exDkqBjXbHHirFFg7HRc33DFRHP0ID6E1XyPsry2zgsyVpP4EVtOs0jl0fEzaLvpKLabFDlqNAwMnnRbPqECazMJ5OTDKGTJsEO9Xj-v-TwqMDWPEwV_Abemj8_deovPCw_3wAxxB3mta1GLqz12iBD7m9jlIWFEzqEvIULhdrQ_isMQwjBaxA2r8oQHqQlxVuUAOPKOgP-mCCUa8kGGAFPtd3dfl4C7EezgNE2xtdjv1ItE4_SCdvaF6-hTMrE5smildtgRp3gGv2_QmgGnU1IV8rPGcT3OyaOtywaaQDBSyGcCkF6OXT30-Ez1guJvllVYJ9AIqg",
"scope":"'openid profile email org userinfo com.write_products web.write_script_tags grant_service ", "session_state": "cE63E1b725ke5g329GmRQLnEydXpuQanSCG_DF8AbKM.15223afbde03d10d258e85b1be797e41"
}

401

Unauthorized

422

{"error": "Unprocessable Entity"}

500

Something went wrong. Please try again later.

Bước 8: Lấy Access_token

- Trên môi trường nodejs sử dụng thư viện: https://www.npmjs.com/package/oauth để lấy access_token.

- Sau khi cài app thành công sẽ được cấp token, lưu token đó lại để dùng lâu dài.

8.1 Code mẫu để lấy access_token:

- Trên môi trường nodejs

var OAuth2 = require('oauth').OAuth2;

let grant_type = 'authorization_code';
let callback_url = 'http://localhost:3000/install/grandservice';
let client_id = '9f83ffc930129e2f4d11af0fc60bd251';
let client_secret = '618e198b891317f02c545e9fe078f8a72e8f57424ee471ac409a8c0d05bfe8f4';
let url_authorize = 'https://accounts.haravan.com/connect/authorize';
let url_connect_token = 'https://accounts.haravan.com/connect/token';
let code = '6a83f22d3363d270b7c18042e6c2db6571df0b8236b708f5d08778d303a85884';

let params = {};
params.grant_type = grant_type;
params.redirect_uri = callback_url;

let _oauth2 = new OAuth2(
  client_id,
  client_secret,
  '',
  url_authorize,
  url_connect_token,
  ''
);

_oauth2.getOAuthAccessToken(code, params, (err, accessToken, refreshToken, params) => {
    if (err) {
      let parseErrData = JSON.parse(err.data);
      console.log('error', parseErrData);
    } else {
      console.log('accessToken', accessToken);
    }
  });

- Trên môi trường postman

Trên môi trường  postman

STT

Thuộc tính

Mô tả

1

OAuth2

Khai báo thư viện OAuth của nodejs

2

grant_type

Tương tự grant_type trên config

3

callback_url

Tương ứng với install_callback_url trên config

4

client_id

Tương ứng với app_id trên config

5

client_secret

Tương ứng với app_secret trên config

6

code

Code được response về ở bước trên.

8.2 Response get Access_token

Status

Response

200

params: {
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NTk4MDUyNTUsImV4cCI6MTU1OTgwNTU1NSwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOWY4M2ZmYzkzMDEyOWUyZjRkMTFhZjBmYzYwYmQyNTEiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU1OTgwNTI1NSwiYXRfaGFzaCI6InlVcHBoaE15bnZUSUpWV0tzSkMtS3ciLCJzaWQiOiJhMzhkN2M5YWM0ODZiZjBhOTM2OWI4ZjRiZjk2NDcxZCIsInN1YiI6IjEwMDAxMTQ5OTAiLCJhdXRoX3RpbWUiOjE1NTk4MDUwODAsImlkcCI6ImxvY2FsIiwicm9sZSI6WyJjb21fYXBpLmFkbWluIiwiYWRtaW4iXSwib3JnaWQiOiIxMDAwMTEzNzYzIiwibWlkZGxlX25hbWUiOiJCw7lpIMSQaW5oIEhvw6BpIE5hbSIsIm5hbWUiOiJCw7lpIMSQaW5oIEhvw6BpIE5hbSIsImVtYWlsIjoiYnVpZGluaGhvYWluYW1AZ21haWwuY29tIiwib3JnbmFtZSI6ImhvYWluYW0wOSIsIm9yZ2NhdCI6Ik90aGVyIiwiYW1yIjpbInB3ZCJdfQ.P7xXf0ftuiADd5I8v7uQfJk6Xm839z4RFt_Q9RfpMg_MsqIFgnmpJ4lgB2Zcsjw_SwSasEpszXQ2Dwy8-kt0C5YYvAjKPdTk8DNNZidav9FqtM-53rR-DMbyyoDes8-pWed2J_cTFHEhlayf1jYowAsUo6n3snJAwlHdpnRaHVGyFOi56N6Y8eSA84GNrKRPlBpjfhKY8Pk0pmY_0XOfO7aInPt0RPK42sf0gRVWJR2hSksJaOBL5P6pSDq5A_uT2o-YsE8nZ0OASKzE4aQ0Qeqo-Rx9LaJIzwuJKnyVmFSgl2gJHJUVgTZ0slD5fMmtRuZOSFlDibp8J6wtTnb_MQ",
"access_token": "86f6ab839b301903cc6223dbe236aaa874fa5aa882b8d3d121ba91f8ce660f35",
"expires_in": 86400,
"token_type": "Bearer"
}

401

Unauthorized

422

{"error": "Unprocessable Entity"}

500

Something went wrong. Please try again later.

8.3 Sử dụng access_token:

- Sau khi lấy được access_token, có thể dùng token đó query dữ liệu từ api

- Ví dụ dưới đây sẽ dùng access_token để lấy thông shop bằng postman.

Headers : 
    Content-Type : application/json
    Authorization : Bearer + access_token

Trên môi trường  postman