Zepo Couriers Plugin

Glossary

Client side
i) Data elements to be posted by the Client to the url
ii) Data elements posted back to the client after shipment processing.

Client Side

Client would have an order management panel at their end. They would have a ZC Ship button
wrt each order. User would click on the button and user would be redirected to ZC plugin with all
the order and shipment data in a ​new tab​.

Once Shipment is processed, ZC plugin would post back to the client with shipment status and
all info related to the same. Client would store this information in its DB and also show the
Tracking number, current tracking status, courier name and Label download information to the
user besides the order itself.

Note: User shouldn’t be required to reload the orders page to see the data to be processed.

How to Create an Authenticated Request

Authentication information should be provided in the "Authorization" header

Authorization has the following format

Authorization: SHIPIT <API-KEY>:<SIGNATURE>

The Signature are as follows

Signature = Base64.Encode(HmacSHA1 (UTF-8-Encode(StringToSign)))

StringToSign = <Http-Verb>+"\n"+<RequestURI, Including querystrings>

Note: UTF-8 encoded character of "\n" should be "%0A" which is the equivalent encoding of the
newline character. Some encoders available online donot recognize "\n" as a newline
character.The HmacSHA1 of the StringToSign should be created using for signing.
Finally, Base64 encode this HmacSHA1 and add it in the Authorization header.

The String "SHIPIT" is part of the Authorization header and identifies this header as the custom
authorization header.

Sample Request(Example) :

RequestURL - ​http://api.couriers.vello.in/initiateShipmentRequest

1) String to Sign : POST\n/initiateShipmentRequest

2) Url encoding - POST%0A%2FinitiateShipmentRequest%0A

3) Hash - 547805eea4f594a22ecdb9c3056f33c5574cdc8c

4) Base 64 - NTQ3ODA1ZWVhNGY1OTRhMjJlY2RiOWMzMDU2ZjMzYzU1NzRjZGM4Yw==

Final authentication header

Authorization: SHIPIT
06bd027a79eeeff5b66cbf6961f84e2:NTQ3ODA1ZWVhNGY1OTRhMjJlY2RiOWMzMDU2ZjMzY
zU1NzRjZGM4Yw==
content-type: application/json

Test Paytm credentials.

777777777
Mobile Number – 7
Paytm1234
Password – 5

Sample Codes in PHP

1)​Initiate Shipment
2)​Callback

FAQ Technical :

Please click here to view the technical FAQ’s

FAQ Operational :

Please click here to view the operational FAQ’s

Data elements to be posted by the Client to the API

http://api.couriers.vello.in/initiateShipmentRequest

Request Type : POST

Request Content-Type: application/json
Authorization: SHIPIT API KEY:SIGNATURE

Request :

{
"pickup_pincode": "400080",
"delivery_pincode": "395009",
"order_number": "BOX123ABC",
"payment_mode": "online",
"insurance": false,
"number_of_package": 1,
"package_details": {
"details": {
"weight": 10,
"length": 15,
"height": 14.5,
"width": 100.5,
"invoice": 620,
"packagedescription": "Dummy"
}
},
"delivery_address": {
"company_name": "Zepo",
"address": "Ambaji Dham mandir, Mulund west",
"city": "Bombay",
"state": "Maharashtra",
"pincode": "400080",
"country": "IN",
"contact_no": "9988776655",
 "email": "Sumeet@zepo.in"
},
"success_callback_url":"xyz.success.com",
"failure_callback_url":"xyz.failure.com",
"client_source":"Magento"
}

Response:

In case of success-
{
"​code​": ​200
"​redirectUrl​":
"​http://couriers.zepo.in/#/schedule-new-shipment?srId=56682ea8-7ab1-4607-b7e4-1c
6a1e7fba95​"
"​success​": ​true
}

In case of violation of any validation criteria-

{
"​success​": ​false
"​code​": ​200
"​messages​": [​1​]
0: ​"​Delivery Pincode Required.​"

In case of bad request(i.e if any value is missing, any parameter is missing, wrong data
type data posted, Invalid JSON format)-
{
"​success​": ​false
"​code​": ​200
"​message​": "​Invalid request​"
}

Data elements validation criteria

a) Pickup Pincode - Not mandatory - If it is there, it must have exactly 6 digits.

b) Delivery Pincode - Mandatory - It must have exactly 6 digits.
c) Order Number - Mandatory.
d) Payment Mode - Mandatory - Values must be ‘online’ or ‘COD’ based on end customer
order.
e) Insurance - Optional - If it is there it must be boolean value True or false.
f) No of Package - Mandatory - Must be ‘1’ only.
g) Package Details - Mandatory - List of Package Items.
h) Details - Array of Package Weight, Package Invoice value, Package Dimension
i) Package Weight
1) Unit is Kg
2) Optional
3) Value must be greater than 0 and less than or equal to 70
ii) Package Invoice Value
1) Unit is Rupees
2) Mandatory
3) Value must be numeric only and greater than 0
iii) Package Dimension
1) Optional
2) Unit is CM.
3) If it is there than value of each subelement must be greater than 1 and
must be valid float value and volumetric weight must be less than 70kg.
Volumetric weight = L * W * H / 5000
4) Sub-elements
(a) Length
(b) Width
(c) Height
iv) Package Description - Optional - Possible values are Product name or Category
names.
i) Delivery Address Array
i) Company Name - Mandatory - Only Numbers not allowed.
ii) Address- Mandatory
iii) Customer Mobile number - Mandatory - Must have exactly 10 digits.
iv) Customer Email id - Mandatory - Must be valid Email address.
v) Delivery Pincode - Mandatory - Must have exactly 6 digits.
vi) Delivery City - Mandatory.
vii) Delivery State - Mandatory.
viii) Delivery Country - Mandatory - Must be IN Only.
j) Client Source - Mandatory- This will indicate from where client’s request is coming.
k) Success Callback Url - Mandatory. Client Url on which ZC would make a post request
with the data related to status of the current request in case of Success.
l) Failure Callback Url - Mandatory. Client Url on which ZC would make a post request with
the data related to status of the current request in case of Failure.
Webhook : Data elements posted back to the client after shipment processing.

{
"message": "Schedule pickup is successful.",
"shipment_id": 62197,
"insurance": false,
"courier_id": 1,
"service_id": 3,
"courier_name": "Fedex",
"service_display_name": "Economy",
"checksum":
"MzI2OTI2OsdsM1MTBkNmIyMzY4OGVlZTasdfYTA2MWY2ZDk0MTU0ZWJhZg==",
"order_number": "123456",
"pickup": {
"success": true,
"pickup_number": "STVA1077",
"pickup_date": 1476959400000
},
"shipmentPackages": [
{
"forward_label":
"http://cdntest.zepo.in/users/1718/labels/COURIERS-784404842257-20-10-2016.pd
f",
"cod_return_label":
"http://cdntest.zepo.in/users/1718/return_labels/COURIERS-cod-return-784404842
257-20-10-2016.pdf",
"package_detail": {
"no_of_items": 1,
"package_content": "test1",
"invoice_value": 100,
"package_dimension": {
"weight": 1.0,
"length": 10.0,
"width": 10.0,
"height": 10.0
},
"volumetric_weight": 0.37037
},
"tracking_number": "784404842257",
"status_id": 0
}
]
}
 a) Status message - Indicate Success or Payment failed or Order failed. It would be user
friendly message which can be displayed by the client to the user.
i) Success message - “Schedule Pickup is successful”
ii) Abandon Message - “It seems your payment failed. Please try again”
iii) Failed Message - “There was some issue with processing your request. Please
contact Zepo support @ 9699224488”
b) Shipment Id - Numeric data indicating shipment unique id in the Courier DB
c) Insurance - Either True or False
d) Courier Id - Numeric value indicating courier company id
e) Service Id - Numeric value indicating Service type id
f) Courier Name - Courier Company used for this shipment
g) Service Display Name - Service type for this shipment
h) Checksum- Used to validate and authenticate request.
Checksum can be get by following steps
1) Concat following response parameters and make string
order_number+courier_id+service_id+shipment_id+tracking_number
This order of concatenation must be the same.

2) Encode above concatenated string to make stringToSign

3) Calculate SHA1 hash using API secret key & stringToSign
4) Calculate signature by base64 encoding the output of step3
5) Output of step4 is your checksum, match it with the ​checksum ​which we have
sent in response.
i) Order Number - client’s order number
j) Shipment Package Detail List - It would be List of Shipment Package.
i) Shipment Package Detail - It would be array of Shipment packages
1) Forward Label - It would be url for Shipment label
2) Return Label - It would be url for COD label. This is available only in case
of Fedex and payment type is COD.
3) Tracking number - It would alphanumeric tracking code related to
shipment tracking
4) Package Detail - It would be array of Package details
(a) No of item - Number of items in the package
(b) Package Content - Package content entered by the user
(c) Invoice value
(d) Volumetric Weight
(e) Package dimension
(i) Length
(ii) Width
(iii) Height
(iv) Weight
k) Pickup Array - It would contain Pickup elements
 i) Pickup Number - Unique pickup request identifier. Not available for all courier
companies currently. Available only for Fedex and Aramex.
ii) Pickup Success Status - True or false
iii) Pickup Date - Format 1465900851000