Justo Delivery API Documentation

VERSION


INTRODUCTION

As we are focused on growing our business and reaching more markets, we believe this API-based approach will offer a more robust, maintenance-free solution that ensures you will receive / deliver and track your order at any time. This document covers the various options and details regarding sending and receiving data between your software system and Justo Delivery. If you have additional questions on the API please contact kirk.berube@justodelivery.com.

NEW FEATURES

Now we will take care of your default settings such as:

  1. Warehouse Hub
  2. Billing Method
  3. Authorized Billing Address

NOTE: Please contact administrator at kirk.berube@justodelivery.com only for these default settings.

DATA EXCHANGE

JSON API

Justo Delivery JSON (API) is based on HTTPs Transport Protocol and data is encoded in JSON format.

Base URL

https://api.justodelivery.com/api/v1.1

Content Type

Content-Type: application/json

Response Codes
Code Description
200 The request was successfully completed
201 A new resource was successfully created
303 This can be the URI of a temporary status message, or the URI to some already existing, more permanent, resource
400 The request was invalid
401 The request did not include an authentication token or the authentication token was expired
403 The client did not have permission to access the requested resource
404 The requested resource was not found
405 The HTTPs method in the request was not supported by the resource. For example, the DELETE method cannot be used with the Agent API
409 The request could not be completed due to a conflict. For example, POST Content Store Folder API cannot complete if the given file or folder name already exists in the parent location
412 The code indicates that those preconditions were not met
500 The request was not completed due to an internal error on the server side
503 The server was unavailable


There are following different APIs Requests:


SINGLE IMPORT ORDER INTO JUSTO DELIVERY


URL: The following is the web address used to access the API

{Base URL}/import/single/order

Version: #1.1
Feb 07, 2020
Method:
POST 

Request Parameters:
Sr No. Parameter DataType Required Default Description
1 key Varchar (32) Yes A value that identifies the party invoking the API.

NOTE: Please contact us to get API secret key.
2.1 orders [‘customer_ref’] Varchar (255) This value may be Pro#, SO#, DDC#, etc in your system
2.2 orders[‘po_number’] Varchar (255) Yes This value may be either B/L#, PO#, order#, RA#, etc in your system
2.3 orders[‘order_type’] Varchar (45) Yes Pickup & Deliver Indicates the requested order for delivery.

Valid Options
Pickup & Deliver
Receive In & Deliver.
2.4 orders[‘service_level’] Varchar (45) Yes White Glove Indicates the requested level of service for delivery.

Valid Options
Room of Choice
Threshold
White Glove
2.5

a)
orders[‘origin_address’][‘warehouse] Varchar (5) Optional (If order_type = ‘Receive In & Deliver’ else ignore) Indicates the requested warehouse hub for delivery.

Valid Options
RLA
RSC
RSAC

Full Form
RLA stands for Receiving for Compton i.e. SO CAL terminal
RSC stands for Receiving for Santa Clara i.e. NOR CAL terminal
RSAC stands for Receiving for Sacramento County i.e. Sacramento terminal
2.5

b(i)
orders[‘origin_address’][‘name’] Varchar (150) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates contact person or company name at origin place.
2.5

b(ii)
orders[‘origin_address’][‘phone’] Varchar (255) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates contact number of origin. You can use comma (,) as separator if you have more than one contact numbers. For eg. 9999999999,9999999999
2.5

b(iii)
orders[‘origin_address’][‘email’] Varchar (255) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates contact email address of origin.
2.5

b(iv)
orders[‘origin_address’][‘addressline’] Varchar (255) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates origin’s address line like street address.
2.5

b(v)
orders[‘origin_address’][‘city’] Varchar (150) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates state of origin

NOTE: We automatically overwrite it based on Zip Code, if Zip Code is serviceable else throws error.
2.5

b(vi)
orders[‘origin_address’][‘state’] Varchar (45) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates state of origin

NOTE: We automatically overwrite it based on Zip Code, if Zip Code is serviceable else throws error.
2.5

b(vii)
orders[‘origin_address’][‘zipcode’] Varchar (5) Yes (If order_type = ‘Pickup & Deliver’ else ignore) Indicates zipcode of origin

NOTE: We verify Zip Code that it is serviceable or not
2.5

b(viii)
orders[‘origin_address’][‘is_residence’] Bool False Indicates origin place is residential address
2.5

b(ix)
orders[‘origin_address’][‘can_notify_via_sms’] Bool True Indicates that you want us to notify origin customer via SMS

NOTE: SMS will send to [‘origin_address’][‘phone’]
2.5

b(x)
orders[‘origin_address’][‘can_notify_via_email’] Bool True Indicates that you want us to notify origin customer via Email

NOTE: Email will send to [‘origin_address’][‘email’]
2.6

(i)
orders[‘dest_address’][‘name’] Varchar (150) Yes Indicates contact person or company name at destination place.
2.6

(ii)
orders[‘dest_address’][‘phone’] Varchar (255) Yes Indicates contact number of destination. You can use comma (,) as separator if you have more than one contact numbers. For eg. 9999999999,9999999999
2.6

(iii)
orders[‘dest_address’][‘email’] Varchar (255) Indicates contact email address of destination
2.6

(iv)
orders[‘dest_address’][‘addressline’] Varchar (255) Yes Indicates destination ‘s address line like street address
2.6

(v)
orders[‘dest_address’][‘city’] Varchar (150) Yes Indicates city of destination

NOTE: We automatically overwrite it based on Zip Code, if Zip Code is serviceable else throws error
2.6

(vi)
orders[‘dest_address’][‘state’] Varchar (45) Yes Indicates state of destination

NOTE: We automatically overwrite it based on Zip Code, if Zip Code is serviceable else throws error
2.6

(vii)
orders[‘dest_address’][‘zipcode’] Varchar (5) Yes Indicates zipcode of destination

NOTE: We verify Zip Code that it is serviceable or not
2.6

(viii)
orders[‘dest_address’][‘is_residence’] Bool False Indicates destination place is residential address
2.6

(ix)
orders[‘dest_address’][‘can_notify_via_sms’] Bool True Indicates that you want us to notify destination customer via SMS

NOTE: SMS will send to [‘dest_address’][‘phone’]
2.6

(x)
orders[‘dest_address’][‘can_notify_via_email’] Bool True Indicates that you want us to notify origin customer via Email

NOTE: Email will send to [‘dest_address’][‘email’]
2.7

(i)
orders[‘items’][][‘package_type’] Varchar (15) Blanket Wrap Indicates package type of items in the order

Valid Options
Blanket Wrap
Carton
2.7

(ii)
orders[‘items’][][‘sku’] Varchar (100) Indicates sku of an item
2.7

(iii)
orders[‘items’][][‘item_name’] Varchar (100) Yes Indicates name of an item
2.7

(iv)
orders[‘items’][][‘length’] Int 1 Indicates length of an item
2.7

(v)
orders[‘items’][][‘width’] Int 1 Indicates width of an item
2.7

(vi)
orders[‘items’][][‘height’] Int 1 Indicates height of an item
2.7

(vii)
orders[‘items’][][‘weight’] Int 1 Indicates weight of an item
2.7

(viii)
orders[‘items’][][‘quantity’] Int Yes 1 Indicates number of quantities of a line item to be delivered
2.7

(ix)
orders[‘items’][][‘has_marble_or_stone’] Bool FALSE Indicates that line item has marble or stone
2.8 orders[‘special_handling_notes’] Varchar(1000) Special handling note for the order


Success Response: (below is sample JSON success response)
Here is the data format in which you will receive the data from Justo Delivery

JSON:
{
	"status": true,
	"message": "Order imported.",
	"data": {
		"orders_info": [
			{
				"orders_id": 1000001, //Use this Order ID to get order details and it's status 
				"order_message": “Order created successfully”,
				"order_error": []
			}
		]
	},
	"code": 200
}
					
Error Response: (below is sample JSON error response)

Default Setting not set by Administrator:
{
    "status": false,
    "message": "Please contact administrator for default settings.",
    "data": {
        "key": [
            "Please contact administrator for default settings."
        ]
    },
    "code": 403
}
					
URL does not exist:
{
	"status": false,
	"message": "URL does not exist.",
	"data": [],
	"code": 404
}
					
Method is not allowed:
{
	"status": false,
	"message": "Method is not allowed.",
	"data": [],
	"code": 405
}
Required validation:
{
	"status": false,
	"message": "The API key field is required.",
	"data": {
		"key": [
			"The API key field is required."
		]
	},
	"code": 412
}
Invalid key:
{
	"status": false,
	"message": "Please enter a valid key.",
	"data": [],
	"code": 401
}

Sample Call:

Request Call:
{
	"key": "HgkN1jqnLaIrw70PL35e",
	"orders":

	{
		"customer_ref": "so123",
		"po_number": "po987",
		"order_type": "Receive In & Deliver",
		"service_level": "White Glove",
		"origin_address": {
			"warehouse": "RSC",
			"name": "",
			"phone": "",
			"email": "",
			"addressline": "",
			"city": "",
			"state": "",
			"zipcode": "",
			"is_residence": "1",
			"can_notify_via_sms": "0",
			"can_notify_via_email": "0"
		},
		"dest_address": {
			"name": "David",
			"phone": "9876789098",
			"email": "david@yopmail.com",
			"addressline": "#78",
			"city": "Santa Clara",
			"state": "CA",
			"zipcode": "95054",
			"is_residence": "0",
			"can_notify_via_sms": "1",
			"can_notify_via_email": "1"
		},
		"items": [
			{
				"package_type": "Carton",
				"sku": "CH45",
				"item_name": "Chair with white color",
				"length": "5",
				"width": "6",
				"height": "7",
				"weight": "56",
				"quantity": "4",
				"has_marble_or_stone": "1"
			}

		],
		"special_handling_notes": ""
	}

}
Response:

JSON:
{
    "status": true,
    "message": "Order imported.",
    "data": {
        "orders_info": [
		{
			"orders_id": 1000001, //Use this Order ID to get order details and it's status 
			"order_message": "Order created successfully",
			"order_error":[]
		}
        ]
    },
   "code": 200
}

EXPORT ORDER FROM JUSTO DELIVERY


URL: The following is the base web address used to access the API

{Base URL}/export/orders

Version: #1.1
Feb 07, 2020
Method:
GET

Request Parameters:
Sr No. Parameter Required Default Description
1 key Yes * A value that identifies the party invoking the API.

NOTE: Please contact us to get API secret key
2 scheduled_date ** Get all orders which are scheduled for specific date

NOTE: date in YYYY-MM-DD format.
3 order_type ** Indicates the requested order for delivery.

Valid Options:
Pickup & Deliver
Receive In & Deliver
NOTE: AMPERSAND "&" char should be encoded with %26. For eg. Pickup %26 Deliver
4 order_status ** Justo service order status.

Valid Options
Wait For Pickup Schedule
Scheduled For Pickup
Out For Pickup
Wait For Delivery Schedule
Scheduled For Delivery
Out For Delivery
Cancelled
Delivered
Other
5 po_number_or_customer_ref ** You can serach your unique order number which will store in our po_number or customer_ref fields.
6 orders_id ** Justo unique order number that you want to fetch details.

* Always Required.
** Conditional Required: At least one field required among [scheduled_date, order_type, order_status, orders_id].
Supports only one order at a time - While using this then we are not consider fields among [scheduled_date, order_type, order_status].

Success Response:

JSON:

{
    "status": true,
    "message": "Order found.",
    "data": {
    	"orders_count": 1,
        "orders": [
            {
                "orders_id": 328,
                "order_type": "Receive In & Deliver",
                "order_status": "Scheduled For Delivery",
                "customer_ref": "so123",
                "po_number": "po987",
                "service_level": "White Glove",
                "billing_method": "Shipper",
                "payment_status": "PENDING", //(valid options are PENDING, OVERDUE, PAID, BILLED, PREPAID)
                "scheduled_pickup_date": null,
                "scheduled_pickup_window": null,
                "actual_pickup_date": null,
                "actual_pickup_window": null,
                "scheduled_delivery_date": "2019-08-22",
                "scheduled_delivery_window": "08:00 AM - 04:00 PM",
                "actual_delivery_date": null,
                "actual_delivery_window": null,
                "origin_company_name": "Justo (Compton)",
                "origin_contact_phone": "3106312322",
                "origin_contact_email": "deliveries@justodelivery.com",
                "origin_addressline1": "1448 S. Santa Fe Avenue",
                "origin_city": "Compton",
                "origin_state": "California",
                "origin_zip": "90221",
                "dest_company_name": "David",
                "dest_contact_phone": "9876789098",
                "dest_contact_email": "david@yopmail.com",
                "dest_addressline1": "#78",
                "dest_city": "Santa Clara",
                "dest_state": "CA",
                "dest_zip": "95054",
                "order_date": "2019-08-20", //using YYYY-MM-DD format
                "order_time": "00:12:13", //using 24 hours format
                "items": [
                    {
                        "item_id": 503,
                        "package_type": "Carton",
                        "sku": "CH45",
                        "quantity": 4,
                        "has_marble_or_stone": "yes",
                        "item_name": "Chair with white color",
                        "length": 5,
                        "width": 6,
                        "height": 7,
                        "weight": 56
                    }
                ],
                "delivery_images": [],
                "scan_docs": [],
                "notes": [
                    "By Admin, Aug 20, 2019 4:30am > Delivery Scheduled for 08/22/2019",
                    "By anthony, Aug 20, 2019 4:13am > SPECIAL HANDLING: new order from external api"
                ]
            }
        ]
    },
    "code": 200
}

Error Response:

URL does not exist:
{
	"status": false,
	"message": "URL does not exist",
	"data": [],
	"code": 404
}
Method is not allowed:
{
    "status": false,
    "message": "Method is not allowed.",
    "data": [],
    "code": 405
}
Required validation:
{
	"status": false,
	"message": "The API key field is required.",
	"data": {
		"key": [
			"The API key field is required."
		]
	},
	"code": 412
}
Invalid key:
{
	"status": false,
	"message": "Please enter a valid key.",
	"data": [],
	"code": 401
}

Sample Call:

Request Call:
{
	"key":"HgkN1jqnLaIrw70PL35e",
	"scheduled_date":"2019-07-28",
	"order_type":"Pickup & Deliver",
	"order_status":"Cancelled",
	"orders_id":"308"
}


Response:

JSON:
{
    "status": true,
    "message": "Order found.",
    "data": {
    	"orders_count": 1,
        "orders": [
            {
                "orders_id": 328,
                "order_type": "Receive In & Deliver",
                "order_status": "Scheduled For Delivery",
                "customer_ref": "so123",
                "po_number": "po987",
                "service_level": "White Glove",
                "billing_method": "Shipper",
                "payment_status": "PENDING", //(valid options are PENDING, OVERDUE, PAID, BILLED, PREPAID)
                "scheduled_pickup_date": null,
                "scheduled_pickup_window": null,
                "actual_pickup_date": null,
                "actual_pickup_window": null,
                "scheduled_delivery_date": "2019-08-22",
                "scheduled_delivery_window": "08:00 AM - 04:00 PM",
                "actual_delivery_date": null,
                "actual_delivery_window": null,
                "origin_company_name": "Justo (Compton)",
                "origin_contact_phone": "3106312322",
                "origin_contact_email": "deliveries@justodelivery.com",
                "origin_addressline1": "1448 S. Santa Fe Avenue",
                "origin_city": "Compton",
                "origin_state": "California",
                "origin_zip": "90221",
                "dest_company_name": "David",
                "dest_contact_phone": "9876789098",
                "dest_contact_email": "david@yopmail.com",
                "dest_addressline1": "#78",
                "dest_city": "Santa Clara",
                "dest_state": "CA",
                "dest_zip": "95054",
                "order_date": "2019-08-20", //using YYYY-MM-DD format
                "order_time": "00:12:13", //using 24 hours format
                "items": [
                    {
                        "item_id": 503,
                        "package_type": "Carton",
                        "sku": "CH45",
                        "quantity": 4,
                        "has_marble_or_stone": "yes",
                        "item_name": "Chair with white color",
                        "length": 5,
                        "width": 6,
                        "height": 7,
                        "weight": 56
                    }
                ],
                "delivery_images": [],
                "scan_docs": [],
                "notes": [
                    "By Admin, Aug 20, 2019 4:30am > Delivery Scheduled for 08/22/2019",
                    "By anthony, Aug 20, 2019 4:13am > SPECIAL HANDLING: new order from external api"
                ]
            }
        ]
    },
    "code": 200
}


TRACK YOUR ORDER FROM JUSTO DELIVERY


URL: The following is the base web address used to access the API

{Base URL}/track/orders

Version: #1.1
Feb 07, 2020
Method:
POST 

Request Parameters:
Sr No. Parameter Required Default Description
1 key Yes A value that identifies the party invoking the API.

NOTE: Please contact us to get API secret key.
2 orders_id Yes Justo order number that you want to track.

Success Response:

JSON:
{
	"status": true,
	"message": "Order found.",
	"data": {
		"order_info": {
			"orders_id": 1000001,
			"origin_city": "Santa Clara",
			"origin_state": "CA",
			"origin_zip": "95054",
			"dest_city": "Santa Clara",
			"dest_state": "CA",
			"dest_zip": "95054",
			"num_of_items": 1,
			"num_of_pieces": "2",
			"service_level": "White Glove"
		},
		"tracking_info": {
			"01/03/2019 - Thursday": [{
					"status": "Order Registered",
					"status_time": "12:15PM"
				},
				{
					"status": "Delivery Scheduled for 01/03/2019",
					"status_time": "12:40PM"
				},
				{
					"status": "Out For Delivery",
					"status_time": "12:41PM"
				},
				{
					"status": "Delivery Completed",
					"status_time": "03:35PM"
				}
			]
		}
	},
	"code": 200
}


Error Response:
URL does not exist:
{
	"status": false,
	"message": "URL does not exist",
	"data": [],
	"code": 404
}

Method is not allowed:
{
	"status": false,
	"message": "Method is not allowed.",
	"data": [],
	"code": 405
}

Required validation:
{
	"status": false,
	"message": "The API key field is required.",
	"data": {
		"key": [
			"The API key field is required."
		]
	},
	"code": 412
}

Invalid key:
{
	"status": false,
	"message": "Please enter a valid key.",
	"data": [],
	"code": 401
}


Sample Call:

Request Call:
{
	"key": "HgkN1jqnLaIrw70PL35e",
	"orders_id": "308"
}

Response:

JSON:
{
	"status": true,
	"message": "Order found.",
	"data": {
		"order_info": {
			"orders_id": 1000001,
			"origin_city": "Santa Clara",
			"origin_state": "CA",
			"origin_zip": "95054",
			"dest_city": "Santa Clara",
			"dest_state": "CA",
			"dest_zip": "95054",
			"num_of_items": 1,
			"num_of_pieces": "2",
			"service_level": "White Glove"
		},
		"tracking_info": {
			"01/03/2019 - Thursday": [{
					"status": "Order Registered",
					"status_time": "12:15PM"
				},
				{
					"status": "Delivery Scheduled for 01/03/2019",
					"status_time": "12:40PM"
				},
				{
					"status": "Out For Delivery",
					"status_time": "12:41PM"
				},
				{
					"status": "Delivery Completed",
					"status_time": "03:35PM"
				}
			]
		}
	},
	"code": 200
}