iotoms Docs

Start a day cycle

POST
/api/v1/ops/day-cycles/start

Opens a new day cycle for the calling salesperson, recording the business date, route plan, vehicle, opening cash, start odometer, location and device checklist. Fails if that salesperson already has an open day.

How to use it

  1. Pick a route plan from List route plans and the vehicle from Get the caller's assigned vehicle or List vehicles.
  2. Send the business date, routePlanId, vehicle details, counted openingCash, startOdometerKm and GPS position, signed in as the salesperson.
  3. A new OPEN day cycle is returned; the route plan's stores become the day's planned visits and the vehicle odometer is updated.
  4. A cash drawer open is logged and a draft van-loading transfer from the default warehouse to the van is attempted; if it cannot be created, the day still starts. Fails if the caller already has an open day.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

Request Body

application/json
  1. body
businessDate*string

Business date the day covers (YYYY-MM-DD). Required.

Formatdate
routePlanId*string

ID of the route plan to run, from List route plans. Required; its stores become the day's planned visits.

Formatuuid
vehicleId*string

ID of the vehicle from List vehicles or Get the caller's assigned vehicle. Required.

Formatuuid
vehicleLabel*string

Display label of the vehicle, e.g. its registration number. Required, not blank.

vehicleType*string

Vehicle used for the day: VAN, CAR, MOTORBIKE, FOOT or OTHER. Required.

Value in"VAN""CAR""MOTORBIKE""FOOT""OTHER"
openingCash*number

Cash the salesperson starts the day with, in the merchant's currency. Required.

expectedOpeningCash?|

Cash the salesperson was expected to start with, in the merchant's currency, if known. Optional.

openingCashVarianceReason?|

Why the opening cash differs from the expected amount. Optional.

deviceChecklist?|

Optional device checklist as check name to true/false pairs. Stored as given.

lastSyncAt?|

When the device last synced with the server before starting the day (ISO 8601 timestamp). Optional.

Formatdate-time
attachmentIds?array<>|

Optional IDs of files to attach to the day start record. Stored as given.

startOdometerKm*integer

Vehicle odometer reading at day start, in kilometres. Required, positive.

Formatint32
gpsLat*number

Latitude where the day was started, in decimal degrees. Required.

Formatdouble
gpsLon*number

Longitude where the day was started, in decimal degrees. Required.

Formatdouble
gpsAccuracyMeters?|

Accuracy of the GPS fix in metres. Optional.

Formatint32
remarks?|

Optional opening notes from the salesperson.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request worked, ERROR when it did not.

message*string

Short human-readable message describing the result, for logs or display; do not parse it.

data?

The day cycle as it now stands, or null from Get the active day cycle when no day is open.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/ops/day-cycles/start' \  -H 'Content-Type: application/json' \  -d '{  "businessDate": "2019-08-24",  "routePlanId": "b7d64f28-bbfd-4033-80f5-b73a04c2781d",  "vehicleId": "c406adf4-e700-4483-ad7a-e7447a2941cb",  "vehicleLabel": "string",  "vehicleType": "VAN",  "openingCash": 0,  "startOdometerKm": 0,  "gpsLat": 0.1,  "gpsLon": 0.1}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "dayCycleId": "bbed7a30-80be-4ccf-810d-a33c370a67d1",    "businessDate": "2019-08-24",    "status": "OPEN",    "startedAt": "2019-08-24T14:15:22Z",    "closedAt": "2019-08-24T14:15:22Z",    "vehicleLabel": "string",    "vehicleId": "c406adf4-e700-4483-ad7a-e7447a2941cb",    "vehicleType": "VAN",    "openingCash": 0,    "closingCash": 0,    "startOdometerKm": 0,    "endOdometerKm": 0,    "coveragePercent": 0,    "totalStores": 0,    "visitedStores": 0  }}