Bản đồ & mùa vụ IoT (chỉ đọc)Thu hoạch & truy xuất Sổ nông trại

Thu hoạch & truy xuất

Bản ghi thu hoạch, lô truy xuất nguồn gốc, tem QR, chứng nhận VietGAP/GlobalGAP.

6 thao tác · gốc /api/v1/farm-harvest

GET/api/v1/farm-harvest/harvest-records

Bản ghi thu hoạch: thửa, cây, sản lượng (kg), trạng thái.

Công cụ MCP: harvest_list_recordsPhạm vi: farm-harvest.harvest.view

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`status`	string	query	không	—
`page`	int	query	không	Trang (mặc định 1)
`page_size`	int	query	không	Số dòng/trang (tối đa 100)

Ví dụ

curl https://api-prod.nextfarm.vn/api/v1/farm-harvest/harvest-records?status=...&page=1&page_size=20 \
  -H "Authorization: Bearer nfk_..."

POST/api/v1/farm-harvest/harvest-records

GHI: khai báo một lô thu hoạch (confirm=true thì xác nhận ngay và phát sự kiện harvest.batch.created).

Công cụ MCP: harvest_create_recordPhạm vi: farm-harvest.harvest.create

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`parcel_id`	GUID	body	có	—
`crop_type_id`	GUID	body	có	—
`season_id`	GUID	body	không	—
`declared_quantity_kg`	int	body	có	Sản lượng (kg), số thập phân được
`harvest_date`	date	body	có	YYYY-MM-DD
`notes`	string	body	không	—
`photo_urls`	object	body	có	Mảng URL ảnh — gửi [] nếu không có ảnh
`confirm`	bool	body	không	Mặc định true

Ví dụ

curl -X POST https://api-prod.nextfarm.vn/api/v1/farm-harvest/harvest-records \
  -H "Authorization: Bearer nfk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "parcel_id": "<parcel_id>",
    "crop_type_id": "<crop_type_id>",
    "season_id": "<season_id>",
    "declared_quantity_kg": 1,
    "harvest_date": "2026-06-01",
    "notes": "...",
    "photo_urls": [],
    "confirm": false
  }'

GET/api/v1/farm-harvest/trace

Lô truy xuất đã phát hành.

Công cụ MCP: trace_list_lotsPhạm vi: farm-harvest.trace.view

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`page`	int	query	không	Trang (mặc định 1)
`page_size`	int	query	không	Số dòng/trang (tối đa 100)

Ví dụ

curl https://api-prod.nextfarm.vn/api/v1/farm-harvest/trace?page=1&page_size=20 \
  -H "Authorization: Bearer nfk_..."

GET/api/v1/farm-harvest/trace/{id}

Chi tiết lô: nhật ký canh tác, chứng nhận, ảnh.

Công cụ MCP: trace_get_lotPhạm vi: farm-harvest.trace.view

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`id`	GUID	path	có	—

Ví dụ

curl https://api-prod.nextfarm.vn/api/v1/farm-harvest/trace/<id> \
  -H "Authorization: Bearer nfk_..."

GET/api/v1/farm-harvest/certifications/expiring

Chứng nhận sắp hết hạn.

Công cụ MCP: cert_list_expiringPhạm vi: farm-harvest.certification.view

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`within_days`	int	query	không	Mặc định 30

Ví dụ

curl https://api-prod.nextfarm.vn/api/v1/farm-harvest/certifications/expiring?within_days=1 \
  -H "Authorization: Bearer nfk_..."

GET/api/v1/farm-harvest/search

Tìm lô, tem QR, chứng nhận.

Công cụ MCP: harvest_searchPhạm vi: farm-harvest.harvest.view

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`q`	string	query	có	Từ khoá, không dấu cũng được

Ví dụ

curl https://api-prod.nextfarm.vn/api/v1/farm-harvest/search?q=... \
  -H "Authorization: Bearer nfk_..."