Wialon para desarrolladores Manual de usuario Documentación de API order update

update

El método order/update permite crear, actualizar, eliminar, asignar, confirmar, rechazar y reasignar pedidos, así como moverlos al historial.

Primeros pasos

El parámetro callMode define la acción que realiza la solicitud. Para trabajar con un pedido, envíe las siguientes solicitudes una tras otra:

  1. Cree un pedido con "callMode":"create". Si no se asigna ninguna unidad al pedido, la respuesta contiene "s":0 (inactivo).
  2. Asigne una unidad al pedido con "callMode":"assign". El estado del pedido cambia a 1 (activo).
  3. Mueva el pedido al historial manualmente con "callMode":"register".

Creación o actualización de un pedido

Para crear o actualizar un pedido, utilice la siguiente solicitud:

Copied!
svc=order/update&params={
  "itemId": <long>,    /* ID del recurso */
  "id": <long>,        /* ID del pedido (0 al crear) */
  "n": "<text>",       /* nombre del pedido */
  "oldOrderId": <long>, /* ID del pedido anterior */
  "oldOrderFiles": ["<text>"], /* matriz de archivos del pedido anterior */
  "p": {               /* parámetros del pedido */
    "n": "<text>",     /* nombre del cliente */
    "p": "<text>",     /* teléfono */
    "p2": "<text>",    /* segundo teléfono */
    "e": "<text>",     /* email */
    "a": "<text>",     /* dirección */
    "v": "<text>",     /* volumen */
    "w": "<text>",     /* peso, kg */
    "c": <uint>,       /* coste */
    "ut": <uint>,      /* tiempo de servicio, s */
    "t": "<text>",     /* tipo de vehículo */
    "d": "<text>",     /* descripción */
    "uic": "<text>",   /* número del documento de envío */
    "cid": "<text>",   /* ID personalizado */
    "cm": "<text>",    /* comentario al confirmar o rechazar el pedido */
    "aff": "<text>",   /* [almacén] lista de ID de las unidades del almacén ("123,456") */
    "z": "<text>",     /* [almacén] lista de geocercas del almacén ("resId_geofenceId,...") */
    "ntf": <uint>,     /* flags de notificación: 1 - SMS al primer teléfono; 0x2 - SMS al segundo teléfono; 0x10 - email */
    "pr": <uint>,      /* prioridad del pedido */
    "tags": [<uint>],  /* etiquetas del pedido */
    "r": {             /* información de la ruta */
      "id": "<uint>",  /* ID de la ruta */
      "i": "<uint>",   /* número [0..] */
      "m": "<uint>",   /* kilometraje desde el punto anterior según el plan, m */
      "t": "<uint>",   /* tiempo desde el punto anterior según el plan, s */
      "ndt": <uint>,   /* antelación con respecto a la hora estimada de entrega con la que se notifica al cliente, s */
      "vt": "<uint>"   /* hora de visita según el plan, UNIX_TIME */
    }
  },
  "rp": "<text>",      /* ruta del pedido */
  "f": <uint>,         /* flags del pedido */
  "tf": <uint>,        /* límite inferior del tiempo de ejecución del pedido, tiempo UNIX */
  "tt": <uint>,        /* límite superior del tiempo de ejecución del pedido, tiempo UNIX */
  "trt": <uint>,       /* tiempo permitido de adelanto con respecto al horario, s */
  "r": <uint>,         /* radio del punto del pedido, m */
  "y": <double>,       /* latitud del punto del pedido */
  "x": <double>,       /* longitud del punto del pedido */
  "u": <long>,         /* ID de la unidad */
  "ej": {},            /* JSON extendido (opcional) */
  "tz": <int>,         /* marca de tiempo del usuario */
  "force": <uint>,     /* permitir actualizar un pedido que pertenece a una ruta: 1 - sí, 0 - no (opcional) */
  "callMode": "<text>", /* "create" o "update" para crear o actualizar, respectivamente */
  "dp": ["<uint>", ..] /* matriz de ID de pedidos dependientes */
}

Para conocer los valores del parámetro f, consulte Flags.

Si el pedido pertenece a una ruta (su valor p.r.id no es 0), solo puede actualizarlo si el objeto p.r de la solicitud contiene los mismos valores id, i, m, t, vt y ndt que el pedido. De lo contrario, se devuelve el error 6 con la causa ORDER_IN_ROUTE. Para actualizar dicho pedido de todos modos, especifique "force":1. En Wialon Local, esta comprobación está disponible a partir de la versión 2404.

Eliminación de un pedido

Para eliminar un pedido, utilice la siguiente solicitud:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* ID del recurso */
  "id": <long>,       /* ID del pedido */
  "force": <uint>,    /* permitir eliminar un pedido que pertenece a una ruta: 1 - sí, 0 - no (opcional) */
  "callMode": "delete"
}

No se puede eliminar un pedido que pertenece a una ruta (su valor p.r.id no es 0). En este caso, se devuelve el error 6 con la causa ORDER_IN_ROUTE:

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

Para eliminar dicho pedido de todos modos, especifique "force":1.

Traslado manual de un pedido al historial

Para mover un pedido al historial, utilice la siguiente solicitud:

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

Asignación de una unidad al pedido

Para asignar una unidad a un pedido, utilice la siguiente solicitud:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* ID del recurso */
  "id": <long>,       /* ID del pedido */
  "u": <long>,        /* ID de la unidad */
  "callMode": "assign"
}

Rechazo de un pedido

Para rechazar un pedido, utilice la siguiente solicitud:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* ID del recurso */
  "id": <long>,       /* ID del pedido */
  "ej": {},           /* JSON extendido (opcional) */
  "callMode": "reject"
}

Las claves del objeto ej se combinan con el JSON extendido actual del pedido: las claves con el mismo nombre se reemplazan, las claves nuevas se agregan y las demás claves permanecen sin cambios.

Reasignación de un pedido

Para rechazar un pedido y marcarlo como reasignado, utilice la siguiente solicitud:

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

El estado del pedido cambia de la misma manera que con "callMode":"reject", pero en el parámetro sf se establece el flag 0x2000 (reasignado) en lugar de 0x100 (rechazado).

Confirmación de un pedido

Para confirmar un pedido, utilice la siguiente solicitud:

Copied!
svc=order/update&params={
  "itemId": <long>,   /* ID del recurso */
  "id": <long>,       /* ID del pedido */
  "ds": <uint>,       /* estado de ejecución, por ejemplo, % (opcional, 0 por defecto) */
  "ignoreConfirmInRadius": <uint>, /* confirmar el pedido independientemente de la ubicación de la unidad: 1 - sí, 0 - no (opcional) */
  "ej": {},           /* JSON extendido (opcional) */
  "callMode": "confirm"
}

Si el pedido tiene el flag 0x40, solo se puede confirmar si la unidad asignada al pedido se encuentra dentro del radio del pedido. En este caso, el usuario necesita el derecho de acceso Utilizar unidad en tareas, notificaciones, rutas, repetidores a la unidad. Si la unidad no se encuentra dentro del radio, se devuelve el error 7 con la causa UNIT_NOT_IN_RADIUS. Para omitir esta comprobación, especifique "ignoreConfirmInRadius":1.

El objeto ej se combina con el JSON extendido actual del pedido de la misma manera que al rechazar un pedido.

Flags

Los flags del pedido se pasan en el parámetro f. Están disponibles los siguientes flags:

Valor Descripción
0x1 El pedido se marca como completado si hay al menos un mensaje con velocidad cero dentro del área del pedido.
0x2 El pedido se completa cuando la unidad sale del área del pedido.
0x4 Primer almacén.
0x8 Último almacén.
0x10 Almacén intermedio (de recarga).
0x20 Pedido permanente.
0x40 El pedido no se puede confirmar fuera del radio especificado.
0x80 El estado del pedido no cambia después de que la ruta se completa automáticamente.
0x100 Si la ruta se completa automáticamente, pero el pedido no se ejecuta, se crea un pedido nuevo a partir de una copia del pedido.

Los flags 0x8 y 0x10 se tienen en cuenta durante la optimización solo si los pedidos están en la matriz de almacenes.

Flags internos

Los flags internos se devuelven en el parámetro if. Están disponibles los siguientes flags:

Valor Descripción
0x1 El pedido se está entregando.
0x2 Se notificó al conductor sobre una desviación de la ruta.
0x4 Se notificó al conductor que el pedido no se ha confirmado.
0x8 Se notificó al cliente sobre la hora estimada de llegada anterior.
0x10 Se notificó al cliente sobre la hora estimada de llegada.
0x20 Se notificó al cliente sobre la distancia que queda hasta el punto de entrega.
0x40 El pedido se confirmó, pero la entrega no ha comenzado.
0x80 Se notificó al conductor sobre una desviación de la hora de visita planificada.
0x100 Se notificó al conductor sobre una desviación de la hora de descarga planificada.
0x200 Se notificó al cliente sobre la hora estimada de llegada de la ruta.

Respuesta

Si la solicitud se completa correctamente, la respuesta depende del valor de callMode.

Para "callMode":"create":

Copied!
[
	<uint>,
	{
		"id":<uint>,			/* ID del pedido */
		"n":"<text>",			/* nombre del pedido */
		"p":{				/* parámetros del pedido */
			"n":"<text>",		/* nombre del cliente */
			"p":"<text>",		/* teléfono */
			"p2":"<text>",		/* segundo teléfono */
			"e":"<text>",		/* email */
			"a":"<text>",		/* dirección */
			"v":<uint>,		/* volumen */
			"w":<uint>,		/* peso, kg */
			"c":<uint>,		/* coste */
			"ut":<uint>,		/* tiempo de servicio, s */
			"t":"<text>",		/* tipo de vehículo */
			"d":"<text>",		/* descripción */
			"uic":"<text>",		/* número del documento de envío */
			"cid":"<text>",		/* ID personalizado */
			"cm":"<text>",		/* comentario que se deja al confirmar o rechazar el pedido */
			"aff":"<text>",		/* [ almacén ] lista de ID de las unidades del almacén ("123,456") */
			"z":"<text>",		/* [ almacén ] lista de geocercas del almacén ("resId_geofenceId,...") */
			"ntf":<uint>,		/* flags de notificación */
			"pr":<uint>,		/* prioridad del pedido */
			"r":{			/* información de la ruta */
				"id":"<text>",	/* ID de la ruta */
				"i":"<text>",	/* número [0..] */
				"m":"<text>",	/* kilometraje desde el punto anterior según el plan, m */
				"t":"<text>",	/* tiempo desde el punto anterior según el plan, s */
				"ndt":<uint>,	/* antelación con respecto a la hora estimada de entrega con la que se debe notificar al cliente, s */
				"vt":"<text>"	/* hora de visita según el plan, UNIX_TIME */
			}
		},
		"rp":"<text>",			/* ruta del pedido, formato google polyline encoding */
		"f":<uint>,			/* flags del pedido */
		"tf":<uint>,			/* límite inferior del tiempo de ejecución del pedido, tiempo UNIX */
		"tt":<uint>,			/* límite superior del tiempo de ejecución del pedido, tiempo UNIX */
		"trt":<uint>,			/* tiempo permitido de adelanto con respecto al horario, s */
		"uid":<uint>,			/* ID único (se usa como clave única en el historial de pedidos) */
		"r":<uint>,			/* radio del punto del pedido, m */
		"y":<double>,			/* latitud del punto del pedido */
		"x":<double>,			/* longitud del punto del pedido */
		"u":<long>,			/* ID de la unidad */
		"s":<uint>,			/* estado del pedido: 0 - inactivo (sin unidad asignada), 1 - activo, 2 - completado a tiempo, 3 - completado con retraso, 4 - rechazado, 5 - la unidad está en el área del pedido */
		"sf":<uint>,			/* flag de estado del pedido (0x100 - rechazado, 0x200 - confirmado, 0x400 - se recibió una notificación sobre el pedido (obsoleto), 0x800 - siguiente pedido de la ruta iniciada, 0x1000 - vencido, 0x2000 - reasignado) */
		"st":<uint>,			/* hora de la última modificación del estado */
		"tz":<uint>,			/* marca de tiempo del usuario */
		"eta":<uint>,			/* ETA calculada cada 180 segundos mediante enrutamiento (o considerando la ruta como una línea recta) si hay un pedido siguiente y está activada la notificación sobre ETA/kilometraje (RD) */
		"rd":<double>,			/* kilometraje */
		"cnm":<uint>,			/* contador de kilometraje de las propiedades de la unidad */
		"nt":<uint>,			/* next_time, hora en que los pedidos recibieron el estado 'next' */
		"ds":<uint>,			/* estado de ejecución; se pasa un número entero en el parámetro 'confirm', por ejemplo, % */
		"dp":<uint>,			/* lista de UID de los pedidos de los que depende el pedido actual: el pedido actual no se puede completar hasta que se completen los pedidos enumerados */
		"stt":<uint>,			/* start_transfer_time, hora de llegada */
		"dtt":<uint>,			/* done_transfer_time, hora de salida */
		"if":<uint>			/* internal_flags */
	}
]

Para conocer los valores del parámetro if, consulte Flags internos.

Para "callMode":"update":

Copied!
[
	<uint>		/* ID del pedido actualizado */
]

Para "callMode":"delete":

Copied!
[
	<uint>,		/* ID del pedido eliminado */
	null
]

Para "callMode":"assign", "callMode":"register", "callMode":"reject", "callMode":"reassign" y "callMode":"confirm":

Copied!
{ }	/* éxito */

o

Copied!
{
	"error":4	/* si no se pudo asignar */
}

Si la solicitud falla, se devuelve un código de error.

Códigos de error

Código de error Descripción
4 Modo de llamada no válido o datos proporcionados incorrectos, o el pedido con el ID especificado no existe (para "callMode":"confirm", con la causa ORDER_NOT_FOUND).
6 Uno de los siguientes errores:
  • el pedido con el ID especificado no existe o no se pudo actualizar. Asegúrese de que el ID del pedido proporcionado sea correcto;
  • el pedido pertenece a una ruta (la causa ORDER_IN_ROUTE). Para eliminar o actualizar dicho pedido, especifique "force":1;
  • no se pudo actualizar el JSON extendido del pedido al rechazarlo o confirmarlo (la causa CAN_NOT_UPDATE_EJ).
7 No se pudo obtener el recurso o la unidad. Al confirmar un pedido con el flag 0x40, son posibles las siguientes causas:
  • UNIT_NOT_FOUND: la unidad no existe o el usuario no tiene el derecho de acceso Utilizar unidad en tareas, notificaciones, rutas, repetidores a ella;
  • UNIT_UNKNOWN_POSITION: la ubicación de la unidad es desconocida;
  • UNIT_NOT_IN_RADIUS: la unidad no se encuentra dentro del radio del pedido.

Si nota un error en el texto, por favor resáltelo y presione Ctrl+Intro.