API nhận chỉ số công tơ

Trong app quản lý: trang cơ sở → Cách lấy chỉ số điện nước → chọn Tự động (công tơ thông minh). Chủ nhà bấm Tạo khóa API — khóa chỉ hiện một lần, đổi / thu hồi được bất cứ lúc nào. Mỗi cơ sở một khóa.

Đặt mã công tơ (số seri) cho từng phòng ở trang Công tơ thông minh, hoặc gửi theo mã phòng + loại công tơ.

POST /api/meter-readings trên tên miền app quản lý của chủ nhà, tiêu đề Authorization: Bearer <khóa> (hoặc X-Api-Key). Thân JSON: một chỉ số, một mảng, hoặc { "readings": [...] } — tối đa 500 chỉ số, 256 KB, 60 yêu cầu / phút.

• meter — mã công tơ; hoặc room + kind (ELECTRIC / WATER)
• value — chỉ số cộng dồn (kWh / m³); phần lẻ bị bỏ như số đọc trên công tơ
• readAt — thời điểm đọc, ISO 8601 (không ghi múi giờ = giờ Việt Nam) hoặc epoch giây

curl -X POST https://<tên-miền-app>/api/meter-readings \
  -H "Authorization: Bearer oms_mtr_<khóa của cơ sở>" \
  -H "Content-Type: application/json" \
  -d '{ "readings": [
        { "meter": "SN-0001", "value": 1234.6, "readAt": "2026-10-31T23:55:00+07:00" },
        { "room": "101", "kind": "WATER", "value": 87, "readAt": "2026-10-31T23:55:00+07:00" }
      ] }'

{
  "ok": true,
  "summary": { "saved": 1, "review": 1, "duplicate": 0, "skipped": 0, "invalid": 0 },
  "results": [
    { "index": 0, "status": "saved", "meter": "SN-0001", "room": "101", "period": "2026-10" },
    { "index": 1, "status": "review", "meter": "phòng 101 · nước", "room": "101", "period": "2026-10",
      "flags": ["OUTLIER"] }
  ]
}

saved

Số hợp lý — đã lưu vào trang Chốt điện nước của kỳ (tháng của readAt, giờ Việt Nam; số cuối tháng thắng)

review

Số bất thường (giảm, tăng hơn 3 lần trung bình, công tơ chưa gán phòng, kỳ đã có số nhập tay khác, tháng đã khóa sổ) — chờ nhân viên kiểm tra

duplicate

Đã nhận đúng công tơ + thời điểm này trước đó — gửi lại an toàn, không ghi lần hai

skipped

Không dùng: kỳ đã lập hóa đơn, hoặc đã có số đọc mới hơn trong kỳ

invalid

Dòng sai định dạng (thiếu mã công tơ, chỉ số âm, thời điểm ở tương lai...) — xem message

Lỗi cả yêu cầu: 401 thiếu / sai khóa, 409 cơ sở chưa chọn “Tự động”, 400 JSON sai, 413 quá lớn, 429 gửi quá nhanh (đọc tiêu đề Retry-After), 403 gói dịch vụ hết hạn. Công tơ không gửi dữ liệu quá 3 ngày: nhân viên được báo.

Hãng chỉ xuất tệp: tải tệp CSV / Excel ở trang Công tơ thông minh trong app. Cột như API (hoặc room, kind, value, readAt):

meter,value,readAt
SN-0001,1234,2026-10-31 23:55
SN-0002,987,2026-10-31 23:55