update

The basic method to work with orders is order/update.

How to start?

Create an order with callMode:“create” (if no unit is assigned to the order, the response with the order details will return s:0);
Assign a unit to the order using callMode:"assign" (the response with the order details will return s:1);
Manually move an order to history using callMode:“register”.

Creating or updating an order

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 */
    "callMode": "<text>", /* "create" or "delete" to create or delete, respectively */
    "dp": ["<uint>", ..] /* array of dependent order IDs */
  }
}

Deleting an order

Copied!

{
  "svc": "order/update",
  "params": {
    "itemId": <long>,   /* resource ID */
    "id": <long>,       /* order ID (0 in the case of creation) */
    "force": <uint>,    /* enable force deletion of problem routes (optional) */
    "callMode": "delete"
  }
}

Moving an order to the history manually

Copied!

svc=order/update&params={"itemId":<long>,	/* resource ID */
			 "id":<long>,	    			/* order ID (0 in the case of creation) */
			 "callMode":"register"}

Assigning a unit to the order

Copied!

svc=order/update&params={"itemId":<long>,	/* resource ID */
			 "id":<long>,	    			/* order ID (0 in the case of creation) */
			 "u":<long>,	    			/* unit ID */
			 "callMode":"assign"}

Rejecting an order

Copied!

svc=order/update&params={"itemId":<long>,	/* resource ID */
			 "id":<long>,	    			/* order ID (0 in the case of creation) */
			 "callMode":"reject"}

Confirming an order

Copied!

svc=order/update&params={"itemId":<long>,	/* resource ID */
			 "id":<long>,	    			/* order ID (0 in the case of creation) */
			 "callMode":"confirm"}

Flags

The flags should be passed in the f field in JSON. They are as follows:

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

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

Response

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) */ 	
	"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, see the description below */
	}	
]

callMode=callMode=‘‘update’’:

Copied!

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

callMode=‘‘delete’’:

Copied!

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

callMode=‘‘assign’’,‘‘register’’,‘‘reject’’:

Copied!

{ }	/* success */

Copied!

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

Internal flags

The internal flags should be passed in the if field in JSON. They are as follows:

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.
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.

Error codes

Error code	Description
7	Couldn’t fetch the resource or unit issue. See the reason in the response.
6	Couldn’t update the specified route. Make sure the provided route ID is correct.
4	Invalid call mode or incorrect provided data.

update

How to start?

Creating or updating an order

Deleting an order

Moving an order to the history manually

Assigning a unit to the order

Rejecting an order

Confirming an order

Flags

Response

Internal flags

Error codes

See also