Documentation for the Zaslat.cz API

  • REST API Zaslat.cz is free and can be used by any registered customer
  • production API is located at https://www.zaslat.cz/api/v1
  • test API is available at https://test.zaslat.cz/api/v1
  • all sent and received data is in UTF-8 encoding
  • data is transmitted in JSON format
  • all calls are made using HTTP method POST or GET
  • communication is performed using secure HTTPS protocol

Documentation will be further improved. In the near future, we will add model situations and sample source code for PHP.

If you have any question, suggestion, suggestion for improvement, or you have found a mistake, do not hesitate to contact our IT department at admin@zaslat.cz.

Authentication

Each request is authenticated using the API key provided in your account settings. The API key is added as a parameter x-apikey to the request header for each called API method.

Response to request

The response to each request is identified by an HTTP status code corresponding to the parameter status in the response body and an action message message. There are two types of response according to the processing status: ok (code 200 OK) or error (any other code).

In case of error processing, an error message and an error object with a list of incorrect parameters can be returned in response to the corresponding status code.

If processing is successful, the response is returned with an optional parameter corresponding to the particular method being called .

Response structure
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors string|array error message or array of error objects listing individual errors no
<parameter> array array of objects or values ​​according to a specific method no
Example of success response
    {
        "status": 200,
        "message": "Contact succesfully deleted"
    }
Example of an error response
    {
        "status": 401,
        "message": "Unauthorized request"
    }

    {
        "status": 400,
        "message": "Contact validation error"
        "errors": [{
            "message": "Address line cannot be empty"
        }]
    }

Methods

Offer shipping, prices and delivery dates

Description of the Method

To determine the offer of transport, the method is used, which based on the parameters sent from where, where, the specification of packages and possible additional services, returns the offer of available shipping companies together with the price and expected delivery date. The price for the services and the available shipping companies correspond to the current price group and the authorized carriers for the given customer account.

Request

POST https://www.zaslat.cz/api/v1/rates/get

Body Request
Parameter Type Description Required
currency string ISO 4217 currency code in which to return service prices no
type enum shipment type type (mode) of collection according to shipment type dictionary no
pickup_date date required pickup date (YYYY-MM-DD) no
pickup_branch string parcelPoint code collection point code no
delivery_branch string parcelPoint code drop-off point code no
from object contact only the "state" field is required yes
to object contact only the "state" field is required yes
services array of services array of service objects with additional services no
packages array of packages array of package objects with individual packages yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of error objects with error messages no
rates array of rates array of rate objects with carrier offers no
Example Call
curl -v https://www.zaslat.cz/api/v1/rates/get \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "currency": "CZK",
        "pickup_date": "2016-07-10",
        "from": {
            "country": "ZA"
        },
        "to": {
            "country": "ZA"
        },
        "services": [{
            "code": "cod",
            "data": {
                "value": {
                    "value": 1500,
                    "currency": "CZK"
                }
            }
        }],
        "packages": [{
            "weight": 1,
            "width": 10,
            "height": 20,
            "length": 30
        }]
    }'
Response Example
    {
        "status": 200,
        "message": "Found 3 offers",
        "rates": [{
            "carrier": "UPS",
            "service": "Export SK",
            "service_id": 21,
            "pickup_date": "2016-07-10",
            "delivery_date": "2016-07-12",
            "price": {
                "value": 178.51,
                "currency": "CZK"
            },
            "price_vat": {
                "value": 216,
                "currency": "CZK"
            }
        },{
            ...
        }]
    }

Shipment Operations

A set of methods for handling shipments.

Create a new order

Description of the Method

Create a new order with one or more shipments.

Request

POST https://www.zaslat.cz/api/v1/shipments/create

Body
Parameter Type Description Required
currency string ISO 4217 currency code in which to place the order no*)
payment_type enum payment_type form of payment for this batch / order no*)
shipments array of shipments array of shipment objects yes
payer object contact objekt contact identifying the payer yes**)
voucher string voucher code no

*) If not specified, the default settings for the customer account will be used

**) If the user is authenticated (the request contains the x-apikey), there is no need to enter the payer object. In this case, the payer will be the logged-in user.

Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
Example Call
curl -v https://www.zaslat.cz/api/v1/shipments/create \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-ApiKey: secret-api-key" \
-d '{
        "currency": "CZK",
        "payment_type": "online",
        "shipments": [{
            "carrier": "UPS",
            "pickup_date": 2016-07-11,
            "from": {
                "id": 1001
            },
            "to": {
                "firstname": "David",
                "surname": "Williams",
                "company": "Parcelspot Ltd.",
                "street": "4447 Sheffield Rd",
                "city": "Cape Town",
                "zip": "7750",
                "country": "ZA",
                "phone": "+27115689759",
                "email": "williams@dummymail.com"
            },
            "services": [{
                "code": "cod",
                "data": {
                    "value": {
                        "value": 1500,
                        "currency": "CZK"
                    }
                }
            }, {
                "code": "ins",
                "data": {
                    "value": 12500,
                    "currency": "CZK"
                }
            }],
            "packages": [{
                "weight": 1,
                "width": 10,
                "height": 20,
                "length": 30
            }, {
                ... second package ...
            }]
        }, {
            ... second shipment ...
        }],
        "payer": {
            "firstname": "David",
            "surname": "Williams",
            "company": "Parcelspot Ltd.",
            "street": "4447 Sheffield Rd",
            "city": "Cape Town",
            "zip": "7750",
            "country": "ZA",
            "phone": "+27115689759",
            "email": "williams@dummymail.com"
        }
    }'
Response Example
    {
        "status": 200,
        "message": "Order was successfully created",
        "data": {
            "order": "2eb6987.............5c0f41bfd",
            "order_number": "OP23100000X",
            "shipments": [
                "IZ0123456789",
                "IZ1234567890"
            ]
        }
    }

    {
        "status": 401,
        "message": "You are not allowed to use invoice payment method"
    }

Print shipping labels

Description of the Method

Get labels for specified shipments. This method is intended only for users who have regular package collection.

Request

POST https://www.zaslat.cz/api/v1/shipments/label

Body
Parameter Type Description Requried
shipments array array of shipment identifiers yes
position integer [1 to 4] first label position no*)
format string [pdf, url] return value format containing labels no**)
paper_size string [A4, A6] paper size no***)

*) If not specified, the default value is 1

**) If not specified, default value is used pdf

**) If not specified, the default size A4 will be applied

Response
Parameter Type Description Requried
status integer response status code yes
message string action report yes
errors array array of errors no
data string link to download label (for format url) or base64 encoded label file (for format pdf) no
Example Call
curl -v https://www.zaslat.cz/api/v1/shipments/label \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "shipments": ["IZ0123456789", "IZ1234567890"],
        "position": 2,
        "format": "pdf"
    }'
Response Example
    {
        "status": 200,
        "message": "OK. Found 2 label(s).",
        "data": "data:application/pdf;base64,ZGF0YTphcHBsaWNhdGlvbi9wZGY7YmFz..."
    }
    
    {
        "status": 404,
        "message": "No shipments with specified identificators were found."
    }

List of shipments

Description of the Method

Get a list of shipments. The method always returns a maximum of 100 results sorted by date in descending order.

Request

GET https://www.zaslat.cz/api/v1/shipments/list

The method call address can be further extended with optional parameters:

Parameter Type Description Required
status string(20) shipment status; OPEN, ACTIVE, DELIVERED, STORNO options no
offset int move results to view older shipments no
from_date date date from (YYYY-MM-DD) no
to_date date date to (YYYY-MM-DD) no
reference_number string shipment reference number no
tracking_number string shipment tracking number no
search string search in reference_number or tracking_number no
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of shipments array of shipment objects with shipment information no
Example Call
curl -v https://www.zaslat.cz/api/v1/shipments/list \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key"
Response Example
    {
        "status": 200,
        "message": "OK. Found 10 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "carrier": "UPS",
                "service_id": "7",
                "pickup_date": "2017-02-02 10:24:17",
                "delivery_date": "2017-02-03 10:24:17",
                "status": "INTRANSIT",
                "from": {
                    "firstname": "Joshua",
                    "surname": "Williams",
                    ...
                },
                "to": {
                    "firstname": "Ethan",
                    "surname": "Williams",
                    ...
                },
                "packages": [{
                    "status": "INTRANSIT",
                    "weight": 1,
                    "width": 10,
                    "height": 20,
                    "length": 30
                },
                    ... second package ...
                }]
            },
            "IZ1234567890": {
                ... second shipment ...
            }
        }
    }

Shipment detail

Description of the Method

Get shipment details.

Request

POST https://www.zaslat.cz/api/v1/shipments/detail

Body
Parameter Type Description Required
shipments array of strings array of shipment identifiers yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of shipments array of shipment objects with shipment information no
Example Call
curl -v https://www.zaslat.cz/api/v1/shipments/detail \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "shipments": ["IZ076151CA1F", "IZ1234567890"]
    }'
Response Example
    {
        "status": 200,
        "message": "OK. Found 10 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "carrier": "UPS",
                "service_id": "21",
                "pickup_date": "2017-02-02 10:24:17",
                "delivery_date": "2017-02-03 10:24:17",
                "status": "INTRANSIT",
                "from": {
                    "firstname": "Joshua",
                    "surname": "Williams",
                    ...
                },
                "to": {
                    "firstname": "Ethan",
                    "surname": "Williams",
                    ...
                },
                "packages": [{
                    "status": "INTRANSIT",
                    "weight": 1,
                    "width": 10,
                    "height": 20,
                    "length": 30
                },
                    ... second package ...
                }],
                "services": [{
                    "code": "ins",
                    "data": {
                        "value": 12000,
                        "currency": "CZK"
                    }
                }]
            },
            "IZ1234567890": {
                ... second shipment ...
            }
        }
    }

Shipment Tracking

Description of the Method

Track delivery status.

Request

POST https://www.zaslat.cz/api/v1/shipments/tracking

Body
Parameter Type Description Required
shipments array of strings array of shipment identifiers yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of shipments array of shipment objects with shipment information no
Example Call
curl -v https://www.zaslat.cz/api/v1/shipments/tracking \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "shipments": ["IZ076151CA1F", "IZ1234567890"]
    }'
Response Example
    {
        "status": 200,
        "message": "OK. Found 1 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "status": "INTRANSIT",
                "packages": [
                    [
                        {
                            "date": "2016-07-04",
                            "time": "15:00:00",
                            "name": "The package was received by the UPS.",
                            "status": "INTRANSIT",
                            "location": "South Africa"
                        }, {
                            "date": "2016-07-02",
                            "time": "12:00:00",
                            "name": "The package data has been entered into the UPS system.",
                            "status": "EXPORTED"
                        }
                    ], [
                        ... second package ...
                    ]
                ]
            },
            "IZ1234567890": {
                ... second shipment ...
            }
        }
    }

Collection Request

You can also track and create collection requests via the API.

List of collection requests

Description of the Method

Get a list of collection requests.

Request

GET https://www.zaslat.cz/api/v1/pickups/list

Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of pickups array of pickup objects no
Example Call
curl -v https://www.zaslat.cz/api/v1/pickups/list \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key"
Response Example
    {
        "status": 200,
        "message": "OK. Found 4 pickup(s).",
        "data": {
            "16": {
                "id": 16,
                "date": "2017-01-31",
                "carrier": "UPS",
                "address_id": 1001
            }, {
            ...
            }
        }
    }

Create a new collection request

Description of the Method
Request

POST https://www.zaslat.cz/api/v1/pickups/add

Body
Parameter Type Description Required
pickups array of pickups array of pickup objects yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of integers array of identifiers of newly created contacts no
Example Call
curl -v https://www.zaslat.cz/api/v1/pickups/add \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "pickups": [{
            "date": "2017-02-10",
            "carrier": "UPS",
            "address_id": 1001
        }, {
          ...
        }]
    }'
Response Example
    {
        "status": 200,
        "message": "2 pickups successfuly added.",
        "data": [35, 36]
    }

Drop-off Points

A list of drop-off points can be obtained through the API.

Seznam podacích/výdejních míst

Description of the Method

Obtain a list of drop-off points.

Request

GET https://www.zaslat.cz/api/v1/parcelpoints/list

Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of parcelPoints array of parcelPoint of parcelPoint objects no
Example Call
curl -v https://www.zaslat.cz/api/v1/parcelpoints/list \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key"
Response Example
    {
        "status": 200,
        "message": "OK. Found 148 item(s).",
        "data": {
            16604": {
                "id": 16604,
                "carrier": "PPL",
                "code": "KM11730100",
                "name": "„V Háji“",
                "street": "28. října 89/51",
                "city": "Plzeň",
                "zip": "30100",
                "country": "CZ",
                "phone": null,
                "location": {
                    "lat": "49.778694444444",
                    "lng": "13.409666666667"
                },
                "is_collection": true,
                "is_locker": 0,
                "is_depot": 0,
                "card_payment": 1,
                "wheelchair_access": 0,
                "no_lunch_break": 1,
                "open_saturday": 0,
                "open_sunday": 0,
                "opening_hours": {
                    "7": {
                        "from1": "13:00",
                        "to1": "22:00",
                        "from2": null,
                        "to2": null
                    },
                    "1": {
                        "from1": "13:00",
                        "to1": "22:00",
                        "from2": null,
                        "to2": null
                    },
                    "2": {
                        "from1": "13:00",
                        "to1": "22:00",
                        "from2": null,
                        "to2": null
                    },
                    ...
                    "6": {
                        "from1": "13:00",
                        "to1": "22:00",
                        "from2": null,
                        "to2": null
                    }
                },
                "distance": 0,
                "user": null
            }, {
            ...
            }
        }
    }

Address Book

The address book can also be managed via the API. The sender or recipient of the shipment can then select the selected contact from the address book identified by a unique ID. When entering a shipment, there is no need to enter addresses and contact details.

Address book list

Description of the Method

Get contact list from address book.

Request

GET https://www.zaslat.cz/api/v1/contacts/list

Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of contacts array of contact objects no
Example Call
curl -v https://www.zaslat.cz/api/v1/contacts/list \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key"
Response Example
    {
        "status": 200,
        "message": "OK. Found 25 contact(s).",
        "data": {
            "1002": {
                "id": 1002,
                "firstname": "Samantha",
                "surname": "Smith",
                "street": "5 Well St, Riviera",
                "city": "Pretoria",
                "zip": "0084",
                "country": "ZA",
                "phone": "+27115689759",
                "email": "smith.samantha@dummymail.com"
            }, {
            ...
            }
        }
    }

Create a new contact in the address book

Description of the Method

Add one or more contacts to the address book.

Request

POST https://www.zaslat.cz/api/v1/contacts/add

Body
Parameter Type Description Required
contacts array of contacts array of contact objects to add to the address book yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of integers array of identifiers of newly created contacts no
Example Call
curl -v https://www.zaslat.cz/api/v1/contacts/add \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "contacts": [{
          "firstname": "David",
          "surname": "Williams",
          "company": "Parcelspot Ltd.",
          "street": "4447 Sheffield Rd",
          "city": "Cape Town",
          "zip": "7750",
          "country": "ZA",
          "phone": "+27115689759",
          "email": "williams@dummymail.com"
        }, {
          ...
        }]
    }'
Response Example
    {
        "status": 200,
        "message": "2 contacts successfuly added.",
        "data": [1000, 1001]
    }

Edit contact in address book

Description of the Method

Edit one or more contacts to the address book.

Request

POST https://www.zaslat.cz/api/v1/contacts/edit

Body
Parameter Type Description Required
contacts array of contacts array of contact objects to add to the address boo yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
data array of integers array of identifiers of modified contacts no
Example Call
curl -v https://www.zaslat.cz/api/v1/contacts/edit \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "contacts": [{
          "id": 1234,
          "firstname": "David",
          "surname": "Williams",
          "company": "Parcelspot Ltd.",
          "street": "4447 Sheffield Rd",
          "city": "Cape Town",
          "zip": "7750",
          "country": "ZA",
          "phone": "+27115689759",
          "email": "williams@dummymail.com"
        }, {
          ...
        }]
    }'
Response Example
    {
        "status": 200,
        "message": "2 contacts successfuly updated.",
        "data": [1000, 1001]
    }

Delete contacts from address book

Description of the Method

Delete one or more contacts from the address book.

Request

POST https://www.zaslat.cz/api/v1/contacts/delete

Body
Parameter Type Description Required
contacts array of integers array with contact IDs to delete yes
Response
Parameter Type Description Required
status integer response status code yes
message string action report yes
errors array array of errors no
Example Call
curl -v https://www.zaslat.cz/api/v1/contacts/delete \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Apikey: secret-api-key" \
-d '{
        "contacts": [1111, 1215]
    }'
Response Example
    {
        "status": 200,
        "message": "2 contacts successfuly deleted"
    }

Objects

Rate

Description of the Object

Data representation of the shipping company offer with price and date of collection and delivery.

Parameters
Parameter Type Description Required
carrier string(20) code of the shipping company according to the dictionary carriers -
service string(20) the name of the particular carrier's service -
service_id integer identifier of the particular carrier service -
pickup_date date earliest possible pickup date (YYYY-MM-DD) -
pickup_from_time time pickup from (H:m:s) -
pickup_to_time time pickup to (H:m:s) -
delivery_date date nearest possible delivery date (YYYY-MM-DD) -
price object money price for shipping excluding VAT -
price_vat object money price for shipping including VAT -
insurance_limit object money limit of carrier's liability including VAT -
own_invoice_upload bool custom invoice -
weight_limit int weight limit -
pickup_branch bool is pickup branch -
pickup_branch_required bool required branch for pickup -
delivery_branch_required bool required branch for delivery -
shipment_category string(20) shipment category according to the Shipment Category -
trackable bool shipment tracking -
printable bool label printing -

Note: lines in in italics indicate response parameters.

Example
    {
        "carrier": "UPS",
        "service": "Business-Parcel",
        "service_id": 7,
        "pickup_date": 2016-07-11,
        "delivery_date": 2016-07-12,
        "pickup_from_time": "08:00:00",
        "pickup_to_time": "18:00:00",
        "price": {
            "value": 98.35,
            "currency": "CZK"
        },
        "price_vat": {
            "value": 119,
            "currency": "CZK"
        },
        "insurance_limit": {
            "value": 50000,
            "currency": "CZK"
        },
        "weight_limit": 15,
        "pickup_branch": true,
        "pickup_branch_required": true,
        "delivery_branch_required": true,
        "trackable": true,
        "printable": true,
        "shipment_category": "domestic"
    }

Contact

Description of the Object

Data representation of the contact person and the place of delivery or pickup.

Parameters
Parameter Type Description Required
id integer identifier of an existing contact no*)
company string(75) company name no
firstname string(50) name of the contact person yes**)
surname string(50) surname of the contact person yes**)
street string(100) street with house number yes**)
city string(50) municipality or city yes**)
zip string(12) postal code yes**)
country string(2) ISO 3166-1 alpha-2 country code yes
phone string(50) telephone contact yes**)
email string(50) email contact no

*) If we pass by ID reference, other parameters are optional

**) Optional when used in the method for obtaining the transport offer

Example
    {
        "id": 1001,
        "firstname": "David",
        "surname": "Williams",
        "company": "Parcelspot Ltd.",
        "street": "4447 Sheffield Rd",
        "city": "Cape Town",
        "zip": "7750",
        "country": "ZA",
        "phone": "+27115689759",
        "email": "williams@dummymail.com"
    }


    Can also be passed as reference only by ID:

    {
        "id": 1001
    }

Shipment

Description of the Object

Data representation of the shipment.

Parameters
Parameter Type Description Required
carrier string(20) code of the shipping company according to the dictionary carriers no
service_id integer identifier of the particular carrier service no
type enum shipment type type (mode) of collection according to shipment type codebook no
pickup_date date required pickup date (YYYY-MM-DD) no
pickup_branch
(deprecated)		 string parcelPoint code collection point code no
delivery_branch
(deprecated)		 string parcelPoint code dispensing point code no
pickup_branch_location integer collection point location ID * no
delivery_branch_location integer delivery point location ID * no
from object contact a contact object specifying the pickup location yes
to object contact a contact object specifying the delivery location yes
services array of service service object array with additional services no
packages array of package array of package objects with individual packages yes
reference string(255) self-marking of the consignment no
note string(255) note for drivers no
status string shipment status -

* Location ID can be found in the collection/dropoff points map for each point in the list

Example
    {
        "carrier": "UPS",
        "pickup_date": 2016-07-11,
        "from": {
            "id": 1001
        },
        "to": {
            "firstname": "David",
            "surname": "Williams",
            "company": "Parcelspot Ltd.",
            "street": "4447 Sheffield Rd",
            "city": "Cape Town",
            "zip": "7750",
            "country": "ZA",
            "phone": "+27115689759",
            "email": "williams@dummymail.com"
        },
        "services": [{
            "code": "cod",
            "data": {
                "value": {
                    "value": 1500,
                    "currency": "CZK"
                }
            }
        }, {
            "code": "ins",
            "data": {
                "value": 12500,
                "currency": "CZK"
            }
        }],
        "packages": [{
            "weight": 1,
            "width": 10,
            "height": 20,
            "length": 30
        }, {
            ...
        }]
    }

ParcelPoint

Description of the Object

Data representation of the place for handing over or picking up the shipment.

Parameters
Parameter Type Description Required
id int Identifier -
carrier string(20) carrier by code of carriers -
code string location code -
name string place name -
street string street with house number -
city string municipality or city -
zip string postal code -
country string ISO 3166-1 alpha-2 country code -
phone string contact phone -
location object object of lat, lng" -
is_collection bool is collection point -
is_locker int box 1 yes , 0 no -
is_depot int depot 1 yes , 0 no -
card_payment int payment by card 1 yes , 0 no -
wheelchair_access int wheelchair access 1 yes , 0 no -
no_lunch_break int lunch break 1 yes , 0 no -
open_saturday int open on Saturday 1 yes , 0 no -
open_sunday int open on Sunday 1 yes , 0 no -
opening_hours object array of objects opening hours, field index indicates the day of the week, Monday = 1 -
pickup_branch_location_id int identifier of the pickup/dropoff point of carriers operating at the same address -

Note: lines in in italics indicate response parameters.

Example
        {
        "id": 16604,
        "carrier": "PPL",
        "code": "KM11730100",
        "name": "„V Háji“",
        "street": "28. října 89/51",
        "city": "Plzeň",
        "zip": "30100",
        "country": "CZ",
        "phone": null,
        "location": {
            "lat": "49.778694444444",
            "lng": "13.409666666667"
        },
        "is_collection": true,
        "is_locker": 0,
        "is_depot": 0,
        "card_payment": 1,
        "wheelchair_access": 0,
        "no_lunch_break": 1,
        "open_saturday": 0,
        "open_sunday": 0,
        "opening_hours": {
            "7": {
                "from1": "13:00",
                "to1": "22:00",
                "from2": null,
                "to2": null
            },
            "1": {
                "from1": "13:00",
                "to1": "22:00",
                "from2": null,
                "to2": null
            },
            "2": {
                "from1": "13:00",
                "to1": "22:00",
                "from2": null,
                "to2": null
            },
            ...
            "6": {
                "from1": "13:00",
                "to1": "22:00",
                "from2": null,
                "to2": null
            }
        },
        "distance": 0,
        "pickup_branch_location_id": 123456789,
        "user": null
    }

Package

Description of the Object

Data representation of one package in a shipment. The package is described by its weight, dimensions and additionally by its description and its monetary value.

Parameters
Parameter Type Description Required
weight float weight [kg] yes
width integer width v [cm] yes
height integer height v [cm] yes
length integer length [cm] yes
value object money package value no
content string(255) content of package no
status enum shipment status current package status according to shipment shipment status dictionary yes
history array of history array of history representing package status history no
carrier_tracking string package tracking link no

Note: lines in in italics indicate response parameters.

Example
    {
        "weight": 7.5,
        "width": 50,
        "height": 30,
        "length": 40,
        "status": "CREATED",
        "number": "",
        "value": {
            "value": 100,
            "currency": "EUR"
        },
        "content": "package description"
    }

History

Description of the Object

Data representation of shipment tracking history.

Parameters
Parameter Type Description Required
date date the date the record was created in the package history -
time time time of record creation in package history -
name string text information about the package history record -
status string status in package history -
location string additional information about package location / location -

Note: lines in in italics indicate response parameters.

Example
    {
        "date": "2016-07-16",
        "time": "15:17:00",
        "name": "Package delivered",
        "status": "DELIVERED",
        "location": "South Africa"
    }

Service

Description of the Object

Data representation of additional service (cash on delivery, additional insurance, etc.)

Parameters
Parameter Type Description Required
code string(20) code optional services under dictionaries services yes
data object optional parameters for the service according to dictionaries services yes
Example
    {
        "code": "cod",
        "data": {
            "value": {
                "value": 100,
                "currency": "CZK"
            }
        }
    }

Pickup

Description of the Object

Data representation of the collection request.

Parameters
Parameter Type Description Required
id int collection request identifier yes
date date required collection date (YYYY-MM-DD) yes
carrier string(20) kcode of the shipping company according to the dictionary carriers yes
address_id integer identifier of an existing contact yes
Example
    {
        "id": 12354,
        "date": "2017-01-31",
        "carrier": "UPS",
        "address_id": 1001
    }

Opening Hours

Description of the Object

The data represent the opening hours of the pickup and delivery points.

Parameters
Parameter Type Description Required
from1 time open from (H:m) yes
to1 time open to (H:m) yes
from2 time open from (H:m) no*)
to2 time open to (H:m) no*)

*) If the time is given, the point has a lunch break.

Example
    {
        "from1": "13:00",
        "to1": "22:00",
        "from2": null,
        "to2": null
    },

Money

Description of the Object

An object representing the monetary value in the corresponding currency. The object is used where it is necessary to pass a numerical expression of the value together with the currency. E.g. COD, insurance, parcel value, etc.

Parameters
Parameter Type Description Required
value float the amount in the relevant currency yes
currency string(3) ISO 4217 currency code yes
Example
    {
        "value": 1500,
        "currency": "CZK"
    }

ServiceCOD

Description of the Object

Object representing the COD service.

Parameters
Parameter Type Description Required
bank_account string(64) account number for cash on delivery no*)
bank_code string(4) bank account code for cash on delivery no*)
bank_variable string(20) variable symbol used for cash on delivery no
value object money cash on delivery package amount yes

*) IBAN can be inserted into bank_account, in this case bank_code will remain empty.

Example
    {
        "bank_account": "12-34567890",
        "bank_code": "0100",
        "value": {
            "value": 1500,
            "currency": "CZK"
        }
    }

Error

Description of the Object

The object representing the error message.

Parameters
Parameter Type Description Required
field string the name of the parameter that caused the error -
message string text description of the error -
value string specified parameter value -
Example
    {
        "field": "contacts[0].email",
        "message": "Invalid e-mail format.",
        "value": "f.williams@dummymail.com"
    }

Dictionaries

HTTP status codes

Description of the code

HTTP response status codes.

Code State Description
200 OK Request successfully processed
400 Bad Request Invalid request (input data error)
401 Unauthorized Unauthorized Request (Invalid API Key)
404 Not Found Requested method not found (bad request URL)
500 Internal Server Error Internal application error (error on our side)

Carriers

Description of the code

Dictionary of shipping companies that the Zaslat.cz system integrates.

Code Name
PPL PPL
DPD DPD
GLS GLS
TOPTRANS TOPTRANS
UPS UPS
GLS_SK GLS_SK
LIFTAGO Liftago
TNT TNT
FEDEX FedEx
WEDO WEDO
BALIKOVNA Balíkovna
ZASILKOVNA Zásilkovna

Payment type

Description of the code

List of available forms of payment per batch / order. The invoice payment is only available by prior arrangement for business customers with a forwarding contract. Do you also want to pay by invoice? Please contact us.

Code Description
ONLINE Payment by GoPay on-line via returned URL
CREDIT Payment from prepaid credit on customer account
INVOICE Payment on invoice only for contract customers

Shipment Status

Description of the code

Dictionary of possible states in shipment history.

Code Description
CREATED Shipment created
EXPORTED The shipper acknowledged receipt of the shipment data
ONPICKUP Shipment waiting for pickup by courier
INTRANSIT The shipment is on its way to the destination depot
ONDELIVERY The consignment was handed over to the courier for delivery
DELIVERED The shipment was delivered
CANCELLED Shipment canceled

Shipment Type

Description of the code

Dictionary of possible collection modes.

Code Description
ONDEMAND One-time Collection - labels are printed by the carrier.
OCCASIONAL Occasional collection - labels are printed by the customer.
REGULAR

Shipment Category

Description of the code

List of available shipment categories.

Code Description
domestic Delivery within one country
exportEu Export shipments within EU countries
exportWorld Export shipments outside the EU
importEu Import shipments within EU countries
importWorld Import shipments outside the EU

Services

Description of the code

Dictionary of extra services.

Code Data Description
COD object serviceCOD Cash on delivery to selected countries (CZ, SK)
INS object money Additional insurance beyond basic insurance
DSC string(20) Discount code
Example: COD
    {
        "code": "cod",
        "data": {
            "bank_currency": "CZK",
            "bank_account": "12-34567890",
            "bank_code": "0100",
            "bank_variable": "987654321",
            "value": {
                "value": 1500,
                "currency": "CZK"
            }
        }
    }
Example: insurance
    {
        "code": "ins",
        "data": {
            "value": 500,
            "currency": "CZK"
        }
    }

Pickup Time Range

Description of the code

Dictionary of time windows of collection.

Code Data
1 09:00:00 - 13:00:00
2 09:30:00 - 13:30:00
3 10:00:00 - 14:00:00
4 10:30:00 - 14:30:00
5 11:00:00 - 15:00:00
6 11:30:00 - 15:30:00
7 12:00:00 - 16:00:00
8 12:30:00 - 16:30:00
9 13:00:00 - 17:00:00

Examples of implementation


This section provides examples of the implementation of the Zaslat.cz API in the PHP programming language.

Getting a shipping offer

Implementation

To get a shipping offer, you need to send a POST request to the address https://www.zaslat.cz /api/v1/rates/get.

The input data must be specified in the request body as described in the documentation above.

The example in the box on the right is in PHP using the built-in library curl.

Example: Get a shipping offer in PHP

// First, it is necessary to assemble the data that will be sent in the request body
// as specified in the documentation.
$data = array(
    "from" => array(
        "country" => "ZA"
    ),
    "to" => array(
        "country" => "ZA"
    ),
    "services" => array(
        array(
            "code" => "COD",
            "data" => array(
                "value" => array(
                    "value" => 1500,
                    "currency" => "CZK"
                )
            )
        )
    ),
    "packages" => array(
        array(
            "weight" => 1,
            "width" => 10,
            "height" => 20,
            "length" => 30
        )
    )
);
// The data must be sent in the JSON format in the request body,
// so the data must be transferred to that format.
$data = json_encode($data);

// We will use the cURL PHP library to send the request.
// For all setup options, see http://php.net/manual/en/book.curl.php
// 1. Initialize library
$ch = curl_init();
// 2. Set the API URL
curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.cz/api/v1/rates/get");
// 3. Determine the HTTP call method
curl_setopt($ch, CURLOPT_POST, 1);
// 4. Headers settinfs. Instead of <YOUR-API-KEY> add your API key
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Accept: application/json",
    "Content-Type: application/json",
    "X-Apikey: <YOUR-API-KEY>"
));
// 5. Filling the request body with data
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
// 6. Save response to variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// 7. Call API Zaslat.cz with the selected parameters
$response = curl_exec($ch);
// 8. Close a cURL session
curl_close($ch);

// $response variable now contains the JSON response.
// Let's convert it to an associative array format
$response = json_decode($response, true);

Create a new order

Implementation

To create a new order, it is necessary to send a POST request to the address https://www.zaslat.cz /api/v1/shipments/create.

The input data must be specified in the request body as described in the documentation above.

The example in the box on the right is in PHP using the built-in library curl.

Note: for a detailed description of all the methods and calls in the code, please see the code sample to get a transport offer that is richly commented.

Example: Create a new order in PHP

// Request Data
$data = array(
    "currency" => "CZK",
    "payment_type" => "online",
    "shipments" => array(
        array(
            "pickup_date" => "2017-02-10",
            "from" => array(
                "id" => 1001
            ),
            "to" => array(
                "firstname" => "David",
                "surname" => "Williams",
                "company" => "Parcelspot Ltd.",
                "street" => "4447 Sheffield Rd",
                "city" => "Cape Town",
                "zip" => "7750",
                "country" => "ZA",
                "phone" => "+27115689759",
                "email" => "williams@dummymail.com"
            ),
            "packages" => array(
                array(
                    "weight" => 1,
                    "width" => 10,
                    "height" => 20,
                    "length" => 30
                )
            )
        )
    )
);
$data = json_encode($data);

// Create cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.cz/api/v1/shipments/create");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Accept: application/json",
    "Content-Type: application/json",
    "X-Apikey: <YOUR-API-KEY>"
));
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Response
$response = json_decode($response, true);

Get a contact list

Implementation

To get a shipping offer, you need to send a GET request to https://www.zaslat.cz /api/v1/contacts/list.

The example in the box on the right is in PHP using the built-in library curl.

Note: for a detailed description of all the methods and calls in the code, please see the code sample to get a transport offer that is richly commented.

Example: Get a contact list in PHP

// Create cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.cz/api/v1/contacts/list");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Accept: application/json",
    "Content-Type: application/json",
    "X-Apikey: <YOUR-API-KEY>"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Response
$response = json_decode($response, true);