Khóa API & Open API
Khóa API là một chuỗi ký tự giống mật khẩu, để phần mềm khác lấy dữ liệu từ Resident mà không phải đăng nhập web: phần mềm kế toán, công cụ làm báo cáo (BI) hoặc hệ thống riêng của bạn. Hiện Open API chỉ đọc: lấy được tòa nhà, phòng, hợp đồng, khách thuê, hóa đơn, thu chi và chỉ số điện nước. Bạn dùng khi muốn đẩy số liệu sang phần mềm 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à mới thấy phần này.
Các bước
Tạo khóa
Bấm Tạo khoá, đặt Tên khoá theo phần mềm sẽ dùng khóa đó (ví dụ: MISA AMIS, Power BI) để sau này bạn biết thu hồi đúng khóa nào. 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 giữ 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 duy nhất trong hộp thoại vừa tạo. Bấm Sao chép, cất vào chỗ an toàn rồi bấm Tôi đã lưu khoá. Resident không lưu bản gốc của khóa nên không xem lại được; lỡ mất thì bạn tạo khóa mới.
Gọi API
Gửi khóa kèm trong phần đầu của yêu cầu (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"Kết quả trả về bọc chung một kiểu như mọi API của Resident:
{ "statusCode": 200, "status": 1, "data": { "items": [], "total": 123, "page": 1, "perPage": 50 }, "message": null, "errors": null }Thử ngay trên Swagger
Bấm Mở tài liệu Swagger hoặc vào https://api.resident.vn/open-docs . Đây là trang tài liệu cho phép gọi thử ngay trên trình duyệt: bấm Authorize, dán khóa vào rồi gọi thử từng địa chỉ.
Thu hồi khi không dùng nữa
Ở dòng khóa, bấm Thu hồi rồi xác nhận. Phần mềm đang dùng khóa đó mất quyền lấy dữ liệu ngay, và việc này 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 ai gọi.
Endpoint và tham số
Endpoint là địa chỉ để phần mềm gọi vào lấy từng loại dữ liệu.
| 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 |
Các tham số cho danh sách (đều không bắt buộc), địa chỉ đầy đủ bắt đầu bằng https://api.resident.vn/v1:
| Tham số | Ý nghĩa |
|---|---|
page, perPage | Chia trang kết quả, perPage nhiều nhất 200 |
apartmentId, roomId, contractId | Lọc theo tòa nhà / phòng / hợp đồng |
updatedSince | Ngày giờ theo chuẩn ISO 8601, chỉ lấy bản ghi đổi sau mốc này để lần sau chỉ tải phần mới |
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ỉ có các trường nghiệp vụ. Resident không trả ảnh giấy tờ, ghi chú riêng hay các cột kỹ thuật. Dữ liệu liên quan 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 nào |
429 | Gọi quá 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à, đọc được toàn bộ dữ liệu của tài khoản chứ không giới hạn theo tòa nhà. Bạn chỉ giao khóa cho bên tin cậy, không nhúng vào ứng dụng mà khách thuê dùng, và thu hồi ngay khi nghi khóa bị lộ.
Muốn mỗi lần chỉ tải phần mới, bạn lưu lại mốc updatedAt lớn nhất đã nhận. Lần sau gọi với updatedSince bằng mốc đó trừ 5 phút, rồi bỏ các bản ghi trùng id.
Câu hỏi thường gặp
Hỏi: Nhân viên tạo được khóa API không?
Không. Với tài khoản nhân viên, tab Tích hợp chỉ hiện dòng “Khoá API chỉ do chủ tài khoản quản lý.”
Hỏi: Ghi dữ liệu ngược vào Resident qua API được không?
Chưa được. Đợ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ẽ có sau.
Hỏi: Tôi thu hồi khóa rồi mà phần mềm bên ngoài vẫn lấy được dữ liệu 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, bạn xem lại phần mềm đó có đang hiện bản lưu tạm của chính 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 đều trả 401. Bạn tạo khóa mới rồi cập nhật ở phần mềm bên ngoài; khóa cũ thì bấm Thu hồi cho bảng gọn.