Tài liệu › Tham chiếu API › Bản đồ & mùa vụ

Bản đồ & mùa vụ

Thửa đất, vùng, nông dân, mùa vụ, lớp bản đồ — nền dữ liệu không gian của trang trại.

34 thao tác · gốc /api/v1/gis

GET/api/v1/gis/care-schedules

Các kích hoạt lịch chăm sóc (lọc theo thửa)

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "assignee_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "created_at": "2026-10-28T07:30:00Z",
    "delivery": "…",
    "enabled": true,
    "enabled_at": "2026-10-28T07:30:00Z",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "notify_user_ids": [
      "0190a3c2-5b1e-7c3d-8e4f-000000000001"
    ],
    "parcel_code": "…",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "plot_name": "…",
    "season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "template_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "template_name": "…"
  }
]

GET/api/v1/gis/care-schedules/preview

Xem trước lịch (không ghi gì)

`from` yyyy-MM-dd (mặc định hôm nay giờ VN), `days` 1–400 (mặc định 30).

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/care-schedules/preview" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "from": "…",
  "items": [
    {
      "anchor": "…",
      "due_on": "…",
      "material": "…",
      "quantity": 1.5,
      "rule_key": "…",
      "task_type": "…",
      "title": "…",
      "trees": 1,
      "unit": "…",
      "unknown_age_trees": 1
    }
  ],
  "to": "…",
  "warnings": [
    "…"
  ],
  "weeks": [
    {
      "items": [
        {
          "anchor": "…",
          "due_on": "…",
          "material": "…",
          "quantity": 1.5,
          "rule_key": "…",
          "task_type": "…",
          "title": "…",
          "trees": 1,
          "unit": "…",
          "unknown_age_trees": 1
        }
      ],
      "week_end": "…",
      "week_start": "…"
    }
  ]
}

GET/api/v1/gis/care-schedules/this-week

Việc chăm sóc tuần này (chỉ kích hoạt đang BẬT)

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/care-schedules/this-week" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "plots": [
    {
      "activation_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "delivery": "…",
      "items": [
        {
          "anchor": "…",
          "due_on": "…",
          "material": "…",
          "quantity": 1.5,
          "rule_key": "…",
          "task_type": "…",
          "title": "…",
          "trees": 1,
          "unit": "…",
          "unknown_age_trees": 1
        }
      ],
      "parcel_code": "…",
      "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "plot_name": "…",
      "template_name": "…"
    }
  ],
  "week_end": "…",
  "week_start": "…"
}

GET/api/v1/gis/care-schedules/{id}/calendar

Lịch cả năm của một kích hoạt

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/care-schedules/<id>/calendar" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "from": "…",
  "items": [
    {
      "anchor": "…",
      "due_on": "…",
      "material": "…",
      "quantity": 1.5,
      "rule_key": "…",
      "task_type": "…",
      "title": "…",
      "trees": 1,
      "unit": "…",
      "unknown_age_trees": 1
    }
  ],
  "to": "…",
  "warnings": [
    "…"
  ],
  "weeks": [
    {
      "items": [
        {
          "anchor": "…",
          "due_on": "…",
          "material": "…",
          "quantity": 1.5,
          "rule_key": "…",
          "task_type": "…",
          "title": "…",
          "trees": 1,
          "unit": "…",
          "unknown_age_trees": 1
        }
      ],
      "week_end": "…",
      "week_start": "…"
    }
  ]
}

GET/api/v1/gis/care-schedules/{id}/generations

Lịch sử đã sinh của một kích hoạt

Scope: gis.parcels.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/gis/care-schedules/<id>/generations" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "activation_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "created_at": "2026-10-28T07:30:00Z",
    "delivery": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "item_count": 1,
    "week_end": "…",
    "week_start": "…"
  }
]

GET/api/v1/gis/crop-types

Danh sách loại cây trồng

Lọc theo category (fruit_tree/cereal/vegetable/industrial/other), isActive. Phân trang.

Scope: gis.crop-types.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "bearing_age_years": 1,
      "category": "…",
      "code": "…",
      "effective_lifecycle": "…",
      "grow_days": 1,
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "is_active": true,
      "lifecycle": "…",
      "lifecycle_guessed": true,
      "name": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/crop-types/{id}

Một loại cây trồng theo mã

Dùng bởi nextfarm-harvest để lấy tên loại cây khi dựng phiếu thu hoạch.

Scope: gis.crop-types.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/gis/crop-types/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "category": "…",
  "code": "…",
  "created_at": "2026-10-28T07:30:00Z",
  "grow_days": 1,
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "is_active": true,
  "name": "…",
  "updated_at": "2026-10-28T07:30:00Z"
}

GET/api/v1/gis/crop-types/{id}/perennial-profile

Hồ sơ cây lâu năm của loài

Vòng đời, tuổi cho trái, khoảng cách trồng mặc định, giai đoạn đời cây mẫu.

Scope: gis.crop-types.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/gis/crop-types/<id>/perennial-profile" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "bearing_age_years": 1,
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "default_row_spacing_m": 1.5,
  "default_tree_spacing_m": 1.5,
  "effective_lifecycle": "…",
  "life_stages": [
    {
      "code": "…",
      "from_year": 1,
      "name": "…",
      "to_year": 1
    }
  ],
  "lifecycle": "…",
  "lifecycle_guessed": true
}

GET/api/v1/gis/crop-types/{id}/varieties

Giống và gốc ghép của loài

kind = variety (giống) | rootstock (gốc ghép); bỏ trống = cả hai.

Scope: gis.crop-types.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/crop-types/<id>/varieties" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "code": "…",
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "kind": "…",
    "name": "…",
    "note": "…"
  }
]

GET/api/v1/gis/facilities

Danh sách chuồng trại

Lọc theo facilityType (barn, pasture, feedlot, dairy, poultry_house, piggery, processing_plant, other), status (active, inactive, maintenance) và branchId. Phân trang.

Scope: gis.facilities.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`facilityType`	string	query	không	—
`status`	string	query	không	—
`sourceParcelId`	GUID	query	không	—
`branchId`	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/gis/facilities" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "area_ha": 1.5,
      "boundary_geo_json": "…",
      "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "capacity": 1,
      "created_at": "2026-10-28T07:30:00Z",
      "current_stock": 1,
      "facility_code": "…",
      "facility_type": "…",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "name": "…",
      "source_parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "status": "…",
      "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "zone_name": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/facilities/{id}

Chi tiết chuồng trại

Trả về thông tin đầy đủ gồm GeoJSON boundary, metadata, capacity, current_stock.

Scope: gis.facilities.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/gis/facilities/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "area_ha": 1.5,
  "boundary_geo_json": "…",
  "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "capacity": 1,
  "created_at": "2026-10-28T07:30:00Z",
  "current_stock": 1,
  "facility_code": "…",
  "facility_type": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "metadata": "…",
  "name": "…",
  "source_parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "status": "…",
  "updated_at": "2026-10-28T07:30:00Z",
  "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "zone_name": "…"
}

GET/api/v1/gis/farmer-groups

GET /api/v1/gis/farmer-groups

Scope: gis.farmers.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "code": "…",
    "farmer_count": 1,
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "is_active": true,
    "leader_farmer_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "name": "…",
    "note": "…",
    "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
  }
]

GET/api/v1/gis/farmers

Danh sách nông dân

Lọc theo zone_id. Phân trang.

Scope: gis.farmers.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`zoneId`	GUID	query	không	—
`page`	int	query	không	—
`pageSize`	int	query	không	—
`deleted`	bool	query	không	—
`groupId`	GUID	query	không	—
`memberType`	string	query	không	—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "address": "…",
      "cooperative_name": "…",
      "full_name": "…",
      "group_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "group_name": "…",
      "home_location_geo_json": "…",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "identity_number": "…",
      "member_type": "…",
      "phone": "…",
      "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "zone_name": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/farmers/{id}

Chi tiết nông dân

Trả thông tin đầy đủ + zone name + home location (GeoJSON Point).

Scope: gis.farmers.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/gis/farmers/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "address": "…",
  "cooperative_name": "…",
  "created_at": "2026-10-28T07:30:00Z",
  "full_name": "…",
  "group_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "group_name": "…",
  "home_location_geo_json": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "identity_number": "…",
  "member_type": "…",
  "phone": "…",
  "public_consent_at": "2026-10-28T07:30:00Z",
  "public_consent_by": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "public_name_consent": true,
  "public_phone_consent": true,
  "updated_at": "2026-10-28T07:30:00Z",
  "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "zone_name": "…"
}

GET/api/v1/gis/layers

Danh sách map layers

Lọc theo layer_type (ndvi/satellite/custom/soil/weather), zone_id, status (processing/ready/failed/archived). Phân trang.

Scope: gis.layers.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`layerType`	string	query	không	—
`zoneId`	GUID	query	không	—
`status`	string	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/gis/layers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "captured_at": "2026-10-28",
      "created_at": "2026-10-28T07:30:00Z",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "layer_type": "…",
      "name": "…",
      "source_url": "…",
      "status": "…",
      "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "zone_name": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/layers/{id}

Chi tiết map layer

Trả thông tin đầy đủ + tên zone + ndvi stats + style_config jsonb.

Scope: gis.layers.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/gis/layers/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "captured_at": "2026-10-28",
  "created_at": "2026-10-28T07:30:00Z",
  "file_path": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "layer_type": "…",
  "name": "…",
  "ndvi_avg": 1.5,
  "ndvi_max": 1.5,
  "ndvi_min": 1.5,
  "source_url": "…",
  "status": "…",
  "style_config": "…",
  "updated_at": "2026-10-28T07:30:00Z",
  "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "zone_name": "…"
}

GET/api/v1/gis/map/points

Điểm nhẹ theo bbox: nhà hộ dân + tâm thửa

bbox=minLon,minLat,maxLon,maxLat (bắt buộc, tối đa 10°×10°). zoom 0..22 (tuỳ chọn): dưới 13 mà nhiều hơn limit thì trả mode=clusters (ô gom). limit mặc định 2000, trần 5000; vượt thì cắt và truncated=true (KHÔNG báo lỗi). kind=all|farmer|parcel. Điểm hộ dân chỉ có khi người gọi có thêm gis.farmers.view và không bị giới hạn theo thửa sở hữu.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "clusters": [
    {
      "count": 1,
      "latitude": 1.5,
      "longitude": 1.5
    }
  ],
  "limit": 1,
  "mode": "…",
  "points": [
    {
      "area_ha": 1.5,
      "farmer_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "kind": "…",
      "latitude": 1.5,
      "longitude": 1.5,
      "name": "…",
      "parcel_code": "…",
      "parcel_count": 1,
      "status": "…"
    }
  ],
  "total": 1,
  "truncated": true,
  "zoom": 1
}

GET/api/v1/gis/parcels

Danh sách lô thửa

Lọc theo bbox (minLon,minLat,maxLon,maxLat), zoneId, ownerId, cropTypeId, status, branchId. Phân trang. Bbox max 2°×2°, tối đa 1000 results.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`bbox`	string	query	không	—
`zoneId`	GUID	query	không	—
`ownerId`	GUID	query	không	—
`cropTypeId`	GUID	query	không	—
`status`	string	query	không	—
`branchId`	GUID	query	không	—
`page`	int	query	không	—
`pageSize`	int	query	không	—
`deleted`	bool	query	không	—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "active_season_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "active_season_name": "…",
      "active_seasons": [
        {
          "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
          "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
          "kind": "…",
          "name": "…",
          "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
        }
      ],
      "area_ha": 1.5,
      "boundary_geo_json": "…",
      "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "created_at": "2026-10-28T07:30:00Z",
      "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "crop_type_name": "…",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "latitude": 1.5,
      "longitude": 1.5,
      "owner_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "owner_name": "…",
      "parcel_code": "…",
      "status": "…",
      "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "zone_name": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/parcels/summary

Tổng hợp diện tích thửa theo hộ / vùng / cây

group_by = owner (theo hộ) | zone (theo vùng) | crop (theo cây trồng). Mỗi dòng: số hộ, số thửa, tổng diện tích (đã loại thửa ranh giới vô lý), số thửa CHƯA có ranh giới. Lọc thêm theo zoneId, cropTypeId, status. Phân trang (tối đa 200 dòng/trang), xếp theo tổng diện tích giảm dần. Cùng phạm vi nhìn thấy với danh sách thửa.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`group_by`	string	query	không	—
`zoneId`	GUID	query	không	—
`cropTypeId`	GUID	query	không	—
`status`	string	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/gis/parcels/summary" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "estimated_area_ha": 1.5,
      "excluded_area_ha": 1.5,
      "farmer_count": 1,
      "implausible_count": 1,
      "key": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "name": "…",
      "parcel_count": 1,
      "parcels_without_boundary_count": 1,
      "total_area_ha": 1.5
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/parcels/{id}

Chi tiết lô thửa

Trả về thông tin đầy đủ gồm GeoJSON boundary + nested zone/owner/crop_type + ndvi_history.

Scope: gis.parcels.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/gis/parcels/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "area_ha": 1.5,
  "boundary_geo_json": "…",
  "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "created_at": "2026-10-28T07:30:00Z",
  "crop_type": {
    "category": "…",
    "code": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "name": "…"
  },
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "latitude": 1.5,
  "longitude": 1.5,
  "ndvi_history": [
    {
      "ndvi_value": 1.5,
      "recorded_at": "2026-10-28"
    }
  ],
  "owner": {
    "full_name": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "phone": "…",
    "public_name_consent": true,
    "public_phone_consent": true
  },
  "parcel_code": "…",
  "status": "…",
  "updated_at": "2026-10-28T07:30:00Z",
  "zone": {
    "code": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "name": "…",
    "zone_type": "…"
  }
}

GET/api/v1/gis/parcels/{id}/contains-point

Điểm GPS có nằm trong ranh thửa không

Trả 200 kèm `{ parcel_id, inside }`. NGOÀI RANH LÀ MỘT CÂU TRẢ LỜI HỢP LỆ (`inside=false`), KHÔNG phải lỗi — endpoint này nói sự thật hình học, còn cảnh báo hay chặn là việc của NGƯỜI GỌI. Điểm nằm ĐÚNG TRÊN CẠNH tính là TRONG (Covers, không phải Contains): nông dân đứng ở bờ ruộng không được báo sai. 422 chỉ khi toạ độ ngoài miền hợp lệ. Không có GPS thì đừng gọi. Đây là CHẶNG TRƯỚC MẮT — đích đến là kiểm CỤC BỘ trên máy qua gói offline `GET /gis/sync/parcels` (đã có sẵn), vì chính lúc mất sóng mới là lúc người ta ở giữa ruộng.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/parcels/<id>/contains-point" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "inside": true,
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
}

GET/api/v1/gis/parcels/{id}/history

Lịch sử thay đổi parcel

Audit trail mọi thay đổi (created/boundary-updated/owner-changed/crop-type-changed/status-changed/deleted). Sắp xếp mới nhất trước.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "change_type": "…",
      "changed_at": "2026-10-28T07:30:00Z",
      "changed_by": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "new_boundary_geo_json": "…",
      "notes": "…",
      "old_boundary_geo_json": "…",
      "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/parcels/{parcelId}/photos

Danh sách ảnh của lô thửa

Trả về danh sách ảnh kèm presigned GET URL (TTL 1 giờ).

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "content_type": "…",
    "created_at": "2026-10-28T07:30:00Z",
    "file_name": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "size_bytes": 1,
    "url": "…"
  }
]

GET/api/v1/gis/plots

Danh sách khu của một thửa

Trả về các khu (Plot) thuộc parcel_id, kèm tên cây trồng, nhóm cây (để FE quyết định rải chấm), số cây + mật độ ước tính, và GeoJSON ranh giới.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "area_m2": 1.5,
    "boundary_geo_json": "…",
    "created_at": "2026-10-28T07:30:00Z",
    "crop_category": "…",
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "crop_type_name": "…",
    "crops": [
      {
        "crop_category": "…",
        "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
        "crop_type_name": "…",
        "estimated_tree_count": 1,
        "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
        "note": "…",
        "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
        "role": "…",
        "row_spacing_m": 1.5,
        "tree_spacing_m": 1.5
      }
    ],
    "custom_trees_geo_json": "…",
    "density_per1000_m2": 1.5,
    "estimated_tree_count": 1,
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "name": "…",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "row_spacing_m": 1.5,
    "tree_spacing_m": 1.5
  }
]

GET/api/v1/gis/plots/{id}/crops

Các loài trồng trong khu (trồng xen)

Loài chính đứng đầu (role = main, trùng crop_type_id của khu). Vai trò: main · intercrop (xen) · shade (che bóng) · border (ranh) · temporary (tạm).

Scope: gis.parcels.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/gis/plots/<id>/crops" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
[
  {
    "crop_category": "…",
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "crop_type_name": "…",
    "estimated_tree_count": 1,
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "note": "…",
    "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "role": "…",
    "row_spacing_m": 1.5,
    "tree_spacing_m": 1.5
  }
]

GET/api/v1/gis/search

Tìm thửa, mùa vụ, nông dân, vùng

Không phân biệt dấu ("ca phe" khớp "Cà phê"). Dưới 2 ký tự trả rỗng. Mỗi nhóm tối đa `limit` (1–20, mặc định 8), đã lọc theo quyền + vùng được phép.

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/gis/search" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "farmers": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ],
  "parcels": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ],
  "seasons": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ],
  "zones": [
    {
      "code": "…",
      "edit_path": "…",
      "email": "…",
      "id": "…",
      "path": "…",
      "phone": "…",
      "subtitle": "…",
      "title": "…",
      "type": "…"
    }
  ]
}

GET/api/v1/gis/season-templates

Danh sách quy trình mẫu

`cropTypeId` có ⇒ mẫu của cây đó + mẫu dùng chung (không gắn cây).

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "description": "…",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "name": "…",
    "rules": [
      {
        "age_from": 1,
        "age_to": 1,
        "anchor": "…",
        "day": 1,
        "day_offset": 1,
        "doses": [
          {
            "age_from": null,
            "age_to": null,
            "quantity_per_tree": null
          }
        ],
        "event": "…",
        "every_days": 1,
        "from_day": 1,
        "from_month": 1,
        "key": "…",
        "material": "…",
        "month": 1,
        "note": "…",
        "offset_days": 1,
        "task_type": "…",
        "title": "…",
        "to_day": 1,
        "to_month": 1,
        "unit": "…"
      }
    ],
    "stages": [
      {
        "day_offset": 1,
        "name": "…"
      }
    ],
    "updated_at": "2026-10-28T07:30:00Z"
  }
]

GET/api/v1/gis/season-templates/{id}

Một quy trình mẫu

Scope: gis.parcels.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/gis/season-templates/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "description": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "name": "…",
  "rules": [
    {
      "age_from": 1,
      "age_to": 1,
      "anchor": "…",
      "day": 1,
      "day_offset": 1,
      "doses": [
        {
          "age_from": 1,
          "age_to": 1,
          "quantity_per_tree": 1.5
        }
      ],
      "event": "…",
      "every_days": 1,
      "from_day": 1,
      "from_month": 1,
      "key": "…",
      "material": "…",
      "month": 1,
      "note": "…",
      "offset_days": 1,
      "task_type": "…",
      "title": "…",
      "to_day": 1,
      "to_month": 1,
      "unit": "…"
    }
  ],
  "stages": [
    {
      "day_offset": 1,
      "name": "…"
    }
  ],
  "updated_at": "2026-10-28T07:30:00Z"
}

GET/api/v1/gis/seasons

Danh sách mùa vụ

Cần ít nhất một trong hai: `parcelId` (lịch sử canh tác của một thửa) hoặc `year` (thanh 12 tháng). Với `year`, vụ được lấy khi nó **CHẠM** vào năm đó — vụ trồng 12/2025 thu 03/2026 hiện ở cả hai năm, nếu không thì tháng 1–2 của 2026 trông như không có vụ nào trong khi ngoài ruộng đang có cây.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "closed_on": "2026-10-28",
    "crop_name": "…",
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "expected_harvest_on": "2026-10-28",
    "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "kind": "…",
    "name": "…",
    "notes": "…",
    "parcel_code": "…",
    "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "planted_on": "2026-10-28",
    "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "stages": [
      {
        "day_offset": 1,
        "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
        "name": "…",
        "sort_order": 1
      }
    ],
    "status": "…",
    "year": 1,
    "yield_kg": 1.5
  }
]

GET/api/v1/gis/seasons/groups

Nhóm vụ của một năm (cùng cây, cùng tên vụ)

Dùng cho màn đặt mục tiêu theo vụ: "Lúa · Đông Xuân 2026–27" trên nhiều thửa là MỘT nhóm. Khoá nhóm = <crop_type_id>|<tên vụ>|<năm>. `branchId` lọc vụ trên thửa của một trang trại.

Scope: gis.parcels.viewThử trong API Explorer ▶

Tham số

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

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "branch_ids": [
      "0190a3c2-5b1e-7c3d-8e4f-000000000001"
    ],
    "crop_name": "…",
    "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
    "end_date": "2026-10-28",
    "key": "…",
    "missing_end_count": 1,
    "name": "…",
    "parcel_count": 1,
    "season_count": 1,
    "start_date": "2026-10-28",
    "year": 1
  }
]

GET/api/v1/gis/seasons/{id}

Một mùa vụ theo mã

Dùng bởi `nextfarm-harvest`: lúc khai thu hoạch nó cần biết vụ trồng CÂY GÌ và ĐÃ ĐÓNG CHƯA; lúc dựng trang truy xuất nó cần tên vụ + ngày trồng + ngày dự kiến thu để in lên tem.

Scope: gis.parcels.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/gis/seasons/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "closed_on": "2026-10-28",
  "crop_name": "…",
  "crop_type_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "expected_harvest_on": "2026-10-28",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "kind": "…",
  "name": "…",
  "notes": "…",
  "parcel_code": "…",
  "parcel_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "planted_on": "2026-10-28",
  "plot_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "stages": [
    {
      "day_offset": 1,
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "name": "…",
      "sort_order": 1
    }
  ],
  "status": "…",
  "year": 1,
  "yield_kg": 1.5
}

GET/api/v1/gis/zones

Danh sách zones

Lọc theo zone_type (province/district/commune/material_zone). Phân trang.

Scope: gis.zones.viewThử trong API Explorer ▶

Tham số

Tham số	Kiểu	Vị trí	Bắt buộc	Mô tả
`zone_type`	string	query	không	—
`page`	int	query	không	—
`page_size`	int	query	không	—
`deleted`	bool	query	không	—
`include_stats`	bool	query	không	—
`branch_id`	GUID	query	không	—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/gis/zones?page_size=20" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "items": [
    {
      "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "code": "…",
      "contact_person": "…",
      "contact_phone": "…",
      "description": "…",
      "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "implausible_parcel_count": 1,
      "main_crop": "…",
      "name": "…",
      "parcel_area_ha": 1.5,
      "parcel_count": 1,
      "parent_zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "total_area_ha": 1.5,
      "zone_type": "…"
    }
  ],
  "page": 1,
  "page_size": 1,
  "page_size_capped": true,
  "total": 1
}

GET/api/v1/gis/zones/{id}

Chi tiết zone

Trả thông tin đầy đủ + tên parent zone + boundary GeoJSON.

Scope: gis.zones.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/gis/zones/<id>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "boundary_geo_json": "…",
  "branch_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "code": "…",
  "contact_person": "…",
  "contact_phone": "…",
  "created_at": "2026-10-28T07:30:00Z",
  "description": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "main_crop": "…",
  "name": "…",
  "parent_zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "parent_zone_name": "…",
  "total_area_ha": 1.5,
  "updated_at": "2026-10-28T07:30:00Z",
  "zone_type": "…"
}

GET/api/v1/gis/zones/{id}/stats

Thống kê zone

Số lượng parcel + tổng diện tích thuộc workspace hiện tại trong zone này.

Scope: gis.zones.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/gis/zones/<id>/stats" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Phản hồi mẫu

200 OK
{
  "active_parcel_count": 1,
  "disputed_parcel_count": 1,
  "excluded_area_ha": 1.5,
  "implausible_parcel_count": 1,
  "inactive_parcel_count": 1,
  "parcel_count": 1,
  "total_area_ha": 1.5,
  "zone_id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "zone_name": "…"
}

← Error code IoT (chỉ đọc) →