Welcome

Welcome to the documentation of the Urbaner API. Here you have the necessary resources to generate delivery orders, calculate the delivery price and more.

The Urbaner API:

  • It is developed under the standards REST.
  • The available endpoints are resource oriented and return any of the HTTP response codes to indicate a satisfactory or failed result.
  • A JSON object is obtained in the response of each query to any available endpoint. Either for data obtained satisfactorily or errors.
  • To make use of the available endpoints you need to be authenticated. That's why that you must first have an Urbaner account (test or production environment) and get the associated TOKEN.

Integration Process

Here are the steps for a successful integration:

  1. *Tests in Sandbox Environment :

    • Account registration in [Sandbox](htt ps://app.sandbox.urbaner.com/registro) environment.
    • Use of the different available endpoints using the Token of the registered account in Sandbox. Any question or suggestion can be sent directly to the integration contacts (see section of Integration Contacts).
  2. Go to Production:

    • Account registration in Production environment.
    • Change of route from API to production and switch the Token (see section Urbaner Environments).

Urbaner Environments

Environment Description Root
Sandbox Here all the necessary tests are performed on the available endpoints. https://api.sandbox.urbaner.com/api/
Production Real use of resources using the data of the account registered. https://middleware.urbaner.com/api/

Integration Contacts

Contact Email Skype
Tecnología tecnologia@urbaner.com -

Authentication

To use the resources available in the Urbaner API, it is necessary to have a token that authenticates the account that will be used. There are two ways to obtain said token:

  • Through the WEB.
  • Using the Authentication Endpoint.

Get token via Web

Environment Root
Sandbox https://app.sandbox.urbaner.com
Production https://www.urbaner.com
  1. Registration of an account in the corresponding environment (Initially in sandbox for the necessary tests)

registro-landing

  1. Once inside the account, go to the bottom part of the option 'Mi Cuenta'

account-header

  1. This is the token that is needed to use the endpoints available in the Urbaner API.

micuenta2

Get token via API

Environment Endpoint
Sandbox https://api.sandbox.urbaner.com/api/client/authenticate/
Production https://middleware.urbaner.com/api/client/authenticate/

1. Send a JSON object with the parameters indicated below:

Parameter Description
email Your account email.
password Password

2. Get the TOKEN from the response:

  token = response['auth_token']
POST
/client/authenticate/

Example

$ curl -X POST https://api.sandbox.urbaner.com/api/client/authenticate/

Request Example

{
  "email": "test@cliente.com",
  "password": "lima123456"
}

Response Example

{
  "client": {
    "id": "1b022f3c-aa98-4a31-nn55-57a893ddc44f",
    "client_type_id": 1,
    "business_name": "",
    "email": "test@cliente.com",
    "fb_id": "",
    "last_name": "Juan",
    "name": "Perez",
    "phone": "+5149875421",
    "ruc": "12345678912",
    "tradename": "",
    "is_company": false,
    "is_active": true,
    "code_reference": "",
    "img": "/static/img/persona.png",
    "credit": false,
    "collection": false,
    "dni": "",
    "number_of_submissions": "",
    "score": 1,
    "type": {
      "name": "Usuario",
      "description": "Usuario"
    },
    "purse": 0,
    "use_default_address": false,
    "number_of_orders": 0,
    "has_payment_method": false,
    "order_types": [
      {
        "id": 1,
        "code": "EXP",
        "name": "EXPRESS",
        "image": "/media/package_types/express.png",
        "max_points": 20
      },
      {
        "id": 2,
        "code": "SDAY",
        "name": "SAMEDAY",
        "image": "/media/package_types/sameday.png",
        "max_points": 2
      },
      {
        "id": 3,
        "code": "NDAY",
        "name": "NEXTDAY",
        "image": "/media/package_types/nextday.png",
        "max_points": 2
      }
    ],
    "package_types": [
      {
        "id": 2,
        "name": "Moto",
        "image": "/media/packages/moto.png",
        "description": "",
        "specification": ""
      },
      {
        "id": 3,
        "name": "Auto",
        "image": "/media/packages/auto.png",
        "description": "",
        "specification": ""
      }
    ],
    "coupons": [

    ],
    "billing_account_name": "",
    "billing_email": "",
    "billing_address": "",
    "auth_token": "cb9135487asder14afdb6f1cdfc0e583ef2de8f4497",
    "has_expired_invoices": false,
    "is_merchant": false,
    "is_merchant_show": false,
    "is_merchant_pending": false,
    "is_merchant_active": false,
    "my_reference_code": "TEST01",
    "type_origin": "private",
    "allow_initial_price_modification": false,
    "has_payment_debt": false,
    "is_blocked_for_expired_invoices": false,
    "forms": [

    ],
    "user_origin_data": null,
    "security_configuration": {

    },
    "created_order_types": null
  },
  "auth_token": "cb9135487asder14afdb6f1cdfc0e583ef2de8f4497"
}

Types and Status

Here are the list of the basic values that you need to know to make a correct use of some of the main API endpoints like generate a delivery order or price caculation. You will have to use the ID or code specified below.

Order Types

ID Name Description
1 Express The order goes out in search of a courier instantly as notification until one accepts it
2 Sameday The order appears in the courier's inbox for one to accept and be completed during the day. Previous coordination between courier and client for the delivery time.
3 Nextday The order appears in the inbox of the courier for one to accept and be completed in the course of the programmed date with the specific TIME WINDOW. Previous coordination between courier and client for the delivery time.

Vehicle Types

ID Name Description
2 Motorcycle The most common vehicle to make a delivery.
3 Car It can be used in long distances and packages bigger than motorcycle.

Payment Types

Code Name Description
card Bank Card One card associated in your account.
purse Urbaner Purse Urbaner purse amount in your account. It can be charged only by an associated card.
credit Urbaner Credit Urbaner can give credit. Previous coordination. Contact soporte@urbaner.com.

Order Status

Status Label Description
created Created The order is not searching for a courier. It switches to searching status manually.
searching Searching The order is searching for a courier automatically.
accepted Accepted The order was accepted by a courier.
in_progress In Progress The courier has started the order.
no_courier No Courier The order has not found a courier.
ended Ended The courier has ended the order successfully.
cancelled Cancelled The order was cancelled.

Destination Status

Status Label Description
created Created The destination was created but not initialized.
started Started The courier started the point.
arrived Arrived The courier arrived the point.
failed Failed The courier marked as failed the point.
completed Completed The destination was completed successfully.

Data Structures

Here, each field of the basic structures is specified.

Payment Structure

Field Required Type Description
backend Yes string Code of your available payment.
args No object [Only sent in payment type 'card'] JSON with a field 'bankcard' that recieve and integer (ID of bankcard).

Card Structure

{
    "backend": "card",
    "args": {
        "bankcard": 123
    }
}

Purse Structure

{
    "backend": "purse"
}

Credit Structure

{
    "backend": "credit"
}

Destination Structure

Field Required Type Description
task Yes string Options are pickup, dropoff, return
latlon Yes string Coordinates latitude, longitude.
contact_person Yes string Fullname of the person.
phone Yes string Phone number.
address Yes string Address.
interior No string Specific number of Interior.
special_instructions No string Some reference of the address.
email No string Email of the point contact.
memo No string Client's own destination code identifier.
description No string Custom details about the destination.

Destination Structure

{
    "contact_person": "Visanet",
    "phone": "+51987945643",
    "address": "Jorge Chavez 184, Miraflores 15074, Peru",
    "latlon": "-12.119847 ,  -77.0370547",
    "interior": "floor 5",
    "special_instructions": "near a supermarket",
    "email": "hello@email.com",
    "memo": "CODE1",
    "description": "Hot meal, careful."
}

Order Actions

Action Description
cancel Cancel order with reason detail.
calculate_price Order base price calculation.
detail Get order detail configurations.

Help Endpoints

List Available Order Types

Obtain all your available order types.

GET
/client/order_types/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/order_types/ \
  -H 'authorization: token YOUR_TOKEN'

Example response

{
  "num_pages": 1,
  "next": null,
  "count": 3,
  "previous": null,
  "current_page": 1,
  "results": [
    {
      "id": 1,
      "code": "EXP",
      "name": "EXPRESS",
      "image": "https://urbaner-delivery.s3.amazonaws.com/media/package_types/express_SBfPdqd.png",
      "max_points": 100,
      "allow_return": true,
      "allow_programed_pickup": true,
      "allow_programed_dropoff": false,
      "allow_massiver_order": false
    },
    {
      "id": 2,
      "code": "SDAY",
      "name": "SAMEDAY",
      "image": "https://urbaner-delivery.s3.amazonaws.com/media/package_types/sameday_PtjNUpX.png",
      "max_points": 2,
      "allow_return": false,
      "allow_programed_pickup": false,
      "allow_programed_dropoff": false,
      "allow_massiver_order": true
    },
    {
      "id": 3,
      "code": "NDAY",
      "name": "NEXTDAY",
      "image": "https://urbaner-delivery.s3.amazonaws.com/media/package_types/nextday_ImhFLpE.png",
      "max_points": 2,
      "allow_return": false,
      "allow_programed_pickup": false,
      "allow_programed_dropoff": true,
      "allow_massiver_order": true
    }
  ]
}

List Available Vehicle Types

Obtain all your available vehicle types.

GET
/client/vehicle_types/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/vehicle_types/ \
  -H 'authorization: token YOUR_TOKEN'

Example response

{
  "num_pages": 1,
  "next": null,
  "count": 2,
  "previous": null,
  "current_page": 1,
  "results": [
    {
      "id": 2,
      "name": "Moto",
      "image": "https://urbaner-delivery.s3.amazonaws.com/media/packages/moto.png",
      "description": "Ideal para distancias largas, de mayor urgencia y mayor capacidad. Máximo 12 kg y/o 40x40x40 cm.",
      "specification": ""
    },
    {
      "id": 3,
      "name": "Auto",
      "image": "https://urbaner-delivery.s3.amazonaws.com/media/packages/auto.png",
      "description": "Ideal para mayor volumen y mayor carga. Máximo 90x70x50 cm (Maletera) y 90x60x50 cm (Asientos traseros).",
      "specification": ""
    }
  ]
}

List Payment Methods

Obtain all your available payment methods.

GET
/client/payment_methods/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/payment_methods/ \
  -H 'authorization: token YOUR_TOKEN'

Example response

{
  "results": [
    {
      "backend": "purse",
      "args": {
        "balance": 1000
      },
      "display": "Client purse"
    },
    {
      "backend": "card",
      "args": {
        "bankcard": 324
      },
      "display": "VISA XXXX-XXXX-XXXX-1111"
    },
    {
      "backend": "card",
      "args": {
        "bankcard": 397
      },
      "display": "VISA XXXX-XXXX-XXXX-1111"
    }
  ]
}

Register bankcard

The example shows a bankcard registration for sandbox environment.

Request fields specification

Field Type Description
name string Bankcard owners' name.
ccv string Bankcard ccv.
expiry_date string Bankcard expiration date (mm/yy).
billing_address string Client billing address email.
POST
/client/bankcards/

Example request

$ curl -X POST \
   https://api.sandbox.urbaner.com/api/client/bankcards/ \
  -H 'authorization: token YOUR_TOKEN'
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Sandbox",
        "number": "4111111111111111",
        "ccv": "111",
        "expiry_date": "12/2040",
        "billing_address": "sandbox"
    }'

Example response

{
  "id": 335,
  "number": "XXXX-XXXX-XXXX-1111",
  "card_type": "VISA"
}

List Bankcards

Obtain all your registered bankcards.

GET
/client/bankcards/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/bankcards/ \
  -H 'authorization: token YOUR_TOKEN'

Example response

{
    "previous": null,
    "results": [
        {
            "id": 777,
            "number": "XXXX-XXXX-XXXX-1111",
            "card_type": "VISA"
        },
        {
            "id": 888,
            "number": "XXXX-XXXX-XXXX-1111",
            "card_type": "VISA"
        }
    ],
    "num_pages": 1,
    "current_page": 1,
    "count": 2,
    "next": null
}

List Time Windows

Obtain all your available time windows grouped by Order Type.

Note: You must specify the timezone in the header.

GET
/client/order_types/delivery_windows_all/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/order_types/delivery_windows_all/ \
  -H 'authorization: token YOUR_TOKEN' 
  -H 'Time-Zone: America/Lima'

Example response

{
    "results": [
        {
            "order_type_code": "SDAY",
            "order_type_id": 2,
            "delivery_windows": [
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-27T09:00:00-05:00",
                            "delivery_to": "2019-06-27T12:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-27T00:00:00-05:00"
                }
            ]
        },
        {
            "order_type_code": "NDAY",
            "order_type_id": 3,
            "delivery_windows": [
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-27T09:00:00-05:00",
                            "delivery_to": "2019-06-27T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T12:00:00-05:00",
                            "delivery_to": "2019-06-27T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T15:00:00-05:00",
                            "delivery_to": "2019-06-27T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T18:00:00-05:00",
                            "delivery_to": "2019-06-27T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-27T00:00:00-05:00"
                },
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-28T09:00:00-05:00",
                            "delivery_to": "2019-06-28T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T12:00:00-05:00",
                            "delivery_to": "2019-06-28T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T15:00:00-05:00",
                            "delivery_to": "2019-06-28T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T18:00:00-05:00",
                            "delivery_to": "2019-06-28T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-28T00:00:00-05:00"
                },
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-29T09:00:00-05:00",
                            "delivery_to": "2019-06-29T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T12:00:00-05:00",
                            "delivery_to": "2019-06-29T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T15:00:00-05:00",
                            "delivery_to": "2019-06-29T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T18:00:00-05:00",
                            "delivery_to": "2019-06-29T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-29T00:00:00-05:00"
                }
            ]
        }
    ]
}

List Time Windows per Order Type

Obtain all the available time windows of a specific Order Type.

Note: You must specify the timezone in the heaer

GET
/client/order_types/{order_type_id}/delivery_windows_per_order_type/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/order_types/3/delivery_windows_per_order_type/ \
  -H 'authorization: token YOUR_TOKEN'
  -H 'Time-Zone: America/Lima'

Example response

{
    "results": [
        {
            "order_type_code": "NDAY",
            "order_type_id": 3,
            "delivery_windows": [
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-27T09:00:00-05:00",
                            "delivery_to": "2019-06-27T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T12:00:00-05:00",
                            "delivery_to": "2019-06-27T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T15:00:00-05:00",
                            "delivery_to": "2019-06-27T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-27T18:00:00-05:00",
                            "delivery_to": "2019-06-27T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-27T00:00:00-05:00"
                },
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-28T09:00:00-05:00",
                            "delivery_to": "2019-06-28T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T12:00:00-05:00",
                            "delivery_to": "2019-06-28T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T15:00:00-05:00",
                            "delivery_to": "2019-06-28T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-28T18:00:00-05:00",
                            "delivery_to": "2019-06-28T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-28T00:00:00-05:00"
                },
                {
                    "windows": [
                        {
                            "delivery_from": "2019-06-29T09:00:00-05:00",
                            "delivery_to": "2019-06-29T12:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T12:00:00-05:00",
                            "delivery_to": "2019-06-29T15:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T15:00:00-05:00",
                            "delivery_to": "2019-06-29T18:00:00-05:00"
                        },
                        {
                            "delivery_from": "2019-06-29T18:00:00-05:00",
                            "delivery_to": "2019-06-29T21:00:00-05:00"
                        }
                    ],
                    "date": "2019-06-29T00:00:00-05:00"
                }
            ]
        }
    ]
}

Delivery Generation Endpoints

Price Calculation

Obtain the delivery price calculation.

Request fields specification

Field Required Type Description
order_type_id No string ID of type of order
destinations Yes list List of Destinations
vehicle_type_id Yes string ID of vehicle type.
is_return Yes boolean If the courier needs to return to the origin point.

Response fields specification

Field Type Description
prices list List of objects with 2 fields: 'order_type' => string, 'price' => decimal.
distance decimal Total meters between pickup point to the final dropoff point.
duration decimal Total seconds between pickup point to the final dropoff point.
POST
/cli/price/

Example request

{
    "destinations": [
        {
            "latlon": "-12.119847 ,  -77.0370547"
        },
        {
            "latlon": "-12.0813873 , -77.07160499999999"
        }
    ],
    "vehicle_type_id": 1,
    "is_return": true
}
$ curl -X POST \
  https://api.sandbox.urbaner.com/api/cli/price/ \
  -H 'authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "destinations": [
        {
            "latlon": "-12.119847 ,  -77.0370547"
        },
        {
            "latlon": "-12.0813873 , -77.07160499999999"
        }
    ],
    "vehicle_type_id": 1,
    "is_return": true
}'

Example response

{
    "prices": [
        {
            "order_type": "EXPRESS",
            "price": 21.7
        },
        {
            "order_type": "NEXTDAY",
            "price": 9
        },
        {
            "order_type": "SAMEDAY",
            "price": 11
        }
    ],
    "distance": 14768.7,
    "duration": 1390.7
}

Delivery Generation

Create the delivery order.

Request fields specification

Field Required Type Description
type Yes string ID of type of order
destinations Yes list List of Destinations, minimun 2 points.
payment Yes object Backend of the payment
description Yes string Description of the order.
vehicle_id Yes string ID of vehicle.
memo No string Memo of the order.
programmed_date No timestamp Date and hour of the Order that must be delivered (This parameter only work with EXPRESS Orders and you have to add 5 hours [GMT-5] to your date because our server hour is in UTC)
is_return No boolean If the Courier needs to return to the origin point ‘true’, otherwise ‘false’
has_extended_search_time No boolean ‘False’ If the Order can be cancelled automatically when the searching time expired or ‘True’ If the time of searching for a Courier can be extended.
coupon No string The registered coupon of a client. If you do not have a cupon the do not pass this parameter in the body.
delivery_window_from No string The date with the start time of the delivery range. Format ISO 8601 (2019-06-28T14:00:00+0000).
delivery_window_to No string The date with the end time of the delivery range. Format ISO 8601 (2019-06-28T20:00:00+0000).

Response fields specification

Field Type Description
id integer ID of the delivery order.
code string Code of the delivery order.
status string Initial status of the delivery order.
tracking string URL of the realtime tracking for the delivery order.
POST
/cli/order/

Example request

{
    "type": "1",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    }
    ],
    "payment": {
        "backend": "purse"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "programmed_date": "2018-11-10 13:00:00",
    "is_return": "false",
    "has_extended_search_time": "true",
    "coupon": "MY_REGISTERED_COUPON",
    "delivery_window_from": "2019-06-28T14:00:00+0000",
    "delivery_window_to": "2019-06-28T20:00:00+0000"
}
$ curl -X POST \
  https://api.sandbox.urbaner.com/api/cli/order/ \
  -H 'authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "1",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    }
    ],
    "payment": {
        "backend": "purse"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "programmed_date": "2018-11-10 13:00:00",
    "is_return": "false",
    "has_extended_search_time": "true",
    "coupon": "MY_REGISTERED_COUPON"
}'

Example response

{
    "id": 12345,
    "code": "EXP-qeKoQLYc",
    "status": "searching",
    "tracking": "https://app.sandbox.urbaner.com/tracking/?data=NDc0NjY:1gr9ZS:PQwpezqgL_kynk4tdvm3emygcXQ"
}

NextDay

Create the delivery order.

Request fields specification

Field Required Type Description
type Yes string ID of type of order
destinations Yes list List of Destinations, minimun 2 points.
payment Yes object Backend of the payment
description Yes string Description of the order.
vehicle_id Yes string ID of vehicle.
memo No string Memo of the order.
programmed_date No timestamp Date and hour of the Order that must be delivered (This parameter only work with EXPRESS Orders and you have to add 5 hours [GMT-5] to your date because our server hour is in UTC)
is_return No boolean If the Courier needs to return to the origin point ‘true’, otherwise ‘false’
has_extended_search_time No boolean ‘False’ If the Order can be cancelled automatically when the searching time expired or ‘True’ If the time of searching for a Courier can be extended.
coupon No string The registered coupon of a client. If you do not have a cupon the do not pass this parameter in the body.
delivery_window_from No string The date with the start time of the delivery range. Format ISO 8601 (2019-06-28T14:00:00+0000).
delivery_window_to No string The date with the end time of the delivery range. Format ISO 8601 (2019-06-28T20:00:00+0000).

Response fields specification

Field Type Description
id integer ID of the delivery order.
code string Code of the delivery order.
status string Initial status of the delivery order.
tracking string URL of the realtime tracking for the delivery order.
POST
/cli/order/

Example request

{
    "type": "3",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    }
    ],
    "payment": {
        "backend": "credit"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "is_return": "false",
    "has_extended_search_time": "true",
    "delivery_window_from": "2020-07-15T09:00:00-05:00",
    "delivery_window_to": "2020-07-15T12:00:00-05:00"
}
$ curl -X POST \
  https://api.sandbox.urbaner.com/api/cli/order/ \
  -H 'authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
          "type": "3",
          "destinations": [
          {
            "contact_person": "Visanet",
            "phone": "+51987945643",
            "address": "Jorge Chavez 184, Miraflores 15074, Peru",
            "latlon": "-12.119847 ,  -77.0370547",
            "interior": "5",
            "special_instructions": "",
            "email": ""
          },
          {
            "contact_person": "Cliente de Visanet",
            "phone": "+51987456321",
            "address": "Avenida La Marina 550,  Pueblo Libre",
            "latlon": "-12.0813873 , -77.07160499999999",
            "interior": "5",
            "special_instructions": "",
            "email": ""
          }
          ],
          "payment": {
              "backend": "credit"
          },
          "description": "comida",
          "vehicle_id": "2",
          "memo": "Orden #34",
          "is_return": "false",
          "has_extended_search_time": "true",
          "delivery_window_from": "2020-07-15T09:00:00-05:00",
          "delivery_window_to": "2020-07-15T12:00:00-05:00"
      }'

Example response

{
    "id": 12345,
    "code": "EXP-qeKoQLYc",
    "status": "searching",
    "tracking": "https://app.sandbox.urbaner.com/tracking/?data=NDc0NjY:1gr9ZS:PQwpezqgL_kynk4tdvm3emygcXQ"
}

Simplify the orders generation

Draft Creation

You can save a draft of the order to rebuild it more quickly.

POST
/client/drafts/

Example request

$ curl -X POST \
  https://api.sandbox.urbaner.com/api/client/drafts/ \
  -H 'Authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "1",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    }
    ],
    "payment": {
        "backend": "purse"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "programmed_date": "2018-11-10 13:00:00",
    "is_return": "false",
    "has_extended_search_time": "true",
    "coupon": "MY_REGISTERED_COUPON"
}'

Example response

{   
    "id": 217,
    "coupon": "MY_REGISTERED_COUPON",
    "price": 0,
    "memo": "Orden #34",
    "type": "1",
    "payment": {
        "backend": "purse"
    },
    "vehicle_id": "2",
    "has_extended_search_time": "true",
    "programmed_date": "2018-11-10 13:00:00",
    "description": "comida",
    "created_at": "2019-02-06T15:06:38.438214Z",
    "destinations": [
        {
            "interior": "5",
            "latlon": "-12.119847 ,  -77.0370547",
            "phone": "+51987945643",
            "special_instructions": "",
            "contact_person": "Visanet",
            "email": "",
            "address": "Jorge Chavez 184, Miraflores 15074, Peru"
        },
        {
            "interior": "5",
            "latlon": "-12.0813873 , -77.07160499999999",
            "phone": "+51987456321",
            "special_instructions": "",
            "contact_person": "Cliente de Visanet",
            "email": "",
            "address": "Avenida La Marina 550,  Pueblo Libre"
        }
    ],
    "is_return": "false"
}

My Orders information

Retrieve Order

Obtain the data of a specific order.

GET
/client/orders/{id}/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/orders/123/ \
  -H 'Authorization: token YOUR_TOKEN'

Example response

{
    "id": 123,
    "code": "EXP-0fRe1nQy",
    "type": 1,
    "price": 11.2,
    "cancelation_price": 0,
    "waiting_time_price": 0,
    "price_modification": 0,
    "total_price": 11.2,
    "duration": "658.60",
    "distance": "6936.90",
    "description": "comida",
    "memo": "Orden #34",
    "destinations": [
        {
            "number": 1,
            "task": "pickup",
            "task_label": "Recojo",
            "phone": "+51987945643",
            "email": "",
            "interior": "5",
            "contact_person": "Visanet",
            "name_destination": "Jorge Chavez 184, Miraflores 15074, Peru",
            "special_instructions": "",
            "status": "created",
            "latlon": "-12.119847,-77.0370547",
            "created_at": "2019-02-06T15:42:29+0000",
            "updated_at": "2019-02-06T15:42:29+0000",
            "started_at": null,
            "status_label": "Fecha de creación",
            "arrived_at": null,
            "failed_at": null,
            "completed_at": null,
            "signature": null,
            "photo": null,
            "photo2": null,
            "destination_contact": null,
            "destination_dni": null,
            "collection": null,
            "rating": null,
            "rating_description": null,
            "waiting_time_seconds": 0,
            "leaves_at": null,
            "out_point": null,
            "failed_reason": null,
            "is_secure": false,
            "photos": []
        },
        {
            "number": 2,
            "task": "dropoff",
            "task_label": "Entrega",
            "phone": "+51987456321",
            "email": "",
            "interior": "5",
            "contact_person": "Cliente de Visanet",
            "name_destination": "Avenida La Marina 550,  Pueblo Libre",
            "special_instructions": "",
            "status": "created",
            "latlon": "-12.0813873,-77.07160499999999",
            "created_at": "2019-02-06T15:42:29+0000",
            "updated_at": "2019-02-06T15:42:29+0000",
            "started_at": null,
            "status_label": "Fecha de creación",
            "arrived_at": null,
            "failed_at": null,
            "completed_at": null,
            "signature": null,
            "photo": null,
            "photo2": null,
            "destination_contact": null,
            "destination_dni": null,
            "collection": null,
            "rating": null,
            "rating_description": null,
            "waiting_time_seconds": 0,
            "leaves_at": null,
            "out_point": null,
            "failed_reason": null,
            "is_secure": false,
            "photos": []
        }
    ],
    "status": "searching",
    "courier": null,
    "vehicle_type": {
        "id": 2,
        "name": "Moto",
        "image": "https://urbaner-delivery-dev.s3.amazonaws.com/media/packages/moto_con_caja_omaleta.png",
        "description": "Hasta 45x45x35cm ó 15Kgs",
        "specification": ""
    },
    "end_date": null,
    "start_date": null,
    "created_at": "2019-02-06T15:42:29+0000",
    "assignment_date": null,
    "programmed_date": null,
    "score": null,
    "score_description": null,
    "url": "https://app.dev.urbaner.com/tracking/?data=NDc0OTE:1grPUk:Ig1HalAzWlRRXC6Q4T6Ur3GsPNQ",
    "is_return": false,
    "collection_type": null,
    "status_label": "Buscando",
    "current_destination_label": "Buscando",
    "current_destination_number": null,
    "expiration_time": 615,
    "payment_type": "purse",
    "has_rated": false,
    "assignment_code": "2afeaf",
    "has_extended_search_time": false,
    "waiting_time_alert": 60,
    "cancellation_reason": null,
    "delivery_window_from": null,
    "delivery_window_to": null,
    "estimated_end_time": null,
    "extra_data": {},
    "city": {
        "country": "Perú",
        "iso_code": "PE",
        "name": "Lima",
        "latlon": "-12.0464,-77.0428",
        "city_code": "1",
        "city_id": "1",
        "timezone": "America/Lima"
    },
    "status_redirect": "active"
}

Retrieve Draft

Get the data of a specific draft.

GET
/client/drafts/{id}/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/drafts/123/ \
  -H 'Authorization: token YOUR_TOKEN'

Example response

{
    "id": 123,
    "vehicle_id": "2",
    "has_extended_search_time": "true",
    "price": 0,
    "memo": "Orden #34",
    "description": "comida",
    "type": "1",
    "destinations": [
        {
            "interior": "5",
            "latlon": "-12.119847 ,  -77.0370547",
            "phone": "+51987945643",
            "special_instructions": "",
            "address": "Jorge Chavez 184, Miraflores 15074, Peru",
            "email": "",
            "contact_person": "Visanet"
        },
        {
            "interior": "5",
            "latlon": "-12.0813873 , -77.07160499999999",
            "phone": "+51987456321",
            "special_instructions": "",
            "address": "Avenida La Marina 550,  Pueblo Libre",
            "email": "",
            "contact_person": "Cliente de Visanet"
        }
    ],
    "created_at": "2019-02-06T15:56:49.586927Z",
    "payment": {
        "backend": "purse"
    },
    "is_return": "true"
}

List Orders

Get orders paginated. Number of orders per page is 300. Default pagination is 1.

GET
/client/orders/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/orders/ \
  -H 'Authorization: token YOUR_TOKEN'

Example response

{
    "num_pages": 2,
    "current_page": 1,
    "previous": null,
    "next": "https://api.sandbox.urbaner.com/api/client/orders/?page=2",
    "count": 73,
    "results": [
        {
            "id": 123,
            "code": "EXP-N2IJ0M1T",
            "created_at": "2019-02-06T15:47:32+0000",
            "programmed_date": null,
            "status": "searching",
            "status_label": "Buscando",
            "current_destination_label": "Buscando",
            "memo": "Orden #34",
            "description": "comida",
            "distance": "6936.90",
            "duration": "658.60",
            "is_return": false,
            "price": 11.2,
            "cancelation_price": 0,
            "waiting_time_price": 0,
            "price_modification": 0,
            "price_modification_comment": "",
            "total_price": 11.2,
            "url": "https://app.sandbox.urbaner.com/tracking/?data=NDc0OTY:1grPbt:YBcAix2slqD2qwso_vk57fNxNiU",
            "assignment_code": "7ae026",
            "type": 1,
            "vehicle_type": {
                "id": 2,
                "name": "Moto",
                "image": "https://urbaner-delivery-sanbox.s3.amazonaws.com/media/packages/moto_con_caja_omaleta.png",
                "description": "Hasta 45x45x35cm ó 15Kgs",
                "specification": ""
            },
            "payment_type": "purse",
            "courier": null,
            "destinations": [
                {
                    "id": 96090,
                    "contact_person": "Visanet",
                    "name_destination": "Jorge Chavez 184, Miraflores 15074, Peru",
                    "interior": "5",
                    "phone": "+51987945643",
                    "special_instructions": "",
                    "number": 1,
                    "task": "pickup",
                    "task_label": "Recojo",
                    "email": "",
                    "latlon": "-12.119847,-77.0370547",
                    "created_at": "2019-02-06T15:47:32+0000",
                    "started_at": null,
                    "arrived_at": null,
                    "completed_at": null,
                    "failed_at": null,
                    "status": "created",
                    "status_label": "Fecha de creación"
                },
                {
                    "id": 96091,
                    "contact_person": "Cliente de Visanet",
                    "name_destination": "Avenida La Marina 550,  Pueblo Libre",
                    "interior": "5",
                    "phone": "+51987456321",
                    "special_instructions": "",
                    "number": 2,
                    "task": "dropoff",
                    "task_label": "Entrega",
                    "email": "",
                    "latlon": "-12.0813873,-77.07160499999999",
                    "created_at": "2019-02-06T15:47:32+0000",
                    "started_at": null,
                    "arrived_at": null,
                    "completed_at": null,
                    "failed_at": null,
                    "status": "created",
                    "status_label": "Fecha de creación"
                }
            ],
            "current_destination_number": null,
            "waiting_time_alert": 60,
            "score": null,
            "score_description": null,
            "has_rated": false,
            "id_order_shop": 0,
            "delivery_window_from": null,
            "delivery_window_to": null,
            "order_batch_code": null
        },
        .
        .
        .
    ]
}

List Drafts

Get all my drafts paginated.

GET
/client/drafts/

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/drafts/ \
  -H 'Authorization: token YOUR_TOKEN'

Example response

{
    "num_pages": 1,
    "current_page": 1,
    "previous": null,
    "next": null,
    "count": 14,
    "results": [
        {
            "id": 123,
            "vehicle_id": "2",
            "has_extended_search_time": "true",
            "price": 0,
            "memo": "Orden #34",
            "description": "comida",
            "type": "1",
            "destinations": [
                {
                    "interior": "5",
                    "latlon": "-12.119847 ,  -77.0370547",
                    "phone": "+51987945643",
                    "special_instructions": "",
                    "address": "Jorge Chavez 184, Miraflores 15074, Peru",
                    "email": "",
                    "contact_person": "Visanet"
                },
                {
                    "interior": "5",
                    "latlon": "-12.0813873 , -77.07160499999999",
                    "phone": "+51987456321",
                    "special_instructions": "",
                    "address": "Avenida La Marina 550,  Pueblo Libre",
                    "email": "",
                    "contact_person": "Cliente de Visanet"
                }
            ],
            "created_at": "2019-02-06T15:56:49.586927Z",
            "payment": {
                "backend": "purse"
            },
            "is_return": "true"
        },
        .
        .
        .
    ]
}

List Cancelation Reasons

Get all cancelation reasons by client or generic.

GET
/client/status_reason/?status=cancelled

Example request

$ curl -X GET \
  https://api.sandbox.urbaner.com/api/client/status_reason/?status=cancelled  \
  -H 'authorization: token YOUR_TOKEN'

Example response

{
  "status_reason": [
    {
      "description": "Anula compra.",
      "status": "cancelled",
      "id": 5
    },
    {
      "description": "Cambio ventana o fecha de despacho.",
      "status": "cancelled",
      "id": 4
    }
  ],
  "allow_optional_cancelation_reason": false
}

Order Cancelation

Sending the ID of a previously created order you can easily cancel that order.

PUT
/client/orders/{id}/cancel/

Example request

{
    "cancellation_reason": "Anula compra."
}
$ curl -X PUT \
  https://api.sandbox.urbaner.com/api/cli/client/orders/123/cancel/ \
  -H 'authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancellation_reason": "Anula compra."
}'

Example response

{
    "id": 123,
    "vehicle_id": "2",
    "has_extended_search_time": "true",
    "price": 0,
    "memo": "Orden #34",
    "description": "comida",
    "type": "1",
    "destinations": [
        {
            "interior": "5",
            "latlon": "-12.119847 ,  -77.0370547",
            "phone": "+51987945643",
            "special_instructions": "",
            "address": "Jorge Chavez 184, Miraflores 15074, Peru",
            "email": "",
            "contact_person": "Visanet"
        },
        {
            "interior": "5",
            "latlon": "-12.0813873 , -77.07160499999999",
            "phone": "+51987456321",
            "special_instructions": "",
            "address": "Avenida La Marina 550,  Pueblo Libre",
            "email": "",
            "contact_person": "Cliente de Visanet"
        }
    ],
    "created_at": "2019-02-06T15:56:49.586927Z",
    "payment": {
        "backend": "purse"
    },
    "is_return": "true"
}

Courier Availability

Use same order creation payload to check courier availability.

POST
/client/order/courier_availability/

Example request

{
    "destinations": [
        {
            "task": "pickup",
            "contact_person": "gaby",
            "interior": "703",
            "latlon": "-12.126,-77.020607",
            "name_destination": "Avenida Alfredo Benavides 1180, Benavides, Miraflores, 15047",
            "phone": "+51999999999",
            "special_instructions": "x"
        },
        {
            "task": "dropoff",
            "contact_person": "haidy",
            "interior": "405 B",
            "latlon": "-12.11511,-77.02638",
            "name_destination": "Avenida Paseo de la República, Surquillo, Miraflores, 15074",
            "phone": "+5134534534",
            "special_instructions": "x"
        }
    ],
    "is_return": false,
    "is_programmed": false,
    "payment": {
        "backend": "purse"
    },
    "type": 1,
    "vehicle_type_id": 2
}

Example response

{
    "result": true
}

Check Danger Point

Check is a point is in a Danger Zone.

POST
/api/client/check/is_danger/coverage/

Example request

{
  "latlon": "-12.5197811,-76.7832343"
}

Example response

{
  "result": true
}

Webhooks

Configuration

You need to active in your account (Sandbox/Production environment) the webhook option and passing an URL to send the differents order and destination status.

URL Webhook

In Development You should sign in to your account and go to the option 'Mi Cuenta'. Go to the section 'Webhook' and put the URL that we can send the differents order and destination status. If your URL endpoint need some headers (Example: Authorization, etc), then you need to register each header. In Production You have to send your endpoint and the required credentials (headers) to the integration contact emails.

Data sent

When a delivery order or destination has changed the status, we will send a POST request with the next fields:

Field Type Description
id integer ID of the delivery order.
status string Status Code of the delivery order.
status_label string Status Label of the delivery order.
destination_status_label string Status Label of the pickup or dropoffs.
memo string Memo of Delivery Order (in this field you may want to save the ID of your order on your system).

The status and content response that we received is saved.

Example request

{
    "id": 123,
    "status": "in_progress",
    "status_label": "In Progress",
    "destination_label": "On the way to pickup",
    "memo": "11111",
    "destinations": [
            {"number":1, "status": "started"},
            {"number":2, "status": "created"}
    ]
}

In Development

New incoming changes

NEW Item Structure

Field Required Type Description
code Yes string Items' code.
width Yes float Items' width.
height Yes float Items' height.
depth Yes float Items' depth.
weight Yes float Items' weight.
quantity No integer Items' quantity. Default 1.

NEW Item Structure

{
    "code": "CODIGOPRO1",
    "width": 8,
    "height": 15,
    "depth": 10,
    "weight": 5,
    "quantity": 1
}

NEW Destination Structure

Field Required Type Description
contact_person Yes string Fullname of the Person.
phone Yes string Phone number.
address Yes string Address.
latlon Yes string Coordinates "latitude, longitude".
interior No string Specific number of Interior.
special_instructions No string Some reference of the address.
email No string Email of the point contact.
package_type_id No string The package that contains the list of your items.
items No list The list of your items with dimensions.

NEW Destination Structure

{
    "contact_person": "Visanet",
    "phone": "+51987945643",
    "address": "Jorge Chavez 184, Miraflores 15074, Peru",
    "latlon": "-12.119847 ,  -77.0370547",
    "interior": "5",
    "special_instructions": "near a supermarket",
    "email": "hello@email.com",
    "package_type_id": "1",
    "items": [
    	{
            "code": "CODIGOPRO1",
            "width": 8,
            "height": 15,
            "depth": 10,
            "weight": 5
        },
        	{
            "code": "CODIGOPRO2",
            "width": 9,
            "height": 10,
            "depth": 15,
            "weight": 8
        }
    ]
}

NEW Delivery Generation

Create the delivery order.

New changes: The 'vehicle_id' is now optional, but you have to put the 'package_type' or the list of items with their dimentions.

Request fields specification

Field Required Type Description
type Yes string ID of type of order
destinations Yes list List of Destinations, minimun 2 points.
payment Yes object Backend of the payment
description Yes string Description of the order.
vehicle_id No string ID of vehicle.
memo No string Memo of the order.
programmed_date No timestamp Date and hour of the Order that must be delivered (This parameter only work with EXPRESS Orders and you have to add 5 hours [GMT-5] to your date because our server hour is in UTC)
is_return No boolean If the Courier needs to return to the origin point ‘true’, otherwise ‘false’
has_extended_search_time No boolean ‘False’ If the Order can be cancelled automatically when the searching time expired or ‘True’ If the time of searching for a Courier can be extended.
coupon No string The registered coupon of a client. If you do not have a cupon the do not pass this parameter in the body.

Response fields specification

Field Type Description
id integer ID of the delivery order.
code string Code of the delivery order.
status string Initial status of the delivery order.
tracking string URL of the realtime tracking for the delivery order.
POST
/cli/order/

Example request

{
    "type": "1",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": "",
      "package_type_id": "1",
      "items": [
            {
                "code": "CODIGOPRO1",
                "width": 8,
                "height": 15,
                "depth": 10,
                "weight": 5
            },
                {
                "code": "CODIGOPRO2",
                "width": 9,
                "height": 10,
                "depth": 15,
                "weight": 8
            }
        ]
    }
    ],
    "payment": {
        "backend": "purse"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "programmed_date": "2018-11-10 13:00:00",
    "is_return": "false",
    "has_extended_search_time": "true",
    "coupon": "MY_REGISTERED_COUPON"
}
$ curl -X POST \
  https://api.sandbox.urbaner.com/api/cli/order/ \
  -H 'authorization: token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "1",
    "destinations": [
    {
      "contact_person": "Visanet",
      "phone": "+51987945643",
      "address": "Jorge Chavez 184, Miraflores 15074, Peru",
      "latlon": "-12.119847 ,  -77.0370547",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    },
    {
      "contact_person": "Cliente de Visanet",
      "phone": "+51987456321",
      "address": "Avenida La Marina 550,  Pueblo Libre",
      "latlon": "-12.0813873 , -77.07160499999999",
      "interior": "5",
      "special_instructions": "",
      "email": ""
    }
    ],
    "payment": {
        "backend": "purse"
    },
    "description": "comida",
    "vehicle_id": "2",
    "memo": "Orden #34",
    "programmed_date": "2018-11-10 13:00:00",
    "is_return": "false",
    "has_extended_search_time": "true",
    "coupon": "MY_REGISTERED_COUPON"
}'

Example response

{
    "id": 12345,
    "code": "EXP-qeKoQLYc",
    "status": "searching",
    "tracking": "https://app.sandbox.urbaner.com/tracking/?data=NDc0NjY:1gr9ZS:PQwpezqgL_kynk4tdvm3emygcXQ"
}
Urbaner API Documentation