API Lấy giờ chấm công từ phần mềm WiseEye
HƯỚNG DẪN SỬ DỤNG API LẤY DỮ LIỆU CHẤM CÔNG Phần mềm Wise Eye Mix3 – TAPusher – ITSV3
1.Giới thiệu
API cho phép các hệ thống bên ngoài (Website, ERP, HRM, phần mềm nội bộ…) truy xuất dữ liệu chấm công từ phần mềm Wise Eye thông qua Server Proxy.
Việc tích hợp API giúp:
- Đồng bộ dữ liệu chấm công sang hệ thống khác
- Xây dựng hệ thống báo cáo riêng
- Tích hợp với phần mềm nhân sự hoặc ERP
- Tự động hóa quy trình xử lý dữ liệu chấm công
API hoạt động theo giao thức HTTP POST và sử dụng API Token để xác thực truy cập.
2. Tạo API Token
Để sử dụng API, cần tạo API Token trong phần mềm Wise Eye.
Thực hiện:
- Mở WiseEye Proxy → vào mục API / Token
- Bấm thêm mới
- Nhập tên API Token
- Bấm thực hiện để lưu lại
- Sao chép API Token
- Sử dụng Token này trong Body Request
→ Hostname của máy chủ WiseEyeProxy
3.Thông tin kết nối API
URL Request
http://hostname/api?id=[id API]
Trong đó:
| Tham số | Ý nghĩa |
|---|---|
| hostname | Địa chỉ Server Proxy của phần mềm Wise Eye |
| api_name | Tên API cần gọi |
Phương thức : POST
Header / Body gửi lên
Dữ liệu gửi lên ở dạng JSON
{
"apitoken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJUb2tlbk5hbWUiOiJUZXN0Iiwi
VG9rZW5QYXNzIjoiVGVzdCJ9.HkS8hk15BJGNl4awJtefw363ZuP_wIr-U6NwJDkxlno"
}
Các tham số khác tùy thuộc vào từng API, apitoken được tạo từ phần Quản lý trên phần mềm chính.
4.Cấu trúc phản hồi của API
Kết quả trả về luôn có cấu trúc như sau:
{Giải thích các trường
|
Trường |
Ý nghĩa |
|
result |
có giá trị boolean, true là thành công, false: thất bại |
|
info |
giá trị 1 object bao gồm code và message – thường biểu diễn cho thông tin lỗi và thông tin của các API như thêm mới, cập nhật và xóa. |
|
total |
giá trị số record thông tin data |
|
data |
dạng array của các object tùy vào api |
5.API Lấy Dữ Liệu Chấm Công
5.1 Lấy dữ liệu chấm công trong ngày hiện tại
API này dùng để lấy toàn bộ dữ liệu chấm công của ngày hôm nay.
URL : http://hostname/api?id=getrecordtoday
Phương thức : POST
Body Request
{
"apitoken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJUb2tlbk5hbWUiOiJXaXNlRXllIn0.Ljv-EyFE4XhlTwOEt177aXzK7UykZQIhm3gZoAzEWUw"
}
Kết quả trả về
{
"result": true,
"total": 2,
"rows": [
{
"userenrollnumber": "10",
"timestr": "2023-06-29 07:27:11",
"origintype": "I",
"source": "FP",
"machineno": 1,
"timedate": "2023-06-29"
},
{
"userenrollnumber": "10",
"timestr": "2023-06-29 17:02:02",
"origintype": "O",
"source": "FP",
"machineno": 1,
"timedate": "2023-06-29"
}
]
}
Ý nghĩa các trường dữ liệu
|
Trường |
Ý nghĩa |
|
userenrollnumber |
mã đăng ký chấm công (ID chấm công) |
|
timestr |
giờ chấm công (yyyy-MM-dd HH:mm:ss) |
|
origintype |
Loại chấm công (I = In, O = Out) |
|
source |
Nguồn chấm công |
|
machineno |
Số máy chấm công khai báo trên phần mềm |
|
timedate |
ngày chấm công (yyyy-MM-dd) |
Các giá trị của source
| Giá trị | Ý nghĩa |
|---|---|
| FP | Chấm công bằng vân tay |
| FACE | Chấm công bằng khuôn mặt |
| PW | Chấm công bằng mật khẩu / thẻ |
| PC | Dữ liệu được thêm từ máy tính |
5.2 Lấy dữ liệu chấm công theo ngày
API này dùng để lấy dữ liệu chấm công của một ngày cụ thể.
URL : http://hostname/api?id=getrecordbydate
Body Request
{
"apitoken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJUb2tlbk5hbWUiOiJXaXNlRXllIn0.Ljv-EyFE4XhlTwOEt177aXzK7UykZQIhm3gZoAzEWUw",
"startdate":"2023-06-01 00:00:00",
"enddate":"2023-06-29 23:59:59"
}Tham số
|
Tham số |
Ý nghĩa |
|
recorddate |
Ngày cần lấy dữ liệu |
|
Định dạng ngày |
yyyy-MM-dd |
5.3 Lấy dữ liệu chấm công theo khoảng thời gian
API này dùng để lấy dữ liệu chấm công trong một khoảng thời gian xác định.
URL : http://hostname/api?id=getrecordbyperiodoftime
Body Request
{
"apitoken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJUb2tlbk5hbWUiOiJXaXNlR
XllIn0.Ljv-EyFE4XhlTwOEt177aXzK7UykZQIhm3gZoAzEWUw",
"startdate":"2023-06-01 00:00:00",
"enddate":"2023-06-29 23:59:59"
}|
Tham số |
Ý nghĩa |
|
startdate |
Thời gian bắt đầu |
|
enddate |
Thời gian kết thúc |
|
Định dạng thời gian |
yyyy-MM-dd HH:mm:ss |
6.Lọc dữ liệu theo nhân viên
Nếu chỉ muốn lấy dữ liệu của một nhân viên cụ thể, thêm tham số: "userenrollnumber"
Ví dụ
"apitoken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJUb2tlbk5hbWUiOiJXaXNlRXllIn0.Ljv-EyFE4XhlTwOEt177aXzK7UykZQIhm3gZoAzEWUw",
"startdate":"2023-06-01 00:00:00",
"enddate":"2023-06-29 23:59:59",
"userenrollnumber": "5555"
}
7.Lưu ý khi tích hợp API
-
Server Proxy của Wise Eye phải đang hoạt động
-
Phải mở port API trên server
-
Token phải hợp lệ
8.Các lỗi thường gặp
| Lỗi | Nguyên nhân |
|---|---|
| Invalid Token | Token sai hoặc hết hạn |
| result = false | Lỗi tham số hoặc server |
| Không trả dữ liệu | Không có record trong thời gian yêu cầu |