Khoá API và phạm vi

Mỗi khoá thuộc một trang trại và chỉ làm được đúng phần đã chọn. Người tạo khoá chỉ cấp được phạm vi mà chính họ đang có. Tạo và thu hồi ở Quản lý › Khoá API.

Gửi khoá

Một trong hai header (gateway nhận cả hai):

Lệnh mẫu

Authorization: Bearer nfk_...
X-Api-Key: nfk_...

Node.js

const res = await fetch("https://api-prod.nextfarm.vn/api/v1/iot/devices?status=offline", {
  headers: { Authorization: `Bearer ${process.env.NEXTFARM_API_KEY}` },
});
const { items } = await res.json();

Phạm vi

Bản đồ & mùa vụ

Phạm vi	Cho phép
`gis.parcels.view`	Xem thửa và mùa vụ
`gis.zones.view`	Xem vùng
`gis.farmers.view`	Xem nông dân
`gis.crop-types.view`	Xem loại cây trồng
`gis.facilities.view`	Xem công trình
`gis.layers.view`	Xem lớp bản đồ

IoT (chỉ đọc)

Phạm vi	Cho phép
`iot.devices.view`	Xem thiết bị
`iot.telemetry.view`	Xem số đo cảm biến
`iot.telemetry.export`	Xuất số đo cảm biến
`iot.alerts.view`	Xem cảnh báo

Thu hoạch & truy xuất

Phạm vi	Cho phép
`farm-harvest.harvest.view`	Xem lô thu hoạch
`farm-harvest.harvest.create`	Tạo lô thu hoạch (ghi)
`farm-harvest.qr-codes.view`	Xem tem QR
`farm-harvest.trace.view`	Xem truy xuất nguồn gốc
`farm-harvest.certification.view`	Xem chứng nhận
`farm-harvest.market-prices.view`	Xem giá thị trường

Sổ nông trại & công việc

Phạm vi	Cho phép
`office.base.record.view`	Xem dữ liệu sổ
`office.base.record.manage`	Thêm, sửa dòng sổ (ghi)
`office.task.view`	Xem công việc
`office.calendar.view`	Xem lịch

Báo cáo

Phạm vi	Cho phép
`report.view`	Xem báo cáo
`report.export`	Xuất báo cáo

Giới hạn an toàn

Khoá API, webhook và MCP không bao giờ điều khiển thiết bị — không có phạm vi nào cho bật/tắt, cấu hình thiết bị, và gateway chặn mọi tuyến ghi của IoT với khoá.

Khoá chỉ đọc, trừ: tạo/sửa lô thu hoạch, thêm/sửa dòng sổ nông trại. Không xoá được gì.
Không vào được quản trị người dùng, nhóm quyền, hay tạo khoá khác.
Thu hồi có hiệu lực ngay; khoá có thể đặt hạn (30 ngày, 90 ngày, 1 năm) hoặc không hết hạn.

Mã lỗi

Mã	Ý nghĩa
`401`	Khoá sai, hết hạn hoặc đã bị thu hồi.
`403`	Khoá thiếu phạm vi, hoặc tuyến không cho khoá API (chi tiết ở trường detail).
`404`	Không tìm thấy dữ liệu.
`422`	Dữ liệu gửi lên không hợp lệ (trường errors liệt kê từng lỗi).
`429`	Gọi quá nhanh — đọc Retry-After rồi thử lại.

Mốc thời gian trả về theo UTC (ISO 8601). Danh sách phân trang bằng page, page_size. Thân JSON gửi lên và trả về đều dùng snake_case (vd parcel_id) — khoá camelCase trong thân bị bỏ qua.

Luật bảo mật đầy đủ cho đối tác: Bảo mật →