Tasks

Tasks are the logistic unit behind Shippify's service. They represent the shipment requests of our clients in our databases. Companies can analyze and manage their tasks through the endpoints provided in our API.


Terminology and Structures

Task status

Specification of status that a task can have. The possible values are:

Status Name Description
1 Getting ready The task is not available yet. The server needs to dispatch it.
2 Available The task is available to nearby shippers
3 Driver assigned / Waiting for response The task was assigned by an admin and needs to be confirmed by the assigned driver, if not will return to available.
4 Driver applied Driver reserved the task, confirming to start the journey to the pickup location.
5 Picked up Driver arrived to the pickup location and stored all the packages in his inventory
6 Delivered Driver arrived to the delivery location and dropped off the package.
7 Confirmed The system admin or receiver confirmed the task has been completed.
0 Not Delivered The driver updates the task as not delivered due to an inconvenience.
-1 Canceled The administrator canceled the task. This status will avoid the driver to collect the products in the pickup point

Task Capacity

All tasks have a total capacity that matches the sizes of the products a driver has to carry. If the capacity is not defined in the task creation then it's calculated by the objects contained in the array of products declared. Drivers can receive tasks with a capacity index less than or equal than their vehicle capacity index.

Size Vehicle Products
1 Bicycle Keys, papers, documents.
2 Motorcycle Teddy Bears, shoe boxes, keyboard, wine box.
3 Car Laptops, PCs, weights, TVs
4 SUV Chairs, a small desk, bicycle, fridge
5 Truck Construction material, furniture, boat.

Products

All tasks have a list of products that should be defined when created. Those products contain information about the items a driver will pickup in the warehouse and a size can be defined for each of those products. If a capacity is not declared then the task capacity will be defined by an internal calculation considering the sizes of the products list.

Products Size

Size Alias Products
1 Extra Small (XS) Keys, papers, documents.
2 Small (S) Teddy Bears, shoe boxes, keyboard, iPad devices.
3 Medium (M) Laptops, PCs, weights.
4 Large (L) Chairs, a small desk, bicycle.
5 Extra large (XL) Desk, furniture, boat.

Locations & Addresses

A task is composed by 2 location points that will define the picking point and the delivery point. Each location contain :

  • Text address
  • Latitude (optional)
  • Longitude (optional)

The right latitude and longitude points will help us define a correct location and give to you the right fare. Our geocoding can handle the text address, however most of the time addresses are not well defined by customers. Here we recommend the use of our widget.

Task Management

Creating a task

Endpoint POST /task/new

  • Creates a new task in the system. Our engine then assigns the task to a shipper when its pickup date gets close.
  • All tasks must be created an hour in advance to guarantee they are properly handled.
  • The fare returned in the creation is defined by the city and company . Some companies might have different fares and fees.

Schema

Request

{
  "task" { // Task object. (object)
    "products" [ // Product list attached to task. (array)
      "id" // Product id represented in the client's platform. (string) (optional)
      "name" // Product name. (string)
      "qty" // Total amount of similar products. (int)
      "size" // Product size refer to the table of sizes
    ]
    "capacity" // Optional but if defined replaces calculations of product sizes. Capacity based on vehicle size chart: 1 - Bicycle, 2 - Motorcycle, 3 - Car, 4 - SUV, 5 - Truck . (integer) (optional)
    "sender" { // Customer object sending the package. (object)
      "email": // Customer email address. (string)
    }
    "recipient" { // Customer object receiving the package. (object)
      //  All customer objects must have at the bare minimum an email address or phone number associated to it.
      "name": // Customer name. (string) (optional)
      "email": // Customer email address. (string)
      "phone": // Customer phone number. (string)
    }
    "pickup" { // Pickup location object. (object)
      "lat" // Location latitude. (double) (optional)
      "lng" // Location longitude. (double) (optional)
      "address" // Location physical address. (string)
      "warehouse" // Warehouse id. Overrides other paameters. (string)
    }
    // Pickup time must be less than delivery time
    "pickup_date" // Estimated pickup date. (default=now + 1 hour) (double) (unix-timestamp)
    "deliver" { // Delivery location object. (object)
      "lat" // Location latitude. (double) (optional)
      "lng" // Location longitude. (double) (optional)
      "address" // Location physical address. (string)
      "warehouse" // Warehouse id. Overrides other paameters. (string)
    }
    // Delivery time must be greater than pickup time
    "delivery_date" // Estimated pickup date. (default=pickup_date + 3 hour) (double) (unix-timestamp)
    "total_amount" // Total amount charged by the shipper in cash, if the recipient did not pay before via bank transfer or credit card online. (double) (optional)
    "extra" { // JSON string for additional data given by the developer for their own use. (string) (json)
      "pk_note":" My pickup note or reference", // Pickup extra information. (string) (optional)
      "note":" Delivery Note ", // Delivery extra information. (string) (optional)
      "custom_developer_label":" Custom value from Developer" // Developer label key , value metadata
      ...
    }
    "ref_id" // Reference ID to index this task with an ID from your system. Used for integrations with other platforms (string)(optional).
    "send_email_params" { // Tracking email configuration for client. (string) (json) (optional)
      "from" // Company name or email. (string)
      "subject" // Email subject. (string)
      "to" // Client email. (string)
    }
    "send_sms_params" { //  Tracking sms custom configuration for companies .  (string) (json) (optional)
      "title" // Tittle of SMS
      "mobile_phone" // phone number to send 
      "text" //  text to send
    }
  }
}

Response

{
  "id" // Task id. (string)
  "price" // Task price. (string) (numeric)
  "distance" // Task total distance. (double)
  "currencySign" // Task currency sign. (string)
}

Example

curl
-X POST
-H 'Accept-Charset: utf-8'
-u '**APIKeyId**:**APISecretId*'
-d 'task[products][0][id]=my_inventory_product_id'
-d 'task[products][0][name]=Glass'
-d 'task[products][0][size]=1'
-d 'task[products][0][qty]=4'
-d 'task[sender][email]=luis@shippify.co'
-d 'task[recipient][email]=miguel@shippify.co'
-d 'task[pickup][address]=Rua Doutor Sette Câmara, Luxemburgo'
-d 'task[pickup][lat]=-19.9430687'
-d 'task[pickup][lng]=-43.95513460000001'
-d 'task[deliver][address]=Rua Curitiba 1957, Lourdes'
-d 'task[deliver][lat]=-19.9298613'
-d 'task[deliver][lng]=-43.94431470000001'
-d 'task[extra]= {"pk_note": "In front of a red house with green roof", "note":"In front of a green building with red roof","change":"$20"}'
-d 'task[pickup_date]=1467244800'
-d 'task[delivery_date]=1467590400'
"https://api.shippify.co/task/new"

Payload

{
  "id": "t-shieam-92",
  "price": "9.90",
  "distance": 2.957,
  "currencySign": "R$"
}

Fetching a task

Endpoint GET /task/info/:task_id

  • Fetches a specific task based on the id provided, if it exists.

Schema

Response

{
  "errFlag" // Error code. (int)
  "errMsg" // Error message. (string)
  "data" { // Data payload object. (object)
    "tid" // Task id. (string)
    "products" [ // Task products. (array)
      "id" // Product id represented in the client's platform. (string)
      "name" // Product name. (string)
      "qty" // Total amount of similar products. (int)
      "size" // Product size based on vehicle size chart: 1 - Bicycle, 2 - Motorcycle, 3 - Car, 4 - SUV, 5 - Truck.. (int) (shippify-package-size)
    ]
    "addr1" // Pickup location physical address. (string)
    "dropAddr1" // Delivery location physical address. (string)
    "amount" // Total amount charged by the shipper in cash, if the recipient did not pay before via bank transfer or credit card online. (double)
    "price" // Total shipping price. (double)
    "city" // City id.
    "pickLat" // Pickup location latitude. (double)
    "pickLong" // Pickup location longitude. (double)
    "dropLat" // Delivery location latitude. (double)
    "dropLong" // Delivery location longitude. (double)
    "date" // Creation date. (double) (unix-timestamp)
    "pickup_date" // Estimated pickup date. (double) (unix-timestamp)
    "delivery_date" // Estimated delivery date. (double) (unix-timestamp)
    "sender" // Sender email address. (string)
    "recipient" // Recipient data
    "totalSize" // Total task size. (int) (shippify-package-size)
    "status" // Task current status. (int) (shippify-task-status)
    "payStatus" // Task payment status from payment chart: 1 - Prepaid, 2 - Paid on reception. (int)
    "payType" // Task payment type from payment chart: 1 - Credit, 2 - Cash, 3 - Bank transfer, 4 - Debit, 5 - Boleto. (int)
    "distance" // Task total distance. (double)
    "shipper" // Assigned shipper id, if exists. (string-null)
    "route" // Route id, if exists. (string-null
    "sign" // Task currency sign. (string)
    "recipientData" { // Recipient customer obejct. (string) (json)
      "name" // Customer name. (string)
      "email" // Customer email. (string)
    }
    "extra" { // JSON string for additional data given by the developer for their own use. (string) (json)
      "pk_note" // Pickup extra information. (string) (optional)
      "note" // Delivery extra information. (string) (optional)
      ...
    }
  }
}

Example

curl
-X GET
-u '**APIKeyId**:**APISecretId*'
"https://api.shippify.co/task/info/10"

Payload

{
  "errFlag": 0,
  "errMsg": "Success",
  "data": {
    "tid": "ibo57hd0px8ncdi",
    "products": [
      {
        "id": "0",
        "name": "42286",
        "qty": 1,
        "size": 3,
        "price": "0"
      }
    ],
    "addr1": "Rua Guilherme Ciriene, 367, Jardim Industrial, Minas Gerais, Brasil",
    "dropAddr1": "R. Corcovado, 572 - Monte Castelo, Contagem - MG, Brazil",
    "amount": 189,
    "price": 4,
    "city": 1,
    "pickLat": "-19.9647343",
    "pickLong": "-44.02099750000002",
    "dropLat": "-19.9441765",
    "dropLong": "-44.066946299999984",
    "date": "2015-07-03T21:38:14.000Z",
    "pickup_date": "2016-06-30T00:00:00.000Z",
    "delivery_date": "2016-07-11T00:00:00.000Z",
    "sender": "chinaloa.ts@gmail.com",
    "recipient": "55761144dacec286b0aa8a55",
    "totalSize": 5,
    "status": 0,
    "payStatus": 1,
    "payType": 1,
    "distance": 5.32,
    "shipper": null,
    "route": null,
    "sign": "R$",
    "recipientData": "{\"email\":\"super_shipper@gmail.com\",\"name\":\"Super Shipper\"}",
    "extra": "{\"note\":\"Riacho das Pedras\"}"
  }
}

Attaching a file to a task

Endpoint POST /v1/tasks/:task_id/files

  • Uploads a file as an attachment to the task.
  • Files should be used as proof of delivery or as notifications of special circumstances during the delivery flow.
  • File limit size is 10MB.
curl
-X POST
-u '**APIKeyId**:**APISecretId*'
-H "Cache-Control: no-cache"
-H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
-F "file=@**NameOfFile**" "https://api.shippify.co/v1/tasks/t-shiinc-15300/files"

results matching ""

    No results matching ""