Obtener entrega

Las entregas en Persat tienen un identificador id unico, mediante el cual podemos consultar su contenido o estado.

Para obtener una entrega que ya se encuentra cargada en Persat se debe realizar un GET como el que se muestra a continuación

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

Path Parameters

Name	Type	Description
id*	String	Identificador de la entrega

Headers

Name	Type	Description
Authorization*	String	Bearer API_KEY

200: OK La consulta se ejecutó con éxito

404: Not Found No se encontro la entrega requerida

{
    "success": false,
    "error": {
        "status": 404,
        "type": "NOT_FOUND",
        "userMessage": "No se encontro entrega con ese número"
    }
}

Análisis de la respuesta

Debido a que el estado de la entrega influye en los campos a ser devueltos. Se explica en esta sección cada uno de los campos, pero luego en las subsecciones siguientes se muestran las respuestas dependiendo el estado de la entrega.

En este ejemplo se preesenta la respuesta de una entrega que ya fue finalizada por el chofer, y que además se encuentra asignada a un cliente. Esto es porque en Persat la entrega puede ser "suelta" o pertenecer a un cliente particular.

{
    "success": true,
    "data": {
        "_id": "ASDKSAL23",
        "state": "FINISHED",
        "created": "2022-05-12T13:26:19.292Z",
        "source_tag":"Jose 19/07/2021 17:19:24",
        "labels_ids": [
            133
        ],
        "due_date": "2022-05-14T00:00:00.000Z",
        "client": {
            "id": 12816,
            "name": "Zapatería Don José",
            "uid_client": "CL565LK"
        },
        "delivery_data": {
            "schema_id": 5,
            "service_time": 150,
            "wt": [480, 1080],
            "capacity": 278,
            "contact": {
                "name": "Jose Perez",
                "phone": "5555-5555",
                "email": "[e-mail]"
            },
            "position": {
                "address": {
                    "clean": "Av. Independencia 1987",
                    "extra_info": "Piso 1A"
                },
                "location": [
                    -58.49390429,
                    -34.677806633
                ]
            },
            "instructions": {
                "FWtQn2m9v": "Entregar zapatos color Rojo",
                "FWJt5MLSn": 5687.00,
                "FWBsxBUIQ": "Cobrar"
            },
            "results": {
                "formvalues": {
                    "FW40IlFW1": "El cliente quedo conforme",
                    "FWy1RBJ2j": "Cobrado",
                    "FWGa6f4zq": 5687.00,
                    "FW_FINAL_STATE": "DELIVERED"
                },
                "log": [
                    {
                        "user_name": "[e-mail]",
                        "user_real_name": "Pedro Lopez",
                        "user_id": 37,
                        "date": "2022-05-12T14:10:24.000Z"
                    },
                    {
                        "user_name": "[e-mail]",
                        "user_real_name": "Pedro Lopez",
                        "user_id": 37,
                        "date": "2022-05-13T14:43:37.867Z"
                    }
                ]
            },
            "rework": {
                "retry": 1,
                "prev": "ASDKSAL22",
                "next": "ASDKSAL22-R3"
            }
        },
        "assignation_info": {
            "date": "2022-05-12T00:00:00.000Z",
            "device_id": 18,
            "device_name": "Vechiculo AB 123 LK",
            "route_id": 1652362114021
        }
    }
}

_id: String identificando inequivocamente a la entrega.

state: Estado de la entrega. Los estados posibles son: "PENDING", "ROUTING", "ASSIGNED", "NOT_FINISHED", "FINISHED_WITH_DEVIATION", "FINISHED". En las siguientes secciones se muestran ejemplos de entregas en estos estados.

created: Fecha de creación de la entrega. No es la fecha de asignación, si no la fecha en la que se inserto dentro de Persat. Es una fecha en formato isoDate

created: Es una fecha en UTC

source_tag: [Opcional]. Tag que se coloca en las entregas que fueron generadas por el importador masivo de Persat. Tienen el nombre del usuario y la fecha de importacion. La fecha se encuentra en horario local, y con un formato como el que se ve en el ejemplo.

        "source_tag":"Jose 19/07/2021 17:19:24",

labels_ids: Array de numbers, identificando etiquetas previamente creadas en Persat.

Es una "referencia débil" a las etiquetas, es decir que puede que no existan a la hora de hacer la consulta, debido a que el usuario administrador de Persat las sacó del sistema, o las modificó por otras.

due_date: Fecha en la que se vence la entrega. No posee horas, minutos, segundos ni milisegundos. Es a modo informativo únicamente.

Fecha en horario local. Esto se debe a un requerimiento de mantener la compatibilidad con una versión anterior de Persat. Entonces para el caso del ejemplo, y sin importar si soy un cliente de Argentina, Ecuardor o Mexico, la fecha mostrada representa el día 14 de Mayo de 2022

"created": "2022-05-14T00:00:00.000Z",

client: [opcional] Datos del cliente en donde hay que realilzar la entrega. No es necesario que una entrega este asociada a un cliente previamente cargado en el sistema, es por eso que este campo puede no esta definido.

• id: Id interno. NO UTILIZAR. Preparar el sistema para incluso dejar de recibir este dato a futuro.

• name: Nombre del cliente

• uid_client: Identificador del cliente. Es el que se utiliza como identificador de este cliente. Es un valor único.

delivery_data: JSON Object. Datos de la entrega

delivery_data.schema_id: Identificador del esquema (plantilla) de la entrega. Por ejemplo: Puedo tener una entrega denominada "Entrega Inmediata" en donde requiero determinados datos y etiquetas, y otra llamada "Entrega Estandar" que es una entrega que requiere menos información. Para saber de que tipo de entrega estoy hablando es que se usa el schema_id. Tener en cuenta que cada entrega puede tener varias versiones dentro de Persat, con lo cual cada una de estas versiones es un schema_id diferente.

Para poder conocer los schema_id de los Tipos de Entrega disponibles Indetificación de Entregas y widgets

También puede obtener el esquema con el endpoint Obtener estructura/esquema de un Tipo de Entrega

delivery_data.service_time: Valor en minutos de la duración estimada para realizar la entrega. Entregas simples pueden tomar 5 minutos, mientras que si estoy haciendo una entrega de materiales (corralon), la descarga puede tomar horas.

delivery_data.wt: Horario de visita (window time). Array de dos items, [start, end]. start y end son minutos transcurridos desde las 00:00 hs. Es decir que si la entrega la tengo que realizar desde las 08:00 hasta las 17:30. Enontces wt = [480, 1050].

En caso de no estar definido, ser null o estar vacio [], significa que no hay horario de visita definido, por lo que se puede entregar en cualquier horario

delivery_data.capacity: Dimensión de capacidad. Puede ser peso, volumen, cantidad. Es a modo informativo de la dimension de la carga.

Por el momento, este valor no es utilizado en el algoritmo de ruteo, pero si se puede usar para visualizar si un camión quedó demasiado cargado comparado con otro.

delivery_data.contact: JSON Object, con los fields

• name: String nombre del contacto a recibir la entrega

• phone: String Teléfono de contacto

• email: String e del mismo tipo de OT.

  Para poder conocer los schema_id de las OTs disponibles Indetificación de OTs y widgets

  También puede obtener el esquema con el endpoint Obtener estructura/esquema de un Tipo de OT

  wo_data.wo_rmail

delivery_data.position: JSON Object, con los fields

delivery_data.position.address: JSON Object, con los fields

• clean: String con la dirección en formato "limpio", indicando nombre de la calle y altura.

• extra_info: String, datos extra de la dirección, como el Piso, el color de puerta, o cualquier dato que pueda ser util para el chofer a la hora de encontrar el punto de entrega.

delivery_data.position.location: [opcional]. Array con [longitud, latitud]. En caso de no estar definido, significa que la etrega no esta geo-referenciada en Persat, y por lo tanto hasta que no se ubique el punto en el mapa, no podrá ser asignada para la entrega.

delivery_data.instructions: Datos de cada uno de los componentes (widgets) del formulario de inficaciones. Cada entrega esta conformada por un formulario de indicaciones y otro de resultados. El de inficaciones, como su palabra lo dice, es el que va a leer el chofer para saber que es lo que tiene que entregar. Cada formulario esta conformado por widgets de distinto tipo, como por ejemplo: Campo Texto, Campo Lista, Campo número, etc.

"instructions": {
    "FWtQn2m9v": "Entregar zapatos color Rojo",
    "FWJt5MLSn": 5687.00,
    "FWBsxBUIQ": "Cobrar"
},

Para el caso del ejemplo, se puede visualizar que el formulario cuenta con 3 widgets. A priori no se pude deducir exactamente que tipo de widget es cada uno, sin embargo podemos inferir que el widget con id FWJt5MLSn es un CAMPO NUMERO.

Dependiendo del tipo de widget, es el tipo de valor. Un widget de tipo Texto, contendrá un string, mientras que uno de tipo Numero contendra un number. Ver todos los widgets disponibles en la siguiente sección: Tipos de Widgets

delivery_data.results: [opcional] JSON Object con los fields "formvalues" y "log" que indica los resultados de la entrega. Dependiendo el estado de la misma este campo puede no estar definido. Una entrega que no ha sido asignada, de ninguna forma pudo haber sido completada por el chofer

delivery_data.results.formvalues: Datos de cada uno de los componentes (widgets) del formulario de resultado. Este formulario es completado por el chofer desde su teléfono, indicando el estado final de la entrega y cualquier otro dato que le sea requerido.

Hay un widget que siempre tiene el mismo identificador "FW_FINAL_STATE", que puede tener los siguientes 3 valores

• "DELIVERED"

• "PARTIAL_DELIVERED"

• "NOT_DELIVERED"

Cada uno estos valores se corresponde con el state final de la entrega. Por eso para el caso del ejemplo, como "FW_FINAL_STATE" = "DELIVERED", entonces la entrega tiene como "state": "FINISHED"

    "formvalues": {
        "FW40IlFW1": "El cliente quedo conforme",
        "FWy1RBJ2j": "Cobrado",
        "FWGa6f4zq": 5687.00,
        "FW_FINAL_STATE": "DELIVERED"
    },

Dependiendo del tipo de widget, es el tipo de valor. Un widget de tipo Texto, contendrá un string, mientras que uno de tipo Numero contendra un number. Ver todos los widgets disponibles en la siguiente sección: Tipos de Widgets

delivery_data.results.log: Array de JSON Objects indicando fecha y horario en que el chofer indico los resultados de la entrega.

    "log": [
        {
            "user_name": "[e-mail]",
            "user_real_name": "Pedro Lopez",
            "user_id": 37,
            "date": "2022-05-12T14:10:24.000Z"
        },
        {
            "user_name": "[e-mail]",
            "user_real_name": "Pedro Lopez",
            "user_id": 37,
            "date": "2022-05-13T14:43:37.867Z"
        }
    ]

• user_name: Nombre de usuario en Persat. Siempre es un email

• user_real_name: Nombre de la persona

• user_id: Identificador del usuario. Para poder identificar a los usuarios, dirijite a la sección Obtener Formulario, en donde se explica el campo "created_by_user_id"

• date: Fecha y hora de modificacion en UTC

delivery_data.rework: Es un campo opcional. En caso de estar presente, indica que la entrega tiene, o es un retrabajo. Si contiene el parametro next, entonces indica que la entrega está siendo retrabajada y dicho parámetro es el id de la entrega. Si contiene le parametro prev, significa que es un retrabajo de una entrega anterior. El parámetro retry indica el número de reintento. Para el caso del ejemplo retry: 1 significa que es la segunda vez que se visita al cliente (primer RE-intento). La entrega original no contiene el parámetro retry, aunque si podría tener el next en caso es estar siendo retrabajada.

• retry: Number. Nro. de reintento. Si indica 1, significa que es el primer Re-intento.

• prev: String, Id de la entrega anterior, a partir de la cual surge esta.

• next: String, id de la siguiente entrega, en donde hariamos el retrabajo

"rework": {
    "retry": 1,
    "prev": "ASDKSAL22",
    "next": "ASDKSAL22-R3"
}

assignation_info: [opcional] JSON Object con los siguientes campos. La entrega en estado PENDING o ROUTING no poseen información respecto a la asignación, es por eso que el campo puede no estar definido.

• date: Fecha del día de la ruta. No tiene horas, minutos, segundos ni milisegundos. No importa en que país me encuentre, se se lee como hora local. Para el caso del ejemplo, representa el 12 de Mayo de 2022.

• device_id: Identificador del vehciulo o celular al que se asigno la entrega. Se pueden obtener mas datos del dispositivo con el siguiente endpoint Obtener dispositivo

• device_name: Nombre de identificación del movil.

• route_id: NO UTLIZAR. Es un identificador interno de la ruta

"assignation_info": {
    "date": "2022-05-12T00:00:00.000Z",
    "device_id": 18,
    "device_name": "Vechiculo AB 123 LK",
    "route_id": 1652362114021
}