Creating a despatch

A despatch records one use of a resource on a work order: the machine or vehicle, how its fuel consumption is measured, the fuel, and the distance or operating time. Next uses it to compute fuel consumption and CO2, and to build delivery notes.

In the Next client, most despatch fields are not chosen freely. When a user picks a resource, the client copies them from the resource and its fuel configuration. The API does not do this for you, and the server does not validate that the values belong together. A despatch created with mismatching values is accepted, but its consumption and CO2 come out empty, and the client will rewrite or refuse to save it the next time a user edits it.

This page describes what to send so the despatch behaves exactly as one created in the client.

Where each value comes from

The two unit ids are fixed system values. The client shows them read-only and always stores them.

A resource has at most one fuel row per fuel type. Each row has a measureitemunitid that is either the kilometre unit (-2) or the hour unit (-1), and a consumption per unit. That row decides which quantity the despatch must carry, see Fuel consumption.

Step by step

1. Read the resource with GET /resource/{resource_id}. Copy resourceno, transportationtypeid and measuringmethodid into the despatch.
   If the resource has no transportation type or measuring method, pick one from GET /type/transportationtype/ or GET /type/measuringmethodtype/. Both are required on the despatch.
2. Read the resource's fuel rows with GET /resource/fuel/{resource_id}. Choose one row. Use its fueltypeid as the despatch fueltypeid and its consumptionunitid as fuelconsumptionitemunitid.
   Do not use a fuel type that is not in this list. The client only offers the resource's own fuel types, and the consumption lookup finds nothing for any other.
3. Always send both unit ids. Set distanceitemunitid to -2 and operatingtimeitemunitid to -1. They are empty when omitted, and an empty unit prevents the fuel row match.
4. Send the quantity the fuel row needs. If the chosen fuel row is measured in kilometres, send distance. If it is measured in hours, send operatingtime. The value must be greater than zero.
5. Keep the dates consistent. startdate must not be after stopdate. When stopdate is set, the client sets performeddate to the date part of stopdate, so send the same.
6. Create order rows yourself if you need them. When the client creates a despatch, it also adds one work order row from the resource's default article, with the despatch id, resource id, performed date and performed user. The API does nothing equivalent. Create the rows with POST /workorderrow/ and set workorderdespatchid on each.

Fuel consumption

The measuring method decides how fuel consumption is handled.

StandardEstimate. The server computes fuelconsumption when the despatch is created:

• fuel row measured in kilometres: fuelconsumption = distance × consumption
• fuel row measured in hours: fuelconsumption = operatingtime × consumption

The matching quantity is mandatory. The request fails with Distance should be provided or OperatingTime should be provided when it is missing. If the fuel type or the unit ids do not match a fuel row, nothing is computed and fuelconsumption stays empty.

ManualMeasurement and AutomaticMeasurement. The consumption is a measured value. The despatch POST and PUT bodies currently have no fuelconsumption field, and unknown fields are dropped. A despatch with one of these measuring methods is therefore created with empty fuelconsumption. See Limitations.

CO2 is computed from fuelconsumption and the fuel type's contained energy and conversion rate. It is returned as co2consumption and copied to the delivery note. With empty fuelconsumption it is empty, and the delivery note reports zero.

Updating a despatch

PUT applies only the fields you send. The server does not recompute fuelconsumption on update and does not cascade from a changed resource or fuel type. When you change resourceid or fueltypeid, re-derive and re-send every field in the table above, and send the matching distance or operatingtime again.

A despatch that belongs to a locked delivery note cannot be updated or deleted.

What the client does with an inconsistent despatch

Opening the despatch in the client changes nothing by itself. As soon as a user edits any field, the client applies its own rules:

• With measuring method StandardEstimate, fuelconsumption is recomputed from distance or operatingtime and the matching fuel row. If no fuel row matches, the result is empty and the client refuses to save until the user picks another resource or fuel type.
• Changing the resource overwrites resourceno, transportationtypeid and measuringmethodid, selects the resource's first fuel row for fueltypeid and fuelconsumptionitemunitid, resets both unit ids to the fixed values, and clears fuelconsumption.
• Changing the fuel type resets fuelconsumptionitemunitid and both unit ids, and clears fuelconsumption.
• Setting stopdate overwrites performeddate.

Values you sent that break these rules are lost at that point.

Example

Resource 10 has resourceno "1", transportation type 1 and measuring method 2 (StandardEstimate). Its fuel row for fuel type -8 has measureitemunitid -2 (kilometres), consumption 0.35 and consumptionunitid 12.

POST /workorder/4711/despatch/

{
  "resourceid": 10,
  "resourceno": "1",
  "transportationtypeid": 1,
  "measuringmethodid": 2,
  "fueltypeid": -8,
  "fuelconsumptionitemunitid": 12,
  "distanceitemunitid": -2,
  "operatingtimeitemunitid": -1,
  "distance": 120.5,
  "startdate": "2025-06-22T08:00:00",
  "stopdate": "2025-06-22T17:00:00",
  "performeddate": "2025-06-22",
  "performeduserid": 1,
  "description": "Transport from depot to worksite"
}

The response contains fuelconsumption 42.175 and a co2consumption derived from it.

Limitations

• fuelconsumption cannot be set through the API. Despatches with measuring method ManualMeasurement or AutomaticMeasurement are created with empty consumption and CO2, and a client user must enter the value before the despatch can be saved again.
• The server does not validate that fueltypeid belongs to the resource, that the unit ids are the fixed values, or that resourceno matches the resource. Following this page is what keeps the data consistent.