Docs › API reference › Reports

Reports

Reports and labour cost by period.

6 operations · base /api/v1/reports

GET/api/v1/reports/catalog

Report catalog with the number of blocks the viewer can see

Scope: report.viewTry in API Explorer ▶

Parameter

No parameters.

Example

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

Sample response

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

Status of an export: pending · running · completed · failed

Scope: report.exportTry in API Explorer ▶

Parameter

ParameterTypeInRequiredDescription
idGUIDpathyes—

Example

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

Sample response

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

Download the exported file (404 after 24 hours)

Scope: report.exportTry in API Explorer ▶

Parameter

ParameterTypeInRequiredDescription
idGUIDpathyes—

Example

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

Sample response

This endpoint does not declare a response schema yet — call it in the API Explorer to see the shape.

GET/api/v1/reports/labor-cost

Labour cost by parcel / season

By WORK DATE within [from, to] (yyyy-MM-dd, up to 731 days). Each row = (parcel, season): time-based wages allocated by labour + finalised piece-rate pay. parcel_id null = not linked to a parcel; season_id null = outside any season. freshness = the last time data was received from each source (null = the source has NEVER sent data, not 0 VND).

Scope: report.viewTry in API Explorer ▶

Parameter

ParameterTypeInRequiredDescription
fromdatequeryno—
todatequeryno—
parcel_idGUIDqueryno—
season_idGUIDqueryno—

Example

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

Sample response

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

Run a report via GET; missing to = today (UTC+7), missing from = to - 29 days

Scope: report.viewTry in API Explorer ▶

Parameter

ParameterTypeInRequiredDescription
codestringqueryno—
fromdatequeryno—
todatequeryno—
grainstringqueryno—
comparestringqueryno—
includeSampleboolqueryno—

Example

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

Sample response

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

Multi-level traceability from a node (harvest record, piece-rate sheet, document, payslip, sales slip…)

kind: harvest_record · piecework_sheet · qr_code · trace_bundle · cash_document · payout_batch · produce_sale · payroll_line · payroll_period. id or key (document number). Negative level = upstream (origin), positive = downstream. A step without permission ⇒ restricted (no name/number), and the chain stops there.

Scope: report.viewTry in API Explorer ▶

Parameter

ParameterTypeInRequiredDescription
kindstringqueryno—
idstringqueryno—
keystringqueryno—
depthintqueryno—

Example

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

Sample response

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
}
← Farm books & tasksRate limit →