Bỏ qua, tới nội dung chính
Fleetwork
Fleetwork
Liên hệ

Liên hệ

Chúng tôi rất mong nhận được liên hệ từ bạn. Vui lòng điền vào biểu mẫu bên dưới.

SDK

API Reference

Tham chiếu đầy đủ tất cả endpoints của hệ thống GPS Tracking dành cho đối tác tích hợp.

Base URLs

GroupBase URL
GPS Trackinghttps://live.fleetwork.vn/api/v1/gps-tracking
Dashboardhttps://live.fleetwork.vn/api/v1/dashboard/gps-manager
Báo cáohttps://live.fleetwork.vn/api/v1/reports

Authentication

Tất cả endpoints xác thực qua request header:

HTTP
X-API-Key: <your_api_key>

Sai hoặc thiếu key → 401 Unauthorized:

JSON
{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid X-API-Key",
  "code": 401
}

Luồng xác thực Dashboard API

Các endpoint thuộc nhóm Dashboard đi qua Fleetwork.Web gateway:

Text
Client
  → X-API-Key → Fleetwork.Web (live.fleetwork.vn)
      → tự inject X-Account-Id + X-Internal-Token
      → YARP proxy → AnalyticsApi (internal)

Client chỉ cần gửi X-API-Key. Không cần và không nên gửi X-Account-Id hay X-Internal-Token từ phía client.

Quy ước thời gian

Tất cả query params và field liên quan thời gian trong tài liệu này dùng Unix timestamp (milliseconds), bao gồm:

  • timestamp
  • date
  • from
  • to
  • startTime
  • endTime
  • generatedAt
  • lastSeenAt

Quy ước áp dụng:

  • với dữ liệu theo ngày, date là timestamp mốc đầu ngày theo timezone hệ thống
  • với khoảng thời gian lọc, from và to là timestamp Unix ms
  • các field hiển thị như formatted vẫn là chuỗi để phục vụ UI

Mục lục

PHẦN 1 — GPS TRACKING

PHẦN 2 — DASHBOARD

PHẦN 3 — BÁO CÁO

PHẦN 1 — GPS TRACKING

1.1 POST /gps-tracking

Ghi tọa độ GPS. Body luôn là một mảng điểm GPS — gửi 1 điểm thì mảng có 1 phần tử.

HTTP
POST https://live.fleetwork.vn/api/v1/gps-tracking
Content-Type: application/json
X-API-Key: <key>

Alias — 3 đường dẫn, cùng một hành vi

Đường dẫnGhi chú
POST /api/v1/gps-trackingĐường dẫn khuyến nghị.
POST /api/v1/gps-tracking/bulkAlias, xem 1.2.
POST /api/v1/accounts/{accountId}/waypointsAlias cũ, giữ cho client đã tích hợp.

Ba route trỏ về cùng một handler: cùng payload, cùng validation, cùng response. Chọn route nào cũng được; account vẫn suy ra từ X-API-Key chứ không lấy từ {accountId} trên URL.

Request Body

  • latDoubleYes
    Vĩ độ (-90 đến 90).
  • lngDoubleYes
    Kinh độ (-180 đến 180).
  • timeLongNo
    Unix timestamp (ms) lúc ghi nhận vị trí.
  • speedFloatNo
    Vận tốc (km/h).
  • headingIntegerNo
    Hướng di chuyển (0–360°).
  • metaDataObjectNo
    Thông tin bổ sung của thiết bị/app.
  • packagesString[]No
    Danh sách mã kiện hàng mà điểm GPS này đang chở. Xem bên dưới.
  • dataStringNo
    Base64. Đặt null cho tracking thông thường.
  • vehicleIdStringNo*
    ID xe.
  • userIdStringNo*
    ID nhân viên.
  • deviceIdStringNo*
    ID thiết bị.

Bắt buộc: phải có ít nhất 1 trong 3: vehicleId, userId, deviceId.

packages — gắn mã kiện hàng vào điểm GPS

Field tuỳ chọn duy nhất được thêm cho luồng giao hàng. Không gửi thì endpoint chạy y hệt như trước, không phát sinh gì thêm.

  • Là mảng vì một toạ độ có thể thuộc nhiều đơn cùng lúc (xe chở nhiều đơn trên một chuyến).
  • Mỗi cặp (điểm × mã) thành một bản ghi lộ trình — đây là dữ liệu mà 1.8 đọc ra.
  • Mã được trim khoảng trắng, bỏ chuỗi rỗng, và khử trùng trong cùng một điểm trước khi lưu.
  • Mã do phía client tự khai (ví dụ "#231"), hệ thống không đối chiếu với danh mục đơn hàng nào.

Ví dụ ngay dưới đây tạo ra 3 bản ghi: #231 có 2 điểm, #3333 có 1 điểm.

Quy tắc tính statusCode tự động:

Text
speed > 0               → statusCode = 1  (Moving)
speed = 0               → statusCode = 2  (Stopping)
không có GPS > 15 phút  → statusCode = 0  (LostGps)

Ví dụ Request

JSON
[
  {
    "lat": 21.0285,
    "lng": 105.8542,
    "time": 1713235100000,
    "speed": 45.2,
    "heading": 90,
    "metaData": { "appVersion": "1.2.0", "battery": 82, "speedSource": "gps" },
    "packages": ["#231", "#3333"],
    "data": null,
    "userId": "user-001",
    "vehicleId": "vehicle-abc"
  },
  {
    "lat": 21.029,
    "lng": 105.855,
    "time": 1713235160000,
    "speed": 38.0,
    "heading": 92,
    "packages": ["#231"],
    "userId": "user-001",
    "vehicleId": "vehicle-abc"
  }
]

Điểm 1 chở 2 đơn, điểm 2 chỉ còn #231 (đơn #3333 đã giao) ⇒ #231 có 2 điểm lộ trình, #3333 có 1.

Response 200 OK

JSON
{}

Response body trả về rỗng. Không có id, address, createdAt trong response push GPS.

1.2 POST /gps-tracking/bulk

Gửi nhiều tọa độ cùng lúc — dùng khi thiết bị vừa mất mạng và cần đẩy lại dữ liệu.

HTTP
POST https://live.fleetwork.vn/api/v1/gps-tracking/bulk
Content-Type: application/json
X-API-Key: <key>

Request Body: Array các object, mỗi object cùng cấu trúc WaypointMSG với 1.1 — bao gồm cả field packages.

JSON
[
  {
    "lat": 21.0285,
    "lng": 105.8542,
    "time": 1713235000000,
    "speed": 40.0,
    "userId": "user-001"
  },
  {
    "lat": 21.029,
    "lng": 105.855,
    "time": 1713235060000,
    "speed": 45.2,
    "userId": "user-001"
  },
  {
    "lat": 21.0295,
    "lng": 105.856,
    "time": 1713235120000,
    "speed": 50.0,
    "userId": "user-001"
  }
]

1.3 GET /gps-tracking/users

Lấy danh sách tất cả user có GPS kèm lastLocation của từng user.

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/users
    ?PageNumber=1&PageSize=20
X-API-Key: <key>

Query Parameters

  • userIdsString[]No
    Lọc theo danh sách user id. Chỉ trả về các user trong danh sách. Bỏ trống = tất cả.
  • StatusIntNo
    1 (moving) / 2 (stopping) / 0 (signal_lost).
  • UpdatedFromInt64No
    Lọc user cập nhật từ mốc này (Unix ms).
  • UpdatedToInt64No
    Lọc user cập nhật đến mốc này (Unix ms).
  • PageNumberInt32No
    Trang hiện tại.
  • PageSizeInt32No
    Số bản ghi / trang.
  • SortDescendingBooleanNo
    true = mới nhất lên đầu.

userIds — định dạng nhiều giá trị: lặp lại key cho mỗi id, không dùng dấu ngoặc [] và không ghép bằng dấu phẩy:

HTTP
GET /gps-tracking/users?userIds=user-001&userIds=user-002

Các dạng userIds[]=a&userIds[]=b hoặc userIds=a,b sẽ bị bỏ qua (API trả về toàn bộ user).

Response 200 OK

JSON
{
  "users": [
    {
      "userId": "user-001",
      "deviceId": "device-xyz",
      "vehicleId": "vehicle-abc",
      "statusCode": 1,
      "status": "moving",
      "lastLocation": {
        "lat": 21.0285,
        "lng": 105.8542,
        "time": 1713235100000,
        "speed": 45.2,
        "heading": 90,
        "userId": "user-001",
        "vehicleId": "vehicle-abc",
        "deviceId": "device-xyz",
        "data": null,
        "metadata": {}
      }
    }
  ],
  "totalCount": 10,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}
  • statusCodeInteger
    0 = LostGps, 1 = Moving, 2 = Stopping.
  • statusString
    Nhãn trạng thái (moving, stopping, signal_lost).
  • lastLocation.timeLong
    Unix ms lúc ghi nhận vị trí cuối.
  • lastLocation.metadataObject
    Thông tin bổ sung từ thiết bị/app.

1.4 GET /latest/users/{userId}

Lấy vị trí mới nhất của một nhân viên theo ID.

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/latest/users/{userId}
X-API-Key: <key>

Response: 200 OK — WaypointMSG của user (xem bảng field bên dưới).

1.5 GET /latest/vehicles/{vehicleId}

Lấy vị trí mới nhất của một xe theo ID.

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/latest/vehicles/{vehicleId}
X-API-Key: <key>

Response: 200 OK hoặc 404 Not Found tuỳ dữ liệu.

1.6 GET /latest/devices/{deviceId}

Lấy vị trí mới nhất của một thiết bị theo ID.

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/latest/devices/{deviceId}
X-API-Key: <key>

Response: Luôn 200 OK kể cả device không tồn tại (DeterministicGuid cache key).

Response WaypointMSG (1.4 / 1.5 / 1.6)

  • latDouble
    Vĩ độ.
  • lngDouble
    Kinh độ.
  • timeLong
    Thời điểm ghi nhận (Unix ms).
  • speedFloat
    Vận tốc (km/h).
  • headingInteger
    Hướng di chuyển (0–360).
  • userIdString
    ID nhân viên (nếu có).
  • vehicleIdString
    ID xe (nếu có).
  • deviceIdString
    ID thiết bị (nếu có).
  • dataString
    Base64 dữ liệu thêm (hoặc null).
  • metadataObject
    Thông tin bổ sung từ thiết bị.

Các field id, address, altitude, accuracy, createdAt không còn trong response.

1.7 GET /gps-tracking/history

Truy vấn lịch sử tọa độ GPS trong một khoảng thời gian. Kết quả phân trang.

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/history
    ?UserId=user-001
    &FromTime=1713225600000
    &ToTime=1713311999000
    &PageNumber=1
    &PageSize=100
    &SortDescending=false
X-API-Key: <key>

Query Parameters

  • DeviceIdStringNo
    Lọc theo ID thiết bị.
  • VehicleIdStringNo
    Lọc theo ID xe.
  • UserIdStringNo
    Lọc theo ID nhân viên.
  • FromTimeInt64No
    Thời gian bắt đầu (Unix ms).
  • ToTimeInt64No
    Thời gian kết thúc (Unix ms).
  • StatusIntNo
    1 (moving) / 2 (stopping).
  • PageNumberInt32No
    Trang hiện tại.
  • PageSizeInt32No
    Số bản ghi / trang.
  • SortDescendingBooleanNo
    true = mới nhất lên đầu.

Response 200 OK

JSON
{
  "trackingData": [
    {
      "lat": 21.0285,
      "lng": 105.8542,
      "time": 1713225600000,
      "speed": 40.0,
      "heading": 90,
      "userId": "user-001",
      "vehicleId": "vehicle-abc",
      "deviceId": "device-xyz",
      "statusCode": 1,
      "data": null,
      "metadata": {}
    }
  ],
  "totalCount": 240,
  "page": 1,
  "pageSize": 100,
  "totalPages": 3,
  "hasNextPage": true,
  "hasPreviousPage": false
}
  • trackingData[].timeLong
    Unix ms lúc ghi nhận vị trí (thay timestamp).
  • trackingData[].statusCodeInteger
    0 = LostGps, 1 = Moving, 2 = Stopping (int).

Các field altitude, accuracy, address, createdAt không còn trong response.

1.8 GET /gps-tracking/packages/route

Đọc lộ trình đã đi của kiện hàng, theo mã kiện mà client đã gắn ở packages khi push GPS (1.1).

HTTP
GET https://live.fleetwork.vn/api/v1/gps-tracking/packages/route
    ?codes=%23231,%233333
X-API-Key: <key>

Query Parameters

  • codesStringNo
    Danh sách mã kiện, phân tách bằng dấu phẩy: #231,#3333. Ký tự # phải encode thành %23.
  • fromStringNo
    Mốc bắt đầu, ISO 8601 (2026-08-11T00:00:00Z).
  • toStringNo
    Mốc kết thúc, ISO 8601. Khoảng lọc là [from, to).
  • maxPointsIntNo
    Trần số điểm trả về cho mỗi kiện. Tối đa 20000.

Riêng endpoint này dùng ISO 8601 cho from/to (các endpoint khác trong tài liệu dùng Unix ms). Trong response, time vẫn là Unix ms.

Hai hành vi khác nhau đáng lưu ý:

Cách gọiPhạm vi thời gian
Có codesKhông giới hạn thời gian. Đây là đường chính: khách đưa mã kiện, không cần biết ngày.
Không codes, không from/toTự giới hạn 7 ngày gần nhất — trả về mọi kiện đã di chuyển trong khoảng đó, tránh quét toàn bộ lịch sử.

Giá trị thực sự áp dụng luôn được echo lại ở appliedFrom / appliedTo, nên client phân biệt được câu trả lời đầy đủ với câu trả lời đã bị giới hạn mà không phải đoán.

Response 200 OK

JSON
{
  "packages": [
    {
      "packageCode": "#231",
      "from": "2026-08-11T02:38:20",
      "to": "2026-08-11T02:39:20",
      "pointCount": 2,
      "returnedPointCount": 2,
      "carriers": [
        {
          "id": "3f2a91c4-8d7e-5b16-9c03-1a4e7f2b6d85",
          "carrierKind": 0,
          "userId": "user-001",
          "vehicleId": "vehicle-abc",
          "deviceId": null,
          "from": "2026-08-11T02:38:20",
          "to": "2026-08-11T02:39:20"
        }
      ],
      "points": [
        {
          "time": 1713235100000,
          "timeStamp": "2026-08-11T02:38:20",
          "lat": 21.0285,
          "lng": 105.8542,
          "speed": 45.2,
          "heading": 90,
          "status": 1
        },
        {
          "time": 1713235160000,
          "timeStamp": "2026-08-11T02:39:20",
          "lat": 21.029,
          "lng": 105.855,
          "speed": 38.0,
          "heading": 92,
          "status": 1
        }
      ],
      "polyline": null,
      "distanceM": null,
      "source": "live"
    },
    {
      "packageCode": "#3333",
      "from": "2026-08-11T02:38:20",
      "to": "2026-08-11T02:38:20",
      "pointCount": 1,
      "returnedPointCount": 1,
      "carriers": ["..."],
      "points": ["..."],
      "source": "live"
    }
  ],
  "total": 2,
  "appliedFrom": null,
  "appliedTo": null,
  "maxPointsPerPackage": 2000
}

Response Fields

  • totalInteger
    Số kiện trả về.
  • appliedFrom / appliedToString
    Khoảng thời gian thực sự đã áp dụng (null = không giới hạn).
  • maxPointsPerPackageInteger
    Trần điểm đã áp dụng sau khi kẹp về [1, 20000].
  • packages[].pointCountInteger
    Số điểm đã ghi nhận cho kiện.
  • packages[].returnedPointCountInteger
    Số điểm trong response — nhỏ hơn pointCount khi bị giảm mẫu.
  • packages[].carriers[]Array
    Các chặng vận chuyển, mỗi chặng một người/xe chở. Xem bên dưới.
  • packages[].points[].timeLong
    Unix ms — dùng field này khi cần chính xác múi giờ.
  • packages[].points[].timeStampString
    ISO 8601 theo giờ UTC, không kèm hậu tố offset.
  • packages[].points[].statusInteger
    0 = LostGps, 1 = Moving, 2 = Stopping.
  • packages[].sourceString
    live = còn dữ liệu từng điểm · archive = lộ trình cũ đã nén.
  • packages[].polylineString
    Chỉ có khi source = "archive": lộ trình đã nén thành polyline, points[] rỗng.
  • packages[].distanceMLong
    Quãng đường (mét), chỉ có với source = "archive".

carriers[] — đơn sang tay giữa đường

carriers tách theo chặng, không lặp lại người chở trên từng điểm. Một đơn được bàn giao giữa đường (shipper → xe tải) sẽ có nhiều phần tử, nói rõ ai chở đoạn nào — trong khi points[] vẫn là một lộ trình liền mạch theo thứ tự thời gian:

JSON
"carriers": [
  { "id": "…", "carrierKind": 0, "userId": "shipper-01", "from": "2026-08-11T02:38:20", "to": "2026-08-11T03:10:00" },
  { "id": "…", "carrierKind": 1, "vehicleId": "truck-77",  "from": "2026-08-11T03:12:40", "to": "2026-08-11T05:02:15" }
]
carrierKindLoại
0User
1Vehicle
4Account

Khi vượt trần điểm

Hệ thống giảm mẫu đều chứ không cắt đuôi — giữ cả điểm đầu và điểm cuối. Cắt đuôi sẽ khiến gói hàng trông như dừng giữa chừng; giảm mẫu giữ đúng hình dạng lộ trình từ đầu đến cuối. So returnedPointCount với pointCount để biết dữ liệu đã bị giảm mẫu hay chưa; cần đầy đủ thì nâng maxPoints (tối đa 20000).

Xác thực

Chỉ cần X-API-Key. Account được suy ra từ key — client không gửi account id.

Mã lỗi

StatuserrorNguyên nhân
401UNAUTHORIZEDThiếu / sai X-API-Key, không xác định được account.
400INVALID_RANGEto không lớn hơn from.
403route_scope_missingKey chưa được cấp scope cho route này ở gateway.
500PACKAGE_ROUTE_FAILEDLỗi khi đọc lộ trình — liên hệ Fleetwork support.

PHẦN 2 — DASHBOARD

Base path: https://live.fleetwork.vn/api/v1/dashboard/gps-manager

VùngEndpointMô tả
4 KPI CardsGET /summaryActive nhân viên, km, thời gian, chi phí nhiên liệu
Bảng usersGET /usersPer-user: km, thời gian, nhiên liệu, trạng thái
HeatmapGET /activity-heatmapDay × Hour grid
Biểu đồ nhiên liệuGET /fuel-trackingkm vs lít theo ngày/tuần/tháng
Chi phí thángGET /monthly-costsStacked bar: nhiên liệu, bảo dưỡng, bảo hiểm
All-in-OneGET /Tất cả trong 1 request

2.1 GET /summary — KPI Overview

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/summary?date=1713225600000
X-API-Key: <key>

Query Parameters

  • dateInt64No
    Mốc ngày cần lấy KPI.

Response 200 OK

JSON
{
  "date": 1713225600000,
  "activeEmployees": { "active": 4, "total": 25 },
  "totalDistance": { "value": 936.9, "unit": "km" },
  "totalTravelTime": { "totalSeconds": 111000, "formatted": "30 giờ 50 phút" },
  "totalFuelCost": {
    "value": 900000,
    "currency": "VND",
    "formatted": "900,000 VND"
  },
  "generatedAt": 1713235200000
}
  • dateInt64
    Timestamp đầu ngày đang tổng hợp (Unix ms).
  • activeEmployees.activeInteger
    Số nhân viên có GPS point trong 5 phút gần nhất.
  • activeEmployees.totalInteger
    Tổng nhân viên trong account.
  • totalDistance.valueDouble
    Tổng km đi trong ngày.
  • totalTravelTime.formattedString
    Ví dụ: "30 giờ 50 phút".
  • totalFuelCost.formattedString
    Ví dụ: "900,000 VND".

2.2 GET /users

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/users
  ?date=1713225600000&page=1&pageSize=20
X-API-Key: <key>

Query Parameters

  • dateInt64No
    Mốc ngày cần thống kê.
  • statusStringNo
    moving / stopped / signal_lost.
  • pageIntNo
    Trang.
  • pageSizeIntNo
    Bản ghi / trang.

Response 200 OK

JSON
{
  "date": 1713225600000,
  "summary": { "total": 7, "moving": 4, "stopped": 2, "signalLost": 1 },
  "users": [
    {
      "userId": "user-001",
      "distance": { "value": 165.0, "unit": "km" },
      "travelTime": { "totalSeconds": 30600, "formatted": "8h 30m" },
      "fuel": {
        "consumedLiters": 11.6,
        "costVnd": 266000,
        "costFormatted": "266,000 VND",
        "efficiencyKmPerL": 14.2
      },
      "statusCode": 1,
      "status": "moving",
      "lastLocation": {
        "lat": 21.0285,
        "lng": 105.8542,
        "speed": 45.2,
        "time": 1713235100000
      },
      "lastSeenAt": 1713235100000
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "totalItems": 7, "totalPages": 1 }
}

Trạng thái user:

statusCodestatusĐiều kiện
1movingspeed > 0 và lastSeenAt < 15 phút
2stoppingspeed = 0 và lastSeenAt < 15 phút
0signal_lost(now - lastSeenAt) > 15 phút

2.3 GET /activity-heatmap

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/activity-heatmap
  ?from=1712793600000&to=1713484799000&metric=distance
X-API-Key: <key>

Query Parameters

  • fromInt64No
    Thời gian bắt đầu khoảng lọc.
  • toInt64No
    Thời gian kết thúc khoảng lọc.
  • metricStringNo
    distance (km) / points (số GPS points).
  • userIdStringNo
    Lọc nhân viên cụ thể.

Response 200 OK

JSON
{
  "from": 1712793600000,
  "to": 1713484799000,
  "metric": "distance",
  "cells": [
    {
      "dayOfWeek": "Thu",
      "date": 1713312000000,
      "hour": 16,
      "value": 60.0,
      "label": "60 km"
    }
  ],
  "maxValue": 124.5,
  "minValue": 0.0,
  "totalCells": 168
}
  • fromInt64
    Timestamp bắt đầu range (Unix ms).
  • toInt64
    Timestamp kết thúc range (Unix ms).
  • cells[].dayOfWeekString
    Tên ngày trong tuần (Mon, Tue, …, Sun).
  • cells[].dateInt64
    Timestamp đầu ngày của ô heatmap (Unix ms).
  • cells[].hourInteger
    Giờ trong ngày (0–23).
  • cells[].valueDouble
    Giá trị km hoặc số GPS points.
  • cells[].labelString
    Nhãn hiển thị, ví dụ: "60 km".
  • maxValueDouble
    Giá trị lớn nhất (dùng tính màu gradient).
  • totalCellsInteger
    Tổng số ô (số ngày × 24).

2.4 GET /fuel-tracking

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/fuel-tracking
    ?from=1704067200000&to=1735689599000&groupBy=week
X-API-Key: <key>

Query Parameters

  • fromInt64No
    Thời gian bắt đầu khoảng phân tích.
  • toInt64No
    Thời gian kết thúc khoảng phân tích.
  • groupByStringNo
    day / week / month.
  • userIdStringNo
    Lọc nhân viên.

Response 200 OK

JSON
{
  "from": 1704067200000,
  "to": 1735689599000,
  "groupBy": "week",
  "fuelEfficiency": { "value": 16.8, "unit": "km/L", "trend": "improving" },
  "series": [
    {
      "period": "2026-W01",
      "label": "T1/W1",
      "distanceKm": 820.5,
      "fuelLiters": 48.8,
      "efficiencyKmPerL": 16.8
    }
  ],
  "totals": {
    "totalDistanceKm": 18420.0,
    "totalFuelLiters": 1096.4,
    "avgEfficiencyKmPerL": 16.8
  }
}
FieldMô tả
fromTimestamp bắt đầu khoảng dữ liệu (Unix ms).
toTimestamp kết thúc khoảng dữ liệu (Unix ms).
fuelEfficiency.trendimproving / declining / stable.
series[].period"2026-W01" (tuần), "2026-01" (tháng), "2026-04-01" (ngày).

2.5 GET /monthly-costs

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/monthly-costs
    ?from=1704067200000&to=1735689599000&currency=VND
X-API-Key: <key>

Query Parameters

  • fromInt64No
    Thời gian bắt đầu khoảng tổng hợp.
  • toInt64No
    Thời gian kết thúc khoảng tổng hợp.
  • currencyStringNo
    Đơn vị tiền tệ trả về.

Response 200 OK

JSON
{
  "from": 1704067200000,
  "to": 1735689599000,
  "currency": "VND",
  "months": [
    {
      "month": 3,
      "label": "Mar",
      "costs": {
        "fuel": 1200000,
        "maintenance": 7000000,
        "insurance": 3000000,
        "other": 1000000,
        "total": 12200000
      }
    }
  ],
  "totals": {
    "fuel": 14400000,
    "maintenance": 28000000,
    "insurance": 12000000,
    "other": 4000000,
    "grandTotal": 58400000
  },
  "categories": [
    { "key": "fuel", "label": "Nhiên liệu", "color": "#4F8EF7" },
    { "key": "maintenance", "label": "Bảo dưỡng", "color": "#F7C24F" },
    { "key": "insurance", "label": "Bảo hiểm", "color": "#4FF79B" },
    { "key": "other", "label": "Khác", "color": "#F74F4F" }
  ]
}
  • fromInt64
    Timestamp bắt đầu khoảng tổng hợp (Unix ms).
  • toInt64
    Timestamp kết thúc khoảng tổng hợp (Unix ms).
  • months[].monthInt
    Tháng trong năm (1..12).
  • months[].labelString
    Nhãn hiển thị tháng.
  • months[].costs.totalLong
    Tổng chi phí của tháng.
  • totals.grandTotalLong
    Tổng chi phí toàn bộ khoảng from..to.

2.6 GET / — All-in-One

Load toàn bộ Dashboard trong 1 request.

HTTP
GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager?date=1713225600000
X-API-Key: <key>
JSON
{
  "summary": { "...": "response của 2.1" },
  "users": {
    "summary": { "total": 7, "moving": 4, "stopped": 2, "signalLost": 1 },
    "topUsers": []
  },
  "heatmap": { "...": "response của 2.3, 14 ngày gần nhất" },
  "fuelTracking": { "...": "response của 2.4, groupBy=week" },
  "monthlyCosts": { "...": "response của 2.5" }
}

PHẦN 3 — BÁO CÁO

Base path: https://live.fleetwork.vn/api/v1/reports

Tất cả báo cáo hỗ trợ xuất file — thêm ?format=excel hoặc ?format=csv.

3.1 GET /reports/trip/summary

Báo cáo hành trình tổng hợp theo nhân viên.

HTTP
GET https://live.fleetwork.vn/api/v1/reports/trip/summary
  ?from=1711929600000&to=1712793599000&page=1&pageSize=20
X-API-Key: <key>

Query Parameters

  • fromInt64Yes
    Thời gian bắt đầu (Unix ms).
  • toInt64Yes
    Thời gian kết thúc (Unix ms).
  • userIdStringNo
    Lọc nhân viên.
  • groupIdUUIDNo
    Lọc nhóm.
  • pageIntNo
    Trang.
  • pageSizeIntNo
    Bản ghi / trang.
  • sortByStringNo
    totalDistance / travelTime / maxSpeed / name.
  • sortDescBooleanNo
    Giảm dần.
  • formatStringNo
    excel / csv.

Response 200 OK

JSON
{
  "reportType": "trip_summary",
  "from": 1711929600000,
  "to": 1712793599000,
  "employees": [
    {
      "userId": "user-001",
      "name": "Nguyễn Văn A",
      "groupName": "Đội A",
      "totalDistanceKm": 1245.8,
      "travelTime": { "totalSeconds": 152100, "formatted": "42 giờ 30 phút" },
      "stopTime": { "totalSeconds": 29700, "formatted": "8 giờ 15 phút" },
      "maxSpeedKmh": 95.0,
      "minSpeedKmh": 15.0,
      "tripDays": 10
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "totalItems": 4, "totalPages": 1 },
  "generatedAt": 1713235200000
}

3.2 GET /reports/trip/detail

1 hàng = 1 nhân viên × 1 ngày.

HTTP
GET https://live.fleetwork.vn/api/v1/reports/trip/detail
  ?from=1711929600000&to=1712793599000&page=1&pageSize=50
X-API-Key: <key>

Query parameters tương tự 3.1 (pageSize max 500).

Response 200 OK

JSON
{
  "reportType": "trip_detail",
  "trips": [
    {
      "date": 1712707200000,
      "userId": "user-001",
      "name": "Nguyễn Văn A",
      "startTime": 1712734200000,
      "endTime": 1712771100000,
      "distanceKm": 156.8,
      "travelTime": { "totalSeconds": 30600, "formatted": "8 giờ 30 phút" },
      "stopTime": { "totalSeconds": 6300, "formatted": "1 giờ 45 phút" },
      "maxSpeedKmh": 95.0,
      "minSpeedKmh": 15.0,
      "startLocation": {
        "lat": 21.0285,
        "lng": 105.8542,
        "address": "Hà Nội, Hoàn Kiếm"
      },
      "endLocation": {
        "lat": 21.035,
        "lng": 105.8,
        "address": "Hà Nội, Cầu Giấy"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 38,
    "totalPages": 1
  },
  "generatedAt": 1713235200000
}
  • trips[].dateInt64
    Timestamp đầu ngày của bản ghi (Unix ms).
  • trips[].startTimeInt64
    Timestamp bắt đầu hành trình (Unix ms).
  • trips[].endTimeInt64
    Timestamp kết thúc hành trình (Unix ms).

3.3 GET /reports/fuel/summary

HTTP
GET https://live.fleetwork.vn/api/v1/reports/fuel/summary
    ?from=1711929600000&to=1712793599000&page=1&pageSize=20
X-API-Key: <key>

Query Parameters

  • fromInt64Yes
    Thời gian bắt đầu (Unix ms).
  • toInt64Yes
    Thời gian kết thúc (Unix ms).
  • userIdStringNo
    Lọc nhân viên.
  • groupIdUUIDNo
    Lọc nhóm.
  • pageIntNo
    Trang.
  • pageSizeIntNo
    Bản ghi / trang.
  • sortByStringNo
    distanceKm / fuelStandardLiters / totalCostVnd / name.
  • sortDescBooleanNo
    Giảm dần.
  • formatStringNo
    excel / csv.

Response 200 OK

JSON
{
  "reportType": "fuel_summary",
  "fuelConfig": { "efficiencyLper100km": 7.0, "pricePerLiterVnd": 23000 },
  "employees": [
    {
      "userId": "user-001",
      "name": "Nguyễn Văn A",
      "groupName": "Đội A",
      "distanceKm": 1245.8,
      "travelTime": { "totalSeconds": 152100, "formatted": "42 giờ 30 phút" },
      "fuelStandardLiters": 87.2,
      "totalCostVnd": 2005600,
      "totalCostFormatted": "2.005.600 VNĐ"
    }
  ],
  "totals": {
    "distanceKm": 4446.2,
    "fuelStandardLiters": 311.2,
    "totalCostVnd": 7157600,
    "totalCostFormatted": "7.157.600 VNĐ"
  },
  "pagination": { "page": 1, "pageSize": 20, "totalItems": 4, "totalPages": 1 },
  "generatedAt": 1713235200000
}

Định mức = distanceKm × efficiencyLper100km / 100 | Chi phí = fuelStandardLiters × pricePerLiterVnd

3.4 GET /reports/fuel/detail

1 hàng = 1 nhân viên × 1 ngày.

HTTP
GET https://live.fleetwork.vn/api/v1/reports/fuel/detail
  ?from=1711929600000&to=1712793599000&page=1&pageSize=50
X-API-Key: <key>

Query Parameters

  • fromInt64Yes
    Thời gian bắt đầu (Unix ms).
  • toInt64Yes
    Thời gian kết thúc (Unix ms).
  • userIdStringNo
    Lọc nhân viên.
  • groupIdUUIDNo
    Lọc nhóm.
  • pageIntNo
    Trang.
  • pageSizeIntNo
    Bản ghi / trang.
  • sortByStringNo
    date / distanceKm / fuelStandardLiters / totalCostVnd.
  • sortDescBooleanNo
    Giảm dần.
  • formatStringNo
    excel / csv.

Response 200 OK

JSON
{
  "reportType": "fuel_detail",
  "trips": [
    {
      "date": 1712707200000,
      "userId": "user-001",
      "name": "Nguyễn Văn A",
      "startTime": 1712734200000,
      "endTime": 1712771100000,
      "distanceKm": 156.8,
      "travelTime": { "totalSeconds": 30600, "formatted": "8 giờ 30 phút" },
      "fuelStandardLiters": 11.0,
      "fuelPricePerLiterVnd": 23000,
      "totalCostVnd": 253000,
      "totalCostFormatted": "253.000 VNĐ"
    }
  ],
  "totals": {
    "distanceKm": 746.5,
    "fuelStandardLiters": 52.3,
    "totalCostVnd": 1202900,
    "totalCostFormatted": "1.202.900 VNĐ"
  },
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 38,
    "totalPages": 1
  },
  "generatedAt": 1713235200000
}
  • trips[].dateInt64
    Timestamp đầu ngày của bản ghi (Unix ms).
  • trips[].startTimeInt64
    Timestamp bắt đầu hành trình (Unix ms).
  • trips[].endTimeInt64
    Timestamp kết thúc hành trình (Unix ms).

3.5 GET /reports/activity-time

Mỗi hàng = 1 ngày × 1 giờ, thống kê toàn đội.

HTTP
GET https://live.fleetwork.vn/api/v1/reports/activity-time
  ?from=1711929600000&to=1712793599000
X-API-Key: <key>

Query Parameters

ParameterTypeRequiredDefault
fromInt64Yes—
toInt64Yes—
pageIntNo1
pageSizeIntNo50 (max 500)
formatStringNoexcel / csv

Response 200 OK

JSON
{
  "reportType": "activity_time",
  "totalEmployees": 20,
  "rows": [
    {
      "date": 1712707200000,
      "hour": 7,
      "activeEmployeeCount": 3,
      "inactiveEmployeeCount": 17,
      "totalDistanceKm": 45.2
    },
    {
      "date": 1712707200000,
      "hour": 8,
      "activeEmployeeCount": 8,
      "inactiveEmployeeCount": 12,
      "totalDistanceKm": 112.8
    }
  ],
  "totals": { "totalDistanceKm": 2461.1 },
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 18,
    "totalPages": 1
  },
  "generatedAt": 1713235200000
}
  • rows[].dateInt64
    Timestamp đầu ngày của dòng thống kê (Unix ms).
  • rows[].hourInt32
    Giờ trong ngày, từ 0 đến 23.

Error Responses

StatusMô tả
400 Bad RequestTham số không hợp lệ.
401 UnauthorizedAPI key thiếu hoặc sai.
403 ForbiddenKhông có quyền truy cập resource.
404 Not FoundResource không tồn tại.
429 Too Many RequestsVượt giới hạn rate limit.
500 Internal Server ErrorLỗi hệ thống — liên hệ Fleetwork support.
JSON
{ "error": "BAD_REQUEST", "message": "...", "code": 400 }