Tài liệu API

Tham chiếu API

Mọi thao tác một token OAuth có thể gọi, kèm scope, tham số, nội dung yêu cầu và phản hồi. Được sinh tự động từ định nghĩa API openapi.public.json nên không thể lệch khỏi máy chủ.

Phần mô tả các thao tác và trường dưới đây được sinh tự động từ định nghĩa API nên giữ nguyên tiếng Anh ở mọi ngôn ngữ.

Quy ước

  • Base URL https://api.stracker.vn. Gửi Authorization: Bearer <access_token> và, khi có nội dung, Content-Type: application/json.
  • Danh sách nhận page và limit; đa số nhận thêm searchKeyword. Danh sách webhook trả { "data": [...], "meta": { ... } }.
  • Thao tác ghi nhận header Idempotency-Key tùy chọn: xem idempotency.
  • Lỗi là application/problem+json với code ổn định; xem lỗi.
  • Mỗi thao tác nêu scope cần có. Mọi lệnh gọi cũng có thể trả 401, 403 (OAUTH_INSUFFICIENT_SCOPE, OAUTH_ROUTE_NOT_EXPOSED) và 429 (giới hạn tốc độ).

Drivers

GET/v1/drivers

List drivers (paginated)

Returns a paginated drivers catalog, scoped to the caller's own drivers for Owner permission. Every row carries the server-computed readiness verdict; readiness and unassigned filter on it.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
readinessquerystringGiá trị: drivableblockeddue_soon
unassignedquerystringGiá trị: truefalse
attentionquerystringGiá trị: documentshoursapp
statequerystringGiá trị: drivingreadyrestingonLeaveblockedinactive

Phản hồi

  • 200Paginated driver list
    TrườngKiểuMô tả
    dataobject[]
    data[].namestring
    data[].emailstring
    data[].phonestring
    data[].statusboolean
    data[].typestringGiá trị: parentstudentdriverteacherstaffpassengermotorbike_driver
    data[].descriptionstring
    data[].avatarBase64string
    data[].passwordstringPassword for the driver's linked user account; required only when creating or changing credentialse.g. "Str0ngP@ssw0rd!"
    data[].appAccessbooleanCreate only: true creates the driver-app login (no password; phone-code sign-in, the driver sets one from the app); omitted or false creates no logine.g. false
    data[].licenseStatusstringDerived from license_expiry: valid (>30 days out), expiring_soon (<=30 days), expired, or unknown (no expiry on file, or no driver row exists yet). Read-only, populated only by GET /v1/drivers/:id.e.g. "valid"
    data[].driverIdnumbercó thể nulldriver.id — the identifier every ASSIGNMENT takes (trip.driver_id, route.driver_id, POST /v1/trips/:id/assign). Distinct from this DTO’s id, which is the person.id the driver SCREENS are keyed by. A caller that assigns must send this one: the two spaces do not overlap, and sending a person id answers 404 DRIVER_NOT_FOUND. Absent when the person has no driver row at all, which is exactly the case where they cannot be assigned.e.g. 4
    data[].rowVersionnumberdriver.row_version, bumped by every save of the driver. Send it back as the If-Match header of PUT /v1/drivers/:id to refuse the save when someone else saved the driver in between (409 DRIVER_VERSION_CONFLICT). Populated by GET /v1/drivers/:id and returned by the update.e.g. 3
    data[].licenseExpirystringcó thể nullLicense expiry date (YYYY-MM-DD). Dual-purpose field: readable on every driver response (derived from the driver row's license_expiry), and writable on create/update — SaveDriver persists it to driver.license_expiry whenever the request body supplies it. A PATCH/PUT that omits this field leaves the stored value untouched (partial-update semantics); it is never nulled out implicitly.e.g. "2030-03-01"
    data[].licenseNumberstringLicense number (driver.license_number). Writable on create/update; unique per tenant among non-deleted drivers (uq_driver_license_number) — a collision returns 409 DUPLICATE_ENTRY.e.g. "079203001234"
    data[].licenseClassstringLicense class (driver.license_class), e.g. VN categories A1/A2/B1/B2/C/D/E/F1/F2. Plain string — the DDL column has no native ENUM, so no closed set is enforced. Writable on create/update.e.g. "B2"
    data[].licenseIssueDatestringLicense issue date (YYYY-MM-DD), driver.license_issue_date. Writable on create/update.e.g. "2020-03-01"
    data[].licenseCountrystringCountry/authority that issued the license (driver.license_country) — closest real column to "issuing authority". Writable on create/update.e.g. "VN"
    data[].primaryCampusIdnumbercó thể nullPrimary campus id (driver.primary_campus_id, FK campus.id). Writable on create/update. Omitted leaves the stored value untouched; explicit null clears it. An id that does not exist in the tenant answers 400 VALIDATION_FAILED (field primaryCampusId, code NOT_FOUND). The read-side campus object is derived from this column.e.g. 3
    data[].hosRemainingHoursnumbercó thể nullRemaining hours-of-service today before the driver's max_daily_hours cap. Populated only by GET /v1/drivers/:id.e.g. 4.5
    data[].assignedVehicleIdnumbercó thể nullID of the vehicle assigned via an active route, if any. Populated only by GET /v1/drivers/:id.e.g. 7
    data[].readinessobjectServer-computed readiness verdict. Read-only, populated by GET /v1/drivers and GET /v1/drivers/:id. The FE renders blockers/warnings verbatim and never re-derives canDrive.
    data[].readiness.canDrivebooleanTrue only when blockers is empty.e.g. false
    data[].readiness.blockersobject[]
    data[].readiness.blockers[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    data[].readiness.blockers[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    data[].readiness.blockers[].severitystringGiá trị: blockerwarninge.g. "blocker"
    data[].readiness.blockers[].reasonobject
    data[].readiness.blockers[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Giá trị: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    data[].readiness.blockers[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    data[].readiness.blockers[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    data[].readiness.warningsobject[]
    data[].readiness.warnings[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    data[].readiness.warnings[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    data[].readiness.warnings[].severitystringGiá trị: blockerwarninge.g. "blocker"
    data[].readiness.warnings[].reasonobject
    data[].readiness.warnings[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Giá trị: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    data[].readiness.warnings[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    data[].readiness.warnings[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    data[].licenseobject
    data[].license.classstringcó thể nulle.g. "D"
    data[].license.validUntilstringcó thể nullISO date YYYY-MM-DD.e.g. "2027-03-01"
    data[].license.daysLeftnumbercó thể nullWhole days from today to validUntil; negative when expired, null when no expiry is on file.e.g. 212
    data[].qualificationsobject[]
    data[].qualifications[].idnumbere.g. 12
    data[].qualifications[].codestringThe qualification's licence class — its stable code.e.g. "D"
    data[].qualifications[].namestringDisplay name: the licence class, suffixed with the issuer when one is recorded.e.g. "D — Sở GTVT TP.HCM"
    data[].qualifications[].validUntilstringcó thể nulle.g. "2027-03-01"
    data[].qualifications[].daysLeftnumbercó thể nulle.g. 212
    data[].complianceobject
    data[].compliance.passednumbere.g. 1
    data[].compliance.totalnumbere.g. 2
    data[].compliance.failingstring[]
    data[].hoursobject
    data[].hours.thisWeeknumberOn-duty hours already worked in the current business week.e.g. 32.5
    data[].hours.shiftsThisWeeknumberHow many SHIFTS the driver has in the current business week — a count of shift rows, not hours. Carried separately because the two answer different questions and are not convertible: a client that printed thisWeek under a "shifts" label showed "16.5 shifts".e.g. 6
    data[].hours.byDayobject[]The seven days of the current business week (Monday first), each with the hours worked. Always seven entries, so a day off is a 0 rather than a hole the client has to guess at. Sums to thisWeek — both are derived from the same per-day aggregation.
    data[].hours.byDay[].datestringCalendar day, YYYY-MM-DD.e.g. "2026-09-01"
    data[].hours.byDay[].hoursnumberOn-duty hours worked that day. 0 means a day off, never "unknown".e.g. 8.2
    data[].hours.dailyLimitnumbercó thể nulldriver.max_daily_hours; null means no per-day cap is configured.e.g. 10
    data[].hours.limitnumbercó thể nulldriver.max_weekly_hours; null means no cap is configured and the hours rule is skipped.e.g. 40
    data[].assignmentobjectcó thể nullCurrent active-route assignment, or null when the driver is unassigned.
    data[].assignment.vehicleIdnumbercó thể nulle.g. 7
    data[].assignment.platestringcó thể nulle.g. "51B-123.45"
    data[].assignment.routeLabelstringcó thể nulle.g. "Tuyến 3 — Quận 7"
    data[].availabilityTodaybooleanWhether today falls inside the driver's availability roster.e.g. true
    data[].codestringcó thể nullHuman-readable staff code, e.g. TX-001.e.g. "TX-001"
    data[].campusobjectcó thể nullThe driver's primary campus — the roster's scope label.
    data[].campus.idnumbere.g. 3
    data[].campus.namestringe.g. "THPT Greenfield"
    data[].employmentStatusstringEmployment lifecycle. terminated and on_leave are their own roster row states.Giá trị: activeon_leavesuspendedterminatede.g. "active"
    data[].hireDatestringcó thể nullISO date YYYY-MM-DD.e.g. "2021-08-16"
    data[].requiredDocumentTypesstring[]The papers THIS tenant requires, in display order. Not one list for everybody: school/indep add the child-safety check (wwcc), charter a passenger-carriage certificate (tour), private the dangerous-goods one (adr), transit needs only the universal three. Sent so the client renders the set rather than re-deriving a rule that gates assignment.
    data[].documentsobject[]Required-document strip: one chip per entry of requiredDocumentTypes, in that order, INCLUDING the ones with nothing on file (state pending) — a strip built from existing rows could never show a gap. The licence chip comes from driver.license_expiry, not from a driver_document row.
    data[].documents[].typestringdriver_document.type — the FE maps it to a label.e.g. "licence"
    data[].documents[].statestringexpiring means within 60 days — the same window the attention card counts.Giá trị: validexpiringexpiredpendinge.g. "expiring"
    data[].documents[].validUntilstringcó thể nullISO date YYYY-MM-DD.e.g. "2027-03-01"
    data[].documents[].daysLeftnumbercó thể nulle.g. 41
    data[].shiftobjectcó thể nullToday's rostered shift, or null when nothing is scheduled.
    data[].shift.startsAtstringcó thể nullLocal HH:mm.e.g. "05:00"
    data[].shift.endsAtstringcó thể nullLocal HH:mm; null while the shift is open.e.g. "13:00"
    data[].shift.partstringGiá trị: morningafternoone.g. "morning"
    data[].shift.statusstringGiá trị: openclosedadjustede.g. "open"
    data[].appobjectDriver App connection state.
    data[].app.installedbooleanFalse when last_seen_at was never set — the app has never signed in on this account.e.g. true
    data[].app.onlinebooleanA live app session right now.e.g. false
    data[].app.lastSeenAtstringcó thể nullISO 8601 instant.e.g. "2026-09-01T06:12:00.000Z"
    data[].rowStatestringWhat the driver is DOING today — a different question from readiness.canDrive, which is only whether they may legally take a trip. The roster paints this one.Giá trị: drivingreadyrestingonLeaveblockedinactivee.g. "driving"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the driver read/write/owner permission
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/drivers/{id}

Get a driver by id

Returns a single driver by primary key.

Tham số

TrườngKiểuMô tả
idpathbắt buộcintegerThe driver's PERSON id: the id of a GET /v1/drivers row (list_drivers), never its driverId. driverId is the driver.id that trip and route assignment take; sending it here answers 404 DRIVER_PERSON_NOT_FOUND (reason: driver_id_sent) or, when it happens to equal another driver's person id, acts on that other driver.

Phản hồi

  • 200Driver found
    TrườngKiểuMô tả
    namestring
    emailstring
    phonestring
    statusboolean
    typestringGiá trị: parentstudentdriverteacherstaffpassengermotorbike_driver
    descriptionstring
    avatarBase64string
    passwordstringPassword for the driver's linked user account; required only when creating or changing credentialse.g. "Str0ngP@ssw0rd!"
    appAccessbooleanCreate only: true creates the driver-app login (no password; phone-code sign-in, the driver sets one from the app); omitted or false creates no logine.g. false
    licenseStatusstringDerived from license_expiry: valid (>30 days out), expiring_soon (<=30 days), expired, or unknown (no expiry on file, or no driver row exists yet). Read-only, populated only by GET /v1/drivers/:id.e.g. "valid"
    driverIdnumbercó thể nulldriver.id — the identifier every ASSIGNMENT takes (trip.driver_id, route.driver_id, POST /v1/trips/:id/assign). Distinct from this DTO’s id, which is the person.id the driver SCREENS are keyed by. A caller that assigns must send this one: the two spaces do not overlap, and sending a person id answers 404 DRIVER_NOT_FOUND. Absent when the person has no driver row at all, which is exactly the case where they cannot be assigned.e.g. 4
    rowVersionnumberdriver.row_version, bumped by every save of the driver. Send it back as the If-Match header of PUT /v1/drivers/:id to refuse the save when someone else saved the driver in between (409 DRIVER_VERSION_CONFLICT). Populated by GET /v1/drivers/:id and returned by the update.e.g. 3
    licenseExpirystringcó thể nullLicense expiry date (YYYY-MM-DD). Dual-purpose field: readable on every driver response (derived from the driver row's license_expiry), and writable on create/update — SaveDriver persists it to driver.license_expiry whenever the request body supplies it. A PATCH/PUT that omits this field leaves the stored value untouched (partial-update semantics); it is never nulled out implicitly.e.g. "2030-03-01"
    licenseNumberstringLicense number (driver.license_number). Writable on create/update; unique per tenant among non-deleted drivers (uq_driver_license_number) — a collision returns 409 DUPLICATE_ENTRY.e.g. "079203001234"
    licenseClassstringLicense class (driver.license_class), e.g. VN categories A1/A2/B1/B2/C/D/E/F1/F2. Plain string — the DDL column has no native ENUM, so no closed set is enforced. Writable on create/update.e.g. "B2"
    licenseIssueDatestringLicense issue date (YYYY-MM-DD), driver.license_issue_date. Writable on create/update.e.g. "2020-03-01"
    licenseCountrystringCountry/authority that issued the license (driver.license_country) — closest real column to "issuing authority". Writable on create/update.e.g. "VN"
    primaryCampusIdnumbercó thể nullPrimary campus id (driver.primary_campus_id, FK campus.id). Writable on create/update. Omitted leaves the stored value untouched; explicit null clears it. An id that does not exist in the tenant answers 400 VALIDATION_FAILED (field primaryCampusId, code NOT_FOUND). The read-side campus object is derived from this column.e.g. 3
    hosRemainingHoursnumbercó thể nullRemaining hours-of-service today before the driver's max_daily_hours cap. Populated only by GET /v1/drivers/:id.e.g. 4.5
    assignedVehicleIdnumbercó thể nullID of the vehicle assigned via an active route, if any. Populated only by GET /v1/drivers/:id.e.g. 7
    readinessobjectServer-computed readiness verdict. Read-only, populated by GET /v1/drivers and GET /v1/drivers/:id. The FE renders blockers/warnings verbatim and never re-derives canDrive.
    readiness.canDrivebooleanTrue only when blockers is empty.e.g. false
    readiness.blockersobject[]
    readiness.blockers[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    readiness.blockers[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    readiness.blockers[].severitystringGiá trị: blockerwarninge.g. "blocker"
    readiness.blockers[].reasonobject
    readiness.blockers[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Giá trị: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    readiness.blockers[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    readiness.blockers[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    readiness.warningsobject[]
    readiness.warnings[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    readiness.warnings[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    readiness.warnings[].severitystringGiá trị: blockerwarninge.g. "blocker"
    readiness.warnings[].reasonobject
    readiness.warnings[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Giá trị: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    readiness.warnings[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    readiness.warnings[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    licenseobject
    license.classstringcó thể nulle.g. "D"
    license.validUntilstringcó thể nullISO date YYYY-MM-DD.e.g. "2027-03-01"
    license.daysLeftnumbercó thể nullWhole days from today to validUntil; negative when expired, null when no expiry is on file.e.g. 212
    qualificationsobject[]
    qualifications[].idnumbere.g. 12
    qualifications[].codestringThe qualification's licence class — its stable code.e.g. "D"
    qualifications[].namestringDisplay name: the licence class, suffixed with the issuer when one is recorded.e.g. "D — Sở GTVT TP.HCM"
    qualifications[].validUntilstringcó thể nulle.g. "2027-03-01"
    qualifications[].daysLeftnumbercó thể nulle.g. 212
    complianceobject
    compliance.passednumbere.g. 1
    compliance.totalnumbere.g. 2
    compliance.failingstring[]
    hoursobject
    hours.thisWeeknumberOn-duty hours already worked in the current business week.e.g. 32.5
    hours.shiftsThisWeeknumberHow many SHIFTS the driver has in the current business week — a count of shift rows, not hours. Carried separately because the two answer different questions and are not convertible: a client that printed thisWeek under a "shifts" label showed "16.5 shifts".e.g. 6
    hours.byDayobject[]The seven days of the current business week (Monday first), each with the hours worked. Always seven entries, so a day off is a 0 rather than a hole the client has to guess at. Sums to thisWeek — both are derived from the same per-day aggregation.
    hours.byDay[].datestringCalendar day, YYYY-MM-DD.e.g. "2026-09-01"
    hours.byDay[].hoursnumberOn-duty hours worked that day. 0 means a day off, never "unknown".e.g. 8.2
    hours.dailyLimitnumbercó thể nulldriver.max_daily_hours; null means no per-day cap is configured.e.g. 10
    hours.limitnumbercó thể nulldriver.max_weekly_hours; null means no cap is configured and the hours rule is skipped.e.g. 40
    assignmentobjectcó thể nullCurrent active-route assignment, or null when the driver is unassigned.
    assignment.vehicleIdnumbercó thể nulle.g. 7
    assignment.platestringcó thể nulle.g. "51B-123.45"
    assignment.routeLabelstringcó thể nulle.g. "Tuyến 3 — Quận 7"
    availabilityTodaybooleanWhether today falls inside the driver's availability roster.e.g. true
    codestringcó thể nullHuman-readable staff code, e.g. TX-001.e.g. "TX-001"
    campusobjectcó thể nullThe driver's primary campus — the roster's scope label.
    campus.idnumbere.g. 3
    campus.namestringe.g. "THPT Greenfield"
    employmentStatusstringEmployment lifecycle. terminated and on_leave are their own roster row states.Giá trị: activeon_leavesuspendedterminatede.g. "active"
    hireDatestringcó thể nullISO date YYYY-MM-DD.e.g. "2021-08-16"
    requiredDocumentTypesstring[]The papers THIS tenant requires, in display order. Not one list for everybody: school/indep add the child-safety check (wwcc), charter a passenger-carriage certificate (tour), private the dangerous-goods one (adr), transit needs only the universal three. Sent so the client renders the set rather than re-deriving a rule that gates assignment.
    documentsobject[]Required-document strip: one chip per entry of requiredDocumentTypes, in that order, INCLUDING the ones with nothing on file (state pending) — a strip built from existing rows could never show a gap. The licence chip comes from driver.license_expiry, not from a driver_document row.
    documents[].typestringdriver_document.type — the FE maps it to a label.e.g. "licence"
    documents[].statestringexpiring means within 60 days — the same window the attention card counts.Giá trị: validexpiringexpiredpendinge.g. "expiring"
    documents[].validUntilstringcó thể nullISO date YYYY-MM-DD.e.g. "2027-03-01"
    documents[].daysLeftnumbercó thể nulle.g. 41
    shiftobjectcó thể nullToday's rostered shift, or null when nothing is scheduled.
    shift.startsAtstringcó thể nullLocal HH:mm.e.g. "05:00"
    shift.endsAtstringcó thể nullLocal HH:mm; null while the shift is open.e.g. "13:00"
    shift.partstringGiá trị: morningafternoone.g. "morning"
    shift.statusstringGiá trị: openclosedadjustede.g. "open"
    appobjectDriver App connection state.
    app.installedbooleanFalse when last_seen_at was never set — the app has never signed in on this account.e.g. true
    app.onlinebooleanA live app session right now.e.g. false
    app.lastSeenAtstringcó thể nullISO 8601 instant.e.g. "2026-09-01T06:12:00.000Z"
    rowStatestringWhat the driver is DOING today — a different question from readiness.canDrive, which is only whether they may legally take a trip. The roster paints this one.Giá trị: drivingreadyrestingonLeaveblockedinactivee.g. "driving"
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the driver read/write/owner permission
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Not the person id of a live driver of this tenant
    Ví dụ
    {
      "type": "https://stracker.io/errors/driver-person-not-found",
      "title": "Driver not found for this person id",
      "status": 404,
      "detail": "Driver not found for this person id",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "DRIVER_PERSON_NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Routes

GET/v1/routes

List routes

Returns a paginated, searchable list of routes, optionally filtered by status or school.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringGiá trị: activeinactivedraftarchived
campusIdqueryinteger
directionqueryinteger

Phản hồi

  • 200Paginated list of routes
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumberRoute ID; 0 or omitted on createe.g. 4
    data[].codestringcó thể nullRoute codee.g. "RT-004"
    data[].namestringRoute display namee.g. "Route A - Morning"
    data[].campusIdnumbercó thể nullID of the school (campus) this route servese.g. 12
    data[].campusNamestringcó thể nullName of the campus this route serves; null when unassigned or not joinede.g. "Greenfield High School"
    data[].vehicleIdnumbercó thể nullID of the vehicle assigned to this routee.g. 7
    data[].vehicleNamestringcó thể nullDisplay name of the assigned vehiclee.g. "B-101"
    data[].vehiclePlatestringcó thể nullRegistration plate of the assigned vehiclee.g. "51F-238.45"
    data[].vehicleCapacitynumbercó thể nullSeats on the assigned vehicle (vehicle.capacity); null when no vehicle or not recordede.g. 45
    data[].vehicleReadinessobjectcó thể nullDispatch verdict of the assigned vehicle (detail read only); null when no vehicle is assigned
    data[].vehicleReadiness.canRunbooleanWhether the vehicle may be dispatched todaye.g. true
    data[].vehicleReadiness.blockersobject[]
    data[].vehicleReadiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    data[].vehicleReadiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "advisory"
    data[].vehicleReadiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    data[].vehicleReadiness.warningsobject[]
    data[].vehicleReadiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    data[].vehicleReadiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "advisory"
    data[].vehicleReadiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    data[].vehicleReadiness.inspectionRecordedbooleanTrue when the vehicle has a next-inspection date on recorde.g. true
    data[].driverIdnumbercó thể nullID of the driver assigned to this route (driver.id)e.g. 3
    data[].driverNamestringcó thể nullFull name of the assigned drivere.g. "Nguyen Thu Ha"
    data[].backupDriverIdnumbercó thể nullStanding fallback driver (driver.id) covering this route when the regular driver is awaye.g. 9
    data[].backupDriverNamestringcó thể nullFull name of the backup driver
    data[].directionnumbercó thể null1 outbound (morning pickup), 2 inbound (afternoon drop-off), 3 extra runGiá trị: 123e.g. 1
    data[].colorstringcó thể nullDisplay color (hex)e.g. "#2563eb"
    data[].capacitynumbercó thể nullPassenger capacitye.g. 45
    data[].estimatedTransitTimenumbercó thể nullEstimated transit time, in minutese.g. 35
    data[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].deactivationReasonstringcó thể nullWhy the route was taken out of service
    data[].deactivationEffectiveDatestringcó thể nullDate the withdrawal was intended to take effect. Recorded intent — nothing acts on it yet.e.g. "2026-08-24"
    data[].stopsCountnumberCount of stops on this routee.g. 8
    data[].stopsGeocodednumberStops carrying both lat and lnge.g. 8
    data[].studentsCountnumberRiders with a standing registration on this routee.g. 38
    data[].departureTimestringcó thể nullEarliest planned departure across the route stops, HH:mm:sse.g. "06:35:00"
    data[].pairedRouteIdnumbercó thể nullOpposite-direction sibling — the route sharing this group_ide.g. 12
    data[].pairedRouteCodestringcó thể nullThe paired sibling's code, for the list's link celle.g. "R-101-PM"
    data[].groupIdnumberLinks the legs of one logical service; 0 = ungroupede.g. 4
    data[].totalDistanceKmnumbercó thể nullTotal planned distance, in kilometres (derived; see GetRoute)
    data[].updatedAtstring (date-time)Timestamp of the last edit, used for the review-overdue warning
    data[].readinessobjectThe server's verdict on whether this route generates a usable trip. Never re-derive it client-side.
    data[].readiness.canRunbooleanWhether this route generates a usable tripe.g. false
    data[].readiness.blockersobject[]Every condition that fails; empty when canRun
    data[].readiness.blockers[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    data[].readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    data[].readiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    data[].readiness.blockers[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    data[].readiness.blockers[].missingStopsnumberStops still missing coordinatese.g. 3
    data[].readiness.blockers[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    data[].readiness.blockers[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    data[].readiness.blockers[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    data[].readiness.blockers[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    data[].readiness.warningsobject[]Conditions that need attention but do not block
    data[].readiness.warnings[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    data[].readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    data[].readiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    data[].readiness.warnings[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    data[].readiness.warnings[].missingStopsnumberStops still missing coordinatese.g. 3
    data[].readiness.warnings[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    data[].readiness.warnings[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    data[].readiness.warnings[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    data[].readiness.warnings[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/routes/{id}

Get a route

Returns the route detail aggregate by primary key.

Tham số

TrườngKiểuMô tả
idpathbắt buộcintegerNumeric id of the route, as returned in the id field of the list endpoint.

Phản hồi

  • 200Route found
    TrườngKiểuMô tả
    idnumberRoute ID; 0 or omitted on createe.g. 4
    codestringcó thể nullRoute codee.g. "RT-004"
    namestringRoute display namee.g. "Route A - Morning"
    campusIdnumbercó thể nullID of the school (campus) this route servese.g. 12
    campusNamestringcó thể nullName of the campus this route serves; null when unassigned or not joinede.g. "Greenfield High School"
    vehicleIdnumbercó thể nullID of the vehicle assigned to this routee.g. 7
    vehicleNamestringcó thể nullDisplay name of the assigned vehiclee.g. "B-101"
    vehiclePlatestringcó thể nullRegistration plate of the assigned vehiclee.g. "51F-238.45"
    vehicleCapacitynumbercó thể nullSeats on the assigned vehicle (vehicle.capacity); null when no vehicle or not recordede.g. 45
    vehicleReadinessobjectcó thể nullDispatch verdict of the assigned vehicle (detail read only); null when no vehicle is assigned
    vehicleReadiness.canRunbooleanWhether the vehicle may be dispatched todaye.g. true
    vehicleReadiness.blockersobject[]
    vehicleReadiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    vehicleReadiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "advisory"
    vehicleReadiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    vehicleReadiness.warningsobject[]
    vehicleReadiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    vehicleReadiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "advisory"
    vehicleReadiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    vehicleReadiness.inspectionRecordedbooleanTrue when the vehicle has a next-inspection date on recorde.g. true
    driverIdnumbercó thể nullID of the driver assigned to this route (driver.id)e.g. 3
    driverNamestringcó thể nullFull name of the assigned drivere.g. "Nguyen Thu Ha"
    backupDriverIdnumbercó thể nullStanding fallback driver (driver.id) covering this route when the regular driver is awaye.g. 9
    backupDriverNamestringcó thể nullFull name of the backup driver
    directionnumbercó thể null1 outbound (morning pickup), 2 inbound (afternoon drop-off), 3 extra runGiá trị: 123e.g. 1
    colorstringcó thể nullDisplay color (hex)e.g. "#2563eb"
    capacitynumbercó thể nullPassenger capacitye.g. 45
    estimatedTransitTimenumbercó thể nullEstimated transit time, in minutese.g. 35
    statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    deactivationReasonstringcó thể nullWhy the route was taken out of service
    deactivationEffectiveDatestringcó thể nullDate the withdrawal was intended to take effect. Recorded intent — nothing acts on it yet.e.g. "2026-08-24"
    stopsCountnumberCount of stops on this routee.g. 8
    stopsGeocodednumberStops carrying both lat and lnge.g. 8
    studentsCountnumberRiders with a standing registration on this routee.g. 38
    departureTimestringcó thể nullEarliest planned departure across the route stops, HH:mm:sse.g. "06:35:00"
    pairedRouteIdnumbercó thể nullOpposite-direction sibling — the route sharing this group_ide.g. 12
    pairedRouteCodestringcó thể nullThe paired sibling's code, for the list's link celle.g. "R-101-PM"
    groupIdnumberLinks the legs of one logical service; 0 = ungroupede.g. 4
    totalDistanceKmnumbercó thể nullTotal planned distance, in kilometres (derived; see GetRoute)
    updatedAtstring (date-time)Timestamp of the last edit, used for the review-overdue warning
    readinessobjectThe server's verdict on whether this route generates a usable trip. Never re-derive it client-side.
    readiness.canRunbooleanWhether this route generates a usable tripe.g. false
    readiness.blockersobject[]Every condition that fails; empty when canRun
    readiness.blockers[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    readiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    readiness.blockers[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    readiness.blockers[].missingStopsnumberStops still missing coordinatese.g. 3
    readiness.blockers[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    readiness.blockers[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    readiness.blockers[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    readiness.blockers[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    readiness.warningsobject[]Conditions that need attention but do not block
    readiness.warnings[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    readiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    readiness.warnings[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    readiness.warnings[].missingStopsnumberStops still missing coordinatese.g. 3
    readiness.warnings[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    readiness.warnings[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    readiness.warnings[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    readiness.warnings[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for routes
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Route does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Stops

GET/v1/stops

List stops (paginated)

Returns a paginated, searchable list of stops, optionally filtered to a geographic bounding box, scoped to the caller when using the Owner permission.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
campusIdqueryinteger
zoneIdqueryinteger
minLatquerynumbermax 90
minLngquerynumbermax 180
maxLatquerynumbermax 90
maxLngquerynumbermax 180

Phản hồi

  • 200Paginated list of stops.
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumberStop ID; only used on update.e.g. 12
    data[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campusobjectCampus reference data.
    data[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.capacitynumbercó thể null
    data[].campus.studentsCountnumber
    data[].campus.routesCountnumber
    data[].campus.stopsCountnumber
    data[].campus.arrivalTimestringcó thể null
    data[].campus.departureTimestringcó thể null
    data[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campusobjectCampus reference data.
    data[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].campus.capacitynumbercó thể null
    data[].campus.stops[].campus.studentsCountnumber
    data[].campus.stops[].campus.routesCountnumber
    data[].campus.stops[].campus.stopsCountnumber
    data[].campus.stops[].campus.arrivalTimestringcó thể null
    data[].campus.stops[].campus.departureTimestringcó thể null
    data[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].campus.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].campus.stops[].campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].campus.stops[].campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    data[].campus.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].campus.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].campus.stops[].campus.capacitynumbercó thể null
    data[].campus.stops[].campus.stops[].campus.studentsCountnumber
    data[].campus.stops[].campus.stops[].campus.routesCountnumber
    data[].campus.stops[].campus.stops[].campus.stopsCountnumber
    data[].campus.stops[].campus.stops[].campus.arrivalTimestringcó thể null
    data[].campus.stops[].campus.stops[].campus.departureTimestringcó thể null
    data[].campus.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].campus.stops[].campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].campus.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    data[].campus.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].campus.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].campus.stops[].campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].campus.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].zoneobjectZone reference data.
    data[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].campus.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].campus.stops[].zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].campus.stops[].zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    data[].campus.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].campus.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].zone.stops[].campus.capacitynumbercó thể null
    data[].campus.stops[].zone.stops[].campus.studentsCountnumber
    data[].campus.stops[].zone.stops[].campus.routesCountnumber
    data[].campus.stops[].zone.stops[].campus.stopsCountnumber
    data[].campus.stops[].zone.stops[].campus.arrivalTimestringcó thể null
    data[].campus.stops[].zone.stops[].campus.departureTimestringcó thể null
    data[].campus.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].campus.stops[].zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].campus.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    data[].campus.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].campus.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].campus.stops[].zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].campus.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zoneobjectZone reference data.
    data[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campusobjectCampus reference data.
    data[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].campus.capacitynumbercó thể null
    data[].zone.stops[].campus.studentsCountnumber
    data[].zone.stops[].campus.routesCountnumber
    data[].zone.stops[].campus.stopsCountnumber
    data[].zone.stops[].campus.arrivalTimestringcó thể null
    data[].zone.stops[].campus.departureTimestringcó thể null
    data[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].zone.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].zone.stops[].campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].zone.stops[].campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    data[].zone.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].zone.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].campus.stops[].campus.capacitynumbercó thể null
    data[].zone.stops[].campus.stops[].campus.studentsCountnumber
    data[].zone.stops[].campus.stops[].campus.routesCountnumber
    data[].zone.stops[].campus.stops[].campus.stopsCountnumber
    data[].zone.stops[].campus.stops[].campus.arrivalTimestringcó thể null
    data[].zone.stops[].campus.stops[].campus.departureTimestringcó thể null
    data[].zone.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].zone.stops[].campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].zone.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    data[].zone.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].zone.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].zone.stops[].campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].zone.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].zoneobjectZone reference data.
    data[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    data[].zone.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    data[].zone.stops[].zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    data[].zone.stops[].zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    data[].zone.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    data[].zone.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].zone.stops[].campus.capacitynumbercó thể null
    data[].zone.stops[].zone.stops[].campus.studentsCountnumber
    data[].zone.stops[].zone.stops[].campus.routesCountnumber
    data[].zone.stops[].zone.stops[].campus.stopsCountnumber
    data[].zone.stops[].zone.stops[].campus.arrivalTimestringcó thể null
    data[].zone.stops[].zone.stops[].campus.departureTimestringcó thể null
    data[].zone.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    data[].zone.stops[].zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    data[].zone.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    data[].zone.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    data[].zone.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].zone.stops[].zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].zone.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    data[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].safety.notestringcó thể nullFree-text note left by the assessor.
    data[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    data[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    data[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    data[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/stops/{id}

Get a stop by ID

Returns a single stop with its related entities.

Tham số

TrườngKiểuMô tả
idpathbắt buộcintegerNumeric id of the stop, as returned in the id field of the list endpoint.

Phản hồi

  • 200Stop found.
    TrườngKiểuMô tả
    idnumberStop ID; only used on update.e.g. 12
    namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    latnumberLatitude coordinate of the stop.e.g. 10.7626
    lngnumberLongitude coordinate of the stop.e.g. 106.6602
    codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    contactPhonestringcó thể nulle.g. "0901234567"
    statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    createByUserobjectcó thể nullSummary of the user who created this stop.
    createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campusobjectCampus reference data.
    campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.lifecycleStatusstringGiá trị: activeinactivepaused
    campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.capacitynumbercó thể null
    campus.studentsCountnumber
    campus.routesCountnumber
    campus.stopsCountnumber
    campus.arrivalTimestringcó thể null
    campus.departureTimestringcó thể null
    campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].campus.capacitynumbercó thể null
    campus.stops[].campus.studentsCountnumber
    campus.stops[].campus.routesCountnumber
    campus.stops[].campus.stopsCountnumber
    campus.stops[].campus.arrivalTimestringcó thể null
    campus.stops[].campus.departureTimestringcó thể null
    campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    campus.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].campus.stops[].campus.capacitynumbercó thể null
    campus.stops[].campus.stops[].campus.studentsCountnumber
    campus.stops[].campus.stops[].campus.routesCountnumber
    campus.stops[].campus.stops[].campus.stopsCountnumber
    campus.stops[].campus.stops[].campus.arrivalTimestringcó thể null
    campus.stops[].campus.stops[].campus.departureTimestringcó thể null
    campus.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].campus.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].campus.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    campus.stops[].campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    campus.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    campus.stops[].campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    campus.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    campus.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].campus.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].campus.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    campus.stops[].campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    campus.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].zoneobjectZone reference data.
    campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    campus.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].zone.stops[].campus.capacitynumbercó thể null
    campus.stops[].zone.stops[].campus.studentsCountnumber
    campus.stops[].zone.stops[].campus.routesCountnumber
    campus.stops[].zone.stops[].campus.stopsCountnumber
    campus.stops[].zone.stops[].campus.arrivalTimestringcó thể null
    campus.stops[].zone.stops[].campus.departureTimestringcó thể null
    campus.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].zone.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].zone.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    campus.stops[].zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    campus.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    campus.stops[].zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    campus.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    campus.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    campus.stops[].zone.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    campus.stops[].zone.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    campus.stops[].zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    campus.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    campus.createByUseranycó thể nullSummary of the user who created this campus
    campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zoneobjectZone reference data.
    zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campusobjectCampus reference data.
    zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].campus.capacitynumbercó thể null
    zone.stops[].campus.studentsCountnumber
    zone.stops[].campus.routesCountnumber
    zone.stops[].campus.stopsCountnumber
    zone.stops[].campus.arrivalTimestringcó thể null
    zone.stops[].campus.departureTimestringcó thể null
    zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].campus.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].campus.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].campus.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].campus.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].campus.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].campus.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    zone.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].campus.stops[].campus.capacitynumbercó thể null
    zone.stops[].campus.stops[].campus.studentsCountnumber
    zone.stops[].campus.stops[].campus.routesCountnumber
    zone.stops[].campus.stops[].campus.stopsCountnumber
    zone.stops[].campus.stops[].campus.arrivalTimestringcó thể null
    zone.stops[].campus.stops[].campus.departureTimestringcó thể null
    zone.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].campus.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].campus.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].campus.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    zone.stops[].campus.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    zone.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].campus.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].campus.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].campus.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].campus.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].campus.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    zone.stops[].campus.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    zone.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].campus.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    zone.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].campus.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].campus.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].campus.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].campus.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    zone.stops[].campus.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    zone.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].zone.stops[].createByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].zone.stops[].createByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].zone.stops[].createByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].updateByUser.idintegercó thể nullUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].zone.stops[].updateByUser.namestringcó thể nullComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].zone.stops[].updateByUser.avatarstringcó thể nullAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].zone.stops[].campus.addressstringcó thể nullStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].campus.phonestringcó thể nullVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.stops[].campus.lifecycleStatusstringGiá trị: activeinactivepaused
    zone.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].zone.stops[].campus.capacitynumbercó thể null
    zone.stops[].zone.stops[].campus.studentsCountnumber
    zone.stops[].zone.stops[].campus.routesCountnumber
    zone.stops[].zone.stops[].campus.stopsCountnumber
    zone.stops[].zone.stops[].campus.arrivalTimestringcó thể null
    zone.stops[].zone.stops[].campus.departureTimestringcó thể null
    zone.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].campus.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].campus.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].campus.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].campus.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].campus.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].campus.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].campus.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].zone.stops[].campus.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].campus.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].campus.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].zone.stops[].campus.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].campus.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campus.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].campus.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].campus.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].campus.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].campus.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].zone.stops[].campus.createByUseranycó thể nullSummary of the user who created this campus
    zone.stops[].zone.stops[].campus.updateByUseranycó thể nullSummary of the user who last updated this campus
    zone.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].zone.stops[].zone.descriptionstringcó thể nullFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].zone.stops[].zone.textColorstringcó thể nullHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].zone.stops[].zone.bgColorstringcó thể nullHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].zone.stops[].zone.boundaryobjectcó thể nullZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].zone.stops[].zone.centroidLatnumbercó thể nullCentroid latitude of the boundarye.g. 10.785
    zone.stops[].zone.stops[].zone.centroidLngnumbercó thể nullCentroid longitude of the boundarye.g. 106.705
    zone.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].zone.stops[].zone.codestringcó thể nullShort unique zone codee.g. "Z-001"
    zone.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].zone.stops[].campusIdnumbercó thể nullID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].zone.stops[].zoneIdnumbercó thể nullID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].zone.stops[].stopTypenumbercó thể nullLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].zone.stops[].codestringcó thể nullDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].zone.stops[].walkRadiusMnumbercó thể nullExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].zone.stops[].contactNamestringcó thể nullWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].zone.stops[].contactPhonestringcó thể nulle.g. "0901234567"
    zone.stops[].zone.stops[].zone.stops[].statusstringGiá trị: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].zone.stops[].activeInSmartRoutebooleancó thể nullWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].zone.stops[].createByUserobjectcó thể nullSummary of the user who created this stop.
    zone.stops[].zone.stops[].zone.stops[].updateByUserobjectcó thể nullSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].zone.stops[].createdAtstringcó thể nullCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].zone.stops[].updatedAtstringcó thể nullLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    zone.stops[].zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    zone.stops[].zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].safety.notestringcó thể nullFree-text note left by the assessor.
    zone.stops[].safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    zone.stops[].capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    zone.stops[].capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
    safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    safety.surveyedAtstringcó thể nullWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    safety.notestringcó thể nullFree-text note left by the assessor.
    safety.surveyedByNamestringcó thể nullDisplay name of the assessor, when the caller resolved it.
    capacityRecommendednumbercó thể nullPlanned rider count for the stop.e.g. 14
    capacityMaxnumbercó thể nullMaximum riders the stop can hold.e.g. 16
    routesCountnumberNumber of routes that serve this stop.e.g. 2
    routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    soleRouteDirectionnumbercó thể nullService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    soleRoutePickupEtastringcó thể nullScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Giá trị: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Giá trị: coordssafetyaddresszone
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Stop.Read permission.
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Stop does not exist.
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Trips

GET/v1/trips

List trips

Returns a paginated, searchable list of trips, filterable by status, route, or date.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringGiá trị: scheduledin_progresscompletedcancelled
routeIdqueryinteger
legLabelquerystring | string[]
campusIdquerystring | string[]
driverIdqueryinteger
vehicleIdqueryinteger
unassignedqueryboolean
providerRunqueryboolean
attentionquerystringGiá trị: blockedlateupcoming_unready
datequerystring
dateFromquerystring
dateToquerystring

Phản hồi

  • 200Paginated list of trips
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumberTrip ID; 0 or omitted on createe.g. 91
    data[].codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    data[].routeIdnumberID of the route this trip executese.g. 4
    data[].datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    data[].driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    data[].vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    data[].statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    data[].plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    data[].plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    data[].passengersCountnumberCount of passengers assigned to this tripe.g. 22
    data[].legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    data[].cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    data[].cancelNotestringcó thể nullNote sent with the cancellation
    data[].rescheduleReasonstringcó thể nullWhy the departure was last moved
    data[].originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    data[].revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    data[].needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    data[].reassignmentFlagsobject[]Open reassignment flags of the trip
    data[].reassignmentFlags[].idstring
    data[].reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    data[].reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    data[].reassignmentFlags[].resourceIdnumber
    data[].reassignmentFlags[].unavailabilityIdnumber
    data[].reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    data[].reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    data[].reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    data[].reassignmentFlags[].flaggedAtstringISO instant
    data[].reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    data[].reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    data[].reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    data[].availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    data[].availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    data[].availabilityWarnings[].tripIdstring
    data[].availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    data[].availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    data[].availabilityWarnings[].resourceIdnumber
    data[].availabilityWarnings[].unavailabilityIdnumber
    data[].availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    data[].availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    data[].availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
    data[].routeobjectcó thể null
    data[].route.idnumbere.g. 12
    data[].route.namestringe.g. "Tuyến 12"
    data[].route.codestringcó thể nulle.g. "R-12"
    data[].siteobjectcó thể nullThe route's campus; null when unlinked
    data[].site.idnumbere.g. 3
    data[].site.namestringe.g. "THCS Washington"
    data[].directionstringcó thể nullGiá trị: outboundinboundextra
    data[].driverobjectcó thể nullNull = unassigned, which is a block
    data[].driver.idnumbere.g. 4
    data[].driver.namestringDisplay name from the linked persone.g. "Trần Minh Khoa"
    data[].vehicleobjectcó thể nullNull = unassigned, which is a block
    data[].vehicle.idnumbere.g. 7
    data[].vehicle.numberstringcó thể nullFleet numbere.g. "B-102"
    data[].vehicle.regoNumberstringcó thể nullPlatee.g. "51F-114.09"
    data[].vehicle.capacitynumbercó thể nulle.g. 29
    data[].scheduleobject
    data[].schedule.plannedStartTimestringcó thể nulle.g. "07:10:00"
    data[].schedule.plannedEndTimestringcó thể nulle.g. "07:55:00"
    data[].schedule.actualStartTimestringcó thể nullActual departure on the tenant's wall clock, read from trip.actual_start_at (stamped when the driver starts the trip); null until it startse.g. "07:24:00"
    data[].schedule.actualEndTimestringcó thể nullWhen the trip actually finished on the tenant's wall clock, read from trip.actual_end_at (stamped when the driver completes the trip); null until it does. The drawer's log tab needs it to close the trip's story — without it, a completed trip's history stopped at departure.e.g. "07:55:00"
    data[].schedule.delayMinutesnumbercó thể nullMinutes behind plan; null when never measurede.g. 14
    data[].schedule.estimatedTransitTimenumbercó thể nullPlanned duration in minutese.g. 45
    data[].progressobject
    data[].progress.stopsCompletednumbere.g. 4
    data[].progress.stopsTotalnumbere.g. 10
    data[].progress.percentnumbercó thể nullRounded percentage; null when the trip has no stops, so the client shows "—" not 0%e.g. 40
    data[].passengersobject
    data[].passengers.assignednumberManifest size, excluding cancelled assignmentse.g. 10
    data[].passengers.boardednumberAboard right now — alighted passengers are not countede.g. 4
    data[].passengers.alightednumbere.g. 0
    data[].passengers.absentnumbere.g. 1
    data[].passengers.capacitynumbercó thể nullSeats, from the trip override or the vehiclee.g. 29
    data[].blockedbooleanServer verdict: this trip will not leave as schedulede.g. true
    data[].blockReasonsstring[]Empty when not blocked. Codes, not prose — the client owns the wordingGiá trị: no_driverno_vehicle
    data[].latebooleanTrue when the trip is in progress or scheduled (a driver can report late before departing) and at least 10 minutes behind plane.g. false
    data[].creationSourcestringGiá trị: generatedadhocimportede.g. "generated"
    data[].createdAtstringcó thể nullWhen the trip row was created. Pairs with creationSource to give the drawer log its first entry — the moment the trip came into existence, which no audit row records because generation is a write by the system rather than by a user.e.g. "2026-08-30T05:00:00.000Z"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for trips
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips

Create trip

Creates a new trip (a dated execution of a route). Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
idintegerdefault 0
codestringcó thể nullmax length 40
routeIdbắt buộcnumber
datebắt buộcstringmin length 1
driverIdnumbercó thể null
vehicleIdnumbercó thể null
legLabelstringcó thể nullmax length 60
statusstringGiá trị: scheduledin_progresscompletedcancelled
plannedStartTimestringcó thể null
plannedEndTimestringcó thể null

Phản hồi

  • 201Trip created
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write permission for trips
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 409A trip with the same route/date/schedule combination already exists

    A new trip starts scheduled; any other status is refused. params: tripId, currentStatus, attempted

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Ví dụ
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/trips/{id}

Get a trip

Returns the trip by primary key as the enriched board row: labels, stop progress, manifest counts and the readiness verdict, plus every TripDto field.

Tham số

TrườngKiểuMô tả
idpathbắt buộcintegerNumeric id of the trip, as returned in the id field of the list endpoint.

Phản hồi

  • 200Trip found
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
    routeobjectcó thể null
    route.idnumbere.g. 12
    route.namestringe.g. "Tuyến 12"
    route.codestringcó thể nulle.g. "R-12"
    siteobjectcó thể nullThe route's campus; null when unlinked
    site.idnumbere.g. 3
    site.namestringe.g. "THCS Washington"
    directionstringcó thể nullGiá trị: outboundinboundextra
    driverobjectcó thể nullNull = unassigned, which is a block
    driver.idnumbere.g. 4
    driver.namestringDisplay name from the linked persone.g. "Trần Minh Khoa"
    vehicleobjectcó thể nullNull = unassigned, which is a block
    vehicle.idnumbere.g. 7
    vehicle.numberstringcó thể nullFleet numbere.g. "B-102"
    vehicle.regoNumberstringcó thể nullPlatee.g. "51F-114.09"
    vehicle.capacitynumbercó thể nulle.g. 29
    scheduleobject
    schedule.plannedStartTimestringcó thể nulle.g. "07:10:00"
    schedule.plannedEndTimestringcó thể nulle.g. "07:55:00"
    schedule.actualStartTimestringcó thể nullActual departure on the tenant's wall clock, read from trip.actual_start_at (stamped when the driver starts the trip); null until it startse.g. "07:24:00"
    schedule.actualEndTimestringcó thể nullWhen the trip actually finished on the tenant's wall clock, read from trip.actual_end_at (stamped when the driver completes the trip); null until it does. The drawer's log tab needs it to close the trip's story — without it, a completed trip's history stopped at departure.e.g. "07:55:00"
    schedule.delayMinutesnumbercó thể nullMinutes behind plan; null when never measurede.g. 14
    schedule.estimatedTransitTimenumbercó thể nullPlanned duration in minutese.g. 45
    progressobject
    progress.stopsCompletednumbere.g. 4
    progress.stopsTotalnumbere.g. 10
    progress.percentnumbercó thể nullRounded percentage; null when the trip has no stops, so the client shows "—" not 0%e.g. 40
    passengersobject
    passengers.assignednumberManifest size, excluding cancelled assignmentse.g. 10
    passengers.boardednumberAboard right now — alighted passengers are not countede.g. 4
    passengers.alightednumbere.g. 0
    passengers.absentnumbere.g. 1
    passengers.capacitynumbercó thể nullSeats, from the trip override or the vehiclee.g. 29
    blockedbooleanServer verdict: this trip will not leave as schedulede.g. true
    blockReasonsstring[]Empty when not blocked. Codes, not prose — the client owns the wordingGiá trị: no_driverno_vehicle
    latebooleanTrue when the trip is in progress or scheduled (a driver can report late before departing) and at least 10 minutes behind plane.g. false
    creationSourcestringGiá trị: generatedadhocimportede.g. "generated"
    createdAtstringcó thể nullWhen the trip row was created. Pairs with creationSource to give the drawer log its first entry — the moment the trip came into existence, which no audit row records because generation is a write by the system rather than by a user.e.g. "2026-08-30T05:00:00.000Z"
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for trips
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

PATCH/v1/trips/{id}

Update trip

Updates an existing trip identified by the path ID. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
idintegerdefault 0
codestringcó thể nullmax length 40
routeIdbắt buộcnumber
datebắt buộcstringmin length 1
driverIdnumbercó thể null
vehicleIdnumbercó thể null
legLabelstringcó thể nullmax length 60
statusstringGiá trị: scheduledin_progresscompletedcancelled
plannedStartTimestringcó thể null
plannedEndTimestringcó thể null
expectedRevinteger

Phản hồi

  • 200Trip updated
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409expectedRev differs from the trip rev; nothing was written. params: tripId, expectedRev, actualRev, changedFields, changedBy, changedAt

    status differs from the trip status: the lifecycle moves only through assign, cancel, delete and the driver start / complete. params: tripId, currentStatus, attempted

    A linked provider runs the trip; recall its assignment before crewing it with the school

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Ví dụ
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/assign

Assign or clear a trip’s driver and vehicle

Omit a field to leave it unchanged; send explicit null to unassign. A driver who cannot drive is rejected by the fleet-wide gate; one already committed to an overlapping trip that day is a 409 unless allowDoubleBooking is set, which is recorded in the audit log. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
driverIdintegercó thể null
vehicleIdintegercó thể null
allowDoubleBookingbooleandefault false
expectedRevinteger

Phản hồi

  • 201Assignment saved
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Driver already has an overlapping trip that day

    The driver or vehicle is on an overlapping assigned charter booking (not overridable)

    Trip is cancelled or completed — assigning crew would commit them to a run that will not happen

    A linked provider runs the trip; recall its assignment before crewing it with the school

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Ví dụ
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/cancel

Cancel a trip

Cancels the trip and records why. The reason is required — it selects the guardian notification and is the trip log’s only account of the decision afterwards. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
reasonbắt buộcstringmin length 1 · max length 160
notestringmax length 500
expectedRevinteger

Phản hồi

  • 201Trip cancelled
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip is already cancelled, or has already completed

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    Ví dụ
    {
      "type": "https://stracker.io/errors/stale-trip",
      "title": "Stale trip",
      "status": 409,
      "detail": "Stale trip",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "STALE_TRIP"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/reschedule

Reschedule a trip’s departure

Sets a new departure time and shifts every not-yet-served stop by the same delta. Only a scheduled trip can move — a running or finished trip’s plan is a record of what happened. The reason is required. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
plannedStartTimebắt buộcstringpattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
reasonbắt buộcstringmin length 1 · max length 160
notestringmax length 500
expectedRevinteger

Phản hồi

  • 201Trip rescheduled
    TrườngKiểuMô tả
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringcó thể nullTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbercó thể nullID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbercó thể nullID of the assigned vehiclee.g. 7
    statusstringGiá trị: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringcó thể nullPlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringcó thể nullPlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringcó thể nullOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringcó thể nullWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringcó thể nullNote sent with the cancellation
    rescheduleReasonstringcó thể nullWhy the departure was last moved
    originalStartTimestringcó thể nullDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Giá trị: normalurgent
    reassignmentFlags[].codestringcó thể nullDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Giá trị: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringcó thể nullISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringGiá trị: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringGiá trị: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringGiá trị: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringGiá trị: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip is not scheduled — it is running, finished, or cancelled

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Ví dụ
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

PUT/v1/trips/{id}/stops

Replace a trip’s stop list

Rewrites the running order of one trip: array position becomes sequence, missing rows are removed, and a row may be marked skipped to drop it from this trip while keeping the record that it was planned. The ROUTE is never touched. Stops the vehicle has already reached cannot be moved, retimed or skipped, and must be resent unchanged. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
stopsbắt buộcobject[]min items 2 · max items 80
stops[].stopIdbắt buộcinteger
stops[].expectedArrivalTimebắt buộcstringpattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
stops[].expectedDepartureTimestringcó thể nullpattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
stops[].skippedbooleandefault false
stops[].contactNamestringcó thể nullmax length 120
stops[].contactPhonestringcó thể nullmax length 30 · pattern ^[0-9+().\s-]*$
stops[].contactNotestringcó thể nullmax length 255

Phản hồi

  • 200Updated stop list, in running order
    TrườngKiểuMô tả
    idnumbere.g. 41
    stopIdnumbere.g. 7
    stopNamestringcó thể nulle.g. "Ngã tư Lê Lợi"
    sequencenumbercó thể nullRunning order; null when never sequencede.g. 1
    expectedArrivalTimestringcó thể nulle.g. "06:42:00"
    actualArrivalTimestringcó thể nulle.g. "06:44:00"
    expectedDepartureTimestringcó thể nulle.g. "06:43:00"
    actualDepartureTimestringcó thể nulle.g. "06:45:00"
    arrivedbooleane.g. true
    riderCountnumbere.g. 3
    latnumbercó thể nulle.g. 10.776889
    lngnumbercó thể nulle.g. 106.700806
    ridersWaitingnumbere.g. 2
    ridersPickedUpnumbere.g. 1
    delayMinutesnumbercó thể nulle.g. 1
    skippedbooleane.g. false
    contactobjectcó thể nullThe stop contact for this trip: trip_stop.contact_* when set, else the stop's contact_*; null when neither has a name or a phone
    contact.namestringcó thể nulle.g. "Bác bảo vệ cổng A"
    contact.phonestringcó thể nulle.g. "0901234567"
    contact.notestringcó thể nulle.g. "Gọi trước 5 phút"
  • 400
    Ví dụ
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip has finished or been cancelled, the edit would move an already-served stop, or it would remove a stop riders were already notified about (mark it skipped instead)
    Ví dụ
    {
      "type": "https://stracker.io/errors/trip-invalid-state-transition",
      "title": "Trip invalid state transition",
      "status": 409,
      "detail": "Trip invalid state transition",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_INVALID_STATE_TRANSITION"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Vehicles

GET/v1/vehicles

List vehicles

Returns a paginated, searchable list of vehicles, optionally filtered by status, transport company (tenant), depot, or source (own / hire), scoped to the caller when using the Owner permission.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringGiá trị: in_servicemaintenanceout_of_serviceretired
transportCompanyIdqueryinteger
depotIdqueryinteger
readinessquerystringGiá trị: runnableblockeddue_soon
unassignedqueryboolean
sourcequerystringGiá trị: ownhire
hireWatchqueryboolean

Phản hồi

  • 200Paginated list of vehicles
    TrườngKiểuMô tả
    dataobject[]
    data[].numberstringInternal fleet number/codee.g. "XE-07"
    data[].namestringDisplay name for the vehiclee.g. "Bus 07"
    data[].regoNumberstringVietnamese vehicle registration plate numbere.g. "51F-123.45"
    data[].brandstringVehicle manufacturere.g. "Thaco"
    data[].modelstringVehicle modele.g. "Universe"
    data[].yearintegerModel yeare.g. 2021
    data[].vinstringVehicle identification number (VIN)e.g. "1HGCM82633A004352"
    data[].capacitynumberPassenger seating capacitye.g. 45
    data[].picturestringStored filename/UUID of the vehicle picturee.g. "a1b2c3d4-vehicle.jpg"
    data[].pictureBase64stringBase64-encoded vehicle picture upload (URL-safe)
    data[].transportCompanyIdnumberID of the transport company that owns this vehiclee.g. 3
    data[].depotIdintegerID of the depot this vehicle is based ate.g. 2
    data[].statusstringGiá trị: in_servicemaintenanceout_of_serviceretirede.g. "in_service"
    data[].vehicleTypestringGiá trị: buscoachvanminibusothere.g. "bus"
    data[].fuelTypestringGiá trị: dieselpetrolelectrichybridlpghydrogene.g. "diesel"
    data[].transmissionstringGiá trị: manualautomatice.g. "manual"
    data[].groupIdnumberLegacy vehicle grouping id (no live lookup table)e.g. 1
    data[].currentOdometerKmintegerMost recent odometer reading, in kilometrese.g. 84210
    data[].nextServiceDatestringNext scheduled service date (YYYY-MM-DD)e.g. "2026-09-01"
    data[].nextServiceKmintegerOdometer reading at which the next service is duee.g. 90000
    data[].serviceIntervalKmintegerDistance between scheduled services, in kilometrese.g. 10000
    data[].nextInspectionDatestringNext roadworthy/compliance inspection due datee.g. "2026-08-15"
    data[].registrationExpirystringRegistration (rego) expiry datee.g. "2027-01-01"
    data[].insuranceExpirystringInsurance policy expiry datee.g. "2027-01-01"
    data[].latnumberLast known latitude (read-only, GPS heartbeat)e.g. 10.762622
    data[].lngnumberLast known longitude (read-only, GPS heartbeat)e.g. 106.660172
    data[].descriptionstringFree-text notes about the vehiclee.g. "45-seat coach for long routes"
    data[].documentsCountnumberCount of documents attached to this vehiclee.g. 3
    data[].payloadKgintegercó thể nullGoods payload in kg; null = not recordede.g. 5000
    data[].palletCapacityintegercó thể nullPallet places; null = not recordede.g. 14
    data[].isRefrigeratedbooleancó thể nullRefrigerated body; null = not recordede.g. false
    data[].readinessobjectThe single server-side dispatch verdict
    data[].readiness.canRunbooleanWhether this vehicle may be dispatched todaye.g. false
    data[].readiness.blockersobject[]Every condition that fails; empty when canRun
    data[].readiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    data[].readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    data[].readiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    data[].readiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    data[].readiness.blockers[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    data[].readiness.blockers[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    data[].readiness.warningsobject[]Conditions about to fail (≤30 days / ≤1000 km; a hire contract warns from 60 days before it ends)
    data[].readiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    data[].readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    data[].readiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    data[].readiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    data[].readiness.warnings[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    data[].readiness.warnings[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    data[].readiness.maintenanceTrackedbooleanFalse when the tenant has no maintenance extension — the km cycle is then not tracked at all. Hired vehicles never get a km-cycle verdict either way: the vendor owns their maintenance.e.g. true
    data[].readiness.requiredDocumentTypesstring[]vehicle_document.doc_type codes this vehicle must hold, in the order the documents tab prints them. The tab is a CHECKLIST: a required type with no row on file is drawn as a MISSING row, which is exactly the case an operator opens the tab for. The client renders this list and never re-derives it.
    data[].inspectionobjectSafety-inspection expiry and its countdown
    data[].inspection.validUntilstringcó thể nulle.g. "2026-11-30"
    data[].inspection.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    data[].insuranceobjectInsurance expiry and its countdown
    data[].insurance.validUntilstringcó thể nulle.g. "2026-11-30"
    data[].insurance.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    data[].nextServiceobjectcó thể nullNull when the tenant has no maintenance extension — hide the column, do not render 0
    data[].nextService.dueKmintegerOdometer reading at which the next service falls duee.g. 90000
    data[].nextService.remainingKmintegerKilometres left; negative once overduee.g. 1200
    data[].nextService.cycleKmintegerConfigured distance between servicese.g. 10000
    data[].assignmentobjectcó thể nullToday's driver/route, when assigned
    data[].assignment.driverIdintegercó thể nulle.g. 12
    data[].assignment.driverNamestringcó thể nulle.g. "Nguyễn Thu Hà"
    data[].assignment.routeLabelstringcó thể nulle.g. "Tuyến 12 · Buổi sáng"
    data[].assignment.tripIdintegercó thể nullTrip the assignment came frome.g. 4821
    data[].utilizationobjectSeven day-flags, oldest first
    data[].utilization.last7Daysstring[]1 = ran at least one trip that day
    data[].costobjectRunning cost; nulls when the timeline has too little data
    data[].cost.perKmintegercó thể nullOperating cost per kilometre, tenant currencye.g. 9200
    data[].cost.fuelPer100Kmnumbercó thể nullLitres per 100 kme.g. 18.4
    data[].cost.annualTotalstringcó thể nullTotal recorded cost over the last 12 monthse.g. "61340000.00"
    data[].cost.breakdownobject[]
    data[].cost.breakdown[].categorystringEvent kind the cost was recorded undere.g. "fuel"
    data[].cost.breakdown[].amountstringRecorded amount, tenant currencye.g. "31940000.00"
    data[].cost.breakdown[].sharePctnumberShare of recorded cost, 0-100e.g. 52
    data[].cost.breakdown[].perKmintegercó thể nullThis slice per kilometre; null without witnessed distancee.g. 4780
    data[].dailyCheckobjectToday's driver walkaround, if recorded
    data[].dailyCheck.recordedAtstringcó thể nullWhen a driver completed today's check (ISO instant); null when none is recorded todaye.g. "2026-09-17T23:12:00.000Z"
    data[].sourceobjectOwn or hired, with the vendor and hire-contract terms when hired
    data[].source.kindstringGiá trị: ownhire
    data[].source.vendorobjectcó thể null
    data[].source.vendor.idnumbere.g. 3
    data[].source.vendor.namestringe.g. "Hồng Phát Transport"
    data[].source.vendor.contactNamestringcó thể nulle.g. "Trần Văn Hải"
    data[].source.vendor.phonestringcó thể nulle.g. "0903 111 222"
    data[].source.vendor.emailstringcó thể nulle.g. "dieudo@hongphat.vn"
    data[].source.contractobjectcó thể null
    data[].source.contract.idnumbere.g. 12
    data[].source.contract.codestringe.g. "HĐ-2026/14"
    data[].source.contract.statusstringGiá trị: draftpendingactiveterminated
    data[].source.contract.startsOnstringISO date (YYYY-MM-DD)e.g. "2026-01-01"
    data[].source.contract.endsOnstringcó thể nullNull while open-endede.g. "2026-12-31"
    data[].source.contract.daysToEndnumbercó thể nullWhole days until endsOn; negative once past; null when open-endede.g. 112
    data[].source.contract.statestringServer-derived validity label; the client never compares dates itselfGiá trị: activedue_soonexpirednot_active
    data[].source.contract.linkedVehiclesnumberLive vehicles attached to this contracte.g. 2
    data[].source.contract.dailyRatestringcó thể nullThe contract's own daily ratee.g. "3100000.00"
    data[].source.dailyRatestringcó thể nullEffective daily rate: the per-vehicle override, else the contract rate. Decimal string.e.g. "2400000.00"
    data[].source.rateOverriddenbooleanTrue when the vehicle carries its own rate instead of the contract rate
    data[].source.serviceScopestringcó thể nulle.g. "Đưa rước 2 chiều · T2–T6"
    data[].source.serviceScopeDerivedbooleanTrue when serviceScope was taken from the contract, not set on the vehicle
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/vehicles/{id}

Get a vehicle

Returns the vehicle detail aggregate by its primary key.

Tham số

TrườngKiểuMô tả
idpathbắt buộcintegerNumeric id of the vehicle, as returned in the id field of the list endpoint.

Phản hồi

  • 200Vehicle found
    TrườngKiểuMô tả
    numberstringInternal fleet number/codee.g. "XE-07"
    namestringDisplay name for the vehiclee.g. "Bus 07"
    regoNumberstringVietnamese vehicle registration plate numbere.g. "51F-123.45"
    brandstringVehicle manufacturere.g. "Thaco"
    modelstringVehicle modele.g. "Universe"
    yearintegerModel yeare.g. 2021
    vinstringVehicle identification number (VIN)e.g. "1HGCM82633A004352"
    capacitynumberPassenger seating capacitye.g. 45
    picturestringStored filename/UUID of the vehicle picturee.g. "a1b2c3d4-vehicle.jpg"
    pictureBase64stringBase64-encoded vehicle picture upload (URL-safe)
    transportCompanyIdnumberID of the transport company that owns this vehiclee.g. 3
    depotIdintegerID of the depot this vehicle is based ate.g. 2
    statusstringGiá trị: in_servicemaintenanceout_of_serviceretirede.g. "in_service"
    vehicleTypestringGiá trị: buscoachvanminibusothere.g. "bus"
    fuelTypestringGiá trị: dieselpetrolelectrichybridlpghydrogene.g. "diesel"
    transmissionstringGiá trị: manualautomatice.g. "manual"
    groupIdnumberLegacy vehicle grouping id (no live lookup table)e.g. 1
    currentOdometerKmintegerMost recent odometer reading, in kilometrese.g. 84210
    nextServiceDatestringNext scheduled service date (YYYY-MM-DD)e.g. "2026-09-01"
    nextServiceKmintegerOdometer reading at which the next service is duee.g. 90000
    serviceIntervalKmintegerDistance between scheduled services, in kilometrese.g. 10000
    nextInspectionDatestringNext roadworthy/compliance inspection due datee.g. "2026-08-15"
    registrationExpirystringRegistration (rego) expiry datee.g. "2027-01-01"
    insuranceExpirystringInsurance policy expiry datee.g. "2027-01-01"
    latnumberLast known latitude (read-only, GPS heartbeat)e.g. 10.762622
    lngnumberLast known longitude (read-only, GPS heartbeat)e.g. 106.660172
    descriptionstringFree-text notes about the vehiclee.g. "45-seat coach for long routes"
    documentsCountnumberCount of documents attached to this vehiclee.g. 3
    payloadKgintegercó thể nullGoods payload in kg; null = not recordede.g. 5000
    palletCapacityintegercó thể nullPallet places; null = not recordede.g. 14
    isRefrigeratedbooleancó thể nullRefrigerated body; null = not recordede.g. false
    readinessobjectThe single server-side dispatch verdict
    readiness.canRunbooleanWhether this vehicle may be dispatched todaye.g. false
    readiness.blockersobject[]Every condition that fails; empty when canRun
    readiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    readiness.blockers[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    readiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    readiness.blockers[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    readiness.blockers[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    readiness.warningsobject[]Conditions about to fail (≤30 days / ≤1000 km; a hire contract warns from 60 days before it ends)
    readiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    readiness.warnings[].severitystringGiá trị: blockingadvisorye.g. "blocking"
    readiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    readiness.warnings[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    readiness.warnings[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    readiness.maintenanceTrackedbooleanFalse when the tenant has no maintenance extension — the km cycle is then not tracked at all. Hired vehicles never get a km-cycle verdict either way: the vendor owns their maintenance.e.g. true
    readiness.requiredDocumentTypesstring[]vehicle_document.doc_type codes this vehicle must hold, in the order the documents tab prints them. The tab is a CHECKLIST: a required type with no row on file is drawn as a MISSING row, which is exactly the case an operator opens the tab for. The client renders this list and never re-derives it.
    inspectionobjectSafety-inspection expiry and its countdown
    inspection.validUntilstringcó thể nulle.g. "2026-11-30"
    inspection.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    insuranceobjectInsurance expiry and its countdown
    insurance.validUntilstringcó thể nulle.g. "2026-11-30"
    insurance.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    nextServiceobjectcó thể nullNull when the tenant has no maintenance extension — hide the column, do not render 0
    nextService.dueKmintegerOdometer reading at which the next service falls duee.g. 90000
    nextService.remainingKmintegerKilometres left; negative once overduee.g. 1200
    nextService.cycleKmintegerConfigured distance between servicese.g. 10000
    assignmentobjectcó thể nullToday's driver/route, when assigned
    assignment.driverIdintegercó thể nulle.g. 12
    assignment.driverNamestringcó thể nulle.g. "Nguyễn Thu Hà"
    assignment.routeLabelstringcó thể nulle.g. "Tuyến 12 · Buổi sáng"
    assignment.tripIdintegercó thể nullTrip the assignment came frome.g. 4821
    utilizationobjectSeven day-flags, oldest first
    utilization.last7Daysstring[]1 = ran at least one trip that day
    costobjectRunning cost; nulls when the timeline has too little data
    cost.perKmintegercó thể nullOperating cost per kilometre, tenant currencye.g. 9200
    cost.fuelPer100Kmnumbercó thể nullLitres per 100 kme.g. 18.4
    cost.annualTotalstringcó thể nullTotal recorded cost over the last 12 monthse.g. "61340000.00"
    cost.breakdownobject[]
    cost.breakdown[].categorystringEvent kind the cost was recorded undere.g. "fuel"
    cost.breakdown[].amountstringRecorded amount, tenant currencye.g. "31940000.00"
    cost.breakdown[].sharePctnumberShare of recorded cost, 0-100e.g. 52
    cost.breakdown[].perKmintegercó thể nullThis slice per kilometre; null without witnessed distancee.g. 4780
    dailyCheckobjectToday's driver walkaround, if recorded
    dailyCheck.recordedAtstringcó thể nullWhen a driver completed today's check (ISO instant); null when none is recorded todaye.g. "2026-09-17T23:12:00.000Z"
    sourceobjectOwn or hired, with the vendor and hire-contract terms when hired
    source.kindstringGiá trị: ownhire
    source.vendorobjectcó thể null
    source.vendor.idnumbere.g. 3
    source.vendor.namestringe.g. "Hồng Phát Transport"
    source.vendor.contactNamestringcó thể nulle.g. "Trần Văn Hải"
    source.vendor.phonestringcó thể nulle.g. "0903 111 222"
    source.vendor.emailstringcó thể nulle.g. "dieudo@hongphat.vn"
    source.contractobjectcó thể null
    source.contract.idnumbere.g. 12
    source.contract.codestringe.g. "HĐ-2026/14"
    source.contract.statusstringGiá trị: draftpendingactiveterminated
    source.contract.startsOnstringISO date (YYYY-MM-DD)e.g. "2026-01-01"
    source.contract.endsOnstringcó thể nullNull while open-endede.g. "2026-12-31"
    source.contract.daysToEndnumbercó thể nullWhole days until endsOn; negative once past; null when open-endede.g. 112
    source.contract.statestringServer-derived validity label; the client never compares dates itselfGiá trị: activedue_soonexpirednot_active
    source.contract.linkedVehiclesnumberLive vehicles attached to this contracte.g. 2
    source.contract.dailyRatestringcó thể nullThe contract's own daily ratee.g. "3100000.00"
    source.dailyRatestringcó thể nullEffective daily rate: the per-vehicle override, else the contract rate. Decimal string.e.g. "2400000.00"
    source.rateOverriddenbooleanTrue when the vehicle carries its own rate instead of the contract rate
    source.serviceScopestringcó thể nulle.g. "Đưa rước 2 chiều · T2–T6"
    source.serviceScopeDerivedbooleanTrue when serviceScope was taken from the contract, not set on the vehicle
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for vehicles
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Vehicle does not exist
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Webhooks

GET/v1/webhooks/event-types

List webhook event types

Every event type a subscription can select, with its labels and the OAuth scope an app needs. available is true when the caller may subscribe to it: a signed-in user needs the permission behind the event (for example ops:trips:view), an app needs the event’s read scope and never gets billing events.

Tham số

Không có tham số.

Phản hồi

  • 200The catalogue
    TrườngKiểuMô tả
    dataobject[]
    data[].typestringe.g. "trip.completed"
    data[].groupstringGiá trị: tripsinvoicespaymentssubscriptionsextensionswebhooks
    data[].labelsobject
    data[].scopestringcó thể nullOAuth scope an app needs to receive it.e.g. "trips:read"
    data[].availablebooleanTrue when the caller may subscribe to this event.
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

GET/v1/webhooks/messages

List webhook messages

The events queued for the tenant’s webhook subscriptions, newest first (an app sees only its own subscriptions’ messages). Filter by subscription, status or event type.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
statusquerystringGiá trị: pendingdeliveredfailedcancelled
eventTypequerystringmin length 1 · max length 80
subscriptionIdqueryinteger

Phản hồi

  • 200PageDto of WebhookMessageDto
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumber
    data[].subscriptionIdnumber
    data[].subscriptionNamestring
    data[].eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    data[].eventTypestringe.g. "trip.completed"
    data[].statusstringGiá trị: pendingdeliveredfailedcancelled
    data[].attemptCountnumber
    data[].nextAttemptAtstring (date-time)có thể null
    data[].lastAttemptAtstring (date-time)có thể null
    data[].lastStatusCodenumbercó thể null
    data[].lastStatusClassstringcó thể nullGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    data[].deliveredAtstring (date-time)có thể null
    data[].cancelReasonstringcó thể nullWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    data[].createdAtstring (date-time)
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

GET/v1/webhooks/messages/{id}

Get a webhook message

One message with every delivery attempt and the exact payload the receiver gets.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger

Phản hồi

  • 200The message, its attempts and its payload
    TrườngKiểuMô tả
    idnumber
    subscriptionIdnumber
    subscriptionNamestring
    eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    eventTypestringe.g. "trip.completed"
    statusstringGiá trị: pendingdeliveredfailedcancelled
    attemptCountnumber
    nextAttemptAtstring (date-time)có thể null
    lastAttemptAtstring (date-time)có thể null
    lastStatusCodenumbercó thể null
    lastStatusClassstringcó thể nullGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    deliveredAtstring (date-time)có thể null
    cancelReasonstringcó thể nullWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    createdAtstring (date-time)
    attemptsobject[]Oldest first.
    attempts[].attemptNonumber
    attempts[].triggerstringGiá trị: automanualtest
    attempts[].attemptedAtstring (date-time)
    attempts[].statusCodenumbercó thể null
    attempts[].statusClassstringGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    attempts[].latencyMsnumbercó thể null
    attempts[].responseExcerptstringcó thể nullFirst characters of a non-2xx response body.
    payloadobjectThe envelope as the receiver gets it: id, type, createdAt, apiVersion, data (and tenant.installId for partner apps).
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

POST/v1/webhooks/messages/{id}/redeliver

Redeliver a webhook message

Sends a delivered, failed or cancelled message again now. The event id is unchanged, so a receiver that dedupes on it sees a repeat. Only within the 30-day retention and while the subscription is enabled.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Phản hồi

  • 200The message, back to pending with an attempt queued
    TrườngKiểuMô tả
    idnumber
    subscriptionIdnumber
    subscriptionNamestring
    eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    eventTypestringe.g. "trip.completed"
    statusstringGiá trị: pendingdeliveredfailedcancelled
    attemptCountnumber
    nextAttemptAtstring (date-time)có thể null
    lastAttemptAtstring (date-time)có thể null
    lastStatusCodenumbercó thể null
    lastStatusClassstringcó thể nullGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    deliveredAtstring (date-time)có thể null
    cancelReasonstringcó thể nullWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    createdAtstring (date-time)
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription is disabled
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-disabled",
      "title": "Webhook subscription disabled",
      "status": 409,
      "detail": "Webhook subscription disabled",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_DISABLED"
    }
  • 410The message is past its retention window
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-message-expired",
      "title": "Webhook message expired",
      "status": 410,
      "detail": "Webhook message expired",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_MESSAGE_EXPIRED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions

List webhook subscriptions

Newest first. A signed-in user sees every subscription of the tenant, the tenant’s own and the ones apps own (owner narrows). Signing secrets are never listed.

Tham số

TrườngKiểuMô tả
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
searchKeywordquerystringmin length 1 · max length 120
statusquerystringGiá trị: activedisabled
ownerquerystringGiá trị: tenantapp

Phản hồi

  • 200PageDto of WebhookSubscriptionDto
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumber
    data[].namestring
    data[].descriptionstringcó thể null
    data[].urlstring
    data[].eventsstring[]
    data[].statusstringGiá trị: activedisabled
    data[].disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    data[].disabledAtstring (date-time)có thể null
    data[].ownerobject
    data[].owner.kindstringGiá trị: tenantapp
    data[].owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    data[].owner.namestringApp name (apps only).
    data[].owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    data[].legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    data[].secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    data[].secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    data[].consecutiveFailuresnumber
    data[].failingSincestring (date-time)có thể null
    data[].lastSuccessAtstring (date-time)có thể null
    data[].lastFailureAtstring (date-time)có thể null
    data[].createdAtstring (date-time)
    data[].createdBynumbercó thể null
    data[].updatedAtstring (date-time)có thể null
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

POST/v1/webhooks/subscriptions

Create a webhook subscription

Registers an https endpoint for the chosen event types. The signing secret is in this response only: store it now. A signed-in user creates a tenant subscription; an app (OAuth token with webhooks:manage) creates one it owns. At most 20 per tenant and 10 per app. Send an Idempotency-Key header to make retries safe: a replay within 24 hours answers with the stored subscription but without secret (it is never cached), so a caller that lost the first response rotates the secret.

Tham số

TrườngKiểuMô tả
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours, without the signing secret (it is shown once, in the first response); the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
namebắt buộcstringmin length 1 · max length 120
urlbắt buộcstringmin length 1 · max length 500
descriptionstringcó thể nullmax length 500
eventsbắt buộcstring[]Giá trị: trip.createdtrip.rescheduledtrip.cancelledtrip.startedtrip.completedinvoice.createdinvoice.paidinvoice.payment_failedinvoice.refundedpayment.completedpayment.failedsubscription.createdsubscription.upgradedsubscription.canceledextension.installedextension.upgradedmin items 1 · max items 30

Phản hồi

  • 201The subscription and its signing secret (shown once)
    TrườngKiểuMô tả
    subscriptionobject
    subscription.idnumber
    subscription.namestring
    subscription.descriptionstringcó thể null
    subscription.urlstring
    subscription.eventsstring[]
    subscription.statusstringGiá trị: activedisabled
    subscription.disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    subscription.disabledAtstring (date-time)có thể null
    subscription.ownerobject
    subscription.owner.kindstringGiá trị: tenantapp
    subscription.owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    subscription.owner.namestringApp name (apps only).
    subscription.owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    subscription.legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    subscription.secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    subscription.secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    subscription.consecutiveFailuresnumber
    subscription.failingSincestring (date-time)có thể null
    subscription.lastSuccessAtstring (date-time)có thể null
    subscription.lastFailureAtstring (date-time)có thể null
    subscription.createdAtstring (date-time)
    subscription.createdBynumbercó thể null
    subscription.updatedAtstring (date-time)có thể null
    secretstringThe signing secret. Shown once: store it now.e.g. "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • 400Invalid body

    The URL is refused (params.reason: 'scheme', 'port', 'credentials', 'fragment', 'unresolvable' or 'private_address')

    The request has no tenant scope (platform context)

    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403The caller may not subscribe to one or more events (params.events)
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-event-not-allowed",
      "title": "Webhook event not allowed",
      "status": 403,
      "detail": "Webhook event not allowed",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_EVENT_NOT_ALLOWED"
    }
  • 409The owner already holds the maximum number of subscriptions (params.limit)
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-limit-reached",
      "title": "Webhook subscription limit reached",
      "status": 409,
      "detail": "Webhook subscription limit reached",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions/{id}

Get a webhook subscription

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger

Phản hồi

  • 200The subscription
    TrườngKiểuMô tả
    idnumber
    namestring
    descriptionstringcó thể null
    urlstring
    eventsstring[]
    statusstringGiá trị: activedisabled
    disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    disabledAtstring (date-time)có thể null
    ownerobject
    owner.kindstringGiá trị: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)có thể null
    lastSuccessAtstring (date-time)có thể null
    lastFailureAtstring (date-time)có thể null
    createdAtstring (date-time)
    createdBynumbercó thể null
    updatedAtstring (date-time)có thể null
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

PATCH/v1/webhooks/subscriptions/{id}

Update a webhook subscription

Changes the name, description, URL or events, or switches the legacy signature off (legacySignature: false). A subscription an app owns cannot be edited by a signed-in user (it can be enabled, disabled or deleted). The signing secret is not changed here: use rotate-secret.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
namestringmin length 1 · max length 120
urlstringmin length 1 · max length 500
descriptionstringcó thể nullmax length 500
eventsstring[]Giá trị: trip.createdtrip.rescheduledtrip.cancelledtrip.startedtrip.completedinvoice.createdinvoice.paidinvoice.payment_failedinvoice.refundedpayment.completedpayment.failedsubscription.createdsubscription.upgradedsubscription.canceledextension.installedextension.upgradedmin items 1 · max items 30
legacySignaturebooleanGiá trị: false

Phản hồi

  • 200The updated subscription
    TrườngKiểuMô tả
    idnumber
    namestring
    descriptionstringcó thể null
    urlstring
    eventsstring[]
    statusstringGiá trị: activedisabled
    disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    disabledAtstring (date-time)có thể null
    ownerobject
    owner.kindstringGiá trị: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)có thể null
    lastSuccessAtstring (date-time)có thể null
    lastFailureAtstring (date-time)có thể null
    createdAtstring (date-time)
    createdBynumbercó thể null
    updatedAtstring (date-time)có thể null
  • 400Invalid body

    The URL is refused (params.reason: 'scheme', 'port', 'credentials', 'fragment', 'unresolvable' or 'private_address')

    The request has no tenant scope (platform context)

    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403The caller may not subscribe to one or more of the added events (params.events)
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-event-not-allowed",
      "title": "Webhook event not allowed",
      "status": 403,
      "detail": "Webhook event not allowed",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_EVENT_NOT_ALLOWED"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription belongs to an app; a signed-in user may not edit it
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

DELETE/v1/webhooks/subscriptions/{id}

Delete a webhook subscription

Soft delete: no more deliveries, pending messages are cancelled and the signing secrets are removed. The delivery log stays readable for its retention period.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Phản hồi

  • 200The id and deleted: true
    TrườngKiểuMô tả
    idnumber
    deletedbooleanGiá trị: true
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/disable

Disable a webhook subscription

Stops deliveries (reason manual) and cancels the messages still waiting to be sent. A signed-in user may disable an app’s subscription; an app only its own.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Phản hồi

  • 200The subscription
    TrườngKiểuMô tả
    idnumber
    namestring
    descriptionstringcó thể null
    urlstring
    eventsstring[]
    statusstringGiá trị: activedisabled
    disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    disabledAtstring (date-time)có thể null
    ownerobject
    owner.kindstringGiá trị: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)có thể null
    lastSuccessAtstring (date-time)có thể null
    lastFailureAtstring (date-time)có thể null
    createdAtstring (date-time)
    createdBynumbercó thể null
    updatedAtstring (date-time)có thể null
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/enable

Enable a webhook subscription

Turns a disabled subscription back on and resets its failure counters. The URL and the owner are checked again first; a subscription whose owner is no longer entitled stays disabled.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Phản hồi

  • 200The subscription
    TrườngKiểuMô tả
    idnumber
    namestring
    descriptionstringcó thể null
    urlstring
    eventsstring[]
    statusstringGiá trị: activedisabled
    disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    disabledAtstring (date-time)có thể null
    ownerobject
    owner.kindstringGiá trị: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)có thể null
    lastSuccessAtstring (date-time)có thể null
    lastFailureAtstring (date-time)có thể null
    createdAtstring (date-time)
    createdBynumbercó thể null
    updatedAtstring (date-time)có thể null
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The stored URL is refused now (params.reason)

    The owner is no longer entitled to receive events (params.reason, e.g. owner_revoked)

    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions/{id}/messages

List the messages of a webhook subscription

The events queued for the subscription and how each delivery went, newest first.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
statusquerystringGiá trị: pendingdeliveredfailedcancelled
eventTypequerystringmin length 1 · max length 80

Phản hồi

  • 200PageDto of WebhookMessageDto
    TrườngKiểuMô tả
    dataobject[]
    data[].idnumber
    data[].subscriptionIdnumber
    data[].subscriptionNamestring
    data[].eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    data[].eventTypestringe.g. "trip.completed"
    data[].statusstringGiá trị: pendingdeliveredfailedcancelled
    data[].attemptCountnumber
    data[].nextAttemptAtstring (date-time)có thể null
    data[].lastAttemptAtstring (date-time)có thể null
    data[].lastStatusCodenumbercó thể null
    data[].lastStatusClassstringcó thể nullGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    data[].deliveredAtstring (date-time)có thể null
    data[].cancelReasonstringcó thể nullWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    data[].createdAtstring (date-time)
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

POST/v1/webhooks/subscriptions/{id}/rotate-secret

Rotate a webhook signing secret

Issues a new signing secret (in this response only). For 24 hours deliveries are signed with both the new and the old secret so the receiver can switch without a gap (a replay with the same Idempotency-Key omits secret: it is never cached); revokePreviousNow drops the old one at once. A signed-in user cannot rotate the secret of an app’s subscription.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours, without the signing secret (it is shown once, in the first response); the same key with another body is a 422.

Nội dung yêu cầu application/json

TrườngKiểuMô tả
revokePreviousNowboolean

Phản hồi

  • 200The subscription and the new signing secret (shown once)
    TrườngKiểuMô tả
    subscriptionobject
    subscription.idnumber
    subscription.namestring
    subscription.descriptionstringcó thể null
    subscription.urlstring
    subscription.eventsstring[]
    subscription.statusstringGiá trị: activedisabled
    subscription.disabledReasonstringcó thể nullGiá trị: manualauto_failuresowner_revoked
    subscription.disabledAtstring (date-time)có thể null
    subscription.ownerobject
    subscription.owner.kindstringGiá trị: tenantapp
    subscription.owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    subscription.owner.namestringApp name (apps only).
    subscription.owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    subscription.legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    subscription.secretPrefixstringcó thể nullFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    subscription.secretRotationEndsAtstring (date-time)có thể nullWhile set, the previous secret still signs next to the new one.
    subscription.consecutiveFailuresnumber
    subscription.failingSincestring (date-time)có thể null
    subscription.lastSuccessAtstring (date-time)có thể null
    subscription.lastFailureAtstring (date-time)có thể null
    subscription.createdAtstring (date-time)
    subscription.createdBynumbercó thể null
    subscription.updatedAtstring (date-time)có thể null
    secretstringThe signing secret. Shown once: store it now.e.g. "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • 400Invalid body

    The request has no tenant scope (platform context)

    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription belongs to an app; a signed-in user may not rotate its secret
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/test

Send a test event

Sends one signed webhook.test event to the subscription and reports how the receiver answered. It is logged as a test delivery and never counts toward the automatic disabling of a failing subscription. At most 10 per minute.

Tham số

TrườngKiểuMô tả
idpathbắt buộcinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Phản hồi

  • 200The outcome of the test delivery
    TrườngKiểuMô tả
    deliveredboolean
    statusCodenumbercó thể null
    statusClassstringGiá trị: 2xx3xx4xx5xxtimeoutnetworkblocked
    latencyMsnumber
    attemptedAtstring (date-time)
  • 400The request has no tenant scope (platform context)
    Ví dụ
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Ví dụ
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Ví dụ
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription is disabled
    Ví dụ
    {
      "type": "https://stracker.io/errors/webhook-subscription-disabled",
      "title": "Webhook subscription disabled",
      "status": 409,
      "detail": "Webhook subscription disabled",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_DISABLED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Ví dụ
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Too many tests, or the per-client OAuth rate limit
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

OAuth token

POST/v1/oauth/token

Issue an OAuth access token (client_credentials, authorization_code, refresh_token)

  • Scope không cần (tài liệu công khai)

Form body. A confidential client authenticates with Authorization: Basic base64(client_id:client_secret); a public client sends client_id and no secret. grant_type=client_credentials takes an optional scope inside the client's scope set. grant_type=authorization_code takes code, redirect_uri (exactly as in the authorize request) and the PKCE code_verifier. grant_type=refresh_token takes refresh_token and an optional narrower scope; the refresh token is single use and rotates (reusing one revokes the grant). Answers { access_token, token_type: "Bearer", expires_in, scope, refresh_token? }. Responses are never cacheable.

Xác thực ứng dụng. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Tham số

Không có tham số.

Nội dung yêu cầu application/x-www-form-urlencoded

TrườngKiểuMô tả
grant_typebắt buộcstringmin length 1 · max length 64
scopestringmax length 1000
client_idstringmin length 1 · max length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192
codestringmin length 1 · max length 128
redirect_uristringmin length 1 · max length 500
code_verifierstringmin length 1 · max length 128
refresh_tokenstringmin length 1 · max length 128
tenantstringmin length 1 · max length 64

Phản hồi

  • 200A new access token (and a rotated refresh token when offline_access was approved)
    TrườngKiểuMô tả
    access_tokenstringES256-signed JWT (typ at+jwt)
    token_typestringe.g. "Bearer"
    expires_innumberLifetime in secondse.g. 1800
    scopestringThe scopes the token carriese.g. "trips:read drivers:read"
    refresh_tokenstringOnly for authorization_code (when offline_access was approved) and refresh_token
  • 400RFC 6749 5.2: invalid_request, invalid_grant, invalid_scope, unsupported_grant_type or unauthorized_client (for example {"error":"invalid_scope","error_description":"..."})
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_grant",
      "error_description": "The grant is invalid, expired, revoked or was issued to another client"
    }
  • 401RFC 6749 5.2: invalid_client, the same answer for an unknown client, a wrong, revoked or expired secret or client assertion, and a disabled client; carries WWW-Authenticate: Basic realm="stracker"
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, no signing key can sign right now or a revocation could not be recorded
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot issue tokens right now"
    }

OAuth revocation

POST/v1/oauth/introspect

Introspect an OAuth access token or refresh token (RFC 7662)

  • Scope không cần (tài liệu công khai)

Form body token (+ optional token_type_hint, ignored). Requires Authorization: Basic base64(client_id:client_secret) of a confidential client. Answers { "active": false } for every token that is not live for the calling client (unknown, expired, revoked, another client's) and, for a live one, active, scope, client_id, token_type, exp, iat, sub, aud, iss, jti, tid (a refresh token: active, scope, client_id, exp, sub, tid). Responses are never cacheable.

Xác thực ứng dụng. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Tham số

Không có tham số.

Nội dung yêu cầu application/x-www-form-urlencoded

TrườngKiểuMô tả
tokenbắt buộcstringmin length 1 · max length 2048
token_type_hintstringmax length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192

Phản hồi

  • 200The token state
    TrườngKiểuMô tả
    activebooleane.g. true
    scopestringe.g. "trips:read drivers:read"
    client_idstring
    token_typestringAccess tokens onlye.g. "Bearer"
    expnumberEpoch seconds
    iatnumberEpoch seconds; access tokens only
    substringUser id (string)
    audanyAccess tokens only
    issstringAccess tokens only
    jtistringAccess tokens only
    tidstringTenant id (string)
  • 400RFC 6749 5.2: invalid_request (not a form, token missing, a parameter repeated or unknown)
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_request",
      "error_description": "The request must be application/x-www-form-urlencoded"
    }
  • 401RFC 6749 5.2: invalid_client, also for a public client (introspection needs a client secret); carries WWW-Authenticate: Basic realm="stracker"
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, whether the token is live cannot be established right now; retry
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot process the request right now; retry later"
    }

POST/v1/oauth/revoke

Revoke an OAuth access token or refresh token (RFC 7009)

  • Scope không cần (tài liệu công khai)

Form body token (+ optional token_type_hint, ignored when wrong, and client_id for a public client). A confidential client authenticates with Authorization: Basic base64(client_id:client_secret). Always answers 200 with {} once the client is authenticated, whether or not the token was live or belonged to the client (a token of another client is left alone). Revoking a refresh token revokes the whole grant; revoking an access token ends that token only.

Xác thực ứng dụng. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Tham số

Không có tham số.

Nội dung yêu cầu application/x-www-form-urlencoded

TrườngKiểuMô tả
tokenbắt buộcstringmin length 1 · max length 2048
token_type_hintstringmax length 64
client_idstringmin length 1 · max length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192

Phản hồi

  • 200The token is revoked, or there was nothing for this client to revoke
  • 400RFC 6749 5.2: invalid_request (not a form, token missing, a parameter repeated or unknown)
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_request",
      "error_description": "The request must be application/x-www-form-urlencoded"
    }
  • 401RFC 6749 5.2: invalid_client, the same answer for an unknown client, a wrong, revoked or expired secret or client assertion, and a disabled client; carries WWW-Authenticate: Basic realm="stracker"
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Ví dụ
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, the revocation could not be recorded; retry
    TrườngKiểuMô tả
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Ví dụ
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot process the request right now; retry later"
    }

OAuth discovery

GET/.well-known/jwks.json

OAuth token signing keys (JWK Set)

  • Scope không cần (tài liệu công khai)

Public keys that verify OAuth access tokens: pending, active and retiring versions. Never private material. Cacheable for 10 minutes.

Tham số

Không có tham số.

Phản hồi

  • 200The JWK Set
    TrườngKiểuMô tả
    keysobject[]
    keys[].ktystringe.g. "EC"
    keys[].crvstringe.g. "P-256"
    keys[].xstring
    keys[].ystring
    keys[].kidstringe.g. "k_3f9a1c"
    keys[].algstringe.g. "ES256"
    keys[].usestringe.g. "sig"
  • 500
    Ví dụ
    {
      "type": "https://stracker.io/errors/internal-error",
      "title": "Internal server error",
      "status": 500,
      "detail": "Internal server error",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "INTERNAL_ERROR"
    }

GET/.well-known/oauth-authorization-server

OAuth authorization server metadata

  • Scope không cần (tài liệu công khai)

RFC 8414 metadata: authorization, token, revocation and introspection endpoints, JWKS URI, supported grant types (client_credentials, authorization_code, refresh_token), PKCE (S256), client authentication methods and scopes. Cacheable for 10 minutes.

Tham số

Không có tham số.

Phản hồi

  • 200The authorization server metadata
    TrườngKiểuMô tả
    issuerstringe.g. "https://api.stracker.vn"
    authorization_endpointstringe.g. "https://app.stracker.vn/oauth/authorize"
    token_endpointstringe.g. "https://api.stracker.vn/v1/oauth/token"
    jwks_uristringe.g. "https://api.stracker.vn/.well-known/jwks.json"
    grant_types_supportedstring[]
    response_types_supportedstring[]
    response_modes_supportedstring[]
    code_challenge_methods_supportedstring[]
    token_endpoint_auth_methods_supportedstring[]
    token_endpoint_auth_signing_alg_values_supportedstring[]Algorithms of a private_key_jwt assertion
    revocation_endpointstringe.g. "https://api.stracker.vn/v1/oauth/revoke"
    revocation_endpoint_auth_methods_supportedstring[]
    revocation_endpoint_auth_signing_alg_values_supportedstring[]
    introspection_endpointstringe.g. "https://api.stracker.vn/v1/oauth/introspect"
    introspection_endpoint_auth_methods_supportedstring[]
    introspection_endpoint_auth_signing_alg_values_supportedstring[]
    authorization_response_iss_parameter_supportedbooleane.g. true
    scopes_supportedstring[]
  • 500
    Ví dụ
    {
      "type": "https://stracker.io/errors/internal-error",
      "title": "Internal server error",
      "status": 500,
      "detail": "Internal server error",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "INTERNAL_ERROR"
    }