Listar Entregas

En Persat, se pueden listar todas las entregas, o las que corresponden a un cliente particular. La consulta a realizar para ambos casos se define aquí.

A diferencia de lo que ocurre en otros módulos, y dada la gran cantidad de datos que se pueden obtener de esta consulta, la misma se encuentra optimizada, y la paginación no está basada en "offset" si no en "cursor" cursor-based pagination

GET https://api.persat.com.ar/v1/deliveries

Query Parameters

Name	Type	Description
limit*	number	Mismo concepto de SQL para la paginación. Max: 100. Min: 1.
uid_client	String	Identificador del cliente, en caso de querer obtener las entregas de este cliente particular
next	number	cursor para la próxima página

Headers

Name	Type	Description
Authorization*	String	Bearer API_KEY

200: OK La consulta se ejecutó con éxito

{
	"success": true,
	"paging": {
		"total": 12,
		"next": 1679422048274
	},
	"data": [{
		"_id": "WMGV40852",
		"state": "ASSIGNED",
		"created": "2023-03-21T18:07:28.274Z",
		"labels_ids": [],
		"due_date": "2023-03-21T00:00:00.000Z",
		"client": {
			"id": 46300,
			"name": "Ferretería José Hnos.",
			"uid_client": "C0203210950"
		},
		"delivery_data": {
			... // Datos de la entrega
		},
		"assignation_info": {
			... // Datos de la asignación
		}
	}, { ... } 	// Siguiente entrega
	]
}

404: Not Found El cliente no existe

{
    "success": false,
    "error": {
        "status": 404,
        "type": "NOT_FOUND",
        "userMessage": "No se encontro un cliente con este uid_client"
    }
}

400: Bad Request Error en alguno de los campos enviados. userMessage contiene informacipon adicional.

{
    "success": false,
    "error": {
        "status": 400,
        "type": "BAD_REQUEST",
        "userMessage": "'limit' es un campo obligatorio y no puede ser mayor a 100"
    }
}

Como obtener el listado completo de entregas

Para obtener el listado completo de entregas, hay que hacer una primer consulta sin el parámetro next, y luego sucesivas consultas usando el valor obtenido de next de la consulta anterior

Consulta Inicial

https://api.persat.com.ar/v1/deliveries?limit=2

En este ejemplo no filtramos por cliente, pero en caso de hacerlo aplica de la misma forma.

Resultado de la consulta

Más allá de los datos obtenidos en data, lo importante es entender como hacer la siguiente consulta.

{
	"success": true,
	"paging": {
		"total": 122,
		"next": 1679422048274
	},
	"data": [{ delivery_1, delivery_2 }]	// Array con los datos de cada entrega	
}

paging.total: Es un número que indica la cantidad de Entregas a devolver. Con lo cual para el caso del ejemplo, debería haber devuelto 122 entregas, pero nos entregó 2 (delivery_1 y delivery_2). Esto es porque el limit era 2. Entonces nos quedan por recibir otras 120 entregas.

paging.next: Es un número que debemos enviar en la próxima consulta para obtener las siguientes entregas

data: Es un array de Objetos JSON, en donde cada item es una entrega. Los campos de ese objeto son los mismos que si hicieramos la consulta en Obtener Entrega. Las entregas recibidas vienen ordenadas por fecha de creación "created" de forma descendente. Con lo cual la primer entrega recibida (delivery_1) es la que fue creada recientemente.

Siguientes consultas

Usamos el next recibido en la consulta anterior

https://api.persat.com.ar/v1/deliveries?limit=2&next=1679422048274

{
	"success": true,
	"paging": {
		"total": 120,
		"next": 1679422049876
	},
	"data": [{ delivery_3, delivery_4 }]	// Array con los datos de cada entrega	
}

Ahora recibimos dos nuevas entregas (porque el limit es 2), y obtenemos un nuevo next.

Como saber si hay mas datos para obtener

Si recibimos next en null, significa que hemos llegado al final de la lista.

{
	"success": true,
	"paging": {
		"total": 0,
		"next": null
	},
	"data": []
}

No utilizar total == 0 para definir el final de la lista. Ya que total puede tener un valor entero que sea igual al tamaño del array data[].

Por ejemplo, otro final de lista podría ser:

{ "success": true, "paging": { "total": 3, "next": null }, "data": [delivery_1, delivery_2, delivery_3] }