ShipBlu API Tutorial

In this tutorial we will tell a story of a merchant who wants to integrate their online e-commerce store to our delivery service.

Geographic Availability

The first question is “Where does ShipBlu operate?” To answer this question, you can explore what governorates we cover:

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -X GET https://api.shipblu.com/api/v1/governorates/

The response gives you back a list of governorates that are covered by ShipBlu Service.

[
    {
        "id": 1,
        "name": "القاهرة - Cairo",
        "code": "EGC"
    },
    {
        "id": 2,
        "name": "الاسكندرية - Alexandria",
        "code": "EGALX"
    },
    ,
    {
        "id": 3,
        "name": "الساحل الشمالي - North Coast",
        "code": "EGSHL"
    },
    :
    :
    <response trimmed for clarity>
]

In each governorate, you can list the cities under it using:

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -X GET https://api.shipblu.com/api/v1/governorates/<governorate-id>/cities/

The response gives you back a list of cities that are served in that governorate. For example, querying for Cairo will give you:

[
    {
        "id": 1,
        "name": "القاهرة الجديدة - New Cairo",
        "governorate": {
            "id": 1,
            "name": "القاهرة - Cairo",
            "code": "EGC"
        }
    },
    {
        "id": 2,
        "name": "وسط البلد - Downtown Cairo",
        "governorate": {
            "id": 1,
            "name": "القاهرة - Cairo",
            "code": "EGC"
        }
    },
    {
        "id": 3,
        "name": "اكتوبر - October",
        "governorate": {
            "name": "الجيزة - Giza",
            "code": "EGGZ"
        }
    }
    :
    :
    <response trimmed for clarity>
]

We divide each city to zones to ensure delivering packages within the customer’s preferred delivery window. In order to get the zones of a city, call:

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -X GET https://api.shipblu.com/api/v1/cities/<city-id>/zones/

The response gives you back the list of zones covered in that city.

[
    {
        "id": 1,
        "name": "التجمع الثالث - 3rd Settlement",
    },
    {
        "id": 2,
        "name": "التجمع الخامس - 5th Settlement",
    }
    :
    :
    <response trimmed for clarity>
]

Statuses

Status	Description
CREATED	This status is assigned to the order when the order is created
PICKUP_REQUESTED	This status is when the merchant allows ShipBlu to pick up the order by changing that status.
RETURN_REQUESTED	This status is when the merchant allows ShipBlu to pick the return order from the customer by changing that status.
PICKUP_RESCHEDULED	This status is assigned to the order when the merchant reschedule the pick up of the order.
RETURN_ATTEMPTED	The customer agent tried to get the order from the customer but couldn’t as well as giving a cause for the failed return.
PICKED_UP	When the merchant agent has picked up the order from the merchant.
IN_TRANSIT	This status means that this order is in the warehouse.
EN_ROUTE	The order is moving from a warehouse to another warehouse.
OUT_FOR_DELIVERY	The customer agent has taken the order from the warehouse and is delivering the order to the customer Today.
OUT_FOR_RETURN	The merchant agent has taken the order from the warehouse and is returning the order to the merchant Today.
DELIVERY_ATTEMPTED	The customer agent tried to deliver the order to the customer but couldn’t as well as giving a cause for the failed delivery.
RETURN_TO_ORIGIN	Happens automatically when the customer agent chooses one of the following options: Customer refused to accept delivery. Packaging does not follow ShipBlu guidelines. Out Of Zone.
RETURN_REFUSED	when the merchant agent tries to return the order to the merchant but the merchant refuses the return.
RETURN_POSTPONED	when the merchant requests that the returns to postpone to the next day.
DELIVERED	Happens when the order is delivered to the customer.
RETURNED	Happens when the order is returned to the merchant.
CANCELLED	when the merchant cancels the order when it is created.

Orders

At this point, you are all set up to start creating orders on our system. ShipBlu offers delivery, return, exchange and cash collection services.

Delivery Orders

List

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -X GET https://api.shipblu.com/api/v1/delivery-orders/?limit=10

Response

{
    "count": Number,
    "next": "https://api.shipblu.com/api/v1/delivery-orders/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": Number,
            :
            :
        },
        :
        <response trimmed for clarity>
    ]
}

Create

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -H "Content-Type: application/json" -X POST -d '<request-body>' https://api.shipblu.com/api/v1/delivery-orders/

where <request-body> is:

{
    "customer": {
        "full_name": String,
        "email": String,
        "phone": String,
        "address":{
            "line_1": String,
            "line_2": String,
            "zone": Integer
        }
    },
    "packages": [
        {
            "package_size": Integer
        }
    ]
}

These are the minimum number of parameters that you need to send. Refer to the API Reference for a full documentation on the other parameters you can set.

Update

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -H 'Content-Type: application/json' -d '<request-body>' -X PATCH https://api.shipblu.com/api/v1/delivery-orders/

where <request-body> is the same as the used in the POST request.

Print Shipping Labels

Our APIs support retrieving the shipping label in two formats: pdf and html

curl -H 'Authorization: Api-Key <YOUR-API-KEY>' -H 'Content-Type: application/json' -X GET 'https://api.staging.shipblu.com/api/v1/orders/shipping-label/?tracking_numbers=12345,12345,12345&type=pdf'

PDF Labels

When you send ?format=pdf as a query parameter, the response is a single PDF file that contains all the shipping labels for all orders.

Note that if one order has multiple packages, you get multiple shipping labels.

Note that the API returns two labels per A4 page. You may choose to return one label per page by sending a parameter ?one_per_page=True. This only works for PDF labels.

HTML Labels

When you send ?format=html as a query parameter, the response is a single <div> element that you can inject inside your HTML code of a page.

This is helpful in cases where your system generates a pick-and-pack label in addition to the shipping label. You can have all of them printed sequentially in a single page by injecting our label in between the labels you generate from your end.

Minimized HTML Labels

You may use this option when merging your own shipping label with ours.

When you send ?format=html&minimized=true as a query parameters, the response is a json that contains “packages” as a list where each item is a minimized <div></div> for the the operational parameters of the shipping labels.

Other Orders

Returns, exchanges and cash collection orders follow the same scheme. Please, refer to the complete API reference for detailed signatures.

What’s Next?

Bravoo! You made it to this point.

You can explore the full API functionality in the API Reference.