Nhà phát triển

Neebo Partner API

API REST cho đối tác, thiết bị kiểm soát ra vào, hệ thống IoT và phần mềm của chủ đầu tư. Đọc dữ liệu căn hộ, cư dân, hóa đơn; tạo phản ánh; kiểm tra quyền vào cổng và nhận sự kiện qua webhook. Có trong gói Doanh nghiệp.

Tải đặc tả OpenAPI 3.1 Đặt lịch demo tích hợp

Xác thực bằng API key

Trưởng Ban quản lý tạo key trong web quản lý (Tích hợp → API key), chọn scope và các tòa được phép truy cập. Key chỉ hiện một lần khi tạo; thu hồi có hiệu lực ngay.

curl https://api.neebo.vn/partner/v1/buildings \
  -H "Authorization: Bearer nb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Base URL: https://api.neebo.vn/partner/v1
JSON UTF-8; thời gian là mili-giây Unix, ngày dạng YYYY-MM-DD giờ Việt Nam.
Lỗi: {"error": {"code": "...", "message": "..."}} kèm mã HTTP (401, 402, 403, 404, 422, 429).
Mỗi key chỉ thấy dữ liệu các tòa được gán (buildingIds).

Scope

Scope	Cho phép
`units:read`	Danh sách căn hộ của tòa
`residents:read`	Cư dân đang hoạt động (số điện thoại được che giữa)
`invoices:read`	Hóa đơn phí theo kỳ và trạng thái thanh toán
`tickets:write`	Tạo phản ánh từ hệ thống của bạn
`access:verify`	Kiểm tra quyền ra vào, gửi sự kiện cửa/barrier
`guests:verify`	Kiểm tra mã QR khách
`vehicles:verify`	Kiểm tra biển số xe đã đăng ký
`webhooks:manage`	Đăng ký và quản lý webhook

Lệnh chính

Lệnh	Scope	Mô tả
`GET /buildings`	`(mọi key)`	Tòa trong phạm vi key
`GET /units`	`units:read`	Căn hộ, phân trang limit/offset
`GET /residents`	`residents:read`	Cư dân đang hoạt động
`GET /invoices`	`invoices:read`	Hóa đơn theo kỳ, trạng thái
`POST /tickets`	`tickets:write`	Tạo phản ánh cho căn hộ
`POST /access/verify`	`access:verify`	QR căn, QR khách, phiếu chuyển đồ, biển số
`POST /access/events`	`access:verify`	Sự kiện thiết bị: cửa, barrier, báo động
`GET/POST /webhooks`	`webhooks:manage`	Danh sách, đăng ký webhook; xem nhật ký gửi

Danh sách phân trang bằng limit (mặc định 100, tối đa 500) và offset; nextOffset = null là hết dữ liệu. Ví dụ kiểm tra quyền vào cổng:

{ "qr": "neebo://unit/unit_abc", "gate": "Cổng A", "buildingId": "bld_x" }

→ { "allowed": true, "reason": "resident",
    "subject": { "kind": "unit", "id": "unit_abc", "unitCode": "A-1208" },
    "logId": "acl_…" }

Webhook

Đăng ký URL https để nhận sự kiện. Khi tạo, Neebo trả secret (whsec_…) đúng một lần. Sự kiện hỗ trợ:

invoice.paidticket.createdticket.status_changedguest.checked_invehicle.approvedmember.verifiedaccess.denied

{ "id": "whd_…", "event": "invoice.paid", "createdAt": 1792771834161,
  "buildingId": "bld_x", "data": { "invoiceId": "…", "total": 1250000 } }

Header gửi kèm: X-Neebo-Event, X-Neebo-Delivery (dùng chống trùng), X-Neebo-Timestamp (giây Unix) và X-Neebo-Signature: sha256=<hex>. Xác minh chữ ký trước khi xử lý:

import crypto from 'node:crypto';

// HMAC-SHA256(secret, "<X-Neebo-Timestamp>.<raw body>"), từ chối nếu lệch giờ quá 5 phút.
function verify(req, rawBody, secret) {
  const ts = req.headers['x-neebo-timestamp'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = req.headers['x-neebo-signature'] ?? '';
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300
    && got.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Phản hồi không phải 2xx hoặc quá 10 giây sẽ được gửi lại sau 30 giây, 2 phút, 8 phút, 32 phút (tối đa 5 lần). Nhật ký gửi có nút gửi lại và gửi thử trong web quản lý.

Giới hạn và bảo mật

600 lệnh/phút/key; vượt quá trả 429 rate_limited.
Mọi lệnh ghi được lưu nhật ký kiểm toán.
Khách hàng tạm ngưng do nợ phí chỉ còn dùng được lệnh GET (402 billing_suspended).
Lệnh ngoài phạm vi tòa của key trả 404, thiếu scope trả 403 insufficient_scope.

Cần tích hợp riêng cho dự án? Nói chuyện với Neebo.

Chúng tôi hỗ trợ kết nối thiết bị ra vào, barrier, phần mềm kế toán và hệ thống của chủ đầu tư. Đặt lịch demo để nhận key thử nghiệm.

Đặt lịch demo Xem bảng giá