Tài liệu › Tham chiếu API › Báo cáo

Báo cáo

Báo cáo và chi phí công theo kỳ.

6 thao tác · gốc /api/v1/reports

GET/api/v1/reports/catalog

Danh mục báo cáo kèm số khối người xem được thấy

Scope: report.viewThử trong API Explorer ▶

Tham số

Không có tham số.

Ví dụ

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

Phản hồi mẫu

200 OK
[
  {
    "accessible": true,
    "blocks": 1,
    "chart": "…",
    "code": "…",
    "description": "…",
    "group": "…",
    "title": "…",
    "visibleBlocks": 1
  }
]
GET/api/v1/reports/exports/{id}

Trạng thái một lượt xuất: pending · running · completed · failed

Scope: report.exportThử trong API Explorer ▶

Tham số

Tham sốKiểuVị tríBắt buộcMô tả
idGUIDpathcó—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "code": "…",
  "completedAt": "2026-10-28T07:30:00Z",
  "createdAt": "2026-10-28T07:30:00Z",
  "downloadPath": "…",
  "error": "…",
  "expiresAt": "2026-10-28T07:30:00Z",
  "fileName": "…",
  "format": "…",
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
  "sizeBytes": 1,
  "status": "…",
  "title": "…"
}
GET/api/v1/reports/exports/{id}/file

Tải tệp đã xuất (404 khi quá 24 giờ)

Scope: report.exportThử trong API Explorer ▶

Tham số

Tham sốKiểuVị tríBắt buộcMô tả
idGUIDpathcó—

Ví dụ

curl -X GET "https://api-prod.nextfarm.vn/api/v1/reports/exports/<id>/file" \
  -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/reports/labor-cost

Chi phí nhân công theo thửa / mùa vụ

Theo NGÀY LÀM trong [from, to] (yyyy-MM-dd, tối đa 731 ngày). Mỗi dòng = (thửa, mùa vụ): lương theo thời gian đã chia theo công + khoán đã chốt. parcel_id null = không gắn thửa; season_id null = ngoài mùa vụ. freshness = lần cuối nhận dữ liệu từ từng nguồn (null = nguồn CHƯA từng gửi, không phải 0đ).

Scope: report.viewThử trong API Explorer ▶

Tham số

Tham sốKiểuVị tríBắt buộcMô tả
fromdatequerykhông—
todatequerykhông—
parcel_idGUIDquerykhông—
season_idGUIDquerykhông—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "freshness": {
    "lastPayrollFinalizedAt": "2026-10-28T07:30:00Z",
    "lastPieceworkReceivedAt": "2026-10-28T07:30:00Z",
    "lastSeasonSyncedAt": "2026-10-28T07:30:00Z"
  },
  "from": "2026-10-28",
  "rows": [
    {
      "costPerKg": 1,
      "cropName": "…",
      "parcelCode": "…",
      "parcelId": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "pieceworkCost": 1,
      "pieceworkQuantities": [
        {
          "quantity": 1.5,
          "unit": "…"
        }
      ],
      "seasonId": "0190a3c2-5b1e-7c3d-8e4f-000000000001",
      "seasonName": "…",
      "timeCost": 1,
      "totalCost": 1,
      "workUnits": 1.5,
      "workerCount": 1,
      "yieldKg": 1.5
    }
  ],
  "to": "2026-10-28",
  "totals": {
    "pieceworkCost": 1,
    "timeCost": 1,
    "totalCost": 1,
    "workUnits": 1.5,
    "workerCount": 1
  }
}
GET/api/v1/reports/query

Chạy báo cáo bằng GET; thiếu to = hôm nay UTC+7, thiếu from = to - 29 ngày

Scope: report.viewThử trong API Explorer ▶

Tham số

Tham sốKiểuVị tríBắt buộcMô tả
codestringquerykhông—
fromdatequerykhông—
todatequerykhông—
grainstringquerykhông—
comparestringquerykhông—
includeSampleboolquerykhông—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "asOf": "2026-10-28T07:30:00Z",
  "blocks": [
    {
      "chart": "…",
      "dataset": "…",
      "drill": "…",
      "groupBy": [
        "…"
      ],
      "hasSample": true,
      "hidden": true,
      "id": "…",
      "kpis": [
        {
          "compare": 1.5,
          "deltaPct": 1.5,
          "key": "…",
          "value": 1.5
        }
      ],
      "measures": [
        {
          "good": "…",
          "key": "…",
          "label": "…",
          "op": "…",
          "unit": "…"
        }
      ],
      "reasonCode": "…",
      "rows": [
        {
          "date": "2026-10-28",
          "dims": {
            "key": null
          },
          "id": "…",
          "values": {
            "key": null
          }
        }
      ],
      "source": "…",
      "span": 1,
      "status": "…",
      "title": "…",
      "totals": {
        "key": 1.5
      },
      "truncated": true,
      "type": "…",
      "updatedAt": "2026-10-28T07:30:00Z"
    }
  ],
  "code": "…",
  "description": "…",
  "group": "…",
  "hasSample": true,
  "hidden": [
    "…"
  ],
  "labels": {
    "key": {
      "key": "…"
    }
  },
  "period": {
    "compareFrom": "2026-10-28",
    "compareTo": "2026-10-28",
    "from": "2026-10-28",
    "grain": "…",
    "to": "2026-10-28"
  },
  "summaryFocus": [
    "…"
  ],
  "title": "…"
}
GET/api/v1/reports/trace

Truy xuất ngược nhiều tầng từ một nút (phiếu thu hoạch, phiếu khoán, chứng từ, phiếu lương, phiếu bán…)

kind: harvest_record · piecework_sheet · qr_code · trace_bundle · cash_document · payout_batch · produce_sale · payroll_line · payroll_period. id hoặc key (số phiếu). level âm = phía lên (gốc), dương = phía xuống. Bước thiếu quyền ⇒ restricted (không tên/số), chuỗi dừng ở đó.

Scope: report.viewThử trong API Explorer ▶

Tham số

Tham sốKiểuVị tríBắt buộcMô tả
kindstringquerykhông—
idstringquerykhông—
keystringquerykhông—
depthintquerykhông—

Ví dụ

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

Phản hồi mẫu

200 OK
{
  "edges": [
    {
      "from": "…",
      "to": "…"
    }
  ],
  "nodes": [
    {
      "id": "…",
      "kind": "…",
      "level": 1,
      "node": {
        "amount": 1.5,
        "date": "2026-10-28",
        "facts": [
          {
            "label": null,
            "value": null
          }
        ],
        "flag": "…",
        "flagOf": {
          "id": "…",
          "key": "…",
          "kind": "…"
        },
        "href": "…",
        "id": "…",
        "key": "…",
        "kind": "…",
        "service": "…",
        "status": "…",
        "subtitle": "…",
        "title": "…",
        "unit": "…"
      },
      "ref": "…",
      "restricted": true,
      "service": "…",
      "sourceError": true
    }
  ],
  "root": "…",
  "truncated": true
}
← Sổ nông trại & công việcRate limit →