Wialon for developers User guide API reference order update

update

The order/update method allows you to create, update, delete, assign, confirm, reject, and reassign orders, as well as move them to the history.

How to start

The callMode parameter defines the action that the request performs. To work with an order, send the following requests one by one:

  1. Create an order with "callMode":"create". If no unit is assigned to the order, the response contains "s":0 (inactive).
  2. Assign a unit to the order with "callMode":"assign". The order status changes to 1 (active).
  3. Move the order to the history manually with "callMode":"register".

Creating or updating an order

To create or update an order, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,    /* resource ID */
  "id": <long>,        /* order ID (0 in the case of creation) */
  "n": "<text>",       /* order name */
  "oldOrderId": <long>, /* old order ID */
  "oldOrderFiles": ["<text>"], /* array of old order files */
  "p": {               /* order parameters */
    "n": "<text>",     /* client name */
    "p": "<text>",     /* phone */
    "p2": "<text>",    /* second phone */
    "e": "<text>",     /* email */
    "a": "<text>",     /* address */
    "v": "<text>",     /* volume */
    "w": "<text>",     /* weight, kg */
    "c": <uint>,       /* cost */
    "ut": <uint>,      /* service time, s */
    "t": "<text>",     /* vehicle type */
    "d": "<text>",     /* description */
    "uic": "<text>",   /* number of the shipping document */
    "cid": "<text>",   /* custom ID */
    "cm": "<text>",    /* comment upon confirming/rejecting order */
    "aff": "<text>",   /* [warehouse] list of warehouse unit IDs ("123,456") */
    "z": "<text>",     /* [warehouse] list of warehouse geofences ("resId_geofenceId,...") */
    "ntf": <uint>,     /* notification flags: 1 - SMS to first phone; 0x2 - SMS to second phone; 0x10 - email */
    "pr": <uint>,      /* order priority */
    "tags": [<uint>],  /* order tags */
    "r": {             /* route information */
      "id": "<uint>",  /* route ID */
      "i": "<uint>",   /* number [0..] */
      "m": "<uint>",   /* mileage from previous point as planned, m */
      "t": "<uint>",   /* time from previous point as planned, s */
      "ndt": <uint>,   /* time before estimated delivery to notify customer, s */
      "vt": "<uint>"   /* visit time as planned, UNIX_TIME */
    }
  },
  "rp": "<text>",      /* order route */
  "f": <uint>,         /* order flags */
  "tf": <uint>,        /* lower bound of order completion time, UNIX-time */
  "tt": <uint>,        /* upper bound of order completion time, UNIX-time */
  "trt": <uint>,       /* acceptable schedule advancement time, s */
  "r": <uint>,         /* order point radius, m */
  "y": <double>,       /* order point latitude */
  "x": <double>,       /* order point longitude */
  "u": <long>,         /* unit ID */
  "ej": {},            /* extended JSON (optional) */
  "tz": <int>,         /* user time stamp */
  "force": <uint>,     /* allow updating an order that belongs to a route: 1 - yes, 0 - no (optional) */
  "callMode": "<text>", /* "create" or "update" to create or update, respectively */
  "dp": ["<uint>", ..] /* array of dependent order IDs */
}

For the values of the f parameter, see Flags.

If the order belongs to a route (its p.r.id value isn’t 0), you can update it only if the p.r object in the request contains the same id, i, m, t, vt, and ndt values as the order. Otherwise, the error 6 with the ORDER_IN_ROUTE reason is returned. To update such an order anyway, specify "force":1. In Wialon Local, this check is available starting from version 2404.

Deleting an order

To delete an order, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "force": <uint>,    /* allow deleting an order that belongs to a route: 1 - yes, 0 - no (optional) */
  "callMode": "delete"
}

You can’t delete an order that belongs to a route (its p.r.id value isn’t 0). In this case, the error 6 with the ORDER_IN_ROUTE reason is returned:

Copied!
{
  "error": 6,
  "reason": "ORDER_IN_ROUTE"
}

To delete such an order anyway, specify "force":1.

Moving an order to the history manually

To move an order to the history, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "callMode": "register"
}

Assigning a unit to the order

To assign a unit to an order, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "u": <long>,        /* unit ID */
  "callMode": "assign"
}

Rejecting an order

To reject an order, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "ej": {},           /* extended JSON (optional) */
  "callMode": "reject"
}

The keys of the ej object are merged with the current extended JSON of the order: the keys with the same names are replaced, new keys are added, and other keys stay unchanged.

Reassigning an order

To reject an order and mark it as reassigned, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "callMode": "reassign"
}

The order status changes in the same way as with "callMode":"reject", but the 0x2000 flag (reassigned) is set in the sf parameter instead of 0x100 (rejected).

Confirming an order

To confirm an order, use the following request:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* resource ID */
  "id": <long>,       /* order ID */
  "ds": <uint>,       /* completion status, for example, % (optional, 0 by default) */
  "ignoreConfirmInRadius": <uint>, /* confirm the order regardless of the unit location: 1 - yes, 0 - no (optional) */
  "ej": {},           /* extended JSON (optional) */
  "callMode": "confirm"
}

If the order has the 0x40 flag, it can be confirmed only if the unit assigned to the order is within the order radius. In this case, the user needs the Use unit in jobs, notifications, routes, retranslators access right to the unit. If the unit isn’t within the radius, the error 7 with the UNIT_NOT_IN_RADIUS reason is returned. To skip this check, specify "ignoreConfirmInRadius":1.

The ej object is merged with the current extended JSON of the order in the same way as when rejecting an order.

Flags

Pass the order flags in the f parameter. The following flags are available:

Value Description
0x1 The order is marked as completed if there is at least one message with zero speed within the order area.
0x2 The order is completed after the unit leaves the order area.
0x4 First warehouse.
0x8 Last warehouse.
0x10 Intermediate (reload) warehouse.
0x20 Permanent order.
0x40 The order can’t be confirmed outside the specified radius.
0x80 The order status doesn’t change after the route is completed automatically.
0x100 If the route is completed automatically, but the order isn’t executed, a new order is created on the basis of the order copy.

The flags 0x8 and 0x10 are taken into account during optimization only if the orders are in the array of warehouses.

Internal flags

The internal flags are returned in the if parameter. The following flags are available:

Value Description
0x1 The order is being delivered.
0x2 The driver has been notified about a deviation from the route.
0x4 The driver has been notified that the order hasn’t been confirmed.
0x8 The client has been notified about the previous estimated time of arrival.
0x10 The client has been notified about the estimated time of arrival.
0x20 The client has been notified what distance is left to the delivery point.
0x40 The order has been confirmed, but the delivery hasn’t started.
0x80 The driver has been notified about a deviation from the planned visit time.
0x100 The driver has been notified about a deviation from the planned unloading time.
0x200 The client has been notified about the estimated time of arrival for the route.

Response

If the request is completed successfully, the response depends on the callMode value.

For "callMode":"create":

Copied!
[
	<uint>,
	{
		"id":<uint>,			/* order ID */
		"n":"<text>",			/* order name */
		"p":{				/* order parameters */
			"n":"<text>",		/* client name */
			"p":"<text>",		/* phone */
			"p2":"<text>",		/* second phone */
			"e":"<text>",		/* email */
			"a":"<text>",		/* address */
			"v":<uint>,		/* volume */
			"w":<uint>,		/* weight, kg */
			"c":<uint>,		/* cost */
			"ut":<uint>,		/* service time, s */
			"t":"<text>",		/* vehicle type */
			"d":"<text>",		/* description */
			"uic":"<text>",		/* number of the shipping document */
			"cid":"<text>",		/* custom ID */
			"cm":"<text>",		/* comment which is left upon confirming or rejecting the order */
			"aff":"<text>",		/* [ warehouse ] list of the warehouse unit IDs ("123,456") */
			"z":"<text>",		/* [ warehouse ] list of the warehouse geofences ("resId_geofenceId,...") */
			"ntf":<uint>,		/* notification flags */
			"pr":<uint>,		/* order priority */
			"r":{			/* route information */
				"id":"<text>",	/* route ID */
				"i":"<text>",	/* number [0..] */
				"m":"<text>",	/* mileage from the previous point according to the plan, m */
				"t":"<text>",	/* time from the previous point according to the plan, s */
				"ndt":<uint>,	/* time within which the customer should be notified before the estimated delivery time, s */
				"vt":"<text>"	/* visit time according to the plan, UNIX_TIME */
			}
		},
		"rp":"<text>",			/* order route, google polyline encoding format */
		"f":<uint>,			/* order flags */
		"tf":<uint>,			/* lower bound of order completion time, UNIX-time */
		"tt":<uint>,			/* upper bound of order completion time, UNIX-time */
		"trt":<uint>,			/* acceptable time of advancing the schedule, s */
		"uid":<uint>,			/* unique ID (is used as the unique key in the order history) */
		"r":<uint>,			/* order point radius, m */
		"y":<double>,			/* order point latitude */
		"x":<double>,			/* order point longitude */
		"u":<long>,			/* unit ID */
		"s":<uint>,			/* order status: 0 - inactive (no unit assigned), 1 - active, 2 - completed on time, 3 - completed late, 4 - rejected, 5 - the unit is in the order area */
		"sf":<uint>,			/* order status flag (0x100 - rejected, 0x200 - confirmed, 0x400 - received a notification about the order (deprecated), 0x800 - the next order in the started route, 0x1000 - expired, 0x2000 - reassigned) */
		"st":<uint>,			/* last status modification time */
		"tz":<uint>,			/* user time stamp */
		"eta":<uint>,			/* ETA calculated every 180 seconds by routing (or considering the route as a straight line) if there is the next order and an activated notification about ETA/mileage(RD) */
		"rd":<double>,			/* mileage */
		"cnm":<uint>,			/* mileage counter from the unit properties */
		"nt":<uint>,			/* next_time, stands for the time when the orders received the status 'next' */
		"ds":<uint>,			/* completion status, an integer is passed in the 'confirm' parameter, for example, % */
		"dp":<uint>,			/* list of order UIDs on which the current order depends: the current order can't be completed until the listed orders are completed first */
		"stt":<uint>,			/* start_transfer_time, stands for the arrival time */
		"dtt":<uint>,			/* done_transfer_time, stands for the exit time */
		"if":<uint>			/* internal_flags */
	}
]

For the values of the if parameter, see Internal flags.

For "callMode":"update":

Copied!
[
	<uint>		/* updated order ID */
]

For "callMode":"delete":

Copied!
[
	<uint>,		/* deleted order ID */
	null
]

For "callMode":"assign", "callMode":"register", "callMode":"reject", "callMode":"reassign", and "callMode":"confirm":

Copied!
{ }	/* success */

or

Copied!
{
	"error":4	/* if failed to assign */
}

If the request fails, an error code is returned.

Error codes

Error code Description
4 Invalid call mode or incorrect provided data, or the order with the specified ID doesn’t exist (for "callMode":"confirm", with the ORDER_NOT_FOUND reason).
6 One of the following errors:
  • the order with the specified ID doesn’t exist or couldn’t be updated. Make sure the provided order ID is correct;
  • the order belongs to a route (the ORDER_IN_ROUTE reason). To delete or update such an order, specify "force":1;
  • couldn’t update the extended JSON of the order when rejecting or confirming it (the CAN_NOT_UPDATE_EJ reason).
7 Couldn’t fetch the resource or unit issue. When confirming an order with the 0x40 flag, the following reasons are possible:
  • UNIT_NOT_FOUND: the unit doesn’t exist, or the user doesn’t have the Use unit in jobs, notifications, routes, retranslators access right to it;
  • UNIT_UNKNOWN_POSITION: the unit position is unknown;
  • UNIT_NOT_IN_RADIUS: the unit isn’t within the order radius.

If you find a mistake in the text, please select it and press Ctrl+Enter.