Account API
API Thực hiện cấp thông tin Token để xác thực request hợp lệ cho khi thực hiện gửi, lấy dữ liệu từ hệ thống CUKCUK.
Xem hướng dẫn tối ưu cơ chế xác thực tại đây
Các thông tin cấu hình cần thiết:
| AppID | Domain | Secret Key |
|---|---|---|
| AppID | Tên kết nối | Mã bảo mật |
Để lấy các thông tin trên xem bài viết tại đây.
About
| URL | Phiên bản |
|---|---|
| graphapi.cukcuk.vn | 1.0 |
Schemes
| Scheme |
|---|
| https |
Endpoints
api/Account/Login
POST
Thực hiện lấy thông tin Token đăng nhập
Expected Response Types
| HttpCode | ServiceResult.ErrorType | Mô tả |
|---|---|---|
| 401 | Chuỗi AccessToken hết hạn hoặc không hợp lệ cần phải gọi cấp phát lại | |
| 200 | 0 | Không có lỗi |
| 200 | 1 | Tham số không hợp lệ null or empty |
| 200 | 2 | Mã nhà hàng không tồn tại |
| 200 | 3 | Mã Appid không tồn tại trên hệ thống |
| 200 | 4 | Chuỗi thông tin chữ ký đăng nhập không hợp lệ, timeout |
| 200 | 7 | Thiết lập kết nối CUKCUK đang ở trạng thái ngắt, không thể lấy dữ liệu |
| 200 | 100 | Lỗi nội bộ API Graph |
| 200 | 102 | Request bị từ chối, do có request cùng loại đang xử lý. Vui lòng chờ xử lý xong hoặc chờ request đang xử lý timeout thì gọi lại. |
Parameters
| Name | In | Description | Required? | Type |
|---|---|---|---|---|
| param | body | Đối tượng chứa thông tin đăng nhập | true | LoginParam |
Content Types Produced
| Produces |
|---|
| application/json |
Content Types Consumed
| Consumes |
|---|
| application/json |
Response
Trả về đối tượng ServiceResult với ServiceResult.Data là LoginResponse
Definitions
LoginData Definition
Thông tin đăng nhập
| Property | Type | Format | Mô tả |
|---|---|---|---|
| Domain | string | Tên miền ví dụ: demoquanao.CUKCUK.vn | |
| AppID | string | AppID cần kết nối | |
| LoginTime | string | Thời gian đăng nhập dạng string (giờ UTC date) |
LoginParam Definition
Tham số thông tin đăng nhập với chuỗi chữ ký tới API
| Property | Type | Format | Mô tả |
|---|---|---|---|
| Domain | string | Tên miền ví dụ: demoquanao.CUKCUK.vn | |
| AppID | string | AppID cần kết nối | |
| LoginTime | string | Thời gian đăng nhập dạng string (giờ UTC date) | |
| SignatureInfo | string | Thông tin chữ ký để validate thông tin đăng nhập |
LoginResponse Definition
| Property | Type | Format | Mô tả |
|---|---|---|---|
| AppID | string | AppID cần kết nối | |
| Domain | string | Tên miền, ví dụ: demoquanao.CUKCUK.vn | |
| AccessToken | string | Chuỗi token dùng để xác thực các request | |
| CompanyCode | string | Mã nhà hàng sẽ gửi cùng các request | |
| Environment | string | Môi trường để build đường dẫn api request lấy, gửi dữ liệu |
ServiceResult Definition
| Property | Type | Format | Mô tả |
|---|---|---|---|
| Code | int | Mã lỗi HttpCode (200, 500...) | |
| ErrorType | int | Loại lỗi | |
| ErrorMessage | string | Thông tin lỗi | |
| Success | bool | True - không có lỗi logic xảy ra | |
| Environment | string | Môi trường triển khai của api | |
| Data | string | object | Dữ liệu trả về client |
| Total | int | Tổng số bản ghi khi lấy dữ liệu phân trang |
ErrorType Definition
- Dải mã lỗi chung
| HttpCode | ServiceResult.ErrorType | Mô tả |
|---|---|---|
| 401 | Chuỗi AccessToken hết hạn hoặc không hợp lệ cần phải gọi cấp phát lại | |
| 200 | 0 | Không có lỗi |
| 200 | 1 | Tham số không hợp lệ null or empty |
| 200 | 2 | Mã nhà hàng không tồn tại |
| 200 | 3 | Mã Appid không tồn tại trên hệ thống |
| 200 | 4 | Chuỗi thông tin chữ ký đăng nhập không hợp lệ, timeout |
| 200 | 5 | Tham số lấy phân trang vượt quá số lượng cấu hình cho phép (max 100) |
| 200 | 6 | Tham số ngày giờ không hợp lệ (01/01/1753 - 31/12/9999) |
| 200 | 7 | Thiết lập kết nối CUKCUK đang ở trạng thái ngắt, không thể lấy dữ liệu |
- Dải mã lỗi nghiêm trọng
| HttpCode | ServiceResult.ErrorType | Mô tả |
|---|---|---|
| 200 | 100 | Lỗi nội bộ API Graph |
| 200 | 102 | Request bị từ chối, do có request cùng loại đang xử lý. Vui lòng chờ xử lý xong hoặc chờ request đang xử lý timeout thì gọi lại. Ví dụ: Khi đang gọi api login mà api chưa trả về dữ liệu lại tiếp tục gọi request login này sẽ trả về lỗi này. |
SignatureInfo Build
SignatureInfo là thông tin chữ ký để đảm bảo gói tin tham số lấy thông tin đăng nhập là toàn vẹn và hợp lệ. Để build chuỗi chữ ký cần có cấu hình SecretKey
Danh sách tham số cấu hình lấy tại trang quản lý CUKCUK
| AppID | Domain | Secret Key |
|---|---|---|
| AppID | Tên kết nối | Mã bảo mật |
xem bài viết lấy thông cấu hình tại đây
Chuỗi chữ ký được build theo dạng bọc thông tin tham số đẩy lên ở dạng JSON, sau đó thực hiện mã hóa một chiều theo chuẩn mã hóa Hash HMACSHA256 với salt là thông tin cấu hình SecretKey.
Example
Ví dụ gửi tham số gọi tới api với thông số cấu hình như sau:
| AppID | Domain | Secret Key |
|---|---|---|
| CUKCUKOpenPlatform | demoquanao.CUKCUK.vn | 8726656e11b7dbdbfcb848c799a4c3b269cdc9d4ebb86e3e456898d45db140a2 |
1.Xử lý toàn vẹn gói tin lấy thông tin đăng nhập
Build chuỗi JSON LoginData - dữ liệu thông tin đăng nhập
Chuỗi thông tin đăng nhập cần truyền thêm thông tin thời gian đăng nhập để tăng độ bảo mật.
Thực hiện đăng nhập vào lúc 15 giờ 00 phút (Thời điểm hiện tại DateTime.Now | GetDate())
PHP
$loginInfo = {AppID => "CUKCUKOpenPlatform",Domain => "demoquanviet.cukcuk.vn",LoginTime => getdate()}
JavaScript
var loginInfo = {AppID:"CUKCUKOpenPlatform",Domain:"demoquanviet.cukcuk.vn",LoginTime:new Date()}
CSharp
var loginInfo = new LoginInfo {AppID="CUKCUKOpenPlatform",Domain="demoquanviet.cukcuk.vn",LoginTime=DateTime.Now}
Sau đó thực hiện Serialize object loginInfo bằng thư viện (JavaScript: JSON.stringify(), C#: JSONConvert, PHP: json_encode($loginInfo)..) được chuỗi:
JSON
{"AppID":"CUKCUKOpenPlatform","Domain":"demoquanviet.cukcuk.vn","LoginTime":"2020-07-29T11:00:18.405Z"}
Thực hiện mã hóa chuỗi JSON trên theo chuẩn mã hóa HMAC_SHA256 với key là
SecretKey = 8726656e11b7dbdbfcb848c799a4c3b269cdc9d4ebb86e3e456898d45db140a2
được chuỗi
SignatureInfo = 07547428bc3a5a60b13bfd8f53fb2012c1d8e938087c6b706ec5f9dfa7609ef2
Note
Có thể thực hiện mã hóa chuỗi JSON string để kiểm nghiệm theo mã hóa HMAC_SHA256 trên trang CodeBeautify.Org chọn chuẩn mã hóa HMAC-SHA256
Warning
Nếu tự cộng chuỗi JSON mà không qua Serialize thì phải đảm bảo cấu trúc chuỗi build các thuộc tính của JSON theo thứ tự alphabet AppID -> Domain -> LoginTime
2. Gửi gói tin đã xử lý toàn vẹn dữ liệu để lấy thông tin AccessToken
Tạo JSON LoginParam = {LoginData + SignatureInfo}
{
"AppID": "CUKCUKOpenPlatform",
"Domain": "demoquanao.CUKCUK.vn",
"LoginTime": "2020-07-29T11:00:18.405Z"
}
nối thêm SignatureInfo = 07547428bc3a5a60b13bfd8f53fb2012c1d8e938087c6b706ec5f9dfa7609ef2.
=> LoginParam
{
"AppID": "CUKCUKOpenPlatform",
"Domain": "demoquanviet.cukcuk.vn",
"LoginTime": "2020-07-29T11:00:18.405Z",
"SignatureInfo": "07547428bc3a5a60b13bfd8f53fb2012c1d8e938087c6b706ec5f9dfa7609ef2"
}
Sau đó thực hiện gửi request với tham số JSON trên với Header Content-Type: application/json
Hệ thống sẽ trả về ServiceResult với Data là LoginResponse JSON response
{
"Code": 200,
"Data": {
"Domain": "demoquanviet.cukcuk2.misa.local",
"AppID": "CUKCUKOpenPlatform",
"AccessToken": "VC-nfF2TtlU-QYMRJ1f5Nc2S_IQIMO23MmNVVFwKmP0gbTtCrCRdmyBRaotsKq88MKmy7An-AkPOKHgeH4N6apa0fGszZHLeZZRAQBMtlyrH-n4iO55CGJHOglh8f-EPohYJ1w6HROH053j5kBmf-POh7B3vU4m0RGjTGoI_Bzkoze2bOFtphtn92xWgS_f1X029mUkgdVkh0f-Owo8nHaAW2FQGGaIOF0w3y5WLAa9tz1zcyiDgReU51X7OIfrgQ9XleF9-87Hvbw3non7zmsE48ZbzKETxqpjVA-VHGh4",
"CompanyCode": "demoquanviet"
},
"Total": 0,
"Success": true
}
Note
Chuỗi JSON request lấy thông tin đăng nhập có thời gian hợp lệ là 5 phút, sau 5 phút mà vẫn gửi tham số này hệ thống sẽ trả về mã lỗi chuỗi chữ ký không hợp lệ Code = 200, ErrorType = 4