Obtener un cliente

Obtener un cliente particular por medio de su uid_client ("nro de cliente"), se puede realizar por medio de la siguiente consulta

GET https://api.persat.com.ar/v1/clients/uid_client

Headers

Name	Type	Description
Authorization*	string	Bearer API_KEY

200 Se obtuvo le cliente con éxito.

{
    "success": true,
    "data": {
        "uid_client": "CL-0044"
        "company_name": "Persat",
        "company_description": "Logistica GPS",
        "type_id": 2,
	"group_id": 3,
        "latitude": -34.54646,
        "longitude": -58.4324324,
        "service_time": 20,          // Opcional
        "wt": [480, 780],            // Opcional
        "street": "Av. Rivadavia",
        "street_nbr": "1000",
        "neighborhood": "Devoto",
        "city": "CABA",
        "country": "Argentina",
        "last_updated": "2021-09-09T14:30:05.000Z",
        "custom_fields": {
            "1": {
                "name": "Notas",
                "value": ""
            },
            "2": {
                "name": "Telefono",
                "value": "4504-5300"
            },
            "8": {
                "name": "Entre calle 1",
                "value": ""
            },
            "9": {
                "name": "Entre calle 2",
                "value": ""
            },
            "10": {
                "name": "Mail de notificación",
                "value": "[e-mail]"
            },
            "13": {
                "name": "Nombre del Contacto",
                "value": "Jose Perez"
            }
        }        
    }

404 El cliente no existe

{
    "success": false,
    "error": {
        "status": 404,
        "type": "NOT_FOUND",
        "userMessage": "No existe un cliente con este número."
    }
}

A continuación un ejemplo con curl, en donde quiero obtener los datos del cliente "CL-0044"

curl --location --request GET "https://api.persat.com.ar/v1/clients/CL-0044" \
  --header "Authorization: Bearer YOUR_API_KEY"

Analizando la Respuesta

En caso que no haya ningun error, obtenemos para nuestro caso de ejemplo algo asi:

{
    "success": true,
    "data": {
        "uid_client": "CL-0044"
        "company_name": "Persat",
        "company_description": "Logistica GPS",
        "type_id": 2,
	"group_id": 3,
        "latitude": -34.54646,
        "longitude": -58.4324324,
        "service_time": 20,    // Puede ser undefined
        "wt": [480, 780],      // Puede ser undefined
        "street": "Av. Rivadavia",
        "street_nbr": "1000",
        "neighborhood": "Devoto",
        "city": "CABA",
        "country": "Argentina",
        "last_updated": "2021-09-09T14:30:05.000Z",
        "custom_fields": {
            "1": {
                "name": "Notas",
                "value": ""
            },
            "2": {
                "name": "Telefono",
                "value": "4504-5300"
            },
            "8": {
                "name": "Entre calle 1",
                "value": ""
            },
            "9": {
                "name": "Entre calle 2",
                "value": ""
            },
            "10": {
                "name": "Mail de notificación",
                "value": "[e-mail]"
            },
            "13": {
                "name": "Nombre del Contacto",
                "value": "Jose Perez"
            }
        }        
    }

uid_client: Es el identificador del cliente en el que se encuentra el objeto.

company_name: Nombre del cliente, razón social o nombre de fantasía. Debe ser un valor único. No puede haber dos clientes con la misma "Razon Social".

company_description: Descripción del cliente. Es un campo útil dentro de Persat para hacer búsquedas. Se suele usar para indicar por ejemplo el rubro de la empresa, pero es un campo libre y puede incluso estar vacío.

type_id: Es un número identificando el tipo de cliente. Los tipos de cliente en Persat, son una clasificación configurable por el usuario, y es muy útil para realizar filtrados o para visualizar sobre el mapa.

Para poder ver los types configurados, hay que ingresar al módulo de Gestión de Clientes -> Ajustes -> Tipos de Cliente, y luego seleccionar Developers en la barra superior

group_id: Es un número identificando el grupo de cliente. Los grupos de cliente en Persat, son una clasificación configurable por el usuario que no solo sirve para filtrar, si no que contempla niveles de permiso. Es decir que si un cliente es del grupo "Zona Norte", luego solo los usuarios que tengan permiso de ver ese grupo podrán ver ese cliente.

Para poder ver los grupos configurados, hay que ingresar al módulo de Gestión de Clientes -> Ajustes -> Grupos de Cliente, y luego seleccionar Developers en la barra superior.

latitude y longitude: Posición del cliente en el globo. Son campos numéricos.

service_time: Número pero puede también no estar definido y no presentarse en la respuesta. En caso de estar definido, indica el tiempo en minutos que debería durar la visita. Esto se utiliza luego por el algoritmo de ruteo para calcular el tiempo de espera en este cliente (por ejemplo: Tiempo de descarga de mercadería).

wt: Array[number, number] pero puede también no estar definido y no presentarse en la respuesta. En caso de estar definido, indica el horario en que el comercio se encuentra abierto. Esto se utiliza luego por el algoritmo de ruteo para calcular en que momento hay que visitar al cliente. En caso de no estar definido, esto indicaría que puede ser visitado en cualquier momento del día.

Ejemplo wt = [480, 780].

Hora de apertura = 480 / 60 = 08:00 AM

Hora de cierre = 780 / 60 = 13:00 PM

Campos de dirección:

street: Dirección del cliente (solo la calle)

street_nbr: Dirección del cliente (solo el número)

neighborhood: Barrio

city: Ciudad

country: País

Si el cliente fue creado desde Persat, los campos mencionados en general están completos, puesto que se hace uso del geocoding.

Cuando el cliente se crea desde la API, los campos son opcionales, pero es recomendable que se respete la nomenclatura mencionada.

last_updated es una fecha UTC que indica la última vez que se modificó el cliente. Es un dato muy útil a la hora de sincronizar todos los clientes. Ver Listar Clientes

custom_fields es un objeto JSON que nos detalla los campos personalizados de la ficha de clientes. Cada campo personalizado tiene un id único, que pasa a ser la key del objeto custom_fields.

Por ejemplo, el campo personalizado "Telefono", tiene id = 2. Es útil conocer el id de cada custom_field, para poder crear nuevos clientes con los campos personalizados completos.

Una forma rápida de averiguar los ids de los custom fields la podes obtener aqui: Campos personalizados.

También se pueden obtener a través de dla API con este endpoint

Si bien cada uno de los campos personalizados tiene un field_type que se usa para la validación para los usuarios web y movil. Dicha validación no se realiza desde la API.

En resumen, todos los campos se reciben, modifican e insertan como si fueran strings, independientemente del tipo.

La validación corre por cuenta del programador