API de pedidos

https://app.optiroute.cl/api/v1/integration-service-requests/

Estados de Objetos de la API

Pedidos y direcciones tienen estado relacionados con la operación de las rutas. A continuación detallaremos cuales son esos estados y bajo que condiciones se aplican.

Estados de pedidos

Los pedidos tienen estados que son actualizados por los eventos realizados por el conductor a medida que la ruta se va efectuando. Estos estados están determinados por números enteros y equivalen a los siguientes:

Para interactuar con este endpoint se deben utilizar las estructuras de datos que se describirán a continuación.

Estados de direcciones

Cada pedido agregado a Optiroute debe tener asociada una dirección la cual será geocodificada en el sistema con la finalidad de obtener la mayor información sobre ella para garantizar el correcto enrutamiento de la entrega.

Para agregar una dirección a Optiroute a través de la API de integración existen dos modalidades:

• A través de la definición del texto de la dirección el sistema realiza un proceso de geocodificación para obtener las coordenadas geográficas de la dirección ingresada.

• A través de la definición de las coordenadas geográficas el sistema realiza un proceso de geocodificación inversa en donde obtiene el texto de la dirección y comuna ingresada.

En ambos procesos la correcta codificación de la dirección depende de la precisión de los datos ingresados. En base a todas las posibilidades en este proceso se determina el estado de la dirección, los cuales son detallados a continuación.

Objetos de la API

Para interactuar con este endpoint se deben utilizar las estructuras de datos que se describirán a continuación.

Objeto pedido de entrada

El objeto pedido de entrada es un hash de cada pedido y sus propiedades, donde la clave es la propiedad id del pedido, que corresponde al Identificador único del pedido en Optiroute. 

Este tipo de objeto se ocupa para ingresar información al sistema.

Objeto cliente

El objeto cliente es un hash con la información del cliente que recibirá el pedido, que contiene sus propiedades. 

Objeto dirección

El objeto dirección es un hash con la información de la dirección que recibirá el pedido, que contiene sus propiedades. 

Para agregar una dirección a Optiroute a través de la API de integración existen dos alternativas:

• A través de la definición en base a texto de la dirección, esto es definiendo las propiedades address_string y commune_string (opcional pero recomendada) el sistema realiza un proceso de geocodificación para obtener las coordenadas geográficas de la dirección ingresada.
• A través de la definición en base a las propiedades de latitude y longitude. En este caso el sistema realiza un proceso de geocodificación inversa en donde obtiene el texto de la dirección ingresada, además de la comuna en donde se encuentra.

Objeto pedido de respuesta

El objeto pedido de respuesta es un hash de cada pedido y sus propiedades, donde la clave es la propiedad id del pedido, que corresponde al Identificador único del pedido en Optiroute. Este tipo de objeto se ocupa cuando el sistema retorna información respecto a un pedido consultado.

Objeto destino

El objeto destino de respuesta es un hash del último destino asignado a este pedido, y sus propiedades, donde la clave es la propiedad id del destino.

Objeto Imagen

El objeto imagen de respuesta es un hash con la información respecto a la imágenes de entrega. Las imágenes serán almacenadas hasta 1 año desde que fueron obtenidas.

Es importante considerar que el vínculo de la imagen tiene una vigencia de 24 horas, luego de eso será generará por otro vínculo.

Agregar pedidos

Al agregar pedidos a Optiroute estos aparecerán disponibles en la plataforma y podrás generar tus rutas en base a ellos. Para ello debes realizar una llamada tipo POST en el endpoint de la API de pedidos, añadiendo a ella el objeto tipo pedido de entrada que deseas crear.

Si la creación fue realizada correctamente la API deberá retornar un objeto tipo pedido de respuesta con la información del pedido recién creado.

En caso de cualquier error de validación la API entregará la descripción apropiada.

{
	'address': {
	    'apartment_number': '5',
	    'address_more_info': 'Villa',
	    'latitude': '-71.5508119'
	},
	'customer': {
	    'name': 'test',
	    'email': 'test@test.com',
	    'phone_number': '987654321',
	    'demand_a': 1
	},
}

Actualizar pedidos

Para actualizar pedidos en Optiroute debes realizar una llamada tipo PUT o PATCH en el endpoint de la API de pedido agregando El ID del pedido en la plataforma a integrar (reference en propiedad del objeto entrada de pedido) al final de la URL, como por ejemplo:

https://app.optiroute.cl/api/v1/integration-service-requests/{id}/

Debes adjuntar a la llamada los parámetros del objeto de tipo pedido de entrada que deseas actualizar.

Los parámetros de un pedido que pueden ser actualizados son los siguientes:

Si la llamada fue realizada correctamente la API deberá retornar un objeto de tipo pedido de respuesta.

Es posible actualizar el estado de un pedido aún cuando esté asignado a una ruta que aún no ha sido realizada o se está efectuando. La información de entrega permanece sin modificaciones desde que fue agregado a la ruta de despacho, por lo que cualquier modificación de estado será actualizada nuevamente cuando el conductor complete, salte o cancele el pedido.

En caso de cualquier error de validación la API entregará la descripción apropiada.

Obtener lista de pedidos

Para obtener la lista de pedidos desde Optiroute debes realizar una llamada tipo GET al endpoint de la API de pedidos.

Puedes filtrar la lista de objetos de tipo pedidos de respuesta obtenidos pueden utilizarse parámetros de consulta que deben ser agregados al final de la URL del endpoint como una serie de pares clave-valor, como por ejemplo:

https://app.optiroute.cl/api/v1/integration-service-requests/?per_page=25&creationStartDate=15-12-2024&creationEndDate=18-12-2024&statuses=0,1,2

Los parámetros que permiten filtrar esta llamada son los siguientes:

La API retorna la lista de objetos pedidos de respuesta de acuerdo a los filtros ingresados.

Obtener pedido particular

Para obtener el detalle del pedido desde Optiroute debes realizar una llamada tipo GET en el endpoint de la API de pedido agregando el id del pedido al final de la URL, de la siguiente manera:

https://app.optiroute.cl/api/v1/integration-service-requests/{id}/

Si la llamada fue realizada correctamente la API deberá retornar un objeto de tipo pedido de respuesta.

Borrar pedidos

Para eliminar un pedido desde Optiroute debes realizar una llamada tipo DELETE en el endpoint de la API de pedido agregando el id del pedido al final de la URL, de la siguiente manera:

https://app.optiroute.cl/api/v1/integration-service-requests/{id}/

Sólo los pedidos en estado REVIEWING pueden ser eliminados. Eliminar pedidos en cualquier otro estado puede provocar problemas de sincronización de datos mientras está siendo gestionado.

Los pedidos no son efectivamente borrados del sistema, sólo su estado es actualizado al estado DELETED.

Imágenes externas de pedidos

https://app.optiroute.cl/api/v1/integration-service-requests/{id}/upload_image/

https://app.optiroute.cl/api/v1/external-images/{id}/

API para carga masiva de pedidos

Si deseas agregar múltiples pedidos a Optiroute en una sola llamada puedes utilizar nuestro endpoint de carga masiva de datos de pedidos:

https://app.optiroute.cl/api/v1/batch-service-request-creation-inputs/

Esta API creará una tarea de importación que se ejecutará de manera asíncrona a la llamada en nuestro sistema, la cual podrá ser monitoreada a través de las distintas llamadas del endpoint.

Objetos de la API

Para interactuar con este endpoint se deben utilizar las estructuras de datos que se describirán a continuación.

Objeto input de pedidos de entrada

El objeto pedido masivo de entrada es un hash que contiene el arreglo de pedidos de entrada que serán agregados a Optiroute.

{
        'data': [
            {
                'reference': '2301989790',
                'address': {
                    'address_string': 'CARMEN BAJO 690',
                    'commune_string': 'IQUIQUE',
                },
                'customer': {
                    'name': 'NIBALDO TITO MAMANI MANINI',
                    'phone_number': '932321321',
                    'demand_a': 0,
                    'reference': '0649776'
                },
            },
            {
                'reference': '2301988831',
                'address': {
                    'address_string': 'CARMEN BAJO 690',
                    'commune_string': 'IQUIQUE',
                },
                'customer': {
                    'name': 'CAMILA MARY MORI ESPINOZA',
                    'phone_number': '991111111',
                    'demand_a': 1,
                    'reference': '0975945'
                },
            }
        ]
}

Objeto input de pedidos de respuesta

Este objeto es un hash que contiene la información de un input de pedidos que es retornado en una respuesta a una llamada de alguno de los endpoints de esta API.

Agregar pedidos en batch

Para agregar pedidos de forma masiva debes realizar una llamada tipo POST agregando el objeto de tipo pedido masivo de entrada.

Esta llamada creará todos los pedidos cuya referencia no haya sido encontrada en tu cuenta. Si el pedido ya existe sólo se actualizará si está en el estado REVIEWING o DELETED.

Si las propiedades id o reference de alguno de los pedidos ingresados está presente en alguno de los pedidos ingresados se efectuará una actualización del pedido (si es que existe en la plataforma).

Obtener estado de input de pedido

Si deseas obtener todos el estado de un input de pedidos particular, debes hacer una llamada tipo GET en el endpoint de la API de pedido agregando la referencia del objeto de tipo input de tipo pedido masivo de entrada creado en la plataforma (reference en propiedad del objeto) al final de la URL, como por ejemplo:

https://app.optiroute.cl/api/v1/batch-service-request-creation-inputs/{id}/

Si la llamada fue realizada correctamente la API deberá retornar un input de pedidos de respuesta.