Developers
NAV Navbar
logo SimpliRoute
shell java javascript
  • Introduction
  • Authentication
  • Visits
  • Plans management
  • Routes
  • Route Properties
  • Vehicles
  • Customers
  • Users
  • Skills
  • Webhooks
  • Optimization
  • Optimization: Metadata
  • Validate Incompatibilities
  • Invoices
  • The Checkout Process
  • TMS: Transportation provider
  • GPS Integration
  • Errors
  • Datamart

    • Introduction

    API Endpoint:

    URL: https://api.simpliroute.com/v1/

    URL: https://api.simpliroute.com/v1/

    URL: https://api.simpliroute.com/v1/

    The SimpliRoute API is a set of REST endpoints. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, included error logs.

    The main objective of this docs to allow any developer to start working with our API thanks to different examples and use-cases exposed in this documentation. There are 2 basic use-cases to be working with our API:

    • You (or your company) are a SimpliRoute web platform and want to send information from your system to SimpliRoute or vice-versa. If that is the case, you'll be mostly interested in our Visit endpoints

    • You are developer and you are interested in improve our system adding route intelligence. If that is the case, our Route Optimization API is the right path to follow.

    If you have feedback, error or out-dated info, feel free to contact us at [email protected].

    Authentication

    Basic endpoint to show how to make a call with the Authorization Token

    Basic endpoint to show how to make a call with the Authorization Token

    var settings = {
    async: true,
    crossDomain: true,
    url: "https://api.simpliroute.com/v1/accounts/me/",
    method: "GET",
    headers: {
        "content-type": "application/json",
        authorization: "Token 12345678900987sr",
    },
};
$.ajax(settings).done(function (response) {
    console.log(response);
});

    OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/accounts/me/")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();

    curl curl -X GET \
  https://api.simpliroute.com/v1/accounts/me/ \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \

    Make sure to replace 12345678900987sr with your API key.

    To use SimpliRoute API, you have to provide a valid Token through the header "Authorization". If you don't have a Token, you can get it from your account in the url: https://app2.simpliroute.com/#/uprofile/info.

    If you don't have an account, you can create a 14-days free trial in this URL: https://app2.simpliroute.com/#/signup.

    Visits

    If you want to integrate your system with SimpliRoute, the most relevant endpoint in our API is Visit. A visit object is anything that a driver has to do in the street: a service order, a delivery, a pickup. Then, if you want to optimize those orders and track then in SimpliRoute, you have to create a visit object. In this particular object, you have to specify a few simple things, these are the only mandatory fields to create a visit in Simpliroute.

    • Title
    • Address
    • Planned Date

    That is the basic information that a visit must contain to be accepted in the API. As all the endpoints in SimpliRoute API, it implements GET, POST, PUT and DELETE http methods.

    The Visit Object

    Visit Object example

    {
    "id": 200189436,
    "order": null,
    "tracking_id": "SR98278668985242",
    "status": "pending",
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "latitude": "-33.413433",
    "longitude": "-70.585503",
    "load": 39.0,
    "load_2": 100.0,
    "load_3": 0.0,
    "window_start": null,
    "window_end": null,
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": null,
    "reference": "",
    "notes": "",
    "skills_required": [],
    "skills_optional": [],
    "tags": [],
    "planned_date": "2016-06-30",
    "programmed_date": null,
    "route": null,
    "estimated_time_arrival": null,
    "estimated_time_departure": null,
    "checkin_time": null,
    "checkout_time": null,
    "checkout_latitude": null,
    "checkout_longitude": null,
    "checkout_comment": "",
    "checkout_observation": null,
    "signature": null,
    "pictures": [],
    "created": "2022-09-03T01:19:42.786633Z",
    "modified": "2022-09-03T01:19:42.786633Z",
    "eta_predicted": "2016-06-30T00:00:00-04:00",
    "eta_current": "2016-06-30T00:00:00-04:00",
    "priority": false,
    "has_alert": false,
    "priority_level": null,
    "extra_field_values": null,
    "geocode_alert": null,
    "visit_type": null,
    "current_eta": null,
    "fleet": null,
    "properties": {
      "city": "Santiago"
    },
    "items": [
        {
            "id": 221544,
            "title": "bar",
            "status": "pending",
            "load": 2.0,
            "load_2": 1.5,
            "load_3": 0.0,
            "reference": "bar",
            "visit": 200189436,
            "notes": "",
            "quantity_planned": 2.0,
            "quantity_delivered": 0.0
        },
        {
            "id": 221543,
            "title": "foo",
            "status": "pending",
            "load": 15.0,
            "load_2": 0.0,
            "load_3": 0.5,
            "reference": "foo",
            "visit": 200189436,
            "notes": "",
            "quantity_planned": 1.0,
            "quantity_delivered": 0.0
        }
    ],
    "on_its_way": null
}
    Attributes Data Type Description
    id uuid Unique identifier for the object.
    order Integer Visit order when the visit already belongs to a delivery route
    tracking_id String Autogenerated tracking code to follow the delivery
    status String Visit's status (pending, completed, failed)
    title String String to identify the delivery. Usually company or person's name
    address String Address text. Best practice is to use Googlemaps format.
    planned_date Date Date when the visit will be delivered
    latitude Float Visit's latitude location
    longitude Float Visit's longitude location
    load Double Space of the truck that visit uses.
    load_2 Double Space of the truck that visit uses.
    load_3 Double Space of the truck that visit uses.
    window_start Time Initial Hour when the visit can be visit
    window_end Time Final Hour when the visit can be visit
    window_start_2 Time Initial Hour when the visit can be visit
    window_end_2 Time Final Hour when the visit can be visit
    duration Timestamp Time spent in the delivery (HH:mm:ss)
    contact_name String Name of who will receive the delivery
    contact_phone String Phone of who will receive the delivery
    contact_email String E-mail of who will receive the delivery
    reference String Reference or internal identifier of the company. Example: Invoice or order number.
    notes String Information to help the driver
    skills_required Integer array Array of required skills id that this visit needs
    skills_optional Integer array Array of optional skills id that this visit needs
    Tags Integer array Array of tag IDs that characterize the visit.
    route* UUID Unique identifier of the route.YYYY-MM-DD
    route_estimated_time_start* Time Estimated time that the vehicle will start the route in "HH:mm:ss"
    estimated_time_arrival Time SimpliRoute estimation of arrival to the visit.
    estimated_time_departure Time SimpliRoute estimation of departure from visit.
    checkin_time Timestamp Timestamp when the driver started the delivery.
    checkout_time Timestamp Timestamp when the driver completed the delivery.
    checkout_latitude Float Latitude of the driver when he completed the delivery
    checkout_longitude Float Longitude of the driver when he completed the delivery
    checkout_comment* String Information provided by the driver when she was completing the delivery
    checkout_observation* UUID Unique identifier of the observation.
    signature* String Contains the URL with the image of the client's signature..
    pictures URL array Array with URLs of pictures added with the delivery.
    created* Timestamp Timestamp of the creation of the visit.
    modified* Timestamp Timestamp of the last edition of the visit.
    driver* Integer Driver ID
    vehicle* Integer Vehicle ID.
    has alert* Boolean Contains a boolean value to identify an alert...
    priority_level Integer If the visit is more important than others. It goes from 1 to 5. 1: First of the day, 2: Last of the day. 3: High priority, 4: Medium priority, 5: Low priority.
    extra_field_values String json object containing attributes and values ​​pre-configured by SimpliRoute.
    geocode_alert* String Geocoding alert.
    visit_type* String Contains the URL with the image of the client's signature..
    fleet Integer Fleet ID.
    items Array Object Arrangement containing the elements to deliver on the visit.
    on its way Boolean
    properties Object Extra properties of a visit

    The Property Object

    Attributes Data Type Description
    city String The city of the visit address
    delivery_type String Specifies the delivery type: DELIVERY or PICK
    source String The source of the data to be saved: CLIENT
    source_ident String An identifier used to reference the source, e.g., client ID
    merchant String The merchant associated with the data

    The Items Object

    The items object is presented, where you can manage quantities of items for each visit, as well as their partial delivery. To do this, they will be able to create visits with item arrangements by establishing up to 3 loads of the item, reference, notes, quantity planned and delivered.

    Items Object example

    {
        {
        "id": 64,
        "title": "prueba2",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    }
}
    Attributes Data Type Description
    id uuid Unique identifier for the object.
    title String Title of the item to deliver.route
    status String Element status: pending, failed, or completed
    load Double Space or load that the element occupies in the vehicle
    load_2 Double Second load unit complementary to the first
    load_3 Double Third load unit complementary to the first and the second
    reference Date Internal element identifier
    notes String Additional item notes
    quantity_planned Float Planned quantity of the item
    quantity_delivered Float Delivered quantity of the item

    Create a visit with items

    You can create visit adding quantities of items for each visit, these fields are optional.

    URL Definition

    
POST https://api.simpliroute.com/v1/routes/visits/

    Example Request

    curl --location --request POST 'https://api.simpliroute.com/v1/routes/visits' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "load": 39,
    "load_2": 100,
    "window_start": null,
    "window_end": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "planned_date": "2016-06-30",
    "items": [
      {
          "title": "foo",
          "load": 15,
          "load_3": 0.5     ,
          "reference": "foo",
          "quantity_planned": 1
      },
      {
          "title": "bar",
          "load": 2,
          "load_2": 1.5,
          "reference": "bar",
          "quantity_planned": 2
      }
  ]
}'



    OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"title\": \"Kwik e mart\",\n  \"address\": \"742 Evergreen Terrace, Springfield, USA\",\n  \"latitude\": 44.052698,\n  \"longitude\": -123.020718,\n  \"contact_name\": \"Apu Nahasapeemapetilon\",\n  \"contact_phone\": \"+123413123212\",\n  \"contact_email\": \"[email protected]\",\n  \"reference\": \"invoice_id\",\n  \"notes\": \"Leave at front door\",\n  \"planned_date\": \"2020-01-01\"\n}");
Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();

    var settings = {
    async: true,
    crossDomain: true,
    url: "https://api.simpliroute.com/v1/routes/visits/",
    method: "POST",
    headers: {
        "content-type": "application/json",
        authorization: "Token 12345678900987sr",
    },
    processData: false,
    data: '{\n  "title": "Kwik e mart",\n  "address": "742 Evergreen Terrace, Springfield, USA",\n  "latitude": 44.052698,\n  "longitude": -123.020718,\n  "contact_name": "Apu Nahasapeemapetilon",\n  "contact_phone": "+123413123212",\n  "contact_email": "[email protected]",\n  "reference": "invoice_id",\n  "notes": "Leave at front door",\n  "planned_date": "2020-01-01"\n}',
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

    To create a visit, the bare minimum information is a title, address and a planned_date. The other parameters in the visit object are optional and you'll need them depending of your implementation.

    You can create visits one by one or as an array. The examples in the right side only shows one visit creation per request but if you need to create a batch of visit, the input will be something like this:

    Example Request

    
[ 
    {
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "load": 39,
    "load_2": 100,
    "window_start": null,
    "window_end": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "planned_date": "2016-06-30",
    "items":
    [
        {
            "title": "foo",
            "load": 15,
            "load_3": 0.5     ,
            "reference": "foo",
            "quantity_planned": 1
        },
        {
            "title": "bar",
            "load": 2,
            "load_2": 1.5,
            "reference": "bar",
            "quantity_planned": 2
            }
        ]
    }
    ]

    Returns

    Returns the visit object if the creation succeeded. This call will return an error if some of parameters are invalid.

    Retrieve a visit

    URL Definition

    
GET https://api.simpliroute.com/v1/routes/visits/{{visit_id}}

    Example Request Using as '12345' as example for visit_id

    curl -X GET \
  https://api.simpliroute.com/v1/routes/visits/{{visit_id}}\
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \

    OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/12345")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();

    var settings = {
    async: true,
    crossDomain: true,
    url: "https://api.simpliroute.com/v1/routes/visits/12345",
    method: "GET",
    headers: {
        "content-type": "application/json",
        authorization: "Token 12345678900987sr",
    },
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

    Example Response

    [
    {
        "id": 199285905,
        "order": null,
        "tracking_id": "SR17562640764438",
        "status": "pending",
        "title": "SimpliRoute3",
        "address": "vespucio norte 22, las condes",
        "latitude": "-33.413433",
        "longitude": "-70.585503",
        "load": 39.0,
        "load_2": 100.0,
        "load_3": 0.0,
        "window_start": null,
        "window_end": null,
        "window_start_2": null,
        "window_end_2": null,
        "duration": "00:00:10",
        "contact_name": "",
        "contact_phone": "",
        "contact_email": null,
        "reference": "",
        "notes": "",
        "skills_required": [],
        "skills_optional": [],
        "tags": [],
        "planned_date": "2016-06-30",
        "programmed_date": null,
        "route": null,
        "estimated_time_arrival": null,
        "estimated_time_departure": null,
        "checkin_time": null,
        "checkout_time": null,
        "checkout_latitude": null,
        "checkout_longitude": null,
        "checkout_comment": "",
        "checkout_observation": null,
        "signature": null,
        "pictures": [],
        "created": "2022-08-31T17:32:55.626342Z",
        "modified": "2022-08-31T17:32:55.626342Z",
        "eta_predicted": "2016-06-30T00:00:00-04:00",
        "eta_current": "2016-06-30T00:00:00-04:00",
        "priority": false,
        "has_alert": false,
        "priority_level": null,
        "extra_field_values": null,
        "geocode_alert": null,
        "visit_type": null,
        "current_eta": null,
        "fleet": null,
        "items": [
            {
                "id": 211775,
                "title": "bar",
                "status": "pending",
                "load": 2.0,
                "load_2": 1.5,
                "load_3": 0.0,
                "reference": "bar",
                "visit": 199285905,
                "notes": "",
                "quantity_planned": 2.0,
                "quantity_delivered": 0.0
            },
            {
                "id": 211774,
                "title": "foo",
                "status": "pending",
                "load": 15.0,
                "load_2": 0.0,
                "load_3": 0.5,
                "reference": "foo",
                "visit": 199285905,
                "notes": "",
                "quantity_planned": 1.0,
                "quantity_delivered": 0.0
            }
        ],
        "on_its_way": null
    }
]

    Retrieves the details of an existing visit. Send the unique visit id and SimpliRoute API will return the corresponding visiti information.

    Adding items to a visit

    By means of the following endpoint, one or more items can be added to a certain visit, for this we must have the visit id, which must be entered as part of the structure in the url.

    Definition

    
POST https://api.simpliroute.com/v1/routes/visits/{{VISIT_ID}}/items

    Example JSON

    [
    {
        "id": 63,
        "title": "prueba1",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    },
    {
        "id": 64,
        "title": "prueba2",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    }
]

    Delete a visit

    To delete a visit, a DELETE call must be made to the SimpliRoute visits service. This is done in the following way:

    Definition

    
DELETE  https://api.simpliroute.com/v1/routes/visits/{{VISIT_ID}}/

    Something important is that the elimination of a visit in an already built route does NOT trigger a recalculation of the arrival times of the following points of the route. The only way to do this currently is via the SimpliRoute web interface or manually update the ETAs for each visit with an external calculation.

    Delete visit masive

    To eliminate multiple visits, a POST type call must be made to the SimpliRoute bulk service. This is done in the following way:

    Definition

    
POST https://api.simpliroute.com/v1/bulk/delete/visits/

    Example Request body ``` json { visits: [000000, 000001...] }

    The visits array must have the id of the visits that you want to delete.

## Retrieve visits by date

> Definition

```url

GET https://api.simpliroute.com/v1/routes/visits/?planned_date={{planned_date}}

    Example Request

    curl -X GET \
  'https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01' \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json'


    OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();

    var settings = {
    async: true,
    crossDomain: true,
    url: "https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01",
    method: "GET",
    headers: {
        "content-type": "application/json",
        authorization: "Token 12345678900987sr",
    },
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

    GET call to request all the visits for a given date. The expected planned date format is "YYYY-mm-dd" (Year-month-day, 2020-10-22). This is a useful call if you want to track your deliveries in real-time because it returns the whole list of visits and the complete activity of each of them (including checkouts and information provided from the drivers in the street.)

    Update a visit

    URL Definition

    
PUT https://api.simpliroute.com/v1/routes/visits/{{visit_id}}

    Example Request

    curl -X PUT \
  https://api.simpliroute.com/v1/routes/visits/1111/ \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \
  -d '{
  "title": "Updated visit",
  "address": "new address",
  "load": 39,
  "duration": "00:00:10",
  "contact_name": "New visit contact",
  "contact_phone": "+12341345",
  "notes": "New information",
  "planned_date": "2020-06-30"
}'

    OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"title\": \"Updated visit\",\n \"address\": \"New address\",\n \"load\": 39,\n  \"duration\": \"00:00:10\",\n  \"contact_name\": \"New visit contact\",\n  \"contact_phone\": \"+12341345\",\n  \"notes\": \"New information\",\n  \"planned_date\": \"2020-06-30\"\n}");
Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/1111/")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();

    var settings = {
    async: true,
    crossDomain: true,
    url: "https://api.simpliroute.com/v1/routes/visits/1111/",
    method: "PUT",
    headers: {
        "content-type": "application/json",
        authorization: "Token 12345678900987sr",
    },
    processData: false,
    data: '{\n  "title": "Updated visit",\n  "address": "New address",\n "load": 39,\n  "duration": "00:00:10",\n  "contact_name": "New visit contact",\n  "contact_phone": "+12341345",\n  "notes": "New information",\n  "planned_date": "2020-06-30"\n}',
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

    Updates the specified argument by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

    Visit detail

    By using the following endpoint you can obtain the detail information of a visit

    GET https://api.simpliroute.com/plans/v1/visits/{{VISIT_ID}}/detail/

    Example response

    {
"window_start":"09:00:00",
"reference":"",
"planned_date":"2017-03-13",
"time_service":"00:00:03",
"window_end":"19:00:00",
"checkout_comment":"",
"duration":"00:20:00",
"estimated_time_arrival":"09:05:00",
"id":89273,
"checkin_time":"2017-03-13T20:17:08Z",
"pictures":[],
"window_start_2":"23:59:00",
"checkout_observation":"Testing",
"latitude":"-33.442880",
"status":"completed",
"checkout_time":"2017-03-13T20:17:11Z",
"window_end_2":"23:59:00",
"vehicle_name":"KILASK31",
"address":"FANOR VELASCO 85, SANTIAGO, Santiago",
"title":"PELUQUERIA DI GIANCARLO",
"longitude":"-70.659729",
"driver_name":"Paperito",
"order":1
}

    This endpoint provides more information, including Checkout Comment and Images

    Obtain details of the visit

    By using the following endpoint you can obtain the detail information of a bulk of visit

    URL Definition

    GET https://api.simpliroute.com/v1/routes/visits/{{VISIT_ID}}

    API validation of time windows - visits

    Current situation

    When creating/editing a visit, the API does not validate the time windows that are reported in it. This causes that there are eventualities in the optimization.

    The two problems found are: - It is not validated that the start time is less than the end - Overlapping time windows is not validated when loading both possible time windows for a visit.

    This problem appears only through the API integration, since there are validations in both the manual upload and the Excel upload.

    Expected situation

    When creating a visit that it has a time windows, the same validation that is used today for manual loading must be replicated, which consists of: - The start time cannot be greater than the end time (Ex: start time 19:00 - end time: 16:00)

    • The time window does not extend to the next day (Ex: start time 23:00 - end time: 04:00). Although it complies with the aforementioned validation, it is important to clarify that there is no "Night" time window.

    The error message that the API will return is:

    Example Time error: the time window order is inverted. Both manual and Excel handle the same messages as before.

    For the second mentioned problem you need to validate:

    • That time window 1 is NOT later than time window 2 (Ex: window 1 from 12:00 to 14:00 and window 2 from 08:00 to 10:00).

    • That there is NO intersection between the two windows (Ex: Window 1 from 12:00 to 14:00 and window 2 from 13:00 to 18:00).

    The error message that the API will return is: Time error: the time window order is inverted. Both manual and Excel handle the same messages as before.

    For more information, contact your account executive, the support chat or write us an email to [email protected].

    Checkout a visit

    Visit checkout (minimal payload)

    curl --location --request POST 'https://api.simpliroute.com/v1/mobile/visit/<visit_id>/checkout/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "completed", 
    "checkout_time": "2024-04-24 13:24:53", 
    "checkout_latitude": -12.105513, 
    "checkout_longitude": -76.965618, 
    "checkout_comment": "everything was OK" 
  }'

    To check out a visit the following service is available: https://api.simpliroute.com/v1/mobile/visit/<visit_id>/checkout/

    A minimal payload cURL is shown at the right panel 👉

    If you plan to implement the same features as our mobile application please check The Checkout process

    Parameter type description
    status string one of the following statuses: pending, completed, failed
    checkout_time string date and hour of checkout following the ISO 8601 standard
    checkout_latitude float latitude at the point of delivery
    checkout_longitude float longitude at the point of delivery
    checkout_comment string optional comment

    Plans management

    A plan is a series of Vehicle and Driver pairings for a specific day.

    Plan is the entity that encompasses a system execution. To avoid problems, it is suggested that plan creation be done with the plan name as a timestamp. The start-end date of the plan, for general cases, is the day of execution of the plan.

    Create Plan

    First of all, there are two main objects to consider in a plan:

    • Routes → The system entity that encompasses a set of visits
    • Visits → Anything that a driver has to do in the street: a service order, a delivery, a pickup Also, we need to know the id of the driver and vehicle that we are going to route, this can be done with the following endpoints: >URL Definition ```url

    GET Vehicles: https://api.simpliroute.com/v1/routes/vehicles/ ```

    URL Definition url GET Driver: https://api.simpliroute.com/v1/accounts/drivers/

    Where we should save the ‘id’ field of each endpoint to use it later on. Once we get those fields, we should be able to create a complete plan using all from above

    URL Definition

    
POST https://api.simpliroute.com/v1/plans/create-plan/

    Example request

    {
  "name": "Plan created through API 2022-09-02 12:55:18",
  "start_date": "2022-09-02",
  "end_date": "2022-09-02",
  "routes": [
    {
      "driver": "183371",
      "vehicle": "288202",
      "planned_date": "2022-09-02",
      "total_distance": "0",
      "total_duration": "00:38:00",
      "total_load": 0,
      "total_load_percentage": 0,
      "total_load_2": 0,
      "total_load_2_percentage": 0,
      "total_load_3": 0,
      "total_load_3_percentage": 0,
      "estimated_time_start": "08:00:00",
      "estimated_time_end": "08:38:00",
      "request_status": "created",
      "comment": null,
      "location_start_address": "Av. San Borja Sur 486, Cercado de Lima 15036",
      "location_start_latitude": -12.101389,
      "location_start_longitude": -77.004534,
      "location_end_address": "Av. San Borja Sur 486, Cercado de Lima 15036",
      "location_end_latitude": -12.101389,
      "location_end_longitude": -77.004534,
      "visits": [
        {
          "title": "Order 1234",
          "address": "Jirón Vesalio 252, San Borja",
          "latitude": -12.105329,
          "longitude": -77.005524,
          "order": 1,
          "load": 1,
          "window_start": "09:00:00",
          "window_end": "17:00:00",
          "duration": "00:10:00",
          "contact_name": "David Rosales",
          "contact_email": "[email protected], [email protected]",
          "reference": "",
          "notes": "Watch out with the dog!",
          "planned_date": "2022-09-02",
          "estimated_time_arrival": "08:02",
          "estimated_time_departure": "08:12",
          "request_status": "created"
        },
        {
          "title": "Order 4567",
          "address": "Jirón Tasso 423, San Borja",
          "latitude": -12.105779,
          "longitude": -77.019189,
          "order": 2,
          "load": 1,"window_start": "09:00:00",
          "window_end": "17:00:00",
          "duration": "00:10:00",
          "contact_name": "David Rosales",
          "contact_email": "[email protected]",
          "reference": "",
          "notes": "Ask for David",
          "planned_date": "2022-09-02",
          "estimated_time_arrival": "08:20",
          "estimated_time_departure": "08:30",
          "request_status": "created"
        }
      ]
    }
  ]
}

    Example response

    {
"id": "4363095e-8d7c-46d0-9a14-8c895c37fa88",
"name": "Plan created through API 2022-09-02 12:55:18",
"start_date": "2022-09-02",
"end_date": "2022-09-02",
"reset_day": 1,
"created": "2022-09-02T06:51:24.937690Z",
"modified": "2022-09-02T06:51:24.937690Z",
"is_cluster": false,
"routes": [
"349cd8a2-5149-4732-b46f-1073fb90ea07"
],
"plan_metadata": null,
"start_time": null,
"end_time": null
}
> Example request

```json
{
        "name": "Agosto",
        "start_date": "2016-08-01",
        "end_date": "2016-08-01"
    }

    Example response

    [{
        "id": "fc65b49f-1f5c-4ca5-9b03-98565e1589f3",
        "name": "Agosto",
        "start_date": "2016-08-01",
        "end_date": "2016-08-01",
        "created": "2016-08-25T15:28:32.400027Z",
        "modified": "2016-08-25T15:28:32.400365Z",
        "is_cluster": false
}]

    Important considerations

    All parameters in bold are considered important to create plans

    Plan

    • name must be unique
    • start_date and end_date must be the same

    Routes

    • driver → driver id
    • vehicle → vehicle id
    • planned_date must be equal to plan’s start_date and end_date
    • estimated_time_start → when the vehicle starts to work
    • estimated_time_end → when vehicle will end working
    • request_status → create a new route

    Visits

    An array with all the visits of a route. - title → Identifier of the shop or person to deliver (will be displayed on mobile app) - address → Address of the delivery (will be displayed on mobile app) - order → The order in which will be delivered - planned_date → Delivery date - estimated_time_arrival → Arrival - estimated_time_departure → Departure - request_status → create a new visit

    The rest of the parameters are not mandatory and should be setted with dummy data if the i nformation is not available.

    Routes

    Route is the system entity that encompasses a set of visits. On this you can do the typical CRUD operations:

    Create routes

    URL Definition

    POST https://api.simpliroute.com/v1/routes/routes/

    Example request

    [
  {
    "vehicle": 2032,
    "driver": null,
    "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
    "planned_date": "2016-05-20",
    "estimated_time_start": "03:00:00",
    "estimated_time_end": "19:33:00",
    "status": "pending",
    "total_duration": "16:33:00",
    "total_distance": 0,
    "total_load": 2086,
    "total_load_percentage": 0,
    "location_start_address": "Enrique Mac Iver 524, Santiago, Chile",
    "location_start_latitude": "-33.436571",
    "location_start_longitude": "-70.647308",
    "location_end_address": "Suecia 151, Providencia, Chile",
    "location_end_latitude": "-33.421958",
    "location_end_longitude": "-70.607270",
    "reference": "my reference"
  }
]

    Example response

    [
  {
    "id": "33ddc43b-5ca8-4455-b3af-16a2f1971c1e",
    "vehicle": 2032,
    "driver": null,
    "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
    "status": "pending",
    "planned_date": "2016-05-20",
    "estimated_time_start": "03:00:00",
    "estimated_time_end": "19:33:00",
    "total_duration": "16:33:00",
    "total_distance": 0,
    "total_load": 2086,
    "total_load_percentage": 0,
     "total_load_2": 0.0,
    "total_load_2_percentage": 0,
    "total_load_3": 0.0,
    "total_load_3_percentage": 0,
    "location_start_address": "Enrique Mac Iver 524, Santiago, Chile",
    "location_start_latitude": "-33.436571",
    "location_start_longitude": "-70.647308",
    "location_end_address": "Suecia 151, Providencia, Chile",
    "location_end_latitude": "-33.421958",
    "location_end_longitude": "-70.607270",
    "comment": "Route 1",
    "start_time": null,
    "end_time": null,
    "created": "2016-08-01T20:45:25.672207Z",
    "modified": "2016-08-01T20:45:25.674460Z",
    "kilometers": null,
    "total_visits": 0,
    "latitude_init": null,
    "longitude_init": null,
    "latitude_finish": null,
    "longitude_finish": null,
    "is_revised": false,
    "reference": "my reference"
  }
]

    List of Vehicles with routes for a date

    URL Definition

    GET https://api.simpliroute.com/v1/plans/{{planned_date}}/vehicles/

    Example response

    [
  {
    "color": "#FFCC33",
    "routes": [
      {
        "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
        "id": "e708c5ba-6d49-4418-b87e-9061e1194b1b"
      }
    ],
    "driver":{
      "id": 742,
      "name": "Conductor Demo"
    },
    "name": "Mi auto",
    "id": 287
  }
]

    A Vehicle can have multiple routes for a day. A route is identified by a uuid.

    List of Visits by Route

    GET https://api.simpliroute.com/v1/plans/routes/{{PLAN_ID}}/visits/

    Example response

    [
  {
    "status": "failed",
    "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
    "reference": "",
    "title": "STARK INDUSTRIES",
    "checkout_time": "2017-03-13T20:17:20Z",
    "longitude": "-70.651066",
    "id": 89274,
    "route_id": "e708c5ba-6d49-4418-b87e-9061e1194b1b",
    "address": "HUERFANOS 1011, SANTIAGO, Santiago",
    "latitude": "-33.439626",
    "estimated_time_arrival": "09:28:00",
    "order": 2
  },
  {
    "status": "completed",
    "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
    "reference": "",
    "title": "PELUQUERIA DI GIANCARLO",
    "checkout_time": "2017-03-13T20:17:11Z",
    "longitude": "-70.659729",
    "id": 89273,
    "route_id": "2d3ced6c-70e4-414e-8313-d5abe9166a15",
    "address": "FANOR VELASCO 85, SANTIAGO, Santiago",
    "latitude": "-33.442880",
    "estimated_time_arrival": "09:05:00",
    "order": 1
  }
]

    A Vehicle can have multiple routes for a day. A route is identified by a uuid.

    Update reference field by Route

    PATCH https://api.simpliroute.com/v1/routes/routes/{{route_id}}/

    Example request

    {
  "reference": "my own reference"
}

    Example response

    {
  "id": "32024005-7b45-455d-b901-f3f9afa2679e",
  "vehicle": 278533,
  "driver": 129373,
  "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
  "status": "pending",
  "planned_date": "2024-02-28",
  "estimated_time_start": "09:00:00",
  "estimated_time_end": "10:54:00",
  "total_duration": "01:54:00",
  "total_distance": 60992,
  "total_load": 0.0,
  "total_load_percentage": 0,
  "total_load_2": 0.0,
  "total_load_2_percentage": 0,
  "total_load_3": 0.0,
  "total_load_3_percentage": 0,
  "location_start_address": "Lord Cochrane 298, Santiago, Chile",
  "location_start_latitude": "-33.449977",
  "location_start_longitude": "-70.654465",
  "location_end_address": "Av. Vicuña Mackenna 2365, Ñuñoa, San Joaquín, Región Metropolitana, Chile",
  "location_end_latitude": "-33.473420",
  "location_end_longitude": "-70.624235",
  "comment": "Route 1",
  "start_time": null,
  "end_time": null,
  "created": "2024-02-28T17:20:37.919471Z",
  "modified": "2024-04-02T20:14:46.945819Z",
  "kilometers": null,
  "total_visits": 2,
  "latitude_init": null,
  "longitude_init": null,
  "latitude_finish": null,
  "longitude_finish": null,
  "is_revised": false,
  "reference": "my own reference"
}

    Route Properties

    Attributes Data Type Description
    color String Stores the color assigned to the route when creating a plan. To use this property, the account configuration enable_colors_for_contiguous_routes must be enabled.
    is_start_blocked Boolean This property is used to block the start of a route.

    Get Route Properties

    URL Definition

    
GET https://api.simpliroute.com/v1/routes/routes-properties/{{ROUTE_ID}}

    Example Response

    {
  "route": "3d20088b-02b8-456b-80f9-ecfa8dbf27d6",
  "color": "#0000FF",
  "is_start_blocked": false
}

    This endpoint retrieves all the properties of a specified route.

    Create Route Properties

    URL Definition

    
POST https://api.simpliroute.com/v1/routes/routes-properties/

    Example Request

    {
  "route": "3d20088b-02b8-456b-80f9-ecfa8dbf27d6",
  "color": null,
  "is_start_blocked": false
}

    This endpoint is used to create properties for a specified route. If properties for the route already exist, an error response will be returned

    Update Route Properties

    URL Definition

    
PUT https://api.simpliroute.com/v1/routes/routes-properties/{{ROUTE_ID}}

    Example Request

    {
  "color": "#D50000",
  "is_start_blocked": true
}

    This endpoint is used to update all the properties for a specified route.

    Partial Update Route Properties

    
PATCH https://api.simpliroute.com/v1/routes/routes-properties/{{ROUTE_ID}}

    Example Request

    {
  "is_start_blocked": false
}

    This endpoint allows for the partial update of route properties. Only the properties included in the request body will be updated.

    Delete Route Properties

    
DELETE https://api.simpliroute.com/v1/routes/routes-properties/{{ROUTE_ID}}

    This endpoint is used to delete all the properties for a specified route.

    Bulk Search Routes Properties

    
POST https://api.simpliroute.com/v1/routes/routes-properties/bulk-search/

    Example Request

    {
  "route_ids": [
    "da6c3bac-898d-4343-8b05-5b80f2d7c26a",
    "3d20088b-02b8-456b-80f9-ecfa8dbf27d6"
  ]
}

    Example Response

    [
    {
        "route": "3d20088b-02b8-456b-80f9-ecfa8dbf27d6",
        "color": "#658900",
        "is_start_blocked": false
    },
    {
        "route": "da6c3bac-898d-4343-8b05-5b80f2d7c26a",
        "color": null,
        "is_start_blocked": true
    }
]

    This endpoint is used to retrieve the properties of multiple routes in a single request. By providing a list of route IDs, you can get the properties for each specified route.

    Vehicles

    To facilitate the integration flow, the loading of the vehicles of each client can be done via API using the following endpoints. The delivery entity is separate from the vehicle entity in SimpliRoute. This in order to better track vehicle performance or other internal user metrics.

    Create vehicles

    URL Definition

    
POST https://api.simpliroute.com/v1/routes/vehicles/

    Example Request with mandatory fields

    
{
    "name": "ASDFQWER",
    "capacity": 2000,
    "default_driver": null,
    "location_start_address": "Direccion A",
    "location_start_latitude": -33.3456,
    "location_start_longitude": -70.2345,
    "location_end_address": "Direccion B",
    "location_end_latitude": -33.34234,
    "location_end_longitude": -70.23456,
    "skills": []
}

    Example Request with all available fields

    
{
    "name": "Camión-1",
    "capacity": 1000,
    "default_driver": null,
    "location_start_address": "1 Calle A, Guatemala City, Guatemala",
    "location_end_address": "1 Calle A, Guatemala City, Guatemala",
    "location_end_latitude": "14.582131",
    "location_end_longitude": "-90.487034",
    "location_start_latitude": "14.582131",
    "location_start_longitude": "-90.487034",
    "skills": [],
    "capacity2": "1",
    "capacity3": "1",
    "cost": null,
    "shift_start": null,
    "shift_end": null,
    "reference_id": "12AB",
    "license_plate": "ABCD",
    "min_load": 0,
    "min_load_2": 0,
    "min_load_3": 0,
    "max_visit": null,
    "max_time": null,
    "rest_time_start": null,
    "rest_time_end": null,
    "rest_time_duration": null,
    "codrivers": []
}

    Example Response

    {
    "id": 487294,
    "name": "Camión-1",
    "shift_start": null,
    "shift_end": null,
    "capacity": 1000.0,
    "capacity_2": 1.0,
    "capacity_3": 1.0,
    "default_driver": null,
    "location_start_address": "1 Calle A, Guatemala City, Guatemala",  //(warehouse starting point of the vehicle)
    "location_start_latitude": "14.582131",
    "location_start_longitude": "-90.487034",
    "location_end_address": "1 Calle A, Guatemala City, Guatemala",  //(warehouse or last point of the vehicle)
    "location_end_latitude": "14.582131",
    "location_end_longitude": "-90.487034",
    "skills": [],
    "created": "2024-06-26T16:28:39.193486Z",
    "modified": "2024-06-26T16:28:39.193486Z",
    "color": "#FF8C00",
    "reference_id": "12AB",
    "license_plate": "ABCD",
    "cost": null,
    "min_load": 0,
    "min_load_2": 0,
    "min_load_3": 0,
    "max_visit": null,
    "rest_time_start": null,
    "rest_time_end": null,
    "rest_time_duration": null,
    "deleted": false,
    "max_time": null,
    "codrivers": [],
    "status": "active"
}

    List Vehicle

    URL Definition

    
GET https://api.simpliroute.com/v1/routes/vehicles/

    Example Response

    [{
    "id": 487294,
    "name": "Camión-1",
    "shift_start": null,
    "shift_end": null,
    "capacity": 1000.0,
    "capacity_2": 1.0,
    "capacity_3": 1.0,
    "default_driver": null,
    "location_start_address": "1 Calle A, Guatemala City, Guatemala",
    "location_start_latitude": "14.582131",
    "location_start_longitude": "-90.487034",
    "location_end_address": "1 Calle A, Guatemala City, Guatemala",
    "location_end_latitude": "14.582131",
    "location_end_longitude": "-90.487034",
    "skills": [],
    "created": "2024-06-26T16:28:39.193486Z",
    "modified": "2024-06-26T16:28:39.193486Z",
    "color": "#FF8C00",
    "reference_id": "12AB",
    "license_plate": "ABCD",
    "cost": null,
    "min_load": 0,
    "min_load_2": 0,
    "min_load_3": 0,
    "max_visit": null,
    "rest_time_start": null,
    "rest_time_end": null,
    "rest_time_duration": null,
    "deleted": false,
    "max_time": null,
    "codrivers": [],
    "status": "active"
}]

    Delete vechicle

    URL Definition

    
DELETE https://api.simpliroute.com/v1/routes/vehicles/{VECHICLE_ID}

    Customers

    A customer is an individual or company. Customers are the end users.

    Create Customers

    URL Definition

    
POST https://api.simpliroute.com/v1/accounts/clients/

    Example Request 

    
[{
    "key": "123456",
    "title": "Coop Enargas",
    "address": "",
    "latitude": null,
    "longitude": null,
    "load": null,
    "load_2": 0.0,
    "load_3": 0.0,
    "window_start": null,
    "window_end": null,
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:00",
    "contact_name": null,
    "contact_phone": null,
    "contact_email": null,
    "notes": null,
    "priority_level": null,
    "skills_required": [
            30744,
            47593
        ],
        "skills_optional": [
            30567
        ],
    "tags": [],
}]

    By using the following POST method, the clients/customers can be uploaded to the Simpliroute application, this generates the client master for each one of the accounts that will be registered and that will connect with the Web services of each ERP. Each main Client must have its own token to make the connection and inject the data to the platform

    When you create clients, it can be viewed from the client master extension on the Simpliroute platform.

    Obtain Customers

    URL Definition

    
GET https://api.simpliroute.com/v1/accounts/clients/?key={{CLIENT_ID}}

    Example Request

    [{
    "id": 68156,
    "key": "123456",
    "title": "Cliente Ejemplo",
    "address": "Pedro Montt 2245, Valparaíso, V Región",
    "latitude": "-33.464115",
    "longitude": "-70.652859",
    "load": 4.0,
    "load_2": 2.0,
    "load_3": 1.0,
    "window_start": "09:00:00",
    "window_end": "17:00:00",
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:00",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": "[email protected]",
    "notes": "Notas de Texto",
    "priority_level": null
    }
]

    Through the GET client method, you can obtain the id and the information related to the client via API, with this information we can generate the visits.

    Delete a Customer

    URL Definition

    DELETE https://api.simpliroute.com/v1/accounts/clients/{{CLIENT_ID}}/

    Delete Customers

    URL Definition

    DELETE https://api.simpliroute.com/v1/accounts/clients/

    Example Request body

    {
 [000000, 000001...]
}

    The array must have the id of the clients that you want to delete.

    Update Customers

    URL Definition

    PUT https://api.simpliroute.com/v1/accounts/clients/

    Example Request

    
[{
    "id": 68156,
    "key": "123456",
    "title": "Coop Enargas",
    "address": "",
    "latitude": null,
    "longitude": null,
    "load": null,
    "load_2": 0.0,
    "load_3": 0.0,
    "window_start": null,
    "window_end": null,
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:00",
    "contact_name": null,
    "contact_phone": null,
    "contact_email": null,
    "notes": null,
    "priority_level": null,
    "skills_required": [
            30744,
            47593
        ],
        "skills_optional": [
            30567
        ],
    "tags": [],
}]

    This endpoint allows for the updating of multiple clients' information

    Client Custom Properties

    Client custom properties are additional attributes that can be added to clients to store any type of necessary information. To add custom properties to your clients, you must first create the attribute in your account. Once created, these attributes can be used when creating and modifying client records.

    Create custom property

    URL Definition

    POST https://api.simpliroute.com/v1/planner/client-properties/

    Example Request

    {
  "label": "price",
  "type": "int"
}

    This endpoint is used to create a custom property for clients in the system/account. Custom properties allow you to add specific attributes tailored to your needs, which can be used when creating or modifying client records.

    Attributes Data Type Description
    label String The name of the custom property.
    type String The data type of the custom property. Possible values include 'str', 'int', 'float', 'bool'

    Using Custom Properties

    Example Request

    [
    {
        "key": "SFKK8976678",
        "title": "Cliente Ejemplo",
        "address": "Pedro Montt 2246, Valparaíso, V Región, Chile",
        "latitude": "-33.047400",
        "longitude": "-71.612920",
        "skills_required": [],
        "skills_optional": [],
        "load": "4",
        "load_2": "2",
        "load_3": "1",
        "window_start": "09:00:00",
        "window_end": "17:00:00",
        "window_start_2": null,
        "window_end_2": null,
        "duration": "00:00:00",
        "contact_name": "Cliente",
        "contact_email": "[email protected]",
        "contact_phone": "56995466337",
        "tags": [],
        "visit_type": null,
        "notes": "The doorbell is faulty",
        "priority_level": null,
        "custom_properties": {
            "price": 100
        }
    }
]

    Once you have created your custom property, you can use it in the creation and modification of client records.

    ForceField

    Example Request

    [
    {
        "key": "SFKK8976678",
        "title": "Cliente Ejemplo",
        "address": "Pedro Montt 2246, Valparaíso, V Región, Chile",
        "latitude": "-33.047400",
        "longitude": "-71.612920",
        "skills_required": [],
        "skills_optional": [],
        "load": "4",
        "load_2": "2",
        "load_3": "1",
        "window_start": "09:00:00",
        "window_end": "17:00:00",
        "window_start_2": null,
        "window_end_2": null,
        "duration": "00:00:00",
        "contact_name": "Cliente",
        "contact_email": "[email protected]",
        "contact_phone": "56995466337",
        "tags": [],
        "visit_type": null,
        "notes": "The doorbell is faulty",
        "priority_level": null,
        "sales_visit_scheduled": {
            "period": 7,
            "interval": 4,
            "frequency": 2
        },
        "scheduled_visit_days": {
            "any_week": [
                "Monday",
                "Tuesday"
            ]
        },
        "custom_properties": {
            "price": 100,
            "currency": "USD"
        }
    },
        {
        "key": "SFKK89766100",
        "title": "Cliente 2 Ejemplo",
        "address": "Pedro Montt 2250, Valparaíso, V Región, Chile",
        "latitude": "-33.047400",
        "longitude": "-71.612920",
        "skills_required": [],
        "skills_optional": [],
        "load": "4",
        "load_2": "2",
        "load_3": "1",
        "window_start": "09:00:00",
        "window_end": "17:00:00",
        "window_start_2": null,
        "window_end_2": null,
        "duration": "00:00:00",
        "contact_name": "Cliente 2",
        "contact_email": "[email protected]",
        "contact_phone": "56995466337",
        "tags": [],
        "visit_type": null,
        "notes": "The doorbell is faulty",
        "priority_level": null,
        "sales_visit_scheduled": {
            "period": 28,
            "interval": 1,
            "frequency": 3
        },
        "scheduled_visit_days": {
            "week_3": [
              "Monday",
              "Tuesday",
              "Sunday"
            ]
        },
        "custom_properties": {
            "price": 200,
            "currency": "USD"
        }
    }
]

    To use the ForceField attributes, it is necessary to activate the territory_planner addon. The new attributes are sales_visit_scheduled and scheduled_visit_days. These can be used in the endpoints for creating, modifying, and retrieving customers.

    Sales Visit Schedule Object

    Attributes Data Type Description
    frequency Integer Represents the number of times a client should be visited within a given period.
    period Integer Represents the duration of a visit cycle for a particular client. Possible values are weekly (7), biweekly (14), or monthly (28).
    interval Integer Represents the time gap between visits.
    seller Integer Specifies who conducts the visit to the client, which can be either a seller or a vehicle.

    Client Scheduled Visit Day Object

    This object defines the days of the week on which a client is scheduled for visits. The attributes are organized by weeks, including a general option for any week where no specific week is predefined. Each attribute lists the possible days of the week that can be selected for scheduling.

    Attributes Data Type Description
    any_week Array This attribute is used when there is no predefined week. Possible values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
    week_1 Array This attribute corresponds to the first week of the month. Possible values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
    week_2 Array This attribute corresponds to the second week of the month. Possible values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
    week_3 Array This attribute corresponds to the third week of the month. Possible values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.
    week_4 Array This attribute corresponds to the fourth week of the month. Possible values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.

    Users

    A user for SimpliRoute is a courier who will make deliveries through our mobile app

    List users

    URL Definition

    
 GET https://api.simpliroute.com/v1/accounts/drivers/

    Example Response ```json [{ "id": 114, "username": "user2", "name": "", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1477, "created": "2016-06-24T20:47:06.859895Z", "modified": "2016-06-30T20:04:51.043122Z", "last_login": null }, { "id": 24, "old_id": 930, "username": "test", "name": "Test", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1477, "created": "2016-06-24T20:47:06.859895Z", "modified": "2016-06-30T20:04:51.043122Z", "last_login": null }]

    ## Create user

With the following endpoint you can create via API a user

> URL Definition

```url

POST https://api.simpliroute.com/v1/accounts/drivers/

    Example Body ```json [{ "username": "testtest2", "name": "Conductor 1", "phone": "", "email": "", "is_admin": false, "password": "driver", "is_driver": true }]

    > Example Response
```json
[{
    "id": 40779,
    "username": "testtest2",
    "name": "Conductor 1",
    "phone": "",
    "email": "",
    "is_owner": false,
    "is_admin": false,
    "is_driver": true,
    "is_router_jr": false,
    "is_monitor": false,
    "is_coordinator": false,
    "is_router": false,
    "is_staff": false,
    "old_id": null,
    "created": "2020-03-19T19:13:45.178268Z",
    "modified": "2020-03-19T19:13:45.223900Z",
    "last_login": null
}]

    Get a determine user

    URL Definition

    
GET https://api.simpliroute.com/v1/accounts/drivers/{{user_id}}/

    Example Response json [ {"id": 203, "username": "driver33", "name": "Driver 3", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1979, "created": "2016-08-01T20:23:31.966307Z", "modified": "2016-08-01T20:23:32.158526Z", "last_login": null } ]

    Update user

    URL Definition

    
PUT https://api.simpliroute.com/v1/accounts/drivers/{{USER_ID}}/

    Example Body ```json [{ "username": "driver3", "name": "Driver 3", "email": "", "is_admin": false, "password": "driver" }]

    > Example Response
``` json
[{
    "id": 24,
  "old_id": 930,
  "username": "test",
  "name": "Test",
  "created": "2016-03-08T15:54:03.095458Z",
  "modified": "2016-03-08T15:54:03.268615Z",
  "last_login": null}]

    Delete user

    URL Definition

    
DELETE https://api.simpliroute.com/v1/accounts/drivers/{{user_id}}/

    Skills

    Skills are ways to tag our visitors and vehicles so that the algorithm uses those tags as constraints. If a visitor has the required skill "COLD" the vehicles that can transport that dispatch must also have the skill "COLD".

    To get the list of skills

    URL Definition

    
GET https://api.simpliroute.com/v1/routes/skills/

    Example response

    
[
  {
    "id": 295,
    "skill": "armijo",
    "created": "2017-01-24T21:06:42.545448Z",
    "modified": "2017-01-24T21:06:42.545683Z"
  },
  {
    "id": 296,
    "skill": "calderon",
    "created": "2017-01-24T21:06:46.328027Z",
    "modified": "2017-01-24T21:06:46.328273Z"
  }
 ]

    Webhooks

    Use webhooks to be notified about events that happen in a SimpliRoute account.

    How to work with SimpliRoute's webhooks

    SimpliRoute can send webhook events that notify your application any time an event happens on your account. This is especially useful for events—like completed or failed deliverURLs that we will notify any time an event happens in your account. When the event occurs, SimpliRoute will send a POST evento to your URL.

    This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. SimpliRoute then sends the Event object, via an HTTP POST request, to any endpoint URLs that you have defined in your account’s Webhooks settings.ies that are not triggered by a direct API request. This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

    Which events can be notified

    Currently, SimpliRoute can notify this events:

    • Plan created
    • Plan edition
    • Route creation
    • Route edition
    • Route deletion
    • Route started
    • Route Finish
    • Visit created
    • Visit updated
    • On it`s way
    • Checkout
      • Completed delivery
      • Failed delivery
      • Partial Delivery
    • Checkout detailed

    If you need some other events, let us know to add them to our roadmap. Feel free to reach us over email to [email protected]

    Configuring your Webhooks settings

    We describe the steps to follow to read, create, update and delete webhooks via API

    Available webhooks

    • plan_created
    • plan_edited
    • route_created
    • route_edited
    • route_started
    • route_finished
    • on_its_way
    • visit_checkout
    • visit_checkout_detailed

    Important: Each webhook is related to a url and headers. For example: route_created is related to: - route_created_webhook_url - route_created_webhook_headers

    Additionally, requests must include the header:

    Example Headers

    [{
    Content-Type: application/json
    authorization: token {{TOKEN}}
}]

// Where {{TOKEN}} equals the SR account token.
    Attributes Description
    webhook Name of the available webhook object.
    url URL provided by the customer
    headers Necessary parameters for communication towards the final server

    If you have doubts or problems to configure Webhooks - Send an emails to our team [email protected] - In this email, send the URL that you want to receive the webhook. - We'll let you know when the configuration is ready.

    Create Webhook

    URL Definition

    
POST https://api.simpliroute.com/v1/addons/webhooks

    Example body

    {
  "webhook": "plan_created",
  "url": "https://estoesunwebhookdeprueba.com",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Token 16a57ec5ad76c627959c75323274d33d8cc0451e"
  }
}

    Example response

    [
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Token 16a57ec5ad76c627959c75323274d33d8cc0451e\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  }
]

    List Webhooks

    URL Definition

    
GET https://api.simpliroute.com/v1/addons/webhooks

    Example response

    [
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Token 16a57ec5ad76c627959c75323274d33d8cc0451e\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  }
]

    Update Webhooks

    URL Definition

    
PUT https://api.simpliroute.com/v1/addons/webhooks

    Example body

    {
  "webhook": "plan_created",
  "url": "https://estoesunwebhookdeprueba.com/nueva-url",
  "headers": {
    "Content-Type": "application/json"
  }
}

    Example response

    [
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com/nueva-url",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team"
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\":\"application/json\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team"
  }
]

    Delete Webhooks

    URL Definition

    
DELETE https://api.simpliroute.com/v1/addons/webhooks

    Example body

    {
    "webhook": "plan_created"
}

    Example response

    [{
  "message": "The webhook was deleted"
}]

    Webhook Plan creation

    SimpliRoute is able to send Webhook for Plan creation, the information available is detailed in the table above at the moment the Plan is created using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

    URL Definition

    
POST https://api.simpliroute.com/v2/plans/create-plan/

    Example

    [{
  "account_id": 295,
  "id": "9503f703-ba7c-41a0-b91f-3bcebeca7b17",
  "start_date": "2020-03-19",
  "end_date": "2020-03-19",
  "reset_day": 1,
  "route_ids": [
    "9894ddcd-e844-4c77-90e8-9d9a2a226f05"
  ],
  "fleet_id": 647
}]
    Attributes Type Description
    id UUID Plan ID
    account_id int Account id.
    start_date Date format YYYY-MM-DD The date when the plan starts.
    end_date Date format YYYY-MM-DD The date when the plan ends.
    reset_day Int, 1=Monday, 2=Tuesday…, 100=no reset The day when the plan resets.
    route_ids Array of uuid List of the routes in the plan.
    fleet_id int Id of the fleet assigned to the plan

    Webhook Plan edition

    SimpliRoute is able to send Webhook when a plan is edited. To use this webhook, the customer should provide a webservice prepared to process POST requests with the information detailed in the tables above.

    The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

    URL Definition

    
POST https://api.simpliroute.com/v2/plans/edit-plan/

    Example 

    {
 "id": "9b420e42-m492-29m1-a214-f2ad927707b4",
 "account": {
   "id": 1,
   "name": "[email protected]"
 },
 "end_date": "2019-12-24",
 "reset_day": 1,
 "start_date": "2019-12-24",
 "fleet_id": 647,
 "routes": [
   {
     "id": "900787e1-k582-0185-9eeb-d93b68c98b85",
     "planned_date": "2019-12-24",
     "total_load": 50,
     "total_load_2": 0,
     "total_load_3": 0,
     "estimated_time_end": "11:37:00",
     "estimated_time_start": "09:00:00",
     "comment": null,
     "driver": {
       "id": 1,
       "name": "Driver Demo"
     },
     "vehicle": {
       "id": 1,
       "reference": "XXXX11",
       "name": "Vehicle Demo"
     },
     "visits": [
       {
         "id": 20661418,
         "title": "foo",
         "planned_date": "2019-12-24",
         "latitude": "-33.370405",
         "longitude": "-70.684798",
         "load": 0,
         "load_2": 0,
         "load_3": 0,
         "duration": "0:10:00",
         "estimated_time_departure": "09:30:00",
         "estimated_time_arrival": "09:20:00",
         "notes": "",
         "order": 1
       },
       {
         "load": 25,
         "estimated_time_departure": "10:00:00",
         "planned_date": "2019-12-24",
         "load_3": 0,
         "load_2": 0,
         "duration": "0:15:00",
         "estimated_time_arrival": "09:45:00",
         "id": 20661406,
         "title": "bar",
         "notes": "",
         "longitude": "-70.758134",
         "latitude": "-33.384390",
         "order": 2
       },
       {
         "load": 0,
         "estimated_time_departure": "10:24:00",
         "planned_date": "2019-12-24",
         "load_3": 0,
         "load_2": 0,
         "duration": "0:10:00",
         "estimated_time_arrival": "10:14:00",
         "id": 20661420,
         "title": "foo-bar",
         "notes": "",
         "longitude": "-70.703681",
         "latitude": "-33.427045",
         "order": 3
       }       
     ]     
   }
 ]
}

    Plan Object

    Attributes Type Description
    id UUID Plan ID
    account {id, name} id: int - name: string. Account information.
    start_date Date format YYYY-MM-DD The date when the plan starts.
    end_date Date format YYYY-MM-DD The date when the plan ends.
    reset_day Int, 1=Monday, 2=Tuesday…, 100=no reset The day when the plan resets.
    fleet_id int Id of the fleet assigned to the plan
    routes list(Route) List of the routes in the plan. See Route Object for details.

    Route Object

    Attributes Type Description
    id UUID Id of the route in SimpliRoute.
    planned_date date (YYYY-MM-DD) Date of the route
    total_load double The total load 1 of the route.
    total_load2 double The total load 2 of the route.
    total_load_3 double The total load 3 of the route.
    estimated_time_start time (hh:mm:ss) Estimated time of the route to start in local timezone of the account.
    estimated_time_end time (hh:mm:ss) Estimated time of the route to end in local timezone of the account.
    comment string Comment of the route.
    driver {id, name} id: id of the driver in SimpliRoute- name: name of the driver Driver information.
    vehicle {id, reference, name} id: id of the vehicle in SimpliRoute.reference: reference id, it could be the licence plate for example.name: name of the vehicle in SimpliRoute Vehicle information
    visits list(Visit) List of the visits in the route. See Visit Object for details.

    Visit Object

    Attributes Type Description
    id int Id of the visit in SimpliRoute.
    title string Title of the visit.
    planned_date Date format YYYY-MM-DD Date of the delivery.
    latitude double The date when the plan ends.
    longitude double The day when the plan resets.
    load double Load 1.
    load2 double Load 2.
    load3 double Load 3.
    duration double Service time of the visit.
    estimated_time_arrival double Estimated time to arrive to the visit.
    estimated_time_departure double Estimated time of departure from the visit. It should be estimated_time_arrival + duration.
    notes string Notes of the visit.
    order int Order of the visit in the route

    Webhook Route creation

    SimpliRoute can send Webhooks for route creation, the available information is detailed in the table below. At the time the route is created using the POST method with headers that the client can specify. The webhook expects a response with status code 200; otherwise, it will try again after 30 seconds, a maximum of 3 times in total.

    Example body

    {
  "id": "e5bb5b51-d494-483f-8180-ace00c89c06d",
  "comment": null,
  "planned_date": "2024-01-12",
  "plan": {
    "id": "1ef9f5c4-2197-41da-8f23-adfcabd272b5",
    "name": "12-01-2024 14:53:03"
  },
  "driver": {
    "id": 118553,
    "name": "rapidoqa1"
  },
  "route_start": {
    "lat": "-33.449977",
    "lon": "-70.654465",
    "address": "Lord Cochrane 298, Santiago, Chile",
    "start_time": null,
    "estimated_time_start": "09:42:00"
  },
  "route_end": {
    "lat": "-33.449977",
    "lon": "-70.654465",
    "address": "Lord Cochrane 298, Santiago, Chile",
    "estimated_time_end": "10:08:00",
    "end_time": null
  },
  "visit_ids": [
    370679703
  ],
  "info_visits": [
    {
      "id": 370679703,
      "reference": "",
      "tracking_id": "SR68561793642931",
      "order": 1,
      "estimated_time_arrival":"09:42:00",
      "notes":"notes"
    }
  ],
  "vehicle": {
    "id": 266603,
    "name": "VEH1F",
    "reference": "XXX333"
  },
  "timestamp": "2024-01-30 15:14:45.708968",
  "order": 3,
  "status": "created"
}
    Attributes Type Description
    vehicle {id, name} id: int - name: string Vehicle information.
    plan {id, name} id: int - name: string Plan information
    timestamp timestamp UTC timestamp of the creation of the route.
    route_start {lat, lon, start_time, estimated_time_start, address} lat: float - lon: float - start_time: time - estimated_time_start: time - address: string Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
    route_end {lat, lon, end_time, estimated_time_end, address} lat: float - lon: float - end_time: time - estimated_time_end: time- address: string. Route end information
    planned_date Date in format YYYY-MM-DD. Date for the route.
    visit_ids id List of the visit ids in the route.
    driver {id, name} id: int - name: string. Driver information.
    order int show the order of the vehicle route.
    status string Display the operation's status event, 'created'

    Webhook Route edition

    SimpliRoute can send Webhooks for route edition, the available information is detailed in the table below. At the time the route is updated using the POST method with headers that the client can specify. The webhook expects a response with status code 200; otherwise, it will try again after 30 seconds, a maximum of 3 times in total.

    Example body

    [
  {  
   "vehicle":{  
      "id":1,
      "name":"Test",
      "reference": "1234FF"
   },
   "plan":{  
      "id":"528e6fa8-129d-4049-9a3c-8ad5ea12502e",
      "name":"Plan name"
   },
   "timestamp":"2019-07-17 14:32:14.799962",
   "route_start":{  
      "lat":"-33.448890",
      "start_time":null,
      "estimated_time_start":"09:00:00",
      "lon":"-70.669265",
      "address":"Santiago, Chile"
   },
   "route_end":{  
      "lat":"-33.448890",
      "lon":"-70.669265",
      "end_time":null,
      "estimated_time_end":"16:23:00",
      "address":"Santiago, Chile"
   },
   "planned_date":"2019-07-17",
   "visit_ids":[15901924, 15901923, 15901922, 15901921, 15901920, 15901919, 15901918, 15901917, 15901916, 15901915, 15901914, 15901913, 15901912, 15901911, 15901910, 15901909],
   "info_visits": [
        {
          "id": 15901924, "reference": "", "tracking_id": "SR88515397622033", "order": 1,   "estimated_time_arrival":"09:42:00", "notes":"notes",
          "id": 15901923, "reference": "", "tracking_id": "SR88515397622034", "order": 2, "estimated_time_arrival":"09:42:00", "notes":"notes",
          "id": 15901922, "reference": "", "tracking_id": "SR88515397622035", "order": 3, "estimated_time_arrival":"09:42:00", "notes":"notes",
          "id": 15901921, "reference": "", "tracking_id": "SR88515397622036", "order": 4, "estimated_time_arrival":"09:42:00", "notes":"notes"
        }
    ],
   "driver":{  
      "id":23870,
      "name":"Conductor 1"
   },
   "order":1,
   "status":"edited",
   "id":"51019ab7-c464-4503-bcd6-d00c3d6209f2"
}]
    Attributes Type Description
    vehicle {id, name} id: int - name: string Vehicle information.
    plan {id, name} id: int - name: string Plan information
    timestamp timestamp UTC timestamp of the creation of the route.
    route_start {lat, lon, start_time, estimated_time_start, address} lat: float - lon: float - start_time: time - estimated_time_start: time - address: string Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
    route_end {lat, lon, end_time, estimated_time_end, address} lat: float - lon: float - end_time: time - estimated_time_end: time- address: string. Route end information
    planned_date Date in format YYYY-MM-DD. Date for the route.
    visit_ids id List of the visit ids in the route.
    info_visits list(visit) List of the visits in the route.
    driver {id, name} id: int - name: string. Driver information.
    order int show the order of the vehicle route.
    status string Display the operation's status event, indicating whether the route has been edited or deleted.

    Webhook Route started

    SimpliRoute is able to send Webhook for route started, the information available is detailed in the table above at the moment the route is started using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

    Url Definition

    
POST https://api.simpliroute.com/v1/events/register/

    Example request

    
curl 
--location 
--request POST 'http://api.simpliroute.com/v1/events/register/' \
--header 'Authorization: Token b2de5a16bccec465aeb9083a4db41e1666520uij' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "date_time" : "2020-05-27 16:35:00",
    "route_id": "402ecd99-a0c9-418c-9cd9-088a0cb70242",
    "type" : "ROUTE_STARTED"
}'

    Example 

    [
{
  "vehicle": {
    "id": 101174,
    "name": "KGST"
  },
  "plan": {
    "id": "728c5d34-ff14-4ccf-9fd8-16257f4332e9",
    "name": "26-05-2020 21:37:25"
  },
  "timestamp": "2020-05-27 20:43:40.650476",
  "route_start": {
    "lat": "-33.459425",
    "start_time": "2020-05-27 16:35:00+00:00",
    "estimated_time_start": "09:00:00",
    "lon": "-70.654531",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "route_end": {
    "lat": "-33.459425",
    "lon": "-70.654531",
    "end_time": null,
    "estimated_time_end": "09:15:00",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "planned_date": "2020-05-26",
  "visit_ids": [
    32397185
  ],
  "driver": {
    "id": 26351,
    "name": "Flash"
  },
  "id": "e1d12cf7-25c6-4f01-98d5-83a52c9b3aed"
}
]
    Attributes Type Description
    vehicle {id, name} id: int - name: string Vehicle information.
    plan {id, name} id: int - name: string Plan information
    timestamp timestamp UTC timestamp of the creation of the route.
    route_start {lat, lon, start_time, estimated_time_start, address} lat: float - lon: float - start_time: time - estimated_time_start: time - address: string Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
    route_end {lat, lon, end_time, estimated_time_end, address} lat: float - lon: float - end_time: time - estimated_time_end: time- address: string. Route end information
    planned_date Date in format YYYY-MM-DD. Date for the route.
    visit_ids id List of the visit ids in the route.
    driver {id, name} id: int - name: string. Driver information.
    id id String with the route id.

    Webhook Route Finish

    SimpliRoute is able to send Webhook for finished route, the information available is detailed in the table above at the moment the route is started using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

    Url Definition

    
POST https://api.simpliroute.com/v1/events/register/

    Example request

    curl 
--location 
--request POST 'http://api.simpliroute.com/v1/events/register/' \
--header 'Authorization: Token b2de5a16bccec465aeb9083a4db41e1666520uij' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "date_time" : "2020-05-27 17:35:00",
    "route_id": "402ecd99-a0c9-418c-9cd9-088a0cb70242",
    "type" : "ROUTE_FINISHED"
}'

    Example 

    [{
  "vehicle": {
    "id": 101174,
    "name": "KGST"
  },
  "plan": {
    "id": "728c5d34-ff14-4ccf-9fd8-16257f4332e9",
    "name": "26-05-2020 21:37:25"
  },
  "timestamp": "2020-05-27 20:46:01.471879",
  "route_start": {
    "lat": "-33.459425",
    "start_time": "2020-05-27 16:35:00+00:00",
    "estimated_time_start": "09:00:00",
    "lon": "-70.654531",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "route_end": {
    "lat": "-33.459425",
    "lon": "-70.654531",
    "end_time": "2020-05-27 17:35:00+00:00",
    "estimated_time_end": "09:15:00",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "planned_date": "2020-05-26",
  "visit_ids": [
    32397185
  ],
  "driver": {
    "id": 26351,
    "name": "Flash"
  },
  "id": "e1d12cf7-25c6-4f01-98d5-83a52c9b3aed"
}
]
    Attributes Type Description
    vehicle {id, name} id: int - name: string Vehicle information.
    plan {id, name} id: int - name: string Plan information
    timestamp timestamp UTC timestamp of the creation of the route.
    route_start {lat, lon, start_time, estimated_time_start, address} lat: float - lon: float - start_time: time - estimated_time_start: time - address: string Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
    route_end {lat, lon, end_time, estimated_time_end, address} lat: float - lon: float - end_time: time - estimated_time_end: time- address: string. Route end information
    planned_date Date in format YYYY-MM-DD. Date for the route.
    visit_ids id List of the visit ids in the route.
    driver {id, name} id: int - name: string. Driver information.

    Webhook On it`s way

    SimpliRoute can send visit information at the time an on 'its way' event is launched by calling a POST method to a webservice provided by clients, the available information is described in the following table (not necessarily in that order) . The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

    Example body

    Attributes Type Description
    id int Id of the visit in SimpliRoute.
    load double Load 1.
    load2 double Load 2.
    load3 double Load 3.
    window_start Time Initial Hour when the visit can be visit
    window_end Time Final Hour when the visit can be visit
    window_start_2 Time Initial Hour when the visit can be visit
    window_end_2 Time Final Hour when the visit can be visit
    reference String Reference or internal identifier of the company. Example: Invoice or order number.
    planned_date date YYYY-MM-DD Date for the route.
    order int planned delivery order
    checkout_comment text Comments on delivery time
    duration time Service time
    calculated_service_time time Calculated service time
    title varchar(254) Visit Title.
    contact_name varchar(254) Contact name
    contact_email text e-mail contat
    contact_phone varchar(254) Contact phone
    notes text Notes of the visit .
    latitude numeric(9,6) Latitud of the visit
    longitude numeric(9,6) Longitud of the visit
    status varchar(100) Status of the visit: pending, completed or failed.
    address varchar(254) Address of the visit
    account varchar(254) Account name
    route varchar(254) Route name.
    status_changed timestamp Date and time of the last status change.
    priority_level int Visit priority.
    created timestamp Creation time of the visit.
    modified timestamp Time of the last modification of the visit.
    estimated_time_arrival time estimated time of arrival to the visit.
    current_eta date Estimated time of arrival of the visit.
    estimated_time_departure time estimated time of departure from the visit.
    tracking_id varchar(254) Tracking id.
    signature varchar(100) Address where the signature is stored
    checkin_time timestamp Arrival time at visit (by GPS driver).
    checkin_latitude numeric(9,6) Latitude of arrival at the visit.
    checkin_longitude numeric(9,6) Longitude of arrival at visit.
    checkout_longitude numeric(9,6) Longitude of checkout.
    checkout_observation uuid Id of the observation selected at checkout.
    checkout_latitude numeric(9,6) Latitude of checkout
    checkout_time timestamp Checkout date and time.
    geocode_alert varchar(22) Alert when georeferencing the address.
    postal_code varchar(15) Zip Code if the visit.
    programmed_date date Scheduled date of visit.
    visit_type json Type of the visit that is being made.
    fleet json Information of the fleet to which the visit belongs.
    has_alert boolean Deprecated.
    priority boolean Deprecated.

    Webhook Checkout

    SimpliRoute can send information about the visit at the time of checkout through a POST method call to a webservice provided by clients, the available information is described in the following table (not necessarily in that order). The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

    Example body

    Ejemplo:
[{
   "id": 18843965,
   "load": 0.0,
   "load_2": 0.0,
   "load_3": 0.0,
   "window_start": "09:00:00",
   "window_end": "19:00:00",
   "window_start_2": "23:59:00",
   "window_end_2": "23:59:00",
   "reference": "",
   "planned_date": "2019-09-09",
   "order": 4,
   "checkout_comment": "Test",
   "duration": "0:20:00",
   "calculated_service_time": "0:00:00",
   "title": "INDUSTRIAS RIC\u00d3N",
   "contact_name": "Victor Gonzalez",
   "contact_email": "",
   "contact_phone": "978567812",
   "notes": "",
   "latitude": "-33.439046",
   "longitude": "-70.648752",
   "status": "completed",
   "address": "HUERFANOS 835 OF. 202, SANTIAGO, Santiago",
   "account": "[email protected]",
   "route": "2019-09-09 - Test",
   "status_changed": "2019-09-09 21:23:01.251595+00:00",
   "priority_level": 0,
   "created": "2019-08-29 22:33:44.015108+00:00",
   "modified": "2019-09-09 21:23:01.251582+00:00",
   "estimated_time_arrival": "10:12:00",
   "estimated_time_departure": "10:32:00",
   "tracking_id": "SR67118024023080",
   "signature": "visit-signatures/2019/09/09/ac6bf49a-35b.png",
   "checkin_time": null,
   "checkin_latitude": null,
   "checkin_longitude": null,
   "checkout_observation": null,
   "checkout_latitude": "-33.420471",
   "checkout_longitude": "-70.603384",
   "checkout_time": "2019-09-09 21:22:56.068000+00:00",
   "on_its_way": null,
   "geocode_alert": null,
   "has_alert": false,
   "priority": false
}]
    Attributes Type Description
    id int Id of the visit in SimpliRoute
    load double Load 1
    load2 double Load 2
    load3 double Load 3
    window_start time Start time window 1. Format HH:MM:SS
    window_end time End time window 1. Format HH:MM:SS
    window_start_2 time Start time window 2. Format HH:MM:SS
    window_end_2 time End time window 2. Format HH:MM:SS.
    reference varchar(254) Visit reference
    planned_date date Delivery date. Format YYYY-MM-DD
    order int Planned delivery order
    checkout_comment string Comments upon delivery
    duration time Service time of the visit
    checkout_comment string Comments upon delivery
    duration time Service time
    calculated_service_time time Calculated service time
    title varchar(254) Title of the visit
    contact_name varchar(254) Contact name
    contact_email string Contact e mail
    contact_phone varchar(254) Contact phone number
    notes string Notes of the visit
    latitude double Latitude of the visit
    longitude double Longitude of the visit
    status varchar(100) Status of the visit: pending, completed, failed, partial
    address varchar(254 Address of the visit
    account varchar(254 Account name
    route varchar(254 Route name
    status_changed timestamp Date and time of the last status change
    priority_level integer Priority of the Visit. Ej 1 high priority, 2 second priority
    created timestamp Creation time of the visit.
    modified timestamp Time of the last modification of the visit.
    estimated_time_arrival time Estimated time of arrival for the visit
    estimated_time_departure time Estimated time of departure from the visit.
    tracking_id varchar(254) Id of tracking
    signature varchar(100) Address where the signature is stored.
    checkin_time timestamp Arrival time for the visit (by GPS driver).
    checkin_latitude double Latitude of arrival at the visit
    checkin_longitude doube Longitude of arrival at the visit
    checkout_observation uuid Id of the observation selected at checkout
    checkout_latitude double Checkout latitude
    checkout_longitude double Checkout longitude
    checkout_time timestamp Checkout date and time
    on_its_way timestamp Date and time when “On its way” was marked.
    geocode_alert Alert when georeferencing the address

    Webhook Checkout detailed

    SimpliRoute can send detailed information about the visit at the time of checkout through a POST method call to a webservice provided by the clients, the information available is described in the following table (not necessarily in that order). The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

    Example 

    {
    "load": 50.0,
    "window_start": "09:00:00",
    "reference": "96018725010003",
    "planned_date": "2020-09-02",
    "has_alert": false,
    "address": "SANTA MARIA 2670, PROVIDENCIA, Santiago",
    "load_3": 0.0,
    "load_2": 0.0,
    "programmed_date": null,
    "window_end": "19:00:00",
    "postal_code": null,
    "longitude": "-70.609643",
    "duration": "0:20:00",
    "status_changed": "2020-09-02 22:36:12.886508+00:00",
    "contact_name": "Paulina Mu\u00f1oz",
    "id": 44678051,
    "window_start_2": "23:59:00",
    "visit_type": null,
    "title": "CONFITERIA SAN RODRIGO",
    "pictures": [
    "https://simpli-visit-images-dev.s3.amazonaws.com/visit-pictures/2020/09/02/vi93grwrv.jpg"
    ],
    "checkout_longitude": "-122.406417",
    "priority": false,
    "checkout_observation": null,
    "latitude": "-33.416713",
    "contact_phone": "967603803",
    "status": "completed",
    "estimated_time_departure": "09:37:00",
    "route": {
        "comment": "Comentario",
        "vehicle": { 
            "id": 153969, 
            "name": "asd",
            "reference": "1234FF"
        },
        "plan": {
            "id": "9ab4c716-020d-44cd-a90c-4dc88cabf884",
            "name": "2-09-2020 18:34:49"
        },
        "timestamp": "2020-09-02 22:36:16.361577",
        "route_start": {
            "lat": "-33.415468",
            "start_time": "2020-09-02 22:35:48.034000+00:00",
            "estimated_time_start": "09:00:00",
            "lon": "-70.667961",
            "address": "Avenida Domingo Santa Mar\u00eda 12, Independencia, Chile"
        },
        "route_end": {
            "lat": "-33.415468",
            "lon": "-70.667961",
            "end_time": null,
            "estimated_time_end": "11:41:00",
            "address": "Avenida Domingo Santa Mar\u00eda 12, Independencia, Chile"
        },
        "planned_date": "2020-09-02",
        "visit_ids": [44678051, 44678052, 44678053, 44678054, 44678055],
        "driver": { "id": 75388, "name": "f" },
        "id": "e05b954e-754d-4774-b91b-000859eef55b"
    },
    "window_end_2": "23:59:00",
    "extra_field_values": {
        "numero_interior": null,
        "cantidad": null,
        "codigo_postal": null,
        "entre_calles_1": null,
        "edificio": null,
        "comentarios": null,
        "remision": null
    },
    "checkout_time": "2020-09-02 22:36:12.330000+00:00",
    "geocode_alert": null,
    "contact_email": "[email protected]",
    "current_eta": null,
    "calculated_service_time": "0:00:00",
    "account": { "id": 28387, "name": "11FabianUrrutia" },
    "priority_level": 0,
    "checkout_latitude": "37.785834",
    "observation": {},
    "created": "2020-09-02 22:35:01.950457+00:00",
    "on_its_way": null,
    "checkin_time": null,
    "modified": "2020-09-02 22:36:12.886496+00:00",
    "checkout_comment": "Comentario del conductor",
    "order": 1,
    "estimated_time_arrival": "09:17:00",
    "tracking_id": "SR99086101951738",
    "signature": "",
    "checkin_latitude": null,
    "fleet": null,
    "notes": "",
    "checkin_longitude": null,
    "plan": {
        "route_ids": ["e05b954e-754d-4774-b91b-000859eef55b"],
        "fleet_id": null,
        "name": "2-09-2020 18:34:49",
        "end_date": "2020-09-02",
        "reset_day": 1,
        "id": "9ab4c716-020d-44cd-a90c-4dc88cabf884",
        "account_id": 28387,
        "start_date": "2020-09-02"
    },
    "invoices": [{
        "id": "21bbbce0-d97f-4735-bd58-afa510c20398",
        "reference": "08224267",
        "type": "bill",
        "items": [{
            "id": 198907,
            "delivery_issue": null,
            "product": "5be6599e-652d-4dcd-b2a2-c6899d4d63ac",
            "reference": "121076",
            "status": "completed",
            "title": "Nordic Zero Ginger Ale PT3,0 x 6",
            "sku": "121076",
            "unit_price": 9335,
            "planned_units": 10,
            "delivered_units": 10,
            "type": "pack"
        },
        {
            "id": 198908,
            "delivery_issue": null,
            "product": null,
            "reference": "122615",
            "status": "completed",
            "title": "Vital C/G PT 1,6 x 6 term.",
            "sku": "122615",
            "unit_price": 13744,
            "planned_units": 10,
            "delivered_units": 10,
            "type": "pack"
        },
        {
            "id": 198909,
            "delivery_issue": {
                "id": 115,
                "title": "14 Duplicado/Mal digitado"
            },
            "product": null,
            "reference": "120111",
            "status": "failed",
            "title": "Coca Cola RP2,0cc x 8",
            "sku": "120111",
            "unit_price": 9916,
            "planned_units": 10,
            "delivered_units": 0,
            "type": "box"
        }],
        "label": null,
        "payment_method": "cash",
        "payment_method_details": null,
        "status": "partial"
    }]
}
    Attributes Type Description
    id int Id of the visit in SimpliRoute
    load double Load 1
    load2 double Load 2
    load3 double Load 3
    window_start time Start time window 1. Format HH:MM:SS
    window_end time End time window 1. Format HH:MM:SS
    window_start_2 time Start time window 2. Format HH:MM:SS
    window_end_2 time End time window 2. Format HH:MM:SS.
    reference varchar(254) Visit reference
    planned_date date Delivery date. Format YYYY-MM-DD
    order int Planned delivery order
    checkout_comment string Comments upon delivery
    duration time Service time of the visit
    checkout_comment string Comments upon delivery
    duration time Service time
    calculated_service_time time Calculated service time
    title varchar(254) Title of the visit
    contact_name varchar(254) Contact name
    contact_email string Contact e mail
    contact_phone varchar(254) Contact phone number
    notes string Notes of the visit
    latitude double Latitude of the visit
    longitude double Longitude of the visit
    status varchar(100) Status of the visit: pending, completed, failed, partial
    address varchar(254 Address of the visit
    account varchar(254) Account name
    account.id integer Id of the account
    account.name varchar(254) Account namme
    route varchar(254) Route name
    route.id varchar(254) Id of the route
    route.comment varchar(254) Route name
    route.driver varchar(254) Route name
    route.driver.id varchar(254) Route name
    route.driver.name varchar(254) Route name
    route.plan varchar(254) Route name
    route.plan.id varchar(254) Route name
    route.plan.name varchar(254) Route name
    route.route_start varchar(254) Route name
    route.route_start.address varchar(254) Route name
    route.route_start.estimated_time_start varchar(254) Route name
    route.route_start.lat varchar(254) Route name
    route.route_start.lon varchar(254) Route name
    route.route_start.start_time varchar(254) Route name
    route.route_end varchar(254) Route name
    route.route_end.address varchar(254) Route name
    route.route_end.estimated_time_start varchar(254) Estimated completion time
    route.route_end.lat double Latitude of the end of the route.
    route.route_end.lon double Longitude of the end of the route
    route.route_end.end_time time Real moment of the end of the route
    route.timestamp date Current time of information request.
    route.vehicle json Contains route vehicle information.
    route.vehicle.id integer Id of the vehicle of the route.
    route.vehicle.name varchar(254) Route vehicle name.
    route.visit_ids array Array with a list of visits corresponding to the assigned checkout route
    route.planned_date date Date of the route planning.
    status_changed timestamp Date and time of the last status change
    priority_level integer Priority of the Visit. Ej 1 high priority, 2 second priority
    created timestamp Creation time of the visit.
    modified timestamp Time of the last modification of the visit.
    estimated_time_arrival time Estimated time of arrival for the visit
    estimated_time_departure time Estimated time of departure from the visit.
    tracking_id varchar(254) Id of tracking
    signature varchar(100) Address where the signature is stored.
    checkin_time timestamp Arrival time for the visit (by GPS driver).
    checkin_latitude double Latitude of arrival at the visit
    checkin_longitude doube Longitude of arrival at the visit
    checkout_observation uuid Id of the observation selected at checkout
    checkout_latitude double Checkout latitude
    checkout_longitude double Checkout longitude
    checkout_time timestamp Checkout date and time
    on_its_way timestamp Date and time when “On its way” was marked.
    geocode_alert varchar (22) Alert when georeferencing the address
    pictures array Array with urls of the photos added to the visit.
    postal_code varchar (15) Postal code of the visit.
    programmed_date date Scheduled date of visit.
    visit_type json Type of the visit that is being made.
    extra_fields_values array Extra values ​​of the visit. Format: [{“key”:”value”}]
    current_eta date Estimated time of arrival to the visit.
    observation json Contains observation information added to the visit
    observation.id integer Id of the Observation
    observation.labe varchar (254) Observation visit label
    fleet json Information of the fleet to which the visit belongs.
    plan json Contains plan information associated with the visit
    plan.id uuid id of the plan associated with the visit.
    plan.route_ids array Array with id of the plan routes.
    plan.fleet_id integer id of the fleet which the plan belongs
    plan.name varchar (254) Name of the plan
    plan.end_date date Plan termination date.
    plan.reset_day integer Plan reset time.
    plan.account_id id Id of the account assigned to the plan
    plan.start_date date Plan start date
    invoices list List of invoices of the visit. See Invoice for its fields.

    Optimization

    Optimization Endpoint

    
http://optimizer.simpliroute.com/vrp/optimize/sync

    Due to our wide experience in route optimization, we guarantee this is the best way to create your company's delivery routes. We believe that everyday problems deserve simple solutions, which is why you now have available the API of our algorithm. Solve your logistics delivery problems in the quickest and easiest way possible.

    SimpliRoute gets these restrictions in consideration:

    • Capacities of your vehicles.
    • Different start and end points for your vehicles.
    • Drivers' shifts.
    • Time windows of your clients.
    • And a lot more

    In the next couple of sections, we'll go in deep detail about our API, which objects it contains and a lot of practical examples to start developing your app using our API. If you have questions, you can send us an email to [email protected]

    Optimization Instance

    Input json

    [{
    "vehicles": [
        {
            "ident": "Vehicle 1",
            "location_start": {
                "ident": "warehouse A",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "location_end": {
                "ident": "warehouse C",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "capacity": 3500,
            "capacity_2": 3500,
            "capacity_3": 3500,
            "shift_start": "9:00",
            "shift_end": "22:00",
            "skills": []
        },
        {
            "ident": "Vehicle 2",
            "location_start": {
                "ident": "warehouse B",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "location_end": {
                "ident": "warehouse C",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "capacity": 3500,
            "capacity_2": 3500,
            "capacity_3": 3500,
            "shift_start": "9:00",
            "shift_end": "22:00",
            "skills": []
        }
    ],
    "nodes": [
        {
            "ident": "El Salto 4875",
            "lat": -33.3887,
            "lon": -70.62304,
            "window_start": "09:00",
            "window_end": "17:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
            "duration": 15
        },
        {
            "ident": "Avenida Del Valle 7",
            "lat": -33.39124,
            "lon": -70.61387,
            "load": 2530,
            "window_start": "9:00",
            "window_end": "11:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
            "duration": 15
        },
        {
            "ident": "Larrain 5862",
            "lat": -33.45066,
            "lon": -70.54915,
            "load": 77,
            "window_start": "09:00",
            "window_end": "17:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
            "priority_level": 1,

            "duration": 10
        }
    ],
    "balance": true,
    "all_vehicles": false,
    "join": true,
    "open_ended": false,
    "single_tour": true,
    "fmv": 1.0
}]

    Our API receives JSON object as input. The Optimization json can be divided in this sections:

    • Vehicles: Array of vehicles with their information to be optimized with our API.
    • Nodes: Array of deliveries with their constraints to be routed with our API.
    • Optimization options: Different optimizations criteria to adjust the optimization to your requirements.

    In the following sections, we'll discuss more in detail each of this objects. Also, we'll show a few examples of how to make a request to our API with different use-cases to make easier for you to start coding with SimpliRoute.

    Vehicles

    Vehicle's object example:

    [{
    "ident": "Vehicle 1",
    "location_start": {
        "ident": "warehouse B",
        "lat": -33.4233926,
        "lon": -70.6104996
    },
    "location_end": {
        "ident": "warehouse C",
        "lat": -33.345523,
        "lon": -70.456992
    },
    "capacity": 3500,
    "capacity_2": 3500,
    "capacity_3": 3500,
    "shift_start": "09:00",
    "shift_end": "18:00",
    "refill": 30,     
    "skills": [
        "47076"
        "47054"
    ],
    "zones": [
        14730
    ],
    "max_tour_duration": 40,
    "cost": 100,
    "min_load": 0,
    "min_load_2": 0,
    "min_load_3": 0,
    "max_visit": 35,
    "max_number_of_routes": 2
}]

    When using our API, the first object that you have to understand is the vehicle object. In our API, a vehicle is any moving device in your city, then if you are working with fleet, field services or sales people, all of them should be created as a "vehicle" in our API. Each of the attributes are described below:

    Attributes Mandatory Type Description
    ident Mandatory String Unique identifier for the object.
    location_start Mandatory Object Location of the vehicle when the optimization was called
    location_end Optional Object Location where the vehicle should end its route
    capacity Optional Float Vehicle's capacity load
    capacity_2 Optional Float Vehicle's second capacity load
    capacity_3 Optional Float Vehicle's third capacity load
    shift_start Optional String String "HH:mm" (military time). When the vehicle's shift starts.
    shift_end Optional String String "HH:mm" (military time). When the vehicle's shift ends.
    skills Optional String array Skills that the vehicles supports. Deliveries must have skills in order to be used.
    refill Optional Integer Minutes that takes to refill the vehicle when it returns to the depot before starts a new route.
    zones Optional Integer array Identifiers of the zones to which the vehicle belongs. A vehicle can belong to more than one zone.
    max_tour_duration Optional Integer Maximum minutes that the vehicle is allowed to make all its routes.
    min_load Optional Integer Percentage of minimum load associated with capacity attribute that the vehicle must have to go out on the road.
    min_load_2 Optional Integer Percentage of minimum load associated with capacity_2 attribute that the vehicle must have to go out on the road.
    min_load_3 Optional Integer Percentage of minimum load associated with capacity_3 attribute that the vehicle must have to go out on the road.
    max_visit Optional Integer Maximum number of visits that the routes carried out by the vehicle can have.
    max_number_of_routes Optional Integer Maximum number of routes that each vehicle can have. If the value is 0 or null, the maximum is infinity.
    open_start Optional Boolean When true, this feature allows vehicles to begin their routes from locations other than the depot. It's false by default.
    open_end Optional Boolean When true, this feature allows vehicles to end their routes in locations other than the depot. It's false by default. If open_ended is true, it overwrites this parameter.

    Deliveries

    Delivery's object example:

    [{
    "nodes": [
        {
            "ident": "Delivery 1",
            "group_id": "Delivery 1",
            "lat": -33.3887,
            "lon": -70.62304
        },
        {
            "ident": "Delivery 2",
            "group_id": "Delivery 1",
            "address": "Ricardo Flores Magon # 28. Nave 12. Parque industrial San Jeronimo Caleras. San Jeronimo Caleras, Pue.",
            "lat": -33.39124,
            "lon": -70.61387,
            "load": 253.1,
            "load_2": 2.0,
            "load_2": 3.2,
            "window_start": "09:00",
            "window_end": "11:00",
            "window_start_2": "13:00",
            "window_end_2": "15:00",
            "duration": 15,
            "skills_required": [
                30744,
                47593
            ],
            "skills_optional": [
                30567
            ],
            "priority_level": 2,
            "zones": [
                14730
            ],
            "open_start": true,
            "open_end": false
        }
    ]
}]

    A delivery is something that your vehicle has to do in the street: delivery orders, sales opportunities, field service orders, etc.

    Attributes Mandatory Type Description
    ident Mandatory String Unique identifier for the object.
    lat Mandatory Float Latitude of the delivery's location.
    lon Mandatory Float Longitude of the delivery's location.
    address Optional String Address of the delivery. If there are lat and lon attributes, it will privilege those fields over this
    group_id Optional String Identifier of the delivery to which this delivery will be linked when using join_v2 (see optimization options).
    load Optional Float Load of this delivery. Must be on same units as vehicle's load.
    load_2 Optional Float Secondary load of this delivery. Must be on same units as vehicle's load 2.
    load_3 Optional Float Third load of this delivery. Must be on same units as vehicle's load 3.
    window_start Optional String String "HH:mm" (military time). Minimum time this delivery can be attended.
    window_end Optional String String "HH:mm" (military time). Maximum time this delivery can be attended.
    window_start_2 Optional String String "HH:mm" (military time). Secondary minimum time this delivery can be attended. (Ex: I can visit this place from 10:00 to 12:00 and from 15:00 to 19:00)
    window_end_2 Optional String String "HH:mm" (military time). Secondary maximum time this delivery can be attended.
    duration Optional Integer Minutes that the vehicle will stay on the delivery.
    skills_required Optional Integer array Skills this delivery needs to be fulfilled. Only the vehicles who have all of these skills will attend the delivery.
    skills_optional Optional Integer array Skills this delivery needs to be fulfilled. Only the vehicles who have at least one of these skills will attend the delivery.
    priority_level Optional Integer Used to indicate this delivery is more important than others. Possible values are 1: First of the day, 2: Last of its route, 3: High Priority, 4: Medium Priority, 5: Low Priority.
    zones Optional Integer array Identifier of the zone to which this delivery belongs. Only vehicles that have this area will attend the delivery.

    Optimization options

    SimpliRoute has some additional features allowing you to configure the optimization in the best possible way that fits your company.

    Attributes Mandatory Type Description
    country Mandatory String ISO code referring to the country where the delivery locations are located.
    balance Optional Boolean Default: False. If true, there will be an enforced balance between all the vehicles, in time and number of locations for the algorithm procedure
    fmv Optional Float Default: 2.0, Speed traffic factor. It could be 1.0 = Low Traffic, 1.5 = Medium Traffic, 2.0 = High Traffic or 3.0 = Intense Traffic.
    all_vehicles Optional Boolean Default: False. If true, the algorithm will use all the selected vehicles. If false, will minimize the number of vehicles.
    open_ended Optional Boolean Default: False. If true, the route will be created assuming the vehicle won't return the depot at the end of the day.
    single_tour Optional Boolean Default: False. If true, all vehicles will have only one route.
    join_v2 Optional Boolean Default: False. If true, the algorithm performs a union of visits with the same address, respecting the capacity of the vehicles, and seeking to minimize the number of vehicles that have similar visits.
    beauty Optional Boolean Default: False. If true, the algorithm groups visits into clusters and creates routes within these clusters.
    fmb Optional Integer Default: 5. Clustering factor. It could be 1.0 = Zero Clustering, 2.0 = Low Clustering, 3.0 = Medium Clustering, 4.0 = High Clustering or 5.0 = Intense Clustering
    use_euclidean_distance Optional Boolean Default: False. If true, it is considered as the distance between two locations, the direct line that joins both nodes.
    autoZone Optional Boolean Default: False. If true, the algorithm assigns the vehicles that serve each specified zone in the visits.
    intensive_intra Optional Boolean Default: False. If true, the algorithm performs a more intensive search on the solution space. Response time may increase.
    open_routes_logic Optional Boolean Default: False. If true, the route will be created assuming the vehicle won't return the depot at the end of the day, BUT it does.
    vehicle_capacities_increment Optional Integer Default: 0. Percentage increase in load capacity of all vehicles.
    vehicle_journey_extention Optional Integer Default: 0. Percentage of increase in the time window of all vehicles.
    enable_soft_window Optional Boolean Default: False. If true, it allows not respecting the deliveries time windows, but seeking to minimize the total delay time.
    isReorder Optional Boolean Default: False. When enabled, this feature will try to insert all nodes, considering only the first time windows. If this is not achievable, it will try again ignoring the time window constraints.
    radial_routing Optional Integer Default: 0. When its value is 1, each route will start close to the depot and end far from the depot. When its value is -1, each route will start far from the depot and end close to the depot. When its value is 0, the option is disabled. Other values are not accepted.

    Example - Basic Optimization JSON input

    {
    "vehicles": [
        {
            "ident": "Vehicle 1",
            "location_start": {
                "ident": "depot_1_start",
                "lat": -33.4233926,
                "lon": -70.6104996
            }
        }
    ],
    "nodes": [
        {
            "ident": "1",
            "lat": -33.436135,
            "lon": -70.6509688
        },
        {
            "ident": "2",
            "lat": -33.4334123,
            "lon": -70.653234
        },
        {
            "ident": "3",
            "lat": -33.333413,
            "lon": -70.5534688
        }
    ]
}

    JSON output

    {
    "vehicles": [
        {
            "ident": "Vehicle 1",
            "tours": [
                {
                    "nodes": [
                        {
                            "arrival": "00:00:00",
                            "ident": "depot_1_start",
                            "lon": -70.6104996,
                            "departure": "00:00:00",
                            "lat": -33.4233926,
                            "order": 0,
                            "priority": null,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:17:00",
                            "ident": "3",
                            "lon": -70.5534688,
                            "departure": "00:17:00",
                            "lat": -33.333413,
                            "order": 1,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:39:00",
                            "ident": "2",
                            "lon": -70.653234,
                            "departure": "00:39:00",
                            "lat": -33.4334123,
                            "order": 2,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:40:00",
                            "ident": "1",
                            "lon": -70.6509688,
                            "departure": "00:40:00",
                            "lat": -33.436135,
                            "order": 3,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "arrival": "01:42:00",
                            "ident": "depot_1_start",
                            "lon": -70.6104996,
                            "departure": "01:42:00",
                            "lat": -33.4233926,
                            "order": 4,
                            "priority": null,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        }
                    ]
                }
            ]
        }
    ],
    "num_vehicles_used": 1,
    "filteredClientsNodes": [],
    "unattendedClientsNodes": []
}

    The most basic example of routing optimization using our API is when there's only one depot, from which all of your vehicles will start and end the day.

    Additionally, on every location your vehicles need to visit there are no restrictions regarding load or time windows. This happens usually on cases like:

    • Delivery of letters and documents
    • Food delivery with vehicles on which load restrictions are not an issue

    You can see an input and output JSON example on the right.

    In this example there are two relevant entities: vehicles and nodes. The first of them must contain:

    "Ident" is required and is the vehicle's id. The object "location_start" is the location from where the vehicle will begin its daily operation. Since in this example we didn't define a "location_end" our algorithm will assume that the vehicle will end its day on "location_start".

    In the nodes case, you must define the following:

    We use "ident" as an ID for the visit, and "lat" and "lon" to specify the latitude and longitude of the node. Since in this example there are no time windows nor loads, there's no need to specify anything else on each visit.

    Vehicle Time Windows

    If no time windows are specified for the vehicle, our algorithm will assume that the vehicle will work between "00:00" and "23:59" hours of that day. If you wish to specify a time window for the vehicle, you must add the values "shift_start" and "shift_end". An example of this:

    Service Times

    If service time is not specified, our algorithm will assume that service time in that location is 0 (zero) minutes. If you wish to add a value, you can specify it on the node object as it follows:

    "Duration" must be an integer in minutes. It represents how long will the vehicle stay on that location.

    Optimization Response

    The optimization response, which is the ouput optimization, can be divided into these sections:

    • Vehicles: Array of vehicles from the Json input.
    • Tours: Array of tours. A tour is the list of all the routes that the vehicle takes from the beginning of its journey until its end.
    • Nodes: Array of deliveries that were included in some route.
    • num_vehicles_used: Number of vehicles used to create the routes.
    • filteredClientsNodes: Array of deliveries' ident that were removed from the Optimization input before optimizing the routes, due to the impossibility of serving them due to the constraints of the problem.
    • unattendedClientsNodes: Array of deliveries' ident, not filtered, that could not be included in some route during the optimization of the problem.

    Some of the attributes that the nodes have in the optmization response are the same as those sent in the request, except for these:

    Attributes Type Description
    arrival String String "HH:mm:ss" (military time). Vehicle arrival time at delivery.
    departure String String "HH:mm:ss" (military time). Vehicle departure time from delivery.
    order Integer Order in which delivery is visited.

    Example - Multiple depots

    Similar to last case, you can define for each vehicle a different location to start and end the day. This way, you can simulate more complex operations in which a vehicle must begin the day on a city and end the day on another place. An example JSON of this is on the right.

    JSON input:

    {
    "vehicles": [
        {
            "ident": "Vehicle 1 different start and end",
            "shift_start": "09:00",
            "shift_end": "19:00",
            "location_start": {
                "ident": "depot_1_start",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "location_end": {
                "ident": "depot_2_end",
                "lat": -33.436662,
                "lon": -70.577584
            }
        }
    ],
    "nodes": [
        {
            "ident": "1",
            "lat": -33.436135,
            "lon": -70.6509688
        },
        {
            "ident": "2",
            "lat": -33.4334135,
            "lon": -70.6534688,
            "duration": 5
        },
        {
            "ident": "3",
            "lat": -33.333413,
            "lon": -70.5534688,
            "duration": 5
        }
    ]
}

    JSON output:

    {
    {
    "vehicles": [{
        "ident": "Vehicle 1 different start and end",
        "tours": [{
            "nodes": [{
                "arrival": "09:00",
                "ident": "depot_1_start",
                "lon": -70.6104996,
                "departure": "09:00",
                "lat": -33.4233926,
                "order": 0
            }, {
                "load": 0,
                "arrival": "09:17",
                "ident": "2",
                "lon": -70.6534688,
                "departure": "09:22",
                "lat": -33.4334135,
                "order": 1
            }, {
                "load": 0,
                "arrival": "10:05",
                "ident": "1",
                "lon": -70.6509688,
                "departure": "10:35",
                "lat": -33.436135,
                "order": 2
            }, {
                "load": 0,
                "arrival": "10:49",
                "ident": "3",
                "lon": -70.5534688,
                "departure": "11:19",
                "lat": -33.333413,
                "order": 3
            },{
                "arrival": "11:56",
                "ident": "depot_2_end",
                "lon": -70.577584,
                "departure": "11:56",
                "lat": -33.436662,
                "order": 4
            }]
        }]
    }],
    "num_vehicles_used": 1
}

    Backhaul Optimization (Routes with picks and drop offs)

    Example of Nodes Object with Loads and Pickloads

    {
    "nodes": [
        {
            "ident": "Regular Delivery",
            "lat": -33.3887,
            "lon": -70.62304,
            "load": 10.1,
            "load_2": 2.0,
            "load_3": 3.2
        },
        {
            "ident": "Regular Pick up",
            "lat": -33.39124,
            "lon": -70.61387,
            "pickload": 5.1,
            "pickload_2": 1.0,
            "pickload_3": 1.2
        },
        {
            "ident": "Pick up and Delivery",
            "lat": -33.4887,
            "lon": -70.92304
            "load": 7.2,
            "load_2": 1.0,
            "load_2": 2.2,
            "pickload": 4.1,
            "pickload_2": 3.0,
            "pickload_3": 3.2
        }
    ]
}

    Our algorithm is extended to also support routes in which your vehicles must deliver products to your customers and also pick up products from your customers that must come back to your depot or warehouse. In this scenario, on each customer you can either deliver, pick up or both pick up and deliver products.

    This type of routing is commonly known as Backhaul Route Optimization, which must not be confused with Pick up And Delivery Optimization which is a slightly different problem. In this type of route optimization, the capacity of the vehicle must be checked on each stop, in order not to overbook it on the middle of the route.

    In order to use our Backhaul Optimization you must use the same route optimization endpoint that is used for regular optimizations, but adding some optional parameters into the nodes object for each visit.

    These are the new parameters you can add, and how they are related to the parameters of regular route optimization:

    Attributes Mandatory Type Description
    load Optional Float Load that must be delivered on this client. Must be on the same unit as vehicle's load.
    load_2 Optional Float Secondary Load that must be delivered on this client. Must be on the same unit as vehicle's secondary load.
    load_3 Optional Float Third Load that must be delivered on this client. Must be on the same unit as vehicle's third load.
    pickload Optional Float Load that must be picked up on this client. Must be on the same unit as vehicle's load and this visit's load.
    pickload_2 Optional Float Secondary Load that must be picked up on this client. Must be on the same unit as vehicle's secondary load and this visit's load_2.
    pickload_3 Optional Float Third Load that must be picked up on this client. Must be on the same unit as vehicle's third load and this visit's load_3.

    Stop Routing

    The visit_joiner object is added to the optimization request and can be used with vrp or big-vrp endpoints.

    Example Request for "Merging Stops by Distance"

    {
    "visit_joiner": {
        "enable_visit_join": true,
        "maximum_distance": 0.5,
        "match_skills": true,
        "match_zones": true,
        "match_time_windows": true
    }
}

    The Stop Routing feature allows grouping or merging visits into a single stop based on specific geographical proximity criteria and other client-configurable parameters. The goal of this feature is to optimize routes by reducing the number of individual visits when they share similar conditions in location and restrictions.

    Parameters

    Parameter Type Description
    enable_visit_join Boolean Enables the stop routing feature when set to true.
    maximum_distance Number Maximum distance (in kilometers) for grouping visits into a stop. Set to 0 to enable merging by exact location.
    match_skills Boolean Groups visits with the same required skills when active.
    match_zones Boolean Groups visits within the same zone when active.
    match_time_windows Boolean Groups visits with the same time window when active.

    Grouping Visits by Distance

    The service processes requests to group visits into a single stop when they meet the following criteria:

    They are within a maximum configured distance. They share the same required skills. They share the same time window.

    Grouping Similar Visits by Address (Distance 0)

    Example Request for "Merging Similar Stops" (Distance 0) json { "visit_joiner": { "enable_visit_join": true, "maximum_distance": 0, "match_skills": true, "match_zones": true, "match_time_windows": true } } This option groups visits located at the exact same spot that share:

    • The same latitude and longitude.
    • The same required skills.
    • The same time window.

    Output for Both Modes

    • Combined Load: The loads of the individual visits are summed.
    • Service Time: The longest service time among the merged visits is assigned.

    Special Conditions and Validations

    • Compatibility with similars_by_priority: When enabled, two visits with the same priority will not be merged.
    • Vehicle Capacity Check: If the combined load of merged visits exceeds vehicle capacity, the visits will not be grouped.
    • Primary Time Window: For visits with the same latitude and longitude but different time windows, the time window of the primary visit (stop) is used.

    API Usage Considerations

    • "Merging Similar Stops" does not validate the address field; only lat and lon are checked.
    • This functionality is backend-only; do not activate join:true in the frontend.

    API Response

    To verify that a visit has been grouped in the optimization response, you can check the attended visits in the parameter order: number. If they have the same order, it indicates that these visits have been grouped into one stop.

    Pick-up and Delivery

    Job object example: one pick node.

    {
  "jobs": [
    {
      "pickNodes": [
        {
          "ident": "OnlyPickUp_1",
          "lat": -22.931935311303512,
          "lon": -43.39394580787891,
          "duration": 11,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }],
    "deliveryNodes": [
      ]}
  ]
}

    Job object example: one delivery node.

    {
  "jobs": [
    {
      "pickNodes": [
      ],
      "deliveryNodes": [
        {
          "ident": "OnlyDelivery_1",
          "lat": -22.928792360672404,
          "lon": -43.389912163599,
          "duration": 12,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }]}
  ]
}

    Job object example: one pick node and one delivery node.

    {
  "jobs": [
    {
      "pickNodes": [
        {
          "ident": "PickUp_1",
          "lat": -22.92770862905761,
          "lon": -43.37154320004268,
          "duration": 29,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }],
      "deliveryNodes": [
        {
          "ident": "Delivery_1",
          "group":[],
          "lat": -22.930334385243487,
          "lon": -43.390728465304214,
          "duration": 3,
          "load": 2,
          "load2": 1,
          "load3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }]}
  ]
}

    One of the variants supported by the routing algorithm is the Pick-up and Delivery Problem. In this problem, nodes are divided into two categories that serve different goals: picks and deliveries. While a pick is meant to pick up load from a fixed location, a delivery has to take it to its destination.

    The fundamental unit of this problem is known as a job, which consists of a group of nodes. Each job falls into one of the following three cases:

    • One pick node: in this case, after visiting the node, the driver will pick and transport its load in the vehicle until the next depot.
    • One delivery node: in this case, when the driver arrives at the node, it delivers the load that comes originally from a depot.
    • One pick node and one delivery node: in this scenario, the driver must first pass through the pick-up node to pick up the load, which consequently must be taken to a specific delivery node.

    Regarding the capacity constraint, it should be noted that the total load of a vehicle changes dynamically depending on whether it picks up or delivers load during the route.

    The optimization input is a JSON object that has a similar structure to the regular optimization case. It is composed of optimization options, a list of vehicles and a list of jobs (instead of nodes). Each job in turn is composed of a list of pick nodes and a list of delivery nodes, to cover the three job cases explained above. In order to use this mode, the request must be sent to the following endpoint: https://optimizer.simpliroute.com/pd/optimize/sync/.

    A pickNode or deliveryNode is very similar to the node (delivery) object that was previously defined and is compatible with the following attributes:

    Attributes Mandatory Type Description
    ident Mandatory String Unique identifier for the object.
    lat Mandatory Float Latitude of the pick or delivery's location.
    lon Mandatory Float Longitude of the pick or delivery's location.
    address Optional String Address of the pick or delivery. If there are lat and lon attributes, it will prioritize those fields over this.
    load Optional Float Load of this pick or delivery. Must be on same units as vehicle's load.
    load_2 Optional Float Secondary load of this pick or delivery. Must be on same units as vehicle's load 2.
    load_3 Optional Float Third load of this pick or delivery. Must be on same units as vehicle's load 3.
    window_start Optional String String "HH:mm" (military time). Minimum time this pick or delivery can be visited.
    window_end Optional String String "HH:mm" (military time). Maximum time this pick delivery can be visited.
    window_start_2 Optional String String "HH:mm" (military time). Secondary minimum time this pick or delivery can be attended. (Ex: I can visit this place from 10:00 to 12:00 and from 15:00 to 19:00)
    window_end_2 Optional String String "HH:mm" (military time). Secondary maximum time this pick or delivery can be attended.
    duration Optional Integer Minutes that the vehicle will stay on the pick or delivery.
    skills_required Optional Integer array Skills this pick or delivery needs to be fulfilled. Only the vehicles who have all of these skills will visit it.
    skills_optional Optional Integer array Skills this pick or delivery needs to be fulfilled. Only the vehicles who have at least one of these skills will visit it.
    priority_level Optional Integer Used to indicate this pick or delivery is more important than others. Possible values are 1: First of the day, 2: Last of its route, 3: High Priority, 4: Medium Priority, 5: Low Priority.

    Rest Time (Routes with a break time)

    Example of Vehicles Object with rest time

    {
       "vehicles": [
        {
            "ident": "159331",
            "location_start": {
                "ident": "vehicle-start-159331",
                "lat": -33.405976,
                "lon": -70.652035
            },
            "location_end": {
                "ident": "vehicle-end-159331",
                "lat": -33.405976,
                "lon": -70.652035
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "11:00",
            "shift_end": "23:00",
            "skills": [
                "32073",
                "32074"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        },
        {
            "ident": "159351",
            "location_start": {
                "ident": "vehicle-start-159351",
                "lat": -33.594771,
                "lon": -70.520194
            },
            "location_end": {
                "ident": "vehicle-end-159351",
                "lat": -33.594771,
                "lon": -70.520194
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "08:00",
            "shift_end": "14:00",
            "skills": [
                "32076"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        },
        {
            "ident": "159349",
            "location_start": {
                "ident": "vehicle-start-159349",
                "lat": -33.486415,
                "lon": -70.609595
            },
            "location_end": {
                "ident": "vehicle-end-159349",
                "lat": -33.486415,
                "lon": -70.609595
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "08:00",
            "shift_end": "14:00",
            "skills": [
                "32073"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        }
    ],
    "enable_rest_time": true
}

    Our algorithm can consider a defined rest time for each vehicle (driver) in order to take a break in the journey that must be traveled during the day. This feature considers only a pause in the route of a vehicle, at a time defined in the request.

    In order to use Rest Time, you must use the same route optimization endpoint that is used for regular optimizations, but adding some optional parameters in the vehicles object for each vehicle. In addition, you must turn on an additional parameter that allows you to use this feature. Only the vehicles that have the additional parameters are considered with a rest time.

    These are the new parameters you can add:

    Attributes Mandatory Type Description
    rest_time_start Mandatory String String "HH:mm" (military time). Minimum time in which this vehicle must take the rest period. This time must be less than the shift end attribute.
    rest_time_end Mandatory String String "HH:mm" (military time). Maximum time in which this vehicle must take the rest period. This time must be greater than the shift start attribute.
    rest_time_duration Mandatory Integer Minutes that this vehicle will remain in a rest time. This duration must be less than or equal to the time window established to take the break.
    enable_rest_time Optional Boolean Default: False. If true, the vehicles considering a rest time on the route, which is defined with the previous parameters.

    Incremental Routing (Vehicles with previously created routes)

    Example of Vehicle object with pre-created routes for each vehicle

    {
  "vehicles": [
    {
      "ident": "7247",
      "location_start": {
        "ident": "7247",
        "lat": -21.6698437,
        "lon": -49.7495409
      },
      "shift_start": "09:12",
      "shift_end": "18:00",
      "partial_tour": {
        "ident": "7247",
        "partial_routes": [
          {
            "nodes": [
              "18112000205726",
              "10081834157634",
              "10089320449243"
            ],
            "fixed_nodes_number": 2
          },
          {
            "nodes": [
              "10089034859206",
              "18162900171426",
              "18109901985501",
              "18162900171339"
            ],
            "fixed_nodes_number": 3
          }
        ]
      }
    }
  ],
    "incremental_routing": true
}

    In some scenarios, there are routes already created and it is desired to optimize considering that these routes are not disassembled but integrating new nodes in the same vehicles or in others. This optimization, called incremental routing, allows to optimize considering that there are routes that must remain fixed.

    The incremental routing optimization have two sections:

    • Partial Tour: Object indicating that the vehicle has previously created partial routes. It contains an ident that is the same vehicle ident. If you don't want the vehicle to have partial routes then this object should be null.
    • Partial Routes: Array of partial route object. Each partial route object is a pre-created route and contains a list of node idents.

    In order to use incremental routing optimization, you must use the same route optimization endpoint that is used for regular optimizations, but adding this sections and some optional parameters in the vehicles object for each vehicle. Only the vehicles that have the additional objects and parameters are considered to have pre-created routes. It is important to consider that both nodes belonging to partial routes and new nodes must be within the deliveries list of the Nodes Object.

    These are the new parameters you can add in the partial route object:

    Attributes Mandatory Type Description
    nodes Mandatory String array Ident of the nodes that are part of the route that you want to keep in the vehicle.
    fixed_nodes_number Mandatory Integer First n nodes that remain fixed in the vehicle and in the position in this previously created route. If the value is equal to 0, all the nodes can change their position but not the vehicle. If the value is equal to the size of the list of nodes, this partial route remains as it is, no node moves.

    Additionally, you must turn on this additional parameter that allows you to use this feature:

    Attributes Mandatory Type Description
    incremental_routing Optional Boolean Default: False. If true, the vehicles considering the previouly created routes which are defined with the previous objetcs and parameters.

    Long Routes

    Example of Vehicles and Nodes Objects with long routes optimization, where a night route starts at 10:00 p.m. and ends at 7:00 a.m. the following day (equivalent to 31:00 hrs).

    {
  "vehicles": [
    {
      "ident": "Vehicle 1",
      "location_start": {
        "ident": "warehouse A",
        "lat": -12.101389,
        "lon": -77.004534
      },
      "capacity": 3500,
      "shift_start": "22:00",
      "shift_end": "31:00"
    }
  ],
  "nodes": [
    {
      "ident": "Jirón Vesalio 252, San Borja",
      "lat": -12.105329,
      "lon": -77.005524,
      "arrayOfTimeWindows": [
        [
          "25:00",
          "28:00"
        ]
      ],
      "load": 77,
      "duration": 10
    },
    {
      "ident": "Jirsón Tasso 423, San Borja",
      "lat": -12.098615,
      "lon": -77.007240,
      "arrayOfTimeWindows": [
        [
          "26:00",
          "30:00"
        ]
      ],
      "load": 77,
      "duration": 10
    }
  ],
  "longRoutes": true
}

    Our algorithm extends the creation of routes to perform overnight routing operations, i.e., beyond the 24 hours of a day, called Long Routes Optimization.

    To use Long Routes Optimization, you must use the same route optimization endpoint that is used for regular optimizations, but add some optional parameters on all node objects. In addition, you must activate an additional parameter that allows you to use this feature.

    It is important to consider that this feature is focused on performing night routing optimizations, but it is possible to make routes of more than one day. However, this feature only supports horizons of no more than 7 days, no more than 10 vehicles and/or 40 nodes per vehicle.

    These are the new parameters you can add:

    Attributes Mandatory Type Description
    arrayOfTimeWindows Optional Object Array of time windows (array of two String in format "HH:mm") to attend the visit. Times can be set for more than 24 hours. This attribute only works if longRoutes is True.
    longRoutes Optional Boolean Default: False. If true, it allows the vehicle to have a shift_end greater than 24 hours. In the visits the time windows must be sent.

    Radial Routing

    This routing option makes the routing tend to be more radial with respect to the depot. When "radial_routing": 1, the routes will tend to start closer to the depot and end farther away, and in the sequence of visits, each visit will tend to be farther from the depot than the previous one. When "radial_routing": -1, the routes will tend to start farther from the depot and end closer, and in the sequence of visits, each visit will tend to be closer to the depot than the previous one. The effect will be more noticeable and is intended for the case of one route per vehicle ("single_tour": true). It is important to note that, for the purposes of this option, the proximity of visits refers to proximity in travel time, not in distance.

    To use Radial Routing, you must turn on the radial_routing parameter (by setting its value to 1 or -1) and one or more of the following conditions should be met: - beauty parameter is turned on ("beauty": true). - min_load parameter has a value greater than 0. - there are more than 800 nodes.

    Estimated Time Calculation

    ETC Update Endpoint

    
https://optimizator.simpliroute.com/etc/sync

    JSON input

    {
    "vehicle": {
        "vehicle_id": "Vehicle 1",
        "lat": -33.45754,
        "lon": -70.92697,
        "departure_time": "09:00"
    },
    "tours": [
        {
            "nodes": [
                {
                    "id": "id1",
                    "lat": -33.45754,
                    "lon": -70.62697,
                    "service_time": 30.0,
                    "order": 0
                },
                {
                    "id": "id2",
                    "lat": -33.45744,
                    "lon": -70.77532,
                    "service_time": 90.0,
                    "order": 1
                },
                {
                    "id": "id3",
                    "lat": -33.45742,
                    "lon": -70.60364,
                    "service_time": 90.0,
                    "order": 2
                }
            ]
        }
    ],
    "fmv": 2.0
}

    After your vehicle is on route, a lot of things can happen:

    • Traffic jams
    • Longer service times than expected
    • Unexpected street situations
    • New priorities along the days

    Then, after a while, the initial calculated ETA is not longer valid and you need to recalculated it. For this cases, we have a dedicated endpoint to solve the issue. A few considerations about this endpoint:

    • You have to provide the current time to recalculate the ETA ("departure_time")
    • It only accepts one vehicle with one tour per request
    • It will maintain the provided order, it will not compute any optimization (VRP or TSP)
    • The predicted ETA/ETD will be based in our traffic estimations.

    Below you can see the input information and their corresponding vehicle's data types:

    Attributes Mandatory Type Description
    vehicle_id Mandatory String The vehicle id identifier
    lat Mandatory Double Current vehicle's latitude
    lon Mandatory Double Current vehicle's longitude
    departure_time Mandatory Time Current time to start the ETA recalculation "HH:mm"

    In the tours and node side, this is the attributes:

    Attributes Mandatory Type Description
    id Mandatory String Visit identifier
    lat Mandatory Double Visit latitude
    lon Mandatory Double Visit longitude
    service_time Mandatory Double Minutes to unload deliveries from the vehicle
    order Mandatory Integer Order of visit inside of the tour.

    At the moment there is only support one route per tour. If more than one route is sent it will respond with an error.

    The request can also include Traffic factor

    Attributes Mandatory Type Description
    fmv Optional Integer Default: 2.0, Speed traffic factor. It could be 1.0 = Low Traffic, 1.5 = Medium Traffic, 2.0 = High Traffic or 3.0 = Intense Traffic.

    You can see an example of the response in the right side of this documentation.

    JSON response:

    {
    "vehicle": {
        "vehicle_id": "Vehicle 1",
        "lat": -33.45754,
        "lon": -70.92697,
        "departure_time": "09:00"
    },
    "tours": [
        {
            "nodes": [
                {
                    "id": "id1",
                    "lat": -33.45754,
                    "lon": -70.62697,
                    "service_time": 30,
                    "order": 0,
                    "arrival": "09:48",
                    "departure": "10:18"
                },
                {
                    "id": "id2",
                    "lat": -33.45744,
                    "lon": -70.77532,
                    "service_time": 90,
                    "order": 1,
                    "arrival": "10:50",
                    "departure": "12:20"
                },
                {
                    "id": "id3",
                    "lat": -33.45742,
                    "lon": -70.60364,
                    "service_time": 90,
                    "order": 2,
                    "arrival": "13:00",
                    "departure": "14:30"
                }
            ]
        }
    ]
}

    Optimization: Metadata

    The Optimization Metadata pretends give to the client information not available in the optimization endpoint, such as the vehicle's route planned distances provided by the Optimization Endpoint.

    Distance

    The distances endpoint offers the estimated kilometers for a previous optimized routes.

    An Authorization Header containing a valid Token is required.

    Optimization Metadata Distances Endpoint

    
https://optimizator.simpliroute.com/v1/optimization/metadata/distance

    Request

    It respects the structure of the Optimization Response, so it should be easier to build after obtaining an optimization.

    Root object:

    Attributes Mandatory Data Type Description
    country Yes String ISO code referring to the country where the delivery locations are located.
    vehicles Yes Object List of vehicles incurred in the Optimization

    Vehicle object:

    Attributes Mandatory Data Type Description
    ident No String Vehicle's identification string
    tours Yes Object List of tours assigned to the current vehicle

    Tour object:

    Attributes Mandatory Data Type Description
    nodes Yes Object List of nodes that forms the current tour graph.

    Node object:

    Attributes Mandatory Data Type Description
    lat Yes Float Coordinate representing the latitude of the visit or depot
    lon Yes Float Coordinate representing the longitude of the visit or depot

    Example of Request

    {
    "country": "CL",
    "vehicles": [
        {
            "ident": "123",
            "tours": [
                {
                    "nodes": [
                        {
                            "lat": -41.319286,
                            "lon": -72.995719
                        },
                        {
                            "lat": -41.319081,
                            "lon": -72.989037
                        }
                    ]
                },
                {
                    "nodes": [
                        {
                            "lat": -41.317910,
                            "lon": -73.006348
                        },
                        {
                            "lat": -41.317449, 
                            "lon": -72.981885
                        }
                    ]
                }
            ]
        },
        {
            "ident": "456",
            "tours": [
                {
                    "nodes": [
                        {
                            "lat": -42.319286,
                            "lon": -73.995719
                        },
                        {
                            "lat": -42.319081,
                            "lon": -73.989037
                        }
                    ]
                },
                {
                    "nodes": [
                        {
                            "lat": -42.317910,
                            "lon": -73.006348
                        },
                        {
                            "lat": -42.317449, 
                            "lon": -73.981885
                        }
                    ]
                }
            ]
        }
    ]
}

    Response

    200

    It will return 200 when the request is successful. It will follow the same object structure than the request.

    200 response example

    {
    "vehicles": [
        {
            "ident": "123",
            "tours": [
                {
                    "distance": 899.5,
                    "metric": "meters"
                },
                {
                    "distance": 2200.6,
                    "metric": "meters"
                }
            ]
        },
        {
            "ident": "456",
            "tours": [
                {
                    "distance": 899.5,
                    "metric": "meters"
                },
                {
                    "distance": 2200.6,
                    "metric": "meters"
                }
            ]
        }
    ]
}

    400 response example

    {
    "statusCode": 400,
    "message": "Country value is required"
}

    5XX reponse example

    {
    "errors": [
        {
            "code": "E5000",
            "message": "Internal server error",
            "metadata": {
                "code": "E5000"
            }
        }
    ]
}

    Validate Incompatibilities

    The validation process involves iterating through each visit and checking against each vehicle for any type of incompatibility based on required skills, optional skills, loads, time windows, or zones constraints.

    This process is only supported for VRP-type problems and is carried out in the optimizer at the beginning of the process, just before the problem is processed. Visits that are found to be incompatible will be filtered out and will not be considered in the optimization process.

    Since a visit can have different incompatibilities for each vehicle, it's challenging to specify a single cause. In such cases, a summary description will be provided, listing the categories that are incompatible with the visit.

    Example

    Here's an example of a problem response that contains 1 visit and 3 vehicles, where neither vehicle meets the visit requirements:

    JSON response:

    {
  "filteredClientsNodes": [
    {
      "ident": "Visit",
      "cause": {
        "description": "No vehicles matching: required skills, optional skills, time windows, zone, load",
        "codes": [
          "W02002",
          "W02102",
          "W03002",
          "W04002",
          "W01001"
        ],
        "details": [
          {
            "code": "W02002",
            "category": "required skills",
            "description": "None Vehicles has the required skills for this visit.",
            "count": 3
          },
          {
            "code": "W02102",
            "category": "optional skills",
            "description": "None Vehicles has the optional skill for this visit.",
            "count": 3
          },
          {
            "code": "W03002",
            "category": "time windows",
            "description": "The visit's time window falls out outside the working hours of all vehicles.",
            "count": 3
          },
          {
            "code": "W04002",
            "category": "zone",
            "description": "None vehicle has been assigned to the visit's zone",
            "count": 3
          },
          {
            "code": "W01001",
            "category": "load",
            "description": "Some vehicles has not the required capacity for this visit.",
            "count": 2
          }
        ]
      }
    }
  ]
}

    While the description informs us that there are incompatibilities in the 5 categories (load, required skills, optional skills, time windows, zone), in the "details" attribute, we can observe a "counter" attribute that indicates the number of vehicles that are not compatible in each category. The causes are ordered in descending order based on the number of incompatible vehicles.

    List of Codes

    Below is the code description and the list of supported incompatibility causes.

    Structure

    <Initial Letter><Problem Category><Specific Number>

    Initial Letter:

    • W: Indicates an Alert or warning related to a poorly created visit.

    Primary Incompatibility Codes

    • W00001: Undefined.
    • W01002: No vehicles have the required capacity for this visit.
    • W02002: No vehicles have the required skills for this visit.
    • W02102: No vehicles have the optional skill for this visit.
    • W03002: The visit's time window falls outside the working hours of all vehicles.
    • W04002: No vehicle has been assigned to the visit's zone.

    Secondary Incompatibility Codes

    • W01001: Some vehicles do not have the required capacity for this visit.
    • W02001: Some vehicles do not have the required skills for this visit.
    • W02101: Some vehicles do not have the optional skill for this visit.
    • W03001: The visit's time window falls outside the working hours of some vehicles.
    • W04001: Some vehicle has not been assigned to the visit's zone.

    Invoices

    To use this API, your account must have the Accounting AddOn activated, please contact your on-boarding specialist.

    Note: this API is constantly adding fields or making small adjustments. The information presented may change.

    Invoice

    Main entity representing a financial document, such as an invoice, receipt, delivery note, etc. We formally use this definition:

    Invoice: a time-stamped commercial document that itemizes and records a transaction between a buyer and a seller

    Invoice creation cURL (minimal payload)

    curl --location --request POST 'http://api.simpliroute.com/v1/accounting/invoices/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference" : "external identifier",
    "currency": "CLP",
    "type": "bill",
    "visit": 15081986
}'

    Invoice creation cURL (full payload)

    curl --location --request POST 'http://api.simpliroute.com/v1/accounting/invoices/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference" : "external_id 1234",
    "currency": "USD",
    "visit": 185202350,
    "payment_method": "transfer",
    "type": "bill",
    "status": "payed",
    "label": "custom_title",
    "items": [{
        "title": "inline item",
        "type": "paquete"
    }]
}'

    Invoice update cURL

    curl --location --request PATCH 'http://api.simpliroute.com/v1/accounting/invoices/<invoice_id>/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference" : "external_id",
    "currency": "CLP",
    "visit": 15081986
}'

    Invoice delete cURL

    curl --location --request DELETE 'http://api.simpliroute.com/v1/accounting/invoices/<invoice_id>/' \
--header 'Authorization: Token <your_token>'

    An Invoice exists decoupled fom Visit, although it relates to it. Its minimum and mandatory properties are:

    Name Type Description
    reference string external identifier for the invoice
    currency string money currency for items prices. Following the ALPHA-3 convention described in the ISO 3166 international standard. Ex: CLP
    visit int visit id to which the invoice relates to
    type string the type of Invoice. Currently supported: ('bill', 'credit_note', 'delivery_note', 'debit_note')

    An Invoice is created using the service https://api.simpliroute.com/v1/accounting/invoices/ (a cURL example is shown at the right panel 👉)

    Other available fields for Invoice are:

    Name Type Default Description
    payment_method string 'cash' the payment method declared for the Invoice. One of ('cash', 'check', 'credit_card', 'debit_card', 'transfer', 'dated_check', 'credit')
    payment_method_details string none available to store extra information about payment method
    status string 'pending' the invoice status. One of ('pending', 'payed', 'overdue', 'canceled', 'partial', 'completed')
    items list of InvoiceItem [] list of items in invoice. Can be initialized with a list of dictionaries like: [{ "title": "item title", "type": "item type"}]
    delivery_issue one of the available DeliveryIssue for the account null indicates if Invoice had a delivery issue, and which one.
    label string null custom field to store a name or title for the Invoice

    The services for retrieval, update, and deletion are as follows:

    GET http://api.simrpliroute.com/v1/accounting/invoices/<invoice_id>/

    PATCH http://api.simrpliroute.com/v1/accounting/invoices/<invoice_id>/

    DELETE http://api.simrpliroute.com/v1/accounting/invoices/<invoice_id>/

    Retrieval service support two query-params: route_id and planned_date

    route_id to query for the Invoices associated with visits from a given route. Ex.:

    GET http://api.simrpliroute.com/v1/accounting/invoices/?route_id=abs-qq2-asas

    planned_date to query for invoices associated with visits from a certain planned date. Ex.:

    GET http://api.simrpliroute.com/v1/accounting/invoices/?planned_date=2024-02-26

    InvoiceItem

    InvoiceItem creation or update cURL

    curl --location --request POST 'http://api.simpliroute.com/v1/accounting/invoices/<invoice_id>/items/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "title": "a good iteam"
    },
    {
        "reference": "new reference",
        "title": "a not so good item"
    }
]'

    InvoiceItem deletion cURL

    curl --location --request DELETE 'http://api.simpliroute.com/v1/accounting/invoices/a947125d-da24-447f-8db4-01ab0b5c4bf9/items/1' \
--header 'Authorization: Token <your_token>'

    InvoiceItem represents an item within an Invoice and can be declared at the time of creating the Invoice, or afterward. The properties of an InvoiceItem are:

    Name Type Mandatory Description
    title string yes name or title for the item
    reference string yes external identifier for this item
    sku string no item’s SKU
    unit_price float no item unitary price
    planned_units float no number of units expected to be delivered
    delivered_units float no number of units actually delivered
    delivery_issue one of the available DeliveryIssue for the account no indicates if item had a delivery issue, and which one.
    type string no item type
    product string no optional Product identifier

    InvoiceItems only exist within an Invoice. An InvoiceItems is created using the service:

    POST http://api.simpliroute.com/v1/accounting/invoices/<invoice_id>/items/

    examples of creation, deletion and update of InvoiceItem can be found at the right panel 👉

    DeliveryIssue

    DeliveryIssue creation cURL

    curl --location --request POST 'http://api.simpliroute.com/v1/accounting/invoices/delivery-issues/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "issue title",
"description": "dog does not allow entrance"
}'

    DeliveryIssue update cURL

    curl --location --request PATCH 'http://api.simpliroute.com/v1/accounting/invoices/delivery-issues/<delivery_issue_id>/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{"title":"delivery issue - new title"}'

    DeliveryIssue delete cURL

    curl --location --request DELETE 'http://api.simpliroute.com/v1/accounting/invoices/delivery-issues/<delivery_issue_id>/' \
--header 'Authorization: Token <your_token>'

    a DeliveryIssue represents a reason for non-delivery or an issue at the time of delivery. The available values are defined by each account. The properties of a DeliveryIssue are:

    Name Type Mandatory Description
    title string yes issue name or title
    description string no issue description
    type string no is this issue available for items or invoices. Expects one of ('item', 'invoice')
    reference string no external identifier for this DeliveryIssue

    examples of creation, deletion and update of DeliveryIssue can be found at the right panel 👉

    Products and ProductCategory

    Product creation cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/accounting/products/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '[{
"title": "title",
"sku": "13231323",
"category": 1
}]'

    Product update cURL

    curl --location --request PATCH 'https://api.simpliroute.com/v1/accounting/products/ae5e625c-a1ec-413b-9a3f-abe3c2825e4d/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "new title"
}'

    Product delete cURL

    curl --location --request DELETE 'https://api.simpliroute.com/v1/accounting/products/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '[{
"title": "title",
"sku": "13231323"
}]'

    Given the need for an InvoiceItem to be described from a "class", a "template", or a pre-existing definition, the Product entity was modeled. So then an InvoiceItem can be associated with a Product optionally.

    A Product has the following properties:

    Name Type Mandatory Description
    title string yes Product name or title
    sku string yes stock keeping unit (SKU) of the Product
    price float no price per 1 unit of this Product
    categories list yes ID of corresponding ProductCategory’s ID

    A ProductCategory allows relating several Products in the same group or category. A Product may or may not define a category, category is an optional property for Product.

    The properties of a ProductCategory are:

    Name Type Mandatory Description
    name string yes ProductCategory name
    parent int no when dealing with hierarchy, parent represents the ProductCategory where this ProductCategory belongs.

    There are creation (POST), retrieval (GET), update (PATCH), and deletion (DELETE) services for Product and ProductCategory at the following endpoints

    Product - http://api.simpliroute.com/v1/accounting/products/

    ProductCategory - http://api.simpliroute.com/v1/accounting/product-categories/

    examples of creation, deletion and update of Product can be found at the right panel 👉

    The Checkout Process

    The full checkout operation is a composition of multiples services:

    1) start the route

    2) checkout a visit

    3) store extra-field-values

    4) store pictures

    5) trigger notifications

    1. Start the route

    Performing this action allow the system to recognize the start time of the route and update visit's ETA accordingly.

    start a route cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/events/register/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "date_time": "2024-04-24T14:20:45.446Z", 
    "latitude": "-0.346644", 
    "longitude": "-78.455834", 
    "route_id": "24b87d96-813e-4176-a85b-d72171160000", 
    "type": "ROUTE_STARTED" 
  }'
    Parameter type description
    date_time string date and hour of start following the ISO 8601 standard (required)
    latitude string latitude at the point of route start
    longitude string longitude at the point of route start
    route_id string identifier or the route to start (required)
    type string indicates the event, for this case value must be ROUTE_STARTED (required)

    2. Checkout a visit

    Checking out a visit allows the system to register the action and display data accordingly in our frontend applications

    Visit checkout (minimal payload) cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/mobile/visit/<visit_id>/checkout/' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "completed", 
    "checkout_time": "2024-04-24 13:24:53", 
    "checkout_latitude": -12.105513, 
    "checkout_longitude": -76.965618, 
    "checkout_comment": "everything was OK" 
  }'

    Mandatory fields are the following:

    Parameter type description
    status string one of the following statuses: pending, completed, failed
    checkout_time string date and hour of checkout following the ISO 8601 standard
    checkout_latitude float latitude at the point of delivery
    checkout_longitude float longitude at the point of delivery
    checkout_comment string optional comment

    Other available parameters are:

    Parameter type description
    checkout_user_id int by default the system will register the user asociated with the token as the performer of the checkout action. In case the user is different, use this field to provide the user id
    signature string base64 representation of the signature image as proof of delivery

    3. Store extra-field-values

    Store extrafields values cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/routes/visits/multiple/extra-field-values' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "json": '{\"operation_nice\":true, \"other_extrafield\":\"a value\" }', \"visits\": [123, 456, 789]}'

    in case extrafields are defined to the given Visit, then extrafield values can be declared using this service https://api.simpliroute.com/v1/routes/visits/multiple/extra-field-values

    expected payload example:

    {'json': '{"georeferencia_incorrecta":false}', 'visits': [01407818]}

    please note that an extrafield value can be assigned to multiples visits. also note that extrafield_name (georeferencia_incorrecta in the example) must correponds to one of the available extrafields for the account. value for an extrafield can be bool, int or string, depending on the extrafield definition.

    An example is available at the right panel 👉

    4. Store pictures

    store picture cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/routes/visits/multiple/pictures/' \
--header 'Authorization: Token <your_token>' \
--form 'visits="[12, 34, 56]"' \
--form 'image=@"/path/to/image/picture.png"'

    In case you need to attach pictures to the checking out visit use this service: https://api.simpliroute.com/v1/routes/visits/multiple/pictures/

    Expected parameters are:

    Parameter description
    image path to file using form request
    visits array of visit_id to associate image to

    5. Trigger notifications

    Trigger notifications cURL

    curl --location --request POST 'https://api.simpliroute.com/v1/routes/visits/multiple/extra-field-values' \
--header 'Authorization: Token <your_token>' \
--header 'Content-Type: application/json' \
--data-raw '
    {"checkout_time": "2024-04-24T16:39:53.076Z", "visits": [407726472]} '

    In order to trigger sms, whatsapp, email and live-tracking notification, a final request must be executed using the service https://api.simpliroute.com/v1/mobile/visit/multiple/checkout/notify

    Expected parameters are:

    Parameter description
    checkout_time date and hour of checkout following the ISO 8601 standard
    visits array of visit_id to trigger notification of

    TMS: Transportation provider

    IMPORTANT: This Service is only available for the clients that has contracted it.

    The following actions are provided for managing the entity Transportation Provider.

    An Authorization Header containing a valid Token is required.

    For accessing this resource the following URL is required: https://api-gateway.simpliroute.com/tms/api/v1

    Creation Request

    Create a Transportation Provider in the system.

    Basic Request

    {
    "trade_name": "FEDEX",
    "status": "active",
    "contact_person": "Doe Dawson"
}

    HTTP method: POST Resource's path: /transportation-providers Body:

    Attributes Mandatory Data Type Default Description
    trade_name Yes String Commercial name for the provider
    legal_name No String Registered name in administrative institutions
    account_id Yes Integer Account’s id corresponding to the Token
    status No String active Registered name in administrative institutions
    contact_person Yes String Representative person for contact purposes
    contact_email No String
    phone_number No String
    address No String
    tax_id_number No String Legal identification number
    reference No String Identification code used by our clients for this entity

    Responses

    Code Description
    201 Successful creation
    422 Payload has formatting errors
    500 Server error

    List Request

    List all Transportation Providers.

    HTTP method: GET Resource's path: /transportation-providers Body: empty

    Responses

    Code Description
    200 Successful creation
    500 Server error

    Retrieve resource Request

    Obtaining an specific Transportation Provider.

    HTTP method: GET Resource's path: /transportation-providers/{id} Body: empty

    NOTE: The desired resource id is specified in the path.

    Responses

    Code Description
    200 Successful creation
    404 Resource doesn't exist
    500 Server error

    Update Request

    Change an specific Transportation Provider.

    HTTP method: GET Resource's path: /transportation-providers/{id} Body: Same as presented in Creation Request.

    NOTE: The desired resource id is specified in the path.

    Responses

    Code Description
    200 Successful update
    400 Wrong request
    403 User without authorization
    404 Resource doesn't exist
    422 Payoad has formatting errors
    500 Server error

    Delete Request

    Deletes an specific Transportation Provider.

    HTTP method: GET Resource's path: /transportation-providers/{id} Body: empty

    NOTE: The desired resource id is specified in the path.

    Responses

    Code Description
    204 Successful deletion
    400 Wrong request
    403 User without authorization
    404 Resource doesn't exist
    500 Server error

    Assign Transportation Provider to Vehicle with Transportation Provider Request

    Assign transportation provider to a vehicle, creating a relation between them.

    This endpoint allows to assign several transportation providers in one request.

    Basic Request

    [
  {
    "vehicle_id": 2,
    "transportation_provider_id": "14383454-keur-64f7-232e-901434a8f5ga"
  },
  {
    "vehicle_id": 3,
    "transportation_provider_id": "42383454-ba4a-4ff7-b52e-90544e8f5e44"
  }
]

    HTTP method: POST Resource's path: /vehicles/transportation-providers Body: Array of objects

    Attributes Mandatory Data Type Description
    vehicle_id Yes Integer Commercial name for the provider
    transportation_provider_id Yes UUID Registered name in administrative institutions

    Responses

    Code Description
    200 Successful request
    404 Resource doesn't exist
    500 Server error

    GPS Integration

    Simpliroute is able to integrate with your GPS in order to obtain important data

    Please contact our Profesional services team to obtain technical details on how to set up this integracion at [email protected]

    Frequency for sending data

    It is recommended to send a maximum of 1 data per vehicle every 20 seconds. for fleets more than 20 vehicles, 1 data per minute/vehicle, optimal frequency for a layout correct of the routes on the map.

    Loss of signal and sending of stored local data

    In the event that one or more vehicles circulate in areas outside the satellite range or before any factor that generates a loss of signal in the installed devices, recommends the use of “queues” (or “queues”) for data that could not be sent because of the above reason, and thus be able to send them later, when the signal is reset. When the latter occurs, the system could send data accumulated in the queue, and send them with a maximum time of 10 seconds between each one, until sending all the saved objects. Important: It should be considered that the range of 10 seconds applies only to data stored locally as a result of signal loss. The range for vehicles that are within satellite coverage maintain the recommended at the beginning of this document. Additionally, the data must be sent independently, an arrangement with all objects can cause errors in the communication of the call.

    Example Input

    {
"latitude":-33.4311548,
"longitude":-70.5701852 ,
"timestamp":"2019-02-20 10:35:00-00”,
"vehicleId”: "JKCT-81",
"providerName”: "LOCALIZAGPS_AGROSUPER”,
}

    Integration of GPS and variable data with SimpliRoute

    For the integration of GPS data and additional variables with SimpliRoute (such as temperature or humidity), the following information must be sent, by POST method, to the endpoint

    Please contact our Profesional services team to obtain technical details on how to set up this integracion at [email protected]

    Payload details

    Attributes Description
    latitude Decimal number up to 6 decimal digits.
    longitude Decimal number up to 6 decimal digits.
    timestamp Date and time in UTC with format YYYY-MM-DD HH:II:SS-00 Example: 2019-02-20 10:35:00-00
    vehicleId Vehicle ID in SimpliRoute system.
    temperature Temperature data, see “temperature” object. (backwards compatible but deprecated, it is recommended to send the temperature information in the alert object)
    alert Alert data, see “alert” object
    providerName Name of the vehicle GPS information provider.

    Temperature object

    Attributes Description
    value Decimal number with the temperature in degrees Celsius.
    alert_type Alert type, “min” when the temperature is below the limit set or “max” when greater.
    alert_message Message to be sent to the supervisor in charge of the trucks and the transport of refrigerated cargo.

    Alert Object

    Attributes Description
    name Alert type identifier.
    type alert type
    value Alert Value
    message Message to be sent to the supervisor in charge of the trucks.

    Alerts

    It is possible to send additional variables through an array of objects that maintain the following structure:

    Attributes Description
    name Alert type identifier.
    type alert type
    value Alert Value
    message Message to be sent to the supervisor in charge of the trucks.

    Available alerts

    Names
    temperature
    geofence
    speed
    humidity
    door
    estado
    brake
    temperature_2
    temperature_3
    jamming
    tiredness
    fuel_cap
    fuel_variation
    driver_door_open
    speeding
    loss_of_load
    no_smoking o smoking
    Demurrage

    Input example

    [
    {
"latitude": -33.4311548,
"longitude": -70.5701852,
"timestamp": "2017-10-19 09:12:02-00",
"vehicleId": "<<vehicle_id>>",
"temperature": {
"value": 2.4,
"alert_type": null,
"alert_message": null
},
"alert": {
"name": “door”,
"type": “open”,
"value": true,
“message”: “open door alert”
},
“alerts”: [
{
"name": “general”,
"type": “ºC”,
"value" 4,
“message”: “temperature is lower than 5 degress”
},
...
],
"providerName": "<<provider>>"
}

    Response example

    {
"status": "Tracked",
"id": "2408269119724499",
"daily_status": "Updated"
4
}

    API response when exist one or more invalid alerts ``` json

    { "status": "Tracked", "id": "2408269119724499", "daily_status": "Updated", "invalid_alerts": [] "invalid_alert": []

    } ```

    Frequency for sending data

    It is recommended to send a maximum of 1 data per vehicle every 20 seconds. for fleets more than 20 vehicles, 1 data per minute/vehicle, optimal frequency for a layout correct of the routes on the map.

    Loss of signal and sending of stored local data

    In the event that one or more vehicles circulate in areas outside the satellite range or before any factor that generates a loss of signal in the installed devices, recommends the use of “queues” (or “queues”) for data that could not be sent because of the above reason, and thus be able to send them later, when the signal is reset. When the latter occurs, the system could send data accumulated in the queue, and send them with a maximum time of 10 seconds between each one, until sending all the saved objects. Important: It should be considered that the range of 10 seconds applies only to data stored locally as a result of signal loss. The range for vehicles that are within satellite coverage maintain the recommended at the beginning of this document. Additionally, the data must be sent independently, an arrangement with all objects can cause errors in the communication of the call.

    Errors

    The SimpliRoute API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid. Review the data type and information sent.
    401 Unauthorized -- You are using the wrong API key to request the information.
    404 Not Found -- The request didn't found results.
    405 Method Not Allowed -- You tried to access to the endpoint with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    Datamart

    Datarmat is a REST API for data querying. To use this API, you will need a token that you can obtain from Customer Support.

    This API is located at https://api-gateway.simpliroute.com/datamart

    curl --location 'https://api-gateway.simpliroute.com/datamart/v1/visits' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZG9jdW1lbnRhdGlvbl9leGFtcGxlIiwiZXhwIjoxOTA2Mzg0MjY1LjB9.f2jx7t95gcZPNhUh31XIVv_9nXN5fYa04Om76U29iu4'

    An Authorization header is expected with a Bearer token.

    As an example, the cURL at the right panel requests Visits data 👉

    How does pagination work?

    Datamart delivers a maximum of 500 results per page. To request the next page, use the query parameter offset. For example, to request the second page of Visits, you would use /datamart/v1/visits?offset=500

    It is also possible to request pages with fewer than 500 results using the limit query parameter. For example: /datamart/v1/visits?limit=10&offset=20

    The response headers always include Content-Range, which indicates the page size and the total number of results. For cases when the number of results is higher the 100.000 the total won't be provided unless you requested with the header: Prefer: count=estimated

    What data is available in Datamart?

    Here's a list of currently available services:

    • /v1/visits: provides access to Visits. For more information about a Visit properties check here
    • /v1/plans: provide access to Plans.For more information about a Plan properties check here
    • /v1/routes: provide access to Plans.For more information about a Plan properties check here
    • /v1/extrafielddefinitions: an extrafield allows checkout forms customization.
    • /v1/extrafieldoptions: if an extrafield uses prefined options, they can be found in this service.
    • /v1/vehicles: provides access to Vehicles. For more information about a Vehicle properties check here
    • /v1/vehicles_skills: list of Skills asociated to a Vehicle.
    • /v1/fleets: a fleet represents a groupt of Vehicles.
    • /v1/vehicles_fleets: relationship between Fleet and Vehicles.
    • /v1/fleets_users: designed User (usually of rol driver) asociated with a given fleet.
    • /v1/observations: during the checkout an Observation can be attached to the Visit. This service provices access to those observations.
    • /v1/skills: list the available skills. For more details check here
    • /v1/tags: one or more Tags can be attached to a Visit. Here is the list of available Tags.
    • /v1/zones: a Zone represents a geographical area. Here the list of Zones defined for your account(s).
    • /v1/vehicles_zones: relationship between Vehicle and Zones.
    • /v1/visits_skills_optional: list of optional Skills defined for a Visit.
    • /v1/visits_skills_required: list of requiered Skills defined for a Visit.
    • /v1/visits_tags: list of Tags attached to a Visit.
    • /v1/visits_extrafieldvalues: list the values given to Extrafields during the Checkout, for a Visit.
    • /v1/visititems: access Visit Items, representing products or services tied to a visit. For more information about a Visit Item's properties, check here.
    • /v1/accounts: provides access to Accounts related to the Datamart role. It includes information about the account and its associated organization.
    • /v1/users: list of Users in your account. Web users, admins, monitors and drivers can be found here.
    • /v1/invoices: access Invoices, which represent financial documents. For more information about an Invoice's properties, check here.
    • /v1/invoiceitems: access Invoice Items, representing products or services listed in an Invoice. For more information about an Invoice Item's properties, check here.

    What filtering and sorting options does Datamart offer?

    Basic filtering

    This filter allows to query especific properties, for example:

    /v1/visits?select=id,address

    Will result in responses with id and address properties only

    Conditional filtering

    Give a condition to query for especific values. For example:

    /v1/visits?visit_type_id=eq.5335

    Will responde with Visit on which visit_type_id is equal to 5335. Aside from eq operator, gt or lt are available too.

    shell java javascript