NAV Navbar
shell

Introduction

Zubut public API grant access to the different types of services that our company provides and our network of couriers.

Authentication

To authorize calls to our API the user must first login:

$ curl -X POST \
  https://api.zubut.com/api/zUsers/login \
  -H 'Content-Type: application/json' \
  -d '{
      "email": "[email protected]",
      "password": "MyZubutPassword"
    }'

If successful, the server will respond with a JSON object from where you can obtain your access token for the upcoming calls:

HTTP/1.1 200 OK
{
    // The "id" field is what you'll want to hold on to.
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ttl": 1209600, // Time in seconds for which this token is valid
    "created": "xxxx-xx-xxTxx:xx:xx.xxxZ", // Date String
    "userId": "XXXXXXXXXXXXXXXXXXXXXXXX"
}

Make sure to place your token's id in the Authorization header of any following request

$ curl -X POST \
  https://api.zubut.com/api/Services/getActiveServices \
  -H "Accept: application/json" \
  -H "Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-type: application/json"

Zubut's API uses Access Tokens to authenticate its users, it is expected that all API requests to the server include a user's valid Access Token in either of the following:

A header:

Authorization: XXXXXXXXXXXXXXX

A query parameter:

<api_call>?access_token=XXXXXXXXXXXXXXX

Errors

Errors may be returned in the following format by our API

HTTP/1.1 400 Bad Request
{
    "error": {
        "statusCode": 400, // HTTP status code.
        "name" : "Missing field 'name'.", // Explanation of this particular error.
        "message": "Error al intentar crear XYZ, campo 'name' faltante." // Error explanation but in spanish.
    }
}

The Zubut API uses standard HTTP status codes as follows:

Error Code Meaning Description
400 Bad Request Your request is invalid.
401 Unauthorized Your access token is invalid or you do not have access.
403 Forbidden Your access is restricted from this resource.
404 Not Found The specified resource could not be found or does not exist.
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.

Services

Request

Definition

POST https://api.zubut.com/api/Services/request

Example Request

$ curl -X POST \
     https://api.zubut.com/api/Services/request \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "service": {
               "destinations": [
                    {
                         "name": "My origin point",
                         "address": "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico",
                         "information": "Entre calle Toronto y calle Otranto, cochera con porton verde",
                         "position": {
                              "lat": 20.6880487,
                              "lng": -103.4182991
                         },
                         "phone": "3322001122"
                    },
                    {
                         "position": {
                              "lat": 20.7234545,
                              "lng": -103.4123161
                         },
                         "name": "Juan Perez",
                         "address": "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                         "phone": "3338887654",
                         "information": "Oficinas Zubut"
                    }
               ]
          },
          "vehicleType": 0,
          "cityId": "x0x00x000xx00x000x00x0xx"
     }'

Example Response

HTTP/1.1 200 Success
{
     "response": {
          "id" : "000000000xx00x000x00x0x0",
          "destinations" : [
               {
                    "order" : 0,
                    "name" : "My origin point",
                    "address" : "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico",
                    "information" : "Entre calle Toronto y calle Otranto, cochera con porton verde",
                    "position" : {
                         "lat" : 20.6880487,
                         "lng" : -103.4182991
                    },
                    "phone" : "3322001122"
               },
               {
                    "position" : {
                         "lat" : 20.7234545,
                         "lng" : -103.4123161
                    },
                    "name" : "Juan Perez",
                    "address" : "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                    "phone" : "3338887654",
                    "information" : "Oficinas Zubut",
                    "order" : 1
               }
          ],
          "km": X.XXX,
          "serviceTime": XX,
          "estimatedRate": XX,
          "paid": false,
          "status": 0,
          "createdAt": "20XX-XX-XXTXX:XX:XX.XXXZ",
          "archived": false,
          "id": "000000000xx00x000x00x0x0",
          "zUsersId": "0x00x0000xx00x000x00x0x0",
          "sentFrom": X,
          "additionalOptions": [
               {
                    "signature": false,
                    "scheduled": false,
                    "evidence": false,
                    "driverReturn": false
               }
          ],
          "vehicleType": 0,
          "cardId": "x00000000xx00x0x0x00x0x0",
          "distinguished": false,
          "cityId": "x0x00x000xx00x000x00x0xx"
     }
}

HTTP Method

POST

This method will create a Service with the given destinations. Also it will automatically search and designate it an available courier.

Body Parameters Type Required Description
service Object Yes JSON object that contains all the info of your destinations.
vehicleType integer Yes Identifier of the desired vehicle. Parameter inside service object.
cityId string Yes Identifier of the city where the service is requested. Parameter inside service object.

Success response

Response Type Description
response Object Service object created.

Error response

Error Code Meaning
400 Missing data.
401 Unauthorized.
500 Internal error.

Edit Service

Definition

POST https://api.zubut.com/api/Services/editService

Example Request

$ curl -X POST \
     https://api.zubut.com/api/Services/editService \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "service": {
              "destinations": [   // Required field.
                  {
                      "name": "My origin point",
                      "address": "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico",
                      "information": "Entre calle Toronto y calle Otranto, cochera con porton azul",
                      "position": {
                          "lat": 20.6880487,
                          "lng": -103.4182991
                      },
                      "phone": "33119902"
                  },
                  {
                      "position" : {
                           "lat" : 20.7234545,
                           "lng" : -103.4123161
                      },
                      "name" : "Juan Perez",
                      "address" : "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                      "phone" : "3338887654",
                      "information" : "Oficinas Zubut"
                  }
              ],
              "vehicleType": 1,
              "cardId": "y00000000yy00y0y0y00y0y0",
              "additionalOptions": [
                  {
                      "signature": true,
                      "scheduled": false,
                      "evidence": true,
                      "driverReturn": false
                  }
              ]
          }
     }'

Example Response

HTTP/1.1 200 Success
{
     "response": {
          "id" : "000000000xx00x000x00x0x0",
          "destinations" : [
              {
                  "order" : 0,
                  "name" : "My origin point",
                  "address" : "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico",
                  "information" : "Entre calle Toronto y calle Otranto, cochera con porton azul",
                  "position" : {
                      "lat" : 20.6880487,
                      "lng" : -103.4182991
                  },
                  "phone" : "33119902"
              },
              {
                  "position" : {
                       "lat" : 20.7234545,
                       "lng" : -103.4123161
                  },
                  "name" : "Juan Perez",
                  "address" : "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                  "phone" : "3338887654",
                  "information" : "Oficinas Zubut",
                  "order" : 1
              }
          ],
          "km": X.XXX,
          "serviceTime": XX,
          "estimatedRate": XX,
          "paid": false,
          "status": 0,
          "createdAt": "20XX-XX-XXTXX:XX:XX.XXXZ",
          "archived": false,
          "id": "000000000bb00b000b00b0b0",
          "zUsersId": "0x00x0000xx00x000x00x0x0",
          "sentFrom": X,
          "additionalOptions": [
              {
                  "signature": true,
                  "scheduled": false,
                  "evidence": true,
                  "driverReturn": false
              }
          ],
          "vehicleType": 1,
          "cardId": "y00000000yy00y0y0y00y0y0",
          "distinguised": false,
          "cityId": "x0x00x000xx00x000x00x0xx"
     }
}

HTTP Method

POST

Update an already existing Service. The user can update destinations, vehicleType, additionalOptions and payment method. A Service's origin point can't be updated if the courier has already arrived, and a Service can no longer be updated if the courier has retrieved the package at the origin. If vehicleType is changed, the current service will be cancelled and a new Service will be created and requested.

Body Parameters Type Required Description
service Object Yes Service JSON including destinations, additional options, vehicleType and payment method.

Success response

Response Type Description
response Object Updated instance of Service.

Error response

Error Code Meaning
400 Can't be updated or missing data.
401 Unauthorized.
404 No such Service was found.
500 Internal error.

Service Estimation

Definition

POST https://api.zubut.com/api/Services/serviceEstimation

Example Request: Using Addresses

$ curl -X POST \
     https://api.zubut.com/api/Services/serviceEstimation \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "destinations": {
               "destinations": [
                    {
                         "address": "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico"
                    },
                    {
                         "address": "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                    }
               ]
          }
     }'

Example Request: Using Coordinates

$ curl -X POST \
     https://api.zubut.com/api/Services/serviceEstimation \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "destinations": {
               "destinations": [
                    {
                         "position": {
                              "lat": 20.6880487,
                              "lng": -103.4182991
                         }
                    },
                    {
                         "position": {
                              "lat": 20.7234545,
                              "lng": -103.4123161
                         },
                    }
               ]
          }
     }'

Example Response

HTTP/1.1 200 Success
{
     "serviceEstimation" : {
          "rate": 70,
          "time": 20
     }
}

HTTP Method

POST

Given two valid map addresses, this method will return the estimated service cost, time and km.

Note: It works with a full address and no zipcode or neighborhood for an accurate calculation.

Body Parameters Type Required Description
destinations Object Yes JSON with service destinations containing either the addresses or coordinates.

Success response

Response Type Description
serviceEstimation Object Estimation values according to request (km, cost, estimated time).

Error response

Error Code Meaning
400 Missing data.
401 Unauthorized.
500 Internal error.

Cancel Request

Definition

POST https://api.zubut.com/api/Services/cancelRequest

Example Request

$ curl -X POST \
     https://api.zubut.com/api/Services/cancelRequest \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "serviceId": "000000000xx00x000x00x0x0"
     }'

Example Response

HTTP/1.1 200 Success
{
     "response" : {
          "status": 200,
          "message" "Service cancelled"
     }
}

HTTP Method

POST

Use this method if you want to cancel ASAP your current service request and it hasn't been accepted.

Body Parameters Type Required Description
serviceId string Yes Id of the requested Service.

Success response

Response Type Description
response Object Response from the server.

Error response

Error Code Meaning
400 Service request couldn't be cancelled or missing data.
401 Unauthorized.
404 No such Service was found.
500 Internal error.

Get & Track Active Services

Definition

GET https://api.zubut.com/api/Services/getActiveServices

Example Request

$ curl -X GET \
     https://api.zubut.com/api/Services/getActiveServices \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \

Example Response

HTTP/1.1 200 Success
{
     "services": [{
          "id" : "000000000xx00x000x00x0x0",
          "destinations" : [
               {
                    "order" : 0,
                    "name" : "My origin point",
                    "address" : "Calle Mónaco 2526, italia providencia, Guadalajara, Mexico",
                    "information" : "Entre calle Toronto y calle Otranto, cochera con porton verde",
                    "position" : {
                         "lat" : 20.6880487,
                         "lng" : -103.4182991
                    },
                    "phone" : "33119902"
               },
               {
                   "position" : {
                        "lat" : 20.7234545,
                        "lng" : -103.4123161
                   },
                   "name" : "Juan Perez",
                   "address" : "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                   "phone" : "3338887654",
                   "information" : "Oficinas Zubut",
                    "order" : 1
               }
          ],
          "km" : 5.358,
          "serviceTime" : 11,
          "estimatedRate" : 48,
          "status": "Aceptado",
          "cancelled": false,
          "createdAt": "2018-12-19T13:02:41-06:00",
          "sentFrom": 3,
          "additionalOptions": [
               {
                    "signature": false,
                    "scheduled": false,
                    "evidence": false,
                    "driverReturn": false
               }
          ],
          "zUserId": "590c9fc89e38f7001e5ceb87",
          "vehicleType": 0,
          "courier": {
               "name": "José López",
               "phone": "345331421111",
               "image": "https://zubut.com/images/profile/1459097361663.jpeg",
               "alpha": true
          },
          "resume": {
               "acceptedAt": "2018-12-19T13:03:32-06:00"
          },
          "serviceOrder": 0,
          "eta": "13:14 pm",
          "progress": "Tu mensajero va en camino a: My origin point",
          "progressId": 0,
          "progressText": "Aceptado"
     },
     ...
     ]
}

Example Response (having no services)

HTTP/1.1 200 Success
{
     "services": []
}

HTTP Method

GET

This method retrieves details of all your active services so your can track them or watch their status, see who's your courier, etc.

Success response

Response Type Description
services Array[Object] Collection response from server with your active services.

Error response

Error Code Meaning
401 Invalid access token.
500 Internal error.

Get a specific Service's details

Definition

GET https://api.zubut.com/api/Services/{id}/details

Example Request

$ curl -X GET \
     https://api.zubut.com/api/Services/000000000xx00x000x00x0x0/details \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \

Example Response

HTTP/1.1 200 Success
{
    "service": {
        "id": "000000000xx00x000x00x0x0",
        "destinations": [
            {
                "address": "Av. Patria, Zapopan, Jal., México",
                "position": {
                    "lat": 20.XXXXXX,
                    "lng": -103.XXXXXX
                },
                "name": "Juan Lopez Casa",
                "phone": "3333333333",
                "order": 0,
                "arrived": true
            },
            {
                "position" : {
                     "lat" : 20.7234545,
                     "lng" : -103.4123161
                },
                "name" : "Juan Perez",
                "address" : "Av. Acueducto 6050, Lomas del Bosque, Plaza Acueducto, 45116 Zapopan, Jal.",
                "phone" : "3338887654",
                "information" : "Oficinas Zubut",
                "order": 1,
                "arrived": true
            }
        ],
        "km": 5.66,
        "serviceTime": 0,
        "estimatedRate": 3,
        "statusText": "Aceptado",
        "status": 2,
        "cancelled": false,
        "createdAt": "2019-05-29T23:23:42.227Z",
        "sentFrom": 3,
        "additionalOptions": [
            {
                "signature": false,
                "evidence": false,
                "driverReturn": false
            }
        ],
        "zUserId": "00xxx0000xx00x000x00x0x0",
        "vehicleType": 0,
        "route": {
            "latLng": [
                {
                    "lat": 20.6816,
                    "lng": -103.42095
                },
                ...
                {
                    "lat": 20.68231,
                    "lng": -103.41975
                }
            ]
        },
        "paymentDetails": {
            "total": 3,
            "fixedRate": 3
        },
        "cardId": "000000xx0x000xx00000x0x0",
        "cardInfo": {
            "brand": "MC",
            "last4": "4444"
        },
        "courier": {
            "name": "Juan López Conductor",
            "phone": "5555555555",
            "image": "https://zubut.com/images/profile/XXXXXXXXX.jpg",
            "alpha": false
        },
        "payment": {
            "method": "Servicio cargado a la cuenta: Cuenta PRODUCCION"
        },
        "resume": {
            "acceptedAt": "2019-05-29T23:24:32.190Z",
            "checkPoints": [
                {
                    "arrived": "2019-05-29T23:24:48.567Z",
                    "order": 0,
                    "delivered": "2019-05-29T23:24:51.769Z"
                },
                {
                    "arrived": "2019-05-29T23:24:54.541Z",
                    "order": 1,
                    "delivered": "2019-05-29T23:24:58.464Z"
                }
            ],
            "finishedAt": "2019-05-29T23:24:58.464Z"
        },
        "serviceOrder": 2,
        "progressId": 5,
        "progressText": "Servicio completado",
        "progress": "El mensajero entregó tu paquete y finalizó el servicio.",
        "eta": "18:31 pm"
    }
}

HTTP Method

GET

Retrieve the details of the specific service (given by an id).

Query Parameters Type Required Description
id string Yes An existing service's Id

Success response

Response Type Description
service Object Response from the server.

Error response

Error Code Meaning
400 Missing data.
401 Invalid access token.
404 No such Service was found.
500 Internal error.

Cancel Service

Definition

POST https://api.zubut.com/api/Services/cancelService/

Example Request

$ curl -X POST \
     https://api.zubut.com/api/Services/cancelService/ \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "id": "000000000xx00x000x00x0x0",
          "userId": "XXXXXXXXXXXXXXXXXXXXXXXX"
     }'

Example Response

HTTP/1.1 200 Success
{
     "response": {
          "success": true,
          "message": "El viaje ha sido cancelado exitosamente."
     }
}

HTTP Method

POST

This method will perform the cancellation of an active service given its id.

Note: It may carry a charge of 35MXN if this request is made 5 minutes or more after the Service was requested.

Body Parameters Type Required Description
id string Yes id of the requested Service.
reason number {1-8} Yes id specifying the reason of cancellation
userId string No The id of the user that's cancelling the service (optional).
driverId string No The id of the courier that's cancelling the service (optional).

Success response

Response Type Description
response Object Response from the server.

Error response

Error Code Meaning
400 Service can't be cancelled or missing data.
401 Unauthorized.
404 No such Service was found.
500 Internal error.

Is in Range?

Definition

POST https://api.zubut.com/api/Services/isInRange/

Example Request

$ curl -X POST \
     https://api.zubut.com/api/Services/isInRange/ \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
          "origin": {
               "latitude": 20.723313,
               "longitude": -103.412732
          },
          "destination": {
               "latitude": 20.7227462,
               "longitude": -103.4295366
          },
          "range": "negocio"
     }'

Example Response

HTTP/1.1 200 Success
{
     "in": true
}

HTTP Method

POST

This method indicates whether two given points are in a specified range of one another.

Body Parameters Type Required Description
origin Object Yes The object containing the coordinates of the origin point.
destination Object Yes The object containing the coordinates of the destination point.
range string No The range in which to validate. Can be either of: "restaurante" / "e-commerce" / "negocio".

Success response

Response Type Description
in Boolean Whether the destination is in the specified range of the origin.

Error response

Error Code Meaning
400 Malformed request body.
401 Unauthorized.
404 No such Service was found.
500 Internal error.

Codes

Add code

Definition

POST https://api.zubut.com/api/Codes/addCodeAsUser/

Example Request

# userId is your own id.
$ curl -X POST \
     https://api.zubut.com/api/Codes/addCodeAsUser/ \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-type: application/json" \
     -d '{
        "data": {
            "name": "FooBar",
            "userId": "x00000000x00x0x0x00x0x0"
        }
     }'

Example Response

HTTP/1.1 200 Success
{
    "response" : {
        "codesId": "FooBar",
        "zUsersId": "x00000000x00x0x0x00x0x0",
        "status": 1,
        "createdAt": "2018-12-19T13:02:41-06:00",
        "codeDetails": {
            "name": "FooBar",
            "type": 1,
            "createdAt": "2018-12-18T12:34:44-06:00",
            "expirationDate": "2018-12-30T00:00:00-06:00",
            "availableForEveryone": true,
        }
    }
}

HTTP Method

POST

Have a code? Add it to your account with this method.

Body Parameters Type Required Description
data Object Yes JSON object with the code data

Success response

Response Type Object
response Object Response from the server.

Error response

Error Code Meaning
400 Code already in use.
401 Unauthorized.
500 Internal error.

Cities

Get Zones

Definition

GET https://api.zubut.com/api/Cities/zones

Example Request

$ curl -X GET\
     https://api.zubut.com/api/Cities/zones?time=0 \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \

Example Response

HTTP/1.1 200 Success
[
    {
        "latitude": 20.XXXX,
        "longitude": -103.XXXX
    },
    ...
    {
        "latitude": 20.XXXX,
        "longitude": -103.XXXX
    }
]

HTTP Method

GET

This method will return the zones where Zubut is available in Guadalajara, Jalisco, MX.

Query Parameters Type Description
time number Specify the time shift, day (0), night (1)

Success response

Response Type Description
Body array The array of latitude longitude objects that represent the coverage zone.

Error response

Error Code Meaning
400 Wrong time.
401 Unauthorized.
500 Internal error.

Get City-specific Zones

Definition

GET https://api.zubut.com/api/Cities/{id}/zones

Example Request

$ curl -X GET\
     https://api.zubut.com/api/Cities/XxXXXxxXXXXXXxxxx/zones?time=0 \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \

Example Response

HTTP/1.1 200 Success
[
    {
        "latitude": 20.XXXX,
        "longitude": -103.XXXX
    },
    ...
    {
        "latitude": 20.XXXX,
        "longitude": -103.XXXX
    }
]

HTTP Method

GET

This method will return the zones where Zubut is available in the specified city.

URL Parameters Type Description
id ID A City's identifier as represented in Zubut's API.
Query Parameters Type Description
time number Specify the time shift, day (0), night (1)

Success response

Response Type Description
Body array The array of latitude longitude objects that represent the coverage zone.

Error response

Error Code Meaning
400 Wrong time.
401 Unauthorized.
500 Internal error.

Get City identifier

Definition

GET https://api.zubut.com/api/Cities/cityId

Example Request

$ curl -X GET\
     https://api.zubut.com/api/Cities/cityId?abbreviation=XX \
     -H "Accept: application/json" \
     -H "Authorization: XXXXXXXXXXXXXXXXXXXXXXXX" \

Example Response

HTTP/1.1 200 Success
[
    {
        "city_id": "5cd5b3243d14f8002253cd65"
    }
]

HTTP Method

GET

This method will return the id of the cities where Zubut is present, according to his abbreviation.

URL Parameters Type Description
abbreviation String City's abbreviation (check the table below for abbreviation examples).
Abbreviation City
ZMG Guadalajara
LN León
MTY Monterrey

Success response

Response Type Description
city_id String City identifier, Use it wisely (on services requests for example).

Error response

Error Code Meaning
400 Abbreviation not found.
401 Unauthorized.
500 Internal error.