Các Endpoint trong tài liệu hướng dẫn này sẽ bắt đầu bằng: http://iot.megaads.vn/api
Các mã lỗi không hợp lệ:
- 400: Dữ liệu gửi lên không hợp lệ.
- 403: Yêu cầu bị từ chối do không có quyền truy cập.
- 500: Có lỗi xảy ra phía máy chủ
Ngoài ra sẽ có các message mô tả chi tiết lỗi trong mỗi response trả về.
1. User
1.1 Đăng nhập
[POST] - /login
Dữ liệu gửi lên gồm:
+ email: (required | string) địa chỉ email mà người dùng đã đăng ký.
+ password: (required | string) mật khẩu của người dùng.
hoặc
+ refreshToken: token đã đăng nhập phía trước đó, dùng cho trường hợp người dùng đã đăng nhập.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"type": "bearer",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTYwMzg1NzgyNn0.5ntwLiNX_W2ArV1z5SMLjYFaqCpjZc6s72daTZIKfG0",
"refreshToken": "f9573dc1a0fd1d8d6f1bab5969dd7ce33cTg8JpUMAyE/xpXhvWpWIeGYGt6NB75Z1BsWRIYt6ip4RrHYsoImavNIk6afPFT"
}
}
Sử dụng giá trị của token để xác thực cho các endpoint bằng cách thêm Authorization = Bearer vào headers của request khi giửi lên. Sử dụng refreshToken để gia hạn token nếu token hết hạn.
1.2 Đăng ký
[POST] - /register
Dữ liệu gửi lên gồm:
+ email: (required | string) địa chỉ email mà người dùng muốn đăng ký, không trùng với các email của người dùng khác.
+ password: (required | string) mật khẩu của người dùng, tối thiểu 6 ký tự.
+ name: (required | string) họ và tên của người dùng.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"type": "bearer",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTYwMzg1NzgyNn0.5ntwLiNX_W2ArV1z5SMLjYFaqCpjZc6s72daTZIKfG0",
"refreshToken": "f9573dc1a0fd1d8d6f1bab5969dd7ce33cTg8JpUMAyE/xpXhvWpWIeGYGt6NB75Z1BsWRIYt6ip4RrHYsoImavNIk6afPFT"
}
}
Sau khi đăng ký thành công hệ thống sẽ tự động đăng nhập luôn cho tài khoản mới tạo.
1.3 Quên mật khẩu
[POST] - /forget
Dữ liệu gửi lên gồm:
+ email: (required | string) địa chỉ email mà người đã đăng ký.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": [
"Email hướng dẫn tạo mật khẩu đã được gửi đến địa chỉ . Hãy kiểm tra email và làm theo hướng dẫn.",
"Nếu không thấy email trong hộp thư đến (Inbox) vui lòng kiểm tra hộp thư Spam hoặc Junk Folder."
]
}
App cần đăng ký deep link với đường dẫn /api/reset/{token}, khi người dùng mở đường dẫn trong email sẽ tự nhảy về App.
1.4 Cập nhật mật khẩu
[POST] - /reset/{token}
Dữ liệu gửi lên gồm:
+ {token}: (required | string) token đã nhận được từ deep link ở API khôi phục mật khẩu.
+ password: (required | string) mật khẩu mới, tối thiểu 6 ký tự.
+ password_confirmation: (required | string) nhập lại mật khẩu mới.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful"
}
1.5 Lấy thông tin tài khoản
[GET] - /profile
Để lấy được thông tin tài khoản cần gửi kèm header Authorization ứng với token đã được cấp.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 1,
"email": "kieutuananh1995@gmail.com",
"name": "Tuấn Anh Zippy",
"created_at": "2020-10-26 16:58:38",
"updated_at": "2020-10-27 23:18:53"
}
}
1.6 Cập nhật thông tin tài khoản
[POST] - /profile
Dữ liệu gửi lên gồm:
+ name: (optional | string) tên tài khoản.
+ password: (optional | string) mật khẩu mới.
Để cập nhật thông tin tài khoản cần gửi kèm header Authorization ứng với token đã được cấp.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 1,
"email": "kieutuananh1995@gmail.com",
"name": "Tuấn Anh Zippy 123",
"created_at": "2020-10-26 16:58:38",
"updated_at": "2020-10-27 23:18:53"
}
}
2. Type
Để lấy được thông tin Loại thiết bị cần gửi kèm header Authorization ứng với token đã được cấp.
2.1. Lấy danh sách loại thiết bị
[GET] - /type/{id}
Dữ liệu gửi lên gồm:
+ {id}: (optional | number) được dùng khi muốn xem chi tiết thông tin của một loại thiết bị.
+ pageId: (optional | number) được bắt đầu bằng trang thứ 0.
+ pageSize: (optional | number ) mặc định là 30, để lấy tất cả danh sách loại thiết bị hãy gửi lên -1.
+ name: (optional | string) tìm kiếm theo tên loại thiết bị.
+ order: (optional | string) sắp xếp theo thông tin trường. Ví dụ order=-sorder có nghĩa là sắp xếp sorder theo thứ tự giảm dần và ngược lại, bỏ dấu - để sắp xếp tăng dần.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"pagesCount": 14,
"pageId": 0,
"pageSize": 1,
"data": [
{
"id": 19,
"name": "VTV3",
"description": "Hello World!",
"sorder": null,
"created_at": "2020-10-28 18:57:06",
"updated_at": "2020-10-28 18:57:06"
}
]
}
2.2. Thêm loại thiết bị
[POST] - /type
Dữ liệu gửi lên gồm:
+ name: (required| string) tên loại thiết bị.
+ sorder: (optional | number) thứ tự sắp xếp tùy chỉnh.
+ description: (optional | string) mô tả cho loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 1,
"name": "Thiết bị điện",
"description": "",
"sorder": null,
"created_at": "2020-10-26 09:58:17",
"updated_at": "2020-10-26 09:58:24"
}
}
2.3. Cập nhật thông tin loại thiết bị
[PATCH] - /type/{id}
Dữ liệu gửi lên gồm:
+ {id}: (required| number) id loại thiết bị.
+ name: (required| string) tên loại thiết bị.
+ sorder: (optional | number) thứ tự sắp xếp tùy chỉnh.
+ description: (optional | string) mô tả cho loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 1,
"name": "Thiết bị thông minh",
"description": "",
"sorder": null,
"created_at": "2020-10-26 09:58:17",
"updated_at": "2020-10-26 10:58:24"
}
}
2.4. Xóa thông tin loại thiết bị
[DELETE] - /type/{id}
Dữ liệu gửi lên gồm:
+ {id}: (required| number) id loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 2,
"name": "Thiết bị chiếu sáng",
"description": null,
"sorder": null,
"created_at": "2020-10-26 09:58:17",
"updated_at": "2020-10-26 09:58:24"
}
}
3. Device
Để lấy được thông tin Thiết bị cần gửi kèm header Authorization ứng với token đã được cấp.
3.1. Lấy danh sách loại thiết bị
[GET] - /device/{id}
Dữ liệu gửi lên gồm:
+ {id}: (optional | number) được dùng khi muốn xem chi tiết thông tin của một thiết bị.
+ pageId: (optional | number) được bắt đầu bằng trang thứ 0.
+ pageSize: (optional | number ) mặc định là 30, để lấy tất cả danh sách loại thiết bị hãy gửi lên -1.
+ terms: (optional | string) tìm kiếm theo tên, bssid, serial_number của thiết bị.
+ name: (optional | string) tìm kiếm theo tên của thiết bị.
+ bssid: (optional | string) tìm kiếm theo mã đăng ký của thiết bị.
+ status: (optional | string) trạng thái connect hoặc disconnect.
+ serial_number: (optional | string) số serial của thiết bị.
+ error_code: (optional | number) mã lỗi.
+ type_id: (optional | number) id loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"pagesCount": 1,
"pageId": 0,
"pageSize": 30,
"data": [
{
"id": 17,
"bssid": "98:1A:6B:7C:2D",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "123456765432",
"fw_version": null,
"error_code": 0,
"signal_strength": 0,
"type_id": 1,
"created_at": "2020-10-29 15:46:25",
"updated_at": "2020-10-29 15:46:25"
}
]
}
3.2. Thêm mới thiết bị
[POST] - /device
Dữ liệu gửi lên gồm:
+ bssid: (required | string) tìm kiếm theo mã đăng ký của thiết bị.
+ status: (optional | string) trạng thái connect hoặc disconnect.
+ serial_number: (optional | string) số serial của thiết bị.
+ fw_version: (optional | string) mã số phiên bản phần mềm.
+ error_code: (optional | number) mã lỗi.
+ signal_strength: (optional | number) cường độ tín hiệu.
+ type_id: (optional | number) id loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 17,
"bssid": "98:1A:6B:7C:2D",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "123456765432",
"fw_version": null,
"error_code": 0,
"signal_strength": 0,
"type_id": 1,
"created_at": "2020-10-29 15:46:25",
"updated_at": "2020-10-29 15:46:25"
}
}
3.3. Cập nhật thông tin thiết bị
[PATCH] - /device/{id}
Dữ liệu gửi lên gồm:
+ {id}: (required | number) mã thiết bị.
+ bssid: (required | string) tìm kiếm theo mã đăng ký của thiết bị.
+ status: (optional | string) trạng thái connect hoặc disconnect.
+ serial_number: (optional | string) số serial của thiết bị.
+ fw_version: (optional | string) mã số phiên bản phần mềm.
+ error_code: (optional | number) mã lỗi.
+ signal_strength: (optional | number) cường độ tín hiệu.
+ type_id: (optional | number) id loại thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 17,
"bssid": "98:1A:6B:7C:2D",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "123456765432",
"fw_version": null,
"error_code": 404,
"signal_strength": 100,
"type_id": 1,
"created_at": "2020-10-29 15:46:25",
"updated_at": "2020-10-29 15:46:25"
}
}
3.4. Xóa thiết bị
[DELETE] - /device/{id}
Dữ liệu gửi lên gồm:
+ {id}: (required | number) mã thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 17,
"bssid": "98:1A:6B:7C:2D",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "123456765432",
"fw_version": null,
"error_code": 0,
"signal_strength": 0,
"type_id": 1,
"created_at": "2020-10-29 15:46:25",
"updated_at": "2020-10-29 15:46:25"
}
}
3.5. Chia sẻ thiết bị
[POST] - /device/sharing
Dữ liệu gửi lên gồm:
+ {deviceId}: (required | number) mã thiết bị muốn chia sẻ.
+ {emails}: (required | array) danh sách địa chỉ email muốn chia sẻ quyền điều kiển thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
}
4. Action
4.1. Danh sách Action theo thiết bị
[GET] - /action/{deviceId}/{id}
Dữ liệu gửi lên gồm:
+ {deviceId}: (required | number) mã thiết bị.
+ {id}: (optional | number) mã action được dùng khi muốn xem chi tiết thông tin của một thiết bị.
+ pageId: (optional | number) được bắt đầu bằng trang thứ 0.
+ pageSize: (optional | number ) mặc định là 30, để lấy tất cả danh sách loại thiết bị hãy gửi lên -1.
+ status: (optional | string) trạng thái của action, có thể là enable hoặc disable.
+ type: (optional | string) loại action, có thể là schedule hoặc timer.
+ action: (optional | string) lệnh thông báo cho thiết bị, thường là on hoặc off.
+ repeat: (optional | string) thời gian lặp lại thực hiện action, thường là once hoặc các ngày trong tuần (monday,tuesday,...).
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"pagesCount": 1,
"pageId": 0,
"pageSize": 30,
"data": [
{
"id": 1,
"device_id": 23,
"status": "enable",
"type": "schedule",
"hour": 0,
"minute": 2,
"action": "on",
"repeat": "once",
"created_at": "2021-03-30 15:55:26",
"updated_at": "2021-03-30 15:55:26",
"user_id": 1
}
]
}
4.2. Thêm Action theo thiết bị
[POST] - /action/{deviceId}
Dữ liệu gửi lên gồm:
+ {deviceId}: (required | number) mã thiết bị.
+ status: (optional | string) trạng thái của action, có thể là enable hoặc disable
+ type: (optional | string) loại action, có thể là schedule hoặc timer.
+ action: (optional | string) lệnh thông báo cho thiết bị, thường là on hoặc off.
+ hour: (number | string) đơn vị giờ, trong khoảng từ 0 đến 23.
+ minute: (number | string) đơn vị giờ, trong khoảng từ 0 đến 59.
+ repeat: (optional | string) thời gian lặp lại thực hiện action, thường là once hoặc các ngày trong tuần (monday,tuesday,...).
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 6,
"device_id": 23,
"status": "enable",
"type": "timer",
"hour": 0,
"minute": 2,
"action": "off",
"repeat": "once",
"created_at": "2021-03-31 10:30:12",
"updated_at": "2021-03-31 10:30:12",
"user_id": 1
}
}
4.3. Cập nhật Action theo thiết bị
[PATCH] - /action/{deviceId}/{id}
Dữ liệu gửi lên gồm:
+ {deviceId}: (required | number) mã thiết bị.
+ {id}: (required | number) mã action.
+ status: (optional | string) trạng thái của action, có thể là enable hoặc disable
+ type: (optional | string) loại action, có thể là schedule hoặc timer.
+ action: (optional | string) lệnh thông báo cho thiết bị, thường là on hoặc off.
+ hour: (number | string) đơn vị giờ, trong khoảng từ 0 đến 23.
+ minute: (number | string) đơn vị giờ, trong khoảng từ 0 đến 59.
+ repeat: (optional | string) thời gian lặp lại thực hiện action, thường là once hoặc các ngày trong tuần (monday,tuesday,...).
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 6,
"device_id": 23,
"status": "enable",
"type": "timer",
"hour": 0,
"minute": 2,
"action": "on",
"repeat": "once",
"created_at": "2021-03-31 10:30:12",
"updated_at": "2021-03-31 10:30:12",
"user_id": 1
}
}
5. Sockets
Để thao tác được giữa App và Device hệ thống sử dụng thư viện socket.io dựa trên giao thức socket.
- Dành cho Device
1. Sau khi kết nối internet thành công, hoặc thiết bị tắt đi bật lại hãy gửi sự kiện:
Tên sự kiện(emit): registerDevice
Dữ liệu gửi kèm:
{
"bssid": "9A-8C-3D-4E-5F",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "12345678765432",
"fw_version": null,
"signal_strength": 100,
"error_code": 1,
"pins": [
{
"pin": 1,
"status": "on",
"startup": "off"
},
{
"pin": 2,
"status": "off",
"startup": "off"
}
]
}
Trong đó:
+ bssid: (required | string) mã định danh của thiết bị.
+ name: (string) tên của thiết bị.
+ status: (string | connect,disconnect) trạng thái của thiết bị đang được kết nối hay mất kết nối.
+ serial_number: (string) số serial của thiết bị.
+ signal_strength: (number) cường độ tín hiệu internet của thiết bị.
+ fw_version: (optional | string) mã số phiên bản phần mềm.
+ error_code: (number) mã lỗi.
+ pins: (required | array) danh sách các kênh của thiết bị có thể điều khiển.
2. Lắng nghe sự kiện điều khiển từ App:
Tên sự kiện(on): message
Dữ liệu gửi xuống: có thể là một (string | number | json)
- Nếu dữ liệu gửi xuống là JSON dùng để điều khiển thiết bị, cần theo đúng định dạng:
{
"pin": 1,
"status": "on",
"startup": "off"
}
Trong đó:
+ pin: (required | number) thiết bị muốn điều khiển, trong trường hợp thiết bị có thể điều khiển nhiều kênh khác nhau.
+ status: (required | on,off) trạng thái của pin muốn điều kiển.
+ startup: (required | on,off,stay) trạng thái của pin sau khi kết nối thành công internet.
3. Cập nhật trạng thái của thiết bị:
Tên sự kiện(emit): stateDevice
Dữ liệu gửi kèm:
{
"bssid": "9A-8C-3D-4E-5F",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "12345678987654321",
"fw_version": null,
"signal_strength": 100,
"error_code": 2,
"pins": [
{
"pin": 1,
"status": "off",
"startup": "off"
},
{
"pin": 2,
"status": "off",
"startup": "off"
}
]
}
Trong đó:
+ bssid: (required | string) mã định danh của thiết bị.
+ name: (string) tên của thiết bị.
+ status: (string | connect,disconnect) trạng thái của thiết bị, đang bật kết nối hay ngắt kết nối.
+ serial_number: (string) số serial của thiết bị.
+ fw_version: (optional | string) mã số phiên bản phần mềm.
+ signal_strength: (number) cường độ tín hiệu internet của thiết bị.
+ error_code: (number) mã lỗi.
+ pins: (required | array) danh sách các kênh của thiết bị có thể điều khiển.
4. Thực hiện Action(schedule, timer):
Tên sự kiện(on): executeAction
Dữ liệu gửi xuống là một (json)
{
"id": 5,
"device_id": 24,
"status": "disable",
"type": "schedule",
"hour": 0,
"minute": 2,
"action": "on",
"created_at": "2021-03-30 16:25:12",
"updated_at": "2021-03-31 10:05:19",
"user_id": 1
}
5. Cập nhật trạng thái Action(schedule, timer):
Tên sự kiện(emit): doneAction
Dữ liệu gửi kèm:
Trong đó:
+ id: (required | string) mã định danh của action.
- Dành cho App
1. Đăng ký App:
Tên sự kiện(emit): registerApp
Dữ liệu gửi kèm:
{
"user": {
"id": 1
},
"version": "1.0.0"
}
Trong đó:
+ user: (required | object) là đối tượng user đã đăng nhập ở app. Được lấy từ API lấy thông tin user.
+ version: (optional | string) phiên bản app hiện tại.
2. Điều khiển thiết bị
Tên sự kiện(emit): sendMessage
Dữ liệu gửi xuống: có thể là một (string | number | json)
- Nếu dữ liệu gửi xuống là JSON dùng để điều khiển thiết bị, cần theo đúng định dạng:
| String |
Number |
JSON |
|
{
"bssid": "9A-8C-3D-4E-5F",
"message": "Hello World!"
}
|
{
"bssid": "9A-8C-3D-4E-5F",
"message": 123456789
}
|
{
"bssid": "9A-8C-3D-4E-5F",
"message": {
"pin": 1,
"status": "on",
"startup": "off"
}
}
|
Trong đó:
+ bssid: (required | string) thiết bị muốn điều khiển.
+ pin: (optional | number) pin hoặc port muốn điều khiển, trong trường hợp thiết bị có thể điều khiển nhiều kênh khác nhau.
+ status: (optional | on,off) trạng thái của pin muốn điều kiển.
+ startup: (optional | on,off,stay) trạng thái của pin muốn điều kiển sau khi kết nối được internet.
3. Danh sách thiết bị
Sử dụng API lấy danh sách thiết bị ở bên trên.
4. Cập nhật trạng thái thiết bị
Tên sự kiện(on): stateDevice
Dữ liệu gửi xuống:
{
"bssid": "9A-8C-3D-4E-5F",
"name": "Công tắc điện",
"status": "connect",
"serial_number": "123456789",
"signal_strength": 100,
"error_code": 2,
"type_id": 1,
"pins": [
{
"pin": 1,
"status": "off",
"startup": "stay"
},
{
"pin": 2,
"status": "off",
"startup": "stay"
}
]
}
Trong đó:
+ bssid: (string) mã định danh của thiết bị.
+ name: (string) tên của thiết bị.
+ status: (string | connect,disconnect) trạng thái của thiết bị, đang kết nối hay ngắt kết nối.
+ serial_number: (string) số serial của thiết bị.
+ fw_version: (optional | string) mã số phiên bản phần mềm.
+ signal_strength: (number) cường độ tín hiệu internet của thiết bị.
+ error_code: (number) mã lỗi.
+ type_id: (number) mã loại thiết bị.
+ pins: (required | array) danh sách các kênh của thiết bị có thể điều khiển.
5. Cập nhật phần mềm
Tên sự kiện(emit): sendMessage
Dữ liệu gửi xuống là một (json). Ví dụ:
{
"bssid": "12ESAF244",
"message": {
"type": "updateFirmware",
"data": {
"id": 4,
"version": "4.0.0",
"description": "Release",
"status": "final",
"created_at": "2021-03-24 14:45:34",
"updated_at": "2021-03-24 14:45:37"
}
}
}
6. Thực hiện Action(schedule, timer):
Tên sự kiện(emit): executeAction
Dữ liệu gửi kèm:
{
"id": 5,
"device_id": 24,
"status": "disable",
"type": "schedule",
"hour": 0,
"minute": 2,
"action": "on",
"created_at": "2021-03-30 16:25:12",
"updated_at": "2021-03-31 10:05:19",
"user_id": 1
}
6. Cập nhật trạng thái Action(schedule, timer):
Tên sự kiện(on): doneAction
Dữ liệu nhận được:
{
"id": 5,
"device_id": 24,
"status": "disable",
"type": "schedule",
"hour": 0,
"minute": 2,
"action": "on",
"created_at": "2021-03-30 16:25:12",
"updated_at": "2021-03-31 10:05:19",
"user_id": 1
}
6. Firmware
6.1. Kiểm tra bản cập nhật phần mềm
[GET] - /firmware/update
Dữ liệu gửi lên gồm:
+ {deviceId}: (required | number) mã thiết bị.
Dữ liệu trả về nếu hợp lệ:
{
"status": "successful",
"message": "successful",
"data": {
"id": 4,
"version": "4.0.0",
"description": "Release",
"status": "final",
"created_at": "2021-03-24 14:45:34",
"updated_at": "2021-03-24 14:45:37"
}
}
ReInDeer