Tài liệu › Tham chiếu API › Thu hoạch & truy xuất

Thu hoạch & truy xuất

Bản ghi thu hoạch, cách ly thuốc, lô truy xuất, tem QR, chứng nhận, giá thị trường.

25 thao tác · gốc /api/v1/harvest

GET/api/v1/harvest/certifications

Danh sách chứng nhận của workspace

Scope: harvest.certification.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/certifications" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "certificate_number": "…",
    "expires_in_days": 1,
    "expiry_date": "2026-10-28",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "is_expired": true,
    "issued_by": "…",
    "issued_date": "2026-10-28",
    "name": "…",
    "parcel_code": "…",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "scheme": "…"
  }
]

GET/api/v1/harvest/certifications/expiring

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

Sắp theo ngày hết hạn TĂNG DẦN — bản đã hết hạn lâu nhất đứng đầu. within_days là cửa sổ nhìn tới tính từ hôm nay (mặc định 90). include_expired mặc định BẬT: nhóm đã hết hạn mới là nhóm gấp nhất.

Scope: harvest.certification.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`within_days`	int	query	không	—
`include_expired`	bool	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/certifications/expiring" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "certificate_number": "…",
    "expires_in_days": 1,
    "expiry_date": "2026-10-28",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "is_expired": true,
    "issued_by": "…",
    "issued_date": "2026-10-28",
    "name": "…",
    "parcel_code": "…",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "scheme": "…"
  }
]

GET/api/v1/harvest/harvest-records

Danh sách bản ghi thu hoạch

Lọc theo status. Phân trang.

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`status`	string	query	không	—
`page`	int	query	không	—
`pageSize`	int	query	không	—
`filter_rules`	string	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "actual_quantity_kg": 1.5,
      "created_at": "2026-10-28T07:30:00Z",
      "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "crop_type_name": "…",
      "declared_quantity_kg": 1.5,
      "farming_task_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "harvest_date": "2026-10-28",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "needs_review": true,
      "parcel_code": "…",
      "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "return_reason": "…",
      "returned_at": "2026-10-28T07:30:00Z",
      "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "status": "…",
      "trace_anchor_date": "2026-10-28",
      "trace_bundle_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "trace_incident": true,
      "trace_status": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 1
}

POST/api/v1/harvest/harvest-records

Khai báo thu hoạch

Tạo HarvestRecord. Nếu confirm=true (mặc định) thì confirm ngay và publish harvest.declared. Nếu confirm=false thì lưu Draft.

Scope: harvest.harvest.createThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`confirm`	bool	body	không	—
`crop_type_id`	GUID	body	không	—
`declared_quantity_kg`	int	body	không	—
`farming_task_id`	GUID	body	không	—
`harvest_date`	date	body	không	—
`notes`	string	body	không	—
`organisms`	object	body	không	—
`parcel_id`	GUID	body	không	—
`phi_override_reason`	string	body	không	—
`photo_urls`	object	body	không	—
`season_id`	GUID	body	không	—

Ví dụ

curl -X POST "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": true, "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001", "declared_quantity_kg": 1.5, "farming_task_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001", "harvest_date": "2026-10-28", "notes": "…", "organisms": [ { "fruit_count": 1, "organism_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001", "quantity_kg": 1.5 } ], "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001", "phi_override_reason": "…", "photo_urls": [ "…" ], "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001" }'

Phản hồi mẫu

201 Created
{
  "created_at": "2026-10-28T07:30:00Z",
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "crop_type_name": "…",
  "declared_quantity_kg": 1.5,
  "farming_task_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "harvest_date": "2026-10-28",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "needs_review": true,
  "parcel_code": "…",
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "return_reason": "…",
  "returned_at": "2026-10-28T07:30:00Z",
  "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "status": "…",
  "trace_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "warnings": [
    "…"
  ]
}

Gửi lại an toàn: mạng chập, không biết phiếu đã vào chưa? Gửi lại y nguyên với cùng Idempotency-Key — phiếu đã có thì nhận lại đúng phiếu đó (201, cùng id); chưa có thì tạo mới. Không gửi mã thì mỗi lần gọi là một phiếu mới.

GET/api/v1/harvest/harvest-records/preview-trace

Kiểm tra trước khi khoá (D2): bó truy xuất sẽ nhận những gì

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`parcelId`	GUID	query	không	—
`seasonId`	GUID	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records/preview-trace" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "certification_expiry": "2026-10-28",
  "certification_name": "…",
  "certification_number": "…",
  "has_season": true,
  "input_count": 1,
  "parcel_has_boundary": true,
  "season_name": "…",
  "stage_count": 1,
  "stages_with_photo": 1
}

GET/api/v1/harvest/harvest-records/summary

Tổng hợp sản lượng theo hộ / vùng / cây / thửa

group_by = owner (theo hộ) | zone (theo vùng) | crop (theo cây) | parcel (theo thửa). Chỉ tính phiếu ĐÃ XÁC NHẬN (Confirmed · Verified · Collected); kg = cân thực tế nếu đã kiểm, ngược lại số khai. from/to lọc theo ngày thu hoạch (yyyy-MM-dd), zoneId/cropTypeId lọc thêm. Hộ và vùng lấy từ gis tại lúc đọc (gis không trả lời được ⇒ báo lỗi dịch vụ ngoài, KHÔNG trả số thiếu). Phân trang (tối đa 200 dòng/trang), xếp theo tổng kg giảm dần.

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`group_by`	string	query	không	—
`from`	date	query	không	—
`to`	date	query	không	—
`zoneId`	GUID	query	không	—
`cropTypeId`	GUID	query	không	—
`page`	int	query	không	—
`pageSize`	int	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records/summary" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "key": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "name": "…",
      "parcel_count": 1,
      "record_count": 1,
      "total_kg": 1.5
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 1
}

GET/api/v1/harvest/harvest-records/{id}

Chi tiết bản ghi thu hoạch

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "actual_quantity_kg": 1.5,
  "created_at": "2026-10-28T07:30:00Z",
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "crop_type_name": "…",
  "declared_quantity_kg": 1.5,
  "farming_task_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "harvest_date": "2026-10-28",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "needs_review": true,
  "parcel_code": "…",
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "return_reason": "…",
  "returned_at": "2026-10-28T07:30:00Z",
  "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "status": "…",
  "trace_anchor_date": "2026-10-28",
  "trace_bundle_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "trace_incident": true,
  "trace_status": "…"
}

PUT/api/v1/harvest/harvest-records/{id}

Cập nhật khai báo thu hoạch

Chỉ cập nhật được khi status = draft.

Scope: harvest.harvest.createThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`id`	GUID	path	có	—
`declared_quantity_kg`	int	body	không	—
`harvest_date`	date	body	không	—
`notes`	string	body	không	—
`phi_override_reason`	string	body	không	—

Ví dụ

curl -X PUT "https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "declared_quantity_kg": 1.5, "harvest_date": "2026-10-28", "notes": "…", "phi_override_reason": "…" }'

Phản hồi mẫu

200 OK
{
  "created_at": "2026-10-28T07:30:00Z",
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "crop_type_name": "…",
  "declared_quantity_kg": 1.5,
  "farming_task_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "harvest_date": "2026-10-28",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "needs_review": true,
  "parcel_code": "…",
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "return_reason": "…",
  "returned_at": "2026-10-28T07:30:00Z",
  "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "status": "…",
  "trace_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "warnings": [
    "…"
  ]
}

GET/api/v1/harvest/market-prices

Danh sách giá đã ghi nhận

Lọc theo mặt hàng (nhiều mã), chợ/vùng và khoảng ngày. Phân trang.

Scope: harvest.market-prices.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`commodityCode`	object	query	không	—
`market`	string	query	không	—
`fromDate`	date	query	không	—
`toDate`	date	query	không	—
`page`	int	query	không	—
`pageSize`	int	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/market-prices" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "commodity_code": "…",
      "commodity_name": "…",
      "created_at": "2026-10-28T07:30:00Z",
      "grade": "…",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "market": "…",
      "note": "…",
      "recorded_by_name": "…",
      "recorded_on": "2026-10-28",
      "source": "…",
      "unit": "…",
      "unit_price": 1.5
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 1
}

GET/api/v1/harvest/market-prices/series

Chuỗi giá theo thời gian để vẽ biểu đồ

Mọi chuỗi trả về CÙNG MỘT đơn vị (trường `unit` ở cấp response). Biểu đồ bên FE chỉ có một trục y — mặt hàng lệch đơn vị bị bỏ qua chứ KHÔNG quy đổi, vì đoán sai hệ số quy đổi là sai số liệu âm thầm. Không truyền `unit` thì lấy đơn vị phổ biến nhất trong khoảng lọc.

Scope: harvest.market-prices.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`commodityCode`	object	query	không	—
`fromDate`	date	query	không	—
`toDate`	date	query	không	—
`unit`	string	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/market-prices/series" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "series": [
    {
      "commodity_code": "…",
      "commodity_name": "…",
      "points": [
        {
          "recorded_on": "2026-10-28",
          "unit_price": 1.5
        }
      ],
      "unit": "…"
    }
  ],
  "unit": "…"
}

GET/api/v1/harvest/market-prices/{id}

Chi tiết một bản ghi giá

Scope: harvest.market-prices.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/market-prices/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "commodity_code": "…",
  "commodity_name": "…",
  "created_at": "2026-10-28T07:30:00Z",
  "grade": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "market": "…",
  "note": "…",
  "recorded_by_name": "…",
  "recorded_on": "2026-10-28",
  "source": "…",
  "unit": "…",
  "unit_price": 1.5
}

GET/api/v1/harvest/parcels/phi-active

Các thửa đang trong thời gian cách ly

Gộp lần phun ghi nhật ký, phiếu xuất thuốc BVTV và thuốc thú y từ kho (GĐ4), thuốc thú y ở sổ đàn/ao — tức cả thửa vườn lẫn ao/chuồng đang cách ly hoặc ngưng thuốc. on = ngày xét (mặc định hôm nay giờ VN). Mỗi dòng: parcel_id, safe_from (ngày sớm nhất được thu), blocking (lần dùng thuốc đang giữ cách ly; kind = spray | inventory | inventory_vet | vet). Theo phạm vi thửa của người xem. Dùng cho màn Thu hoạch và Tổng quan nông trại.

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`on`	date	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/parcels/phi-active" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "active": true,
    "blocking": {
      "active_ingredient": "…",
      "field_log_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "kind": "…",
      "phi_days": 1,
      "product": "…",
      "safe_from": "2026-10-28",
      "sprayed_on": "2026-10-28"
    },
    "on_date": "2026-10-28",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "safe_from": "2026-10-28"
  }
]

GET/api/v1/harvest/parcels/{parcelId}/phi-status

Thửa có đang trong thời gian cách ly không

Tính từ các lần phun thuốc BVTV (và thuốc thú y ở sổ đàn/ao) có ghi số ngày cách ly. on = ngày định thu (yyyy-MM-dd, mặc định hôm nay giờ VN). active=true ⇒ khai thu hoạch ngày đó sẽ bị chặn trừ khi ghi lý do; safe_from = ngày sớm nhất được thu.

Scope: harvest.harvest.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`parcelId`	GUID	path	có	—
`on`	date	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/parcels/<parcelId>/phi-status" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "active": true,
  "blocking": {
    "active_ingredient": "…",
    "field_log_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "kind": "…",
    "phi_days": 1,
    "product": "…",
    "safe_from": "2026-10-28",
    "sprayed_on": "2026-10-28"
  },
  "on_date": "2026-10-28",
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "safe_from": "2026-10-28"
}

GET/api/v1/harvest/product-infos

Danh sách hồ sơ sản phẩm

Gồm hồ sơ riêng của workspace và các hồ sơ dùng chung (workspace_id rỗng).

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/product-infos" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "benefits": [
      {
        "description": "…",
        "title": "…"
      }
    ],
    "crop_name": "…",
    "display_name": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "image_urls": [
      "…"
    ],
    "is_active": true,
    "tagline": "…",
    "updated_at": "2026-10-28T07:30:00Z",
    "usage_note": "…",
    "workspace_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
  }
]

GET/api/v1/harvest/qr-codes

Danh sách mã QR của 1 mùa vụ

Scope: harvest.qr-codes.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`seasonId`	GUID	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/qr-codes" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "code": "…",
    "created_at": "2026-10-28T07:30:00Z",
    "effective_to": "2026-10-28",
    "first_scanned_at": "2026-10-28T07:30:00Z",
    "harvest_date": "2026-10-28",
    "harvest_record_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "last_scanned_at": "2026-10-28T07:30:00Z",
    "scan_count": 1,
    "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
  }
]

GET/api/v1/harvest/qr-codes/usage

Số tem đã dùng / trần của gói Miễn phí (5 tem tổng / workspace)

Scope: harvest.qr-codes.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/qr-codes/usage" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "limit": 1,
  "remaining": 1,
  "used": 1
}

GET/api/v1/harvest/qr-codes/{id}/scans

Lượt quét theo ngày của một mã QR (Q6)

Scope: harvest.qr-codes.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/qr-codes/<id>/scans" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "code": "…",
  "days": [
    {
      "day": "2026-10-28",
      "visitors": 1
    }
  ],
  "first_scanned_at": "2026-10-28T07:30:00Z",
  "last_scanned_at": "2026-10-28T07:30:00Z",
  "qr_code_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "scan_count": 1,
  "warn_threshold": 1
}

GET/api/v1/harvest/search

Tìm bản ghi thu hoạch, tem QR, chứng nhận

Không phân biệt dấu. Dưới 2 ký tự trả rỗng. Mỗi nhóm tối đa `limit` (1–20).

Scope: tự lọc theo scope của khoáThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`q`	string	query	không	—
`limit`	int	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/search" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "certifications": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ],
  "harvests": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ],
  "qr_codes": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ]
}

GET/api/v1/harvest/trace

Danh sách TraceBundle của workspace (yêu cầu đăng nhập)

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "anchor_date": "2026-10-28",
    "anchor_is_backfill": true,
    "anchor_status": "…",
    "bundle_version": 1,
    "certification": "…",
    "content_hash": "…",
    "created_at": "2026-10-28T07:30:00Z",
    "farmer": "…",
    "harvest_date": "2026-10-28",
    "harvest_record_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "has_open_incident": true,
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "is_locked": true,
    "parcel_code": "…",
    "product": "…",
    "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "stage_count": 1,
    "zone_name": "…"
  }
]

GET/api/v1/harvest/trace-anchors

Lượt neo có lô của workspace (D7) + lô đã niêm phong chờ lượt tới

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`take`	int	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-anchors" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "anchor_schedule_local": "…",
  "anchors": [
    {
      "anchor_date": "2026-10-28",
      "attempts": 1,
      "bitcoin_block_height": 1,
      "bitcoin_confirmed_at": "2026-10-28T07:30:00Z",
      "bundles": [
        {
          "bundle_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
          "content_hash": "…",
          "harvest_date": "2026-10-28",
          "harvest_record_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
          "parcel_code": "…",
          "product": "…",
          "version": 1
        }
      ],
      "confirmed_at": "2026-10-28T07:30:00Z",
      "created_at": "2026-10-28T07:30:00Z",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "is_backfill": true,
      "leaf_count": 1,
      "merkle_root": "…",
      "polygon_chain_id": 1,
      "polygon_confirmed_at": "2026-10-28T07:30:00Z",
      "polygon_tx_hash": "…",
      "status": "…",
      "submitted_at": "2026-10-28T07:30:00Z"
    }
  ],
  "pending": [
    {
      "bundle_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "parcel_code": "…",
      "product": "…",
      "sealed_at": "2026-10-28T07:30:00Z",
      "version": 1
    }
  ]
}

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

Chứng thư xác thực blockchain (PDF, D4)

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-certificate/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

Tuyến này chưa khai schema phản hồi — gọi thử trong API Explorer để xem hình dạng.

GET/api/v1/harvest/trace-incidents

Sự cố lệch dữ liệu của workspace (D8)

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`status`	string	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-incidents" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "anchored_hash": "…",
    "bundle_version": 1,
    "current_hash": "…",
    "detected_at": "2026-10-28T07:30:00Z",
    "diff_json": "…",
    "has_newer_version": true,
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "kind": "…",
    "parcel_code": "…",
    "product": "…",
    "resolution": "…",
    "resolution_note": "…",
    "resolved_at": "2026-10-28T07:30:00Z",
    "restore_requested_at": "2026-10-28T07:30:00Z",
    "restore_requested_by": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "status": "…",
    "trace_bundle_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "workspace_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
  }
]

GET/api/v1/harvest/trace-pdf/{code}

Tải hồ sơ truy xuất PDF theo mã QR (YÊU CẦU ĐĂNG NHẬP)

Trả PDF VietGAP của lô. Tệp có họ tên + số điện thoại nông hộ nên KHÔNG phát ra đường công khai. 404 khi: mã không tồn tại · mã hết hạn · lô chưa kết xuất PDF · tệp không còn trong kho.

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-pdf/<code>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

Tuyến này chưa khai schema phản hồi — gọi thử trong API Explorer để xem hình dạng.

GET/api/v1/harvest/trace-seal-document/{id}

Tải văn bản niêm phong (bản đầy đủ đã băm) — chỉ người của nhà

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-seal-document/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

Tuyến này chưa khai schema phản hồi — gọi thử trong API Explorer để xem hình dạng.

GET/api/v1/harvest/trace-settings

GET /api/v1/harvest/trace-settings

Scope: harvest.trace.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/harvest/trace-settings" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "scan_warn_threshold": 1
}

← IoT (chỉ đọc)Sổ nông trại & công việc →