Khóa API & Open API
Khóa API cho phép phần mềm kế toán, công cụ báo cáo (BI) hoặc hệ thống riêng của bạn đọc dữ liệu Resident mà không cần đăng nhập web. Hiện tại Open API chỉ đọc: lấy tòa nhà, phòng, hợp đồng, khách thuê, hóa đơn, thu chi và chỉ số điện nước. Dùng khi bạn muốn đồng bộ số liệu sang hệ thống khác hoặc tự dựng báo cáo.
Cách vào
Mở Cài đặt → Cài đặt chung, chọn tab Tích hợp. Bên trái là bảng Khoá API với các cột Tên, Khoá, Dùng lần cuối, Hết hạn, Trạng thái; bên phải là Tài liệu Open API, Dữ liệu lấy được và Ví dụ. Chỉ tài khoản chủ nhà thấy được nội dung này.
Các bước
Tạo khóa
Bấm Tạo khoá, nhập Tên khoá theo hệ thống sẽ dùng (ví dụ: MISA AMIS, Power BI) để sau dễ thu hồi đúng khóa. Chọn Thời hạn: Không hết hạn, 90 ngày, 180 ngày hoặc 365 ngày. Mỗi tài khoản có tối đa 10 khóa đang hoạt động.
Sao chép và cất khóa
Khóa dạng rsk_live_... chỉ hiện một lần trong hộp thoại vừa tạo. Bấm Sao chép, lưu vào nơi an toàn rồi bấm Tôi đã lưu khoá. Resident chỉ lưu bản băm nên không xem lại được; mất khóa thì tạo khóa mới.
Gọi API
Gửi khóa trong header Authorization: Bearer <khóa> hoặc X-Api-Key: <khóa>:
curl -H "Authorization: Bearer rsk_live_xxxxxxxx" \
"https://api.resident.vn/v1/open/invoices?page=1&perPage=50&updatedSince=2026-09-01"Phản hồi bọc chung như mọi API Resident:
{ "statusCode": 200, "status": 1, "data": { "items": [], "total": 123, "page": 1, "perPage": 50 }, "message": null, "errors": null }Thử trực tiếp trên Swagger
Bấm Mở tài liệu Swagger hoặc vào https://api.resident.vn/open-docs . Bấm Authorize, dán khóa và gọi thử từng endpoint ngay trên trình duyệt.
Thu hồi khi không dùng nữa
Ở dòng khóa, bấm Thu hồi và xác nhận. Hệ thống đang dùng khóa mất quyền truy cập ngay và không hoàn tác được. Cột Dùng lần cuối giúp bạn nhận ra khóa nào đã lâu không gọi.
Endpoint và tham số
| Nhóm | Danh sách | Chi tiết |
|---|---|---|
| Thông tin khóa | GET /open/me | |
| Tòa nhà | GET /open/apartments | GET /open/apartments/:id |
| Phòng | GET /open/rooms | GET /open/rooms/:id |
| Hợp đồng | GET /open/contracts | GET /open/contracts/:id |
| Khách thuê | GET /open/tenants | GET /open/tenants/:id |
| Hóa đơn | GET /open/invoices | GET /open/invoices/:id (kèm items) |
| Thu / chi | GET /open/income-expenses | GET /open/income-expenses/:id |
| Chỉ số điện nước | GET /open/meter-logs | GET /open/meter-logs/:id |
Tham số danh sách (đều tùy chọn), tiền tố đầy đủ là https://api.resident.vn/v1:
| Tham số | Ý nghĩa |
|---|---|
page, perPage | Phân trang, perPage tối đa 200 |
apartmentId, roomId, contractId | Lọc theo tòa nhà / phòng / hợp đồng |
updatedSince | ISO 8601, chỉ lấy bản ghi đổi sau mốc này để đồng bộ tăng dần |
from, to | YYYY-MM-DD, lọc theo ngày lập (hóa đơn, thu chi, chỉ số) |
search | Tìm theo tên / số điện thoại / mã |
Mỗi bản ghi chỉ gồm trường nghiệp vụ; không trả ảnh giấy tờ, ghi chú riêng hay cột kỹ thuật. Quan hệ trả gọn dạng { id, name }.
Mã lỗi
| Mã | Nguyên nhân |
|---|---|
401 | Thiếu khóa, sai khóa hoặc khóa đã thu hồi / hết hạn |
403 | Gói dịch vụ Resident hết hạn (messageCode: ACCOUNT_EXPIRED) |
404 | Không có bản ghi |
429 | Vượt 600 yêu cầu/phút cho một khóa; xem header X-RateLimit-Remaining và Retry-After |
Lưu ý
Khóa chạy với quyền chủ nhà và đọc được toàn bộ dữ liệu của tài khoản, không giới hạn theo tòa nhà. Chỉ giao cho bên tin cậy, không nhúng vào ứng dụng phía người dùng, và thu hồi ngay khi nghi ngờ lộ.
Để đồng bộ tăng dần, lưu updatedAt lớn nhất đã nhận; lần sau gọi với updatedSince bằng mốc đó trừ 5 phút và bỏ trùng theo id.
Câu hỏi thường gặp
Hỏi: Nhân viên có tạo được khóa API không?
Không. Tab Tích hợp chỉ hiện dòng “Khoá API chỉ do chủ tài khoản quản lý.” với tài khoản nhân viên.
Hỏi: Có ghi dữ liệu vào Resident qua API được không?
Chưa. Đợt này Open API chỉ đọc (Quyền truy cập: Chỉ đọc). Quyền ghi và giới hạn theo tòa nhà sẽ bổ sung sau.
Hỏi: Tôi thu hồi khóa nhưng hệ thống ngoài vẫn gọi được vài giây?
Thu hồi có hiệu lực ngay; cột Trạng thái chuyển sang Đã thu hồi. Nếu vẫn thấy dữ liệu, kiểm tra hệ thống ngoài có đang dùng bản cache của riêng nó không.
Hỏi: Khóa hết hạn thì sao?
Trạng thái đổi thành Hết hạn và mọi yêu cầu trả 401. Tạo khóa mới rồi cập nhật ở hệ thống ngoài; khóa cũ có thể Thu hồi để gọn bảng.