API dokumentace | Zaslat.cz

Dokumentace k API rozhraní Zaslat.cz

REST API Zaslat.cz je zdarma a využít jej může každý registrovaný zákazník
provozní API se nachází na adrese https://www.zaslat.cz/api/v1
testovací API je dostupné na adrese https://test.zaslat.cz/api/v1
veškerá odesílaná i příjimaná data jsou v kódování UTF-8
data jsou předávaná ve formátu JSON
všechna volání jsou realizována HTTP metodou POST nebo GET
komunikace probíhá pomocí zabezpečeného protokolu HTTPS

Dokumentace bude dále vylepšována. V nejbližší době přidáme modelové situace a ukázkové zdrojové kódy pro PHP.

Pokud máte nějaký dotaz, připomínku, námět na zlepšení, nebo jste objevili chybu, neváhejte kontaktovat naše IT oddělení na adrese admin@zaslat.cz.

Autentizace

Autentizace každého požadavku probíhá pomocí API klíče, který získáte v nastavení vašeho účtu. API klíč se přidává jako parametr x-apikey do hlavičky požadavku pro každou volanou API metodu.

Odpověď na požadavek

Odpověď na každý požadavek je identifikována stavovým HTTP kódem odpovídající parametru status v těle odpovědi a zprávou o provedené akci message. Rozlišujeme dva typy odpovědi podle stavu zpracování: v pořádku (kód 200 OK) nebo chyba (jakýkoliv jiný kód).

V případě chybného zpracování může být v odpovědi kromě příslušného stavového kódu vrácena a chybového hlášení a objekt error s výpisem chybných parametrů.

Pokud proběhne zpracování úspěšně, bude odpověď vrácena s volitelným parametrem odpovídající konkrétní volané metodě.

STRUKTURA ODPOVĚDI

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	string\|array	chybová hláška nebo pole objektů error s výpisem jednotlivých chyb	ne
<parametr>	array	pole objektů či hodnot dle konkrétní metody	ne

Příklad správného zpracování

    {
        "status": 200,
        "message": "Contact succesfully deleted"
    }

Příklad chybové odpovědi

    {
        "status": 401,
        "message": "Unauthorized request"
    }

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

Metody

Nabídka přepravy, ceny a termínu dodání

POPIS METODY

Pro zjištění nabídky přepravy slouží metoda, která na základě odeslaných parametrů odkud, kam, specifikace balíků a případných příplatkových služeb, vrátí nabídku dostupných přepravních společností spolu s cenou a předpokládaným termínem doručení. Cena za služby a dostupné přepravní společnosti odpovídají aktuální cenové skupině a povoleným dopravcům pro daný zákaznický účet.

POŽADAVEK

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

TĚLO POŽADAVKU

Parametr	Typ	Popis	Povinný
currency	string	kód měny podle ISO 4217, v jaké vrátit ceny služeb	ne
type	enum shipment type	typ (režim) svozu dle číselníku shipment type	ne
pickup_date	date	požadované datum vyzvednutí (YYYY-MM-DD)	ne
pickup_branch	string parcelPoint code	kód sběrného místa	ne
delivery_branch	string parcelPoint code	kód výdejního místa	ne
from	object contact	povinné je pouze pole "stát"	ano
to	object contact	povinné je pouze pole "stát"	ano
services	array of services	pole objektů service s příplatkovými službami	ne
packages	array of packages	pole objektů package s jednotlivými balíky	ano

ODPOVĚĎ

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole objektů error s chybovými hláškami	ne
rates	array of rates	pole objektů rate s nabídkami dopravců	ne

Příklad volání

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": "CZ"
        },
        "to": {
            "country": "SK"
        },
        "services": [{
            "code": "cod",
            "data": {
                "value": {
                    "value": 1500,
                    "currency": "CZK"
                }
            }
        }],
        "packages": [{
            "weight": 1,
            "width": 10,
            "height": 20,
            "length": 30
        }]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "Found 3 offers",
        "rates": [{
            "carrier": "GLS",
            "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"
            }
        },{
            ...
        }]
    }

Operace se zásilkami

Soubor metod pro práci se zásilkami.

Vytvořit novou objednávku

POPIS METODY

Vytvoření nové objednávky s jednou nebo více zásilkami.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
currency	string	kód měny podle ISO 4217, v jaké vystavit objednávku	ne^*)
payment_type	enum payment_type	forma platby za tuto dávku/objednávku	ne^*)
shipments	array of shipments	pole objektů shipment	ano
payer	object contact	objekt contact určující plátce	ne^**)
voucher	string	kód voucheru	ne

^*) Pokud není zadáno, použije se výchozí nastavení pro daný zákaznický účet

^**) Pokud je uživatel autentizován (dotaz obsahuje x-apikey), není potřeba objekt payer zadávat. V takovém případě bude plátce přihlášený uživatel.

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne

Příklad volání

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": "GLS",
            "pickup_date": 2016-07-11,
            "from": {
                "id": 1001
            },
            "to": {
                "firstname": "Jaroslav",
                "surname": "Novotný",
                "company": "Zaslat s.r.o.",
                "street": "Jindřišská 12/1027",
                "city": "Praha 4",
                "zip": "14000",
                "country": "CZ",
                "phone": "+420777152225",
                "email": "novotny@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
            }, {
                ... druhý balík ...
            }]
        }, {
            ... druhá zásilka ...
        }],
        "payer": {
                "firstname": "Miroslav",
                "surname": "Novotný",
                "company": "Zaslat s.r.o.",
                "tin": "00000000"
                "vatin": "CZ00000000"
                "street": "Jindřišská 12/1027",
                "city": "Praha 4",
                "zip": "14000",
                "country": "CZ",
                "phone": "+420777152225",
                "email": "novotny@dummymail.com"
            }
    }'

Příklad odpovědi

    {
        "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"
    }

Tisk štítků k zásilce

POPIS METODY

Získání štítků k zadaným zásilkám. Tato metoda je určena pouze pro uživatele, kteří mají zřízený pravidelný svoz balíků.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
shipments	array	pole identifikátorů zásilek	ano
position	integer [1 až 4]	pozice prvního štítku	ne^*)
format	string [`pdf`, `url`]	formát návratové hodnoty obsahující štítky	ne^**)
paper_size	string [`A4`, `A6`]	formát papíru	ne^***)

^*) Pokud není zadáno, použije se jako výchozí hodnota 1

^**) Pokud není zadáno, použije se jako výchozí hodnota pdf

^**) Pokud není zadáno, bude se aplikovat výchozí velikost A4

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	string	odkaz pro stažení štítků (pro format `url`) nebo base64 kódovaný soubor se štítky (pro format `pdf`)	ne

Příklad volání

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"
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 2 label(s).",
        "data": "data:application/pdf;base64,ZGF0YTphcHBsaWNhdGlvbi9wZGY7YmFz..."
    }
    
    {
        "status": 404,
        "message": "No shipments with specified identificators were found."
    }

Seznam zásilek

POPIS METODY

Získání seznamu zásilek. Metoda vrací vždy maximálně 100 výsledků seřazených podle datumu sestupně.

REQUEST

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

Adresu pro volání metody lze dále rozšířit o volitelné parametry:

Parametr	Typ	Popis	Povinný
status	string(20)	stav zásilky; možnosti: OPEN, ACTIVE, DELIVERED, STORNO	ne
offset	int	posunutí výsledků pro zobrazení starších zásilek	ne
from_date	date	datum od (YYYY-MM-DD)	ne
to_date	date	datum do (YYYY-MM-DD)	ne
reference_number	string	reference zásilky	ne
tracking_number	string	identifikátor zásilky	ne
search	string	vyhledávání v `reference_number` nebo `tracking_number`	ne

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of shipments	pole objektů shipment s informacemi o zásilce	ne

Příklad volání

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"

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 10 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "carrier": "gls",
                "service_id": "7",
                "pickup_date": "2017-02-02 10:24:17",
                "delivery_date": "2017-02-03 10:24:17",
                "status": "INTRANSIT",
                "from": {
                    "firstname": "František",
                    "surname": "Novotný",
                    ...
                },
                "to": {
                    "firstname": "Karel",
                    "surname": "Novotný",
                    ...
                },
                "packages": [{
                    "status": "INTRANSIT",
                    "weight": 1,
                    "width": 10,
                    "height": 20,
                    "length": 30
                },
                    ... druhý balík ...
                }]
            },
            "IZ1234567890": {
                ... druhá zásilka ...
            }
        }
    }

Detail zásilkek

POPIS METODY

Získání detailu zásilek.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
shipments	array of strings	pole identifikátorů zásilek	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of shipments	pole objektů shipment s informacemi o zásilce	ne

Příklad volání

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"]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 10 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "carrier": "gls",
                "service_id": "21",
                "pickup_date": "2017-02-02 10:24:17",
                "delivery_date": "2017-02-03 10:24:17",
                "status": "INTRANSIT",
                "from": {
                    "firstname": "František",
                    "surname": "Novotný",
                    ...
                },
                "to": {
                    "firstname": "Karel",
                    "surname": "Novotný",
                    ...
                },
                "packages": [{
                    "status": "INTRANSIT",
                    "weight": 1,
                    "width": 10,
                    "height": 20,
                    "length": 30
                },
                    ... druhý balík ...
                }],
                "services": [{
                    "code": "ins",
                    "data": {
                        "value": 12000,
                        "currency": "CZK"
                    }
                }]
            },
            "IZ1234567890": {
                ... druhá zásilka ...
            }
        }
    }

Sledování zásilky

POPIS METODY

Sledování stavu doručení zásilky.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
shipments	array of strings	pole identifikátorů zásilek	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of shipments	pole objektů shipment s informacemi o zásilce	ne

Příklad volání

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"]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 1 shipment(s).",
        "data": {
            "IZ076151CA1F": {
                "status": "INTRANSIT",
                "packages": [
                    [
                        {
                            "date": "2016-07-04",
                            "time": "15:00:00",
                            "name": "Balik byl prijat pobockou GLS.",
                            "status": "INTRANSIT",
                            "location": "Ceska Republika"
                        }, {
                            "date": "2016-07-02",
                            "time": "12:00:00",
                            "name": "Udaje k baliku byly zadany do systemu GLS.",
                            "status": "EXPORTED"
                        }
                    ], [
                        ... druhý balík ...
                    ]
                ]
            },
            "IZ1234567890": {
                ... druhá zásilka ...
            }
        }
    }

Žádost o svoz

Přes API lze také sledovat a vytvářet žádosti o svoz.

Seznam žádostí o svoz

POPIS METODY

Získat seznam žádostí o svoz.

REQUEST

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

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of pickups	pole objektů pickup	ne

Příklad volání

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"

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 4 pickup(s).",
        "data": {
            "16": {
                "id": 16,
                "date": "2017-01-31",
                "carrier": "DPD",
                "address_id": 1001
            }, {
            ...
            }
        }
    }

Vytvořit novou žádost o svoz

POPIS METODY

Vytvožit jednu nebo více žádostí o svoz.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
pickups	array of pickups	pole objektů pickup	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of integers	pole identifikátorů nově vytvořených kontaktů	ne

Příklad volání

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": "DPD",
            "address_id": 1001
        }, {
          ...
        }]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "2 pickups successfuly added.",
        "data": [35, 36]
    }

Sběrná/výdejní místa

Přes API lze získat seznam sběrných či výdejních míst.

Seznam sběrných/výdejních míst

POPIS METODY

Získat seznam sběrných/výdejních míst.

REQUEST

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

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of parcelPoints	pole objektů parcelPoint	ne

Příklad volání

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"

Příklad odpovědi

    {
        "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
            }, {
            ...
            }
        }
    }

Adresář

Přes API lze také spravovat adresář kontaktů. Odesilatelem nebo příjemcem zásilky pak může výt vybraný kontakt z adresáře identifikovaný unikátním ID. Při zadávání zásilky pak odpadne nutnost zadávání adres a kontaktních údajů.

Seznam kontaktů v adresáři

POPIS METODY

Získat seznam kontaktů z adresáře.

REQUEST

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

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of contacts	pole objektů contact	ne

Příklad volání

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"

Příklad odpovědi

    {
        "status": 200,
        "message": "OK. Found 25 contact(s).",
        "data": {
            "1002": {
                "id": 1002,
                "firstname": "Alena",
                "surname": "Šimková",
                "street": "Jánská 42",
                "city": "Brno",
                "zip": "60200",
                "country": "CZ",
                "phone": "+420603001552",
                "email": "simkova.alena@dummymail.com"
            }, {
            ...
            }
        }
    }

Vytvořit nový kontakt v adresáři

POPIS METODY

Přidat jeden nebo více kontaktů do adresáře.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
contacts	array of contacts	pole objektů contact pro přidání do adresáře	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of integers	pole identifikátorů nově vytvořených kontaktů	ne

Příklad volání

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": "Jaroslav",
          "surname": "Novotný",
          "company": "Zaslat s.r.o.",
          "street": "Jindřišská 12/1027",
          "city": "Praha 4",
          "zip": "14000",
          "country": "CZ",
          "phone": "+420777152225",
          "email": "novotny@dummymail.com"
        }, {
          ...
        }]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "2 contacts successfuly added.",
        "data": [1000, 1001]
    }

Upravit kontakt v adresáři

POPIS METODY

Upravit jeden nebo více kontaktů do adresáře.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
contacts	array of contacts	pole objektů contact pro přidání do adresáře	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne
data	array of integers	pole identifikátorů upravených kontaktů	ne

Příklad volání

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": "Jaroslav",
          "surname": "Novotný",
          "company": "Zaslat s.r.o.",
          "street": "Jindřišská 12/1027",
          "city": "Praha 4",
          "zip": "14000",
          "country": "CZ",
          "phone": "+420777152225",
          "email": "novotny@dummymail.com"
        }, {
          ...
        }]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "2 contacts successfuly updated.",
        "data": [1000, 1001]
    }

Smazat kontakty z adresáře

POPIS METODY

Smazat jeden nebo více kontaktů z adresáře.

REQUEST

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

BODY

Parametr	Typ	Popis	Povinný
contacts	array of integers	pole s identifikátory kontaktů ke smazání	ano

RESPONSE

Parametr	Typ	Popis	Povinný
status	integer	kód stavu odpovědi	ano
message	string	hlášení o provedené akci	ano
errors	array	pole s výpisem chyb	ne

Příklad volání

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]
    }'

Příklad odpovědi

    {
        "status": 200,
        "message": "2 contacts successfuly deleted"
    }

Objekty

Rate

POPIS OBJEKTU

Datová reprezentace nabídky přepravní společnosti s cenou a termínem vyzvednutí a doručení.

PARAMETRY

Parametr	Typ	Popis	Povinný
carrier	string(20)	kód přepravní společnosti podle číslelníku carriers	-
service	string(20)	název konkrétní služby dopravce	-
service_id	integer	identifikátor konkrétní služby dopravce	-
pickup_date	date	nejbližší možné datum vyzvednutí (YYYY-MM-DD)	-
pickup_from_time	time	vyzvednutí od (H:m:s)	-
pickup_to_time	time	vyzvednutí do (H:m:s)	-
delivery_date	date	nejbližší možné datum doručení (YYYY-MM-DD)	-
price	object money	cena za přepravu bez DPH	-
price_vat	object money	cena za přepravu včetně DPH	-
insurance_limit	object money	limit odpovědnosti dopravce včetně DPH	-
own_invoice_upload	bool	vlastní faktura	-
weight_limit	int	váhový limit	-
pickup_branch	bool	možnost předání na sběrném místě	-
pickup_branch_required	bool	nutnost předat zásilku na sběrné místo	-
delivery_branch_required	bool	nutnost doručení na výdejní místo	-
shipment_category	string(20)	kategorie zásilky podle číselníku Shipment Category	-
trackable	bool	trakování zásilky	-
printable	bool	tisk štítků	-

Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.

Příklad

    {
        "carrier": "GLS",
        "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

POPIS OBJEKTU

Datová reprezentace kontaktní osoby a místa doručení nebo vyzvednutí zásilky.

PARAMETRY

Parametr	Typ	Popis	Povinný
id	integer	identifikátor existujícího kontaktu	ne^*)
company	string(75)	název společnosti	ne
firstname	string(50)	jméno kontaktní osoby	ano^**)
surname	string(50)	příjmení kontaktní osoby	ano^**)
street	string(100)	ulice s číslem popisným	ano^**)
city	string(50)	obec nebo město	ano^**)
zip	string(12)	poštovní směrovací číslo	ano^**)
country	string(2)	kód země ISO 3166-1 alpha-2	ano
phone	string(50)	telefonní kontakt	ano^**)
email	string(50)	e-mailový kontakt	ne
tin	string(50)	identifikační číslo osoby	ne
vatin	string(50)	daňové identifikační číslo	ne

^*) Pokud předáváme pomocí reference na ID, tak ostatní parametry jsou nepovinné

^**) Nepovinné při použití v metodě pro získání nabídky přepravy

Příklad

    {
        "id": 1001,
        "firstname": "Jaroslav",
        "surname": "Novotný",
        "company": "Zaslat s.r.o.",
        "street": "Jindřišská 12/1027",
        "city": "Praha 4",
        "zip": "14000",
        "country": "CZ",
        "phone": "+420777152225",
        "email": "novotny@dummymail.com"
    }


    Lze také předat jako referenci jen pomocí ID:

    {
        "id": 1001
    }

Shipment

POPIS OBJEKTU

Datová reprezentace zásilky.

PARAMETRY

Parametr	Typ	Popis	Povinný
carrier	string(20)	kód přepravní společnosti podle číslelníku carriers	ne
service_id	integer	identifikátor konkrétní služby dopravce	ne
type	enum shipment type	typ (režim) svozu dle číselníku shipment type	ne
pickup_date	date	požadované datum vyzvednutí (YYYY-MM-DD)	ne
pickup_branch	string parcelPoint code	kód sběrného místa	ne
delivery_branch	string parcelPoint code	kód výdejního místa	ne
from	object contact	objekt contact určující místo vyzvednutí	ano
to	object contact	objekt contact určující místo doručení	ano
services	array of service	pole objektů service s příplatkovými službami	ne
packages	array of package	pole objektů package s jednotlivými balíky	ano
reference	string(255)	vlastní označení zásilky	ne
note	string(255)	poznámka pro řidiče	ne
status	string	stav zásilky	-

Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.

Příklad

    {
        "carrier": "GLS",
        "pickup_date": 2016-07-11,
        "from": {
            "id": 1001
        },
        "to": {
            "firstname": "Jaroslav",
            "surname": "Novotný",
            "company": "Zaslat s.r.o.",
            "street": "Jindřišská 12/1027",
            "city": "Praha 4",
            "zip": "14000",
            "country": "CZ",
            "phone": "+420777152225",
            "email": "novotny@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

POPIS OBJEKTU

Datová reprezentace místa pro předání či vyzvednutí zásilky.

PARAMETRY

Parametr	Typ	Popis	Povinný
id	int	identifikátor	-
carrier	string(20)	dopravce podle číselníku carriers	-
code	string	kód místa	-
name	string	název místa	-
street	string	ulice s číslem popisným	-
city	string	obec nebo město	-
zip	string	poštovní směrovací číslo	-
country	string	kód země ISO 3166-1 alpha-2	-
phone	string	kontaktní telefon	-
location	object	objekt `lat`, `lng`"	-
is_collection	bool	sběrné místo	-
is_locker	int	box `1` ano , `0` ne	-
is_depot	int	sklad `1` ano , `0` ne	-
card_payment	int	platba kartou `1` ano , `0` ne	-
wheelchair_access	int	bezbariérový přístup `1` ano , `0` ne	-
no_lunch_break	int	polední přestávka `1` ano , `0` ne	-
open_saturday	int	otevřeno v sobotu `1` ano , `0` ne	-
open_sunday	int	otevřeno v neděli `1` ano , `0` ne	-
opening_hours	object	pole objektů opening hours, index pole udává den v týdnu, pondělí = 1	-

Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.

Příklad

    {
        "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
    }

Package

POPIS OBJEKTU

Datová reprezentace jednoho balíku v zásilce. Balík je popsán jeho váhou, rozměry a doplňkově popisem a jeho peněžní hodnotou.

PARAMETRY

Parametr	Typ	Popis	Povinný
weight	float	hmotnost [kg]	ano
width	integer	šířka v [cm]	ano
height	integer	výška v [cm]	ano
length	integer	délka [cm]	ano
value	object money	hodnota balíku	ne
content	string(255)	obsah balíku	ne
status	enum shipment status	aktuální stav balíku dle číselníku shipment shipment status	ano
history	array of history	pole typu history reprezentující historii stavů balíku	ne
carrier_tracking	string	odkaz na sledování balíku	ne

Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.

Příklad

    {
        "weight": 7.5,
        "width": 50,
        "height": 30,
        "length": 40,
        "status": "CREATED",
        "number": "",
        "value": {
            "value": 100,
            "currency": "EUR"
        },
        "carrier_tracking": "https://www.carrier.com/example-tracking",
        "content": "popis balíku"
    }

History

POPIS OBJEKTU

Datová reprezentace historie sledování zásilky.

PARAMETRY

Parametr	Typ	Popis	Povinný
date	date	datum vytvoření záznamu v historii balíku	-
time	time	čas vytvoření záznamu v historii balíku	-
name	string	textová informace o záznamu v historii balíku	-
status	string	stav v historii balíku	-
location	string	Doplňující informace o místě/lokaci balíku	-

Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.

Příklad

    {
        "date": "2016-07-16",
        "time": "15:17:00",
        "name": "Balik byl dorucen",
        "status": "DELIVERED",
        "location": "Portugalsko"
    }

Service

POPIS OBJEKTU

Datová reprezentace příplatkové služby (dobírka, připojištění, atp.)

PARAMETRY

Parametr	Typ	Popis	Povinný
code	string(20)	kód příplatkové služby podle číselníků services	ano
data	object	parametry pro příplatkovou službu podle číselníků services	ano

Příklad

    {
        "code": "cod",
        "data": {
            "value": {
                "value": 100,
                "currency": "EUR"
            }
        }
    }

Pickup

POPIS OBJEKTU

Datová reprezentace žádosti o svoz.

PARAMETRY

Parametr	Typ	Popis	Povinný
id	int	identifikátor žádosti o svoz	ano
date	date	požadované datum svozu (YYYY-MM-DD)	ano
carrier	string(20)	kód přepravní společnosti podle číslelníku carriers	ano
address_id	integer	identifikátor existujícího kontaktu	ano

Příklad

    {
        "id": 12354,
        "date": "2017-01-31",
        "carrier": "DPD",
        "address_id": 1001
    }

Opening Hours

POPIS OBJEKTU

Data reprezentují otevírací dobu výdejních/sběrných místo.

PARAMETRY

Parametr	Typ	Popis	Povinný
from1	time	otevřteno od (H:m)	ano
to1	time	otevřteno do (H:m)	ano
from2	time	otevřteno od (H:m)	ne^*)
to2	time	otevřteno do (H:m)	ne^*)

^*) V případě uvedení času má výdejní místo polední pauzu.

Příklad

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

Money

POPIS OBJEKTU

Objekt reprezentující peněžní hodnotu v odpovídající měně. Objekt je využíván tam, kde je potřeba předat číselné vyjádření hodnoty spolu s měnou. Např. dobírka, pojištění, hodnota balíku, atd.

PARAMETRY

Parametr	Typ	Popis	Povinný
value	float	částka v příslušné měně	ano
currency	string(3)	kód měny podle ISO 4217	ano

Příklad

    {
        "value": 1500,
        "currency": "CZK"
    }

ServiceCOD

POPIS OBJEKTU

Objekt reprezentující službu dobírky.

PARAMETRY

Parametr	Typ	Popis	Povinný
bank_account	string(64)	číslo účtu pro vyplacení dobírky	ne
bank_code	string(4)	kód banky účtu pro vyplacení dobírky	ne
bank_variable	string(20)	variabilní symbol použitý při vyplacení dobírky	ne
value	object money	výše dobírky balíku	ano

Příklad

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

Error

POPIS OBJEKTU

Objekt reprezentující chybovou hlášku.

PARAMETRY

Parametr	Typ	Popis	Povinný
field	string	název parametru, který vyvolal chybu	-
message	string	textový popis chyby	-
value	string	zadaná hodnota parametru	-

Příklad

    {
        "field": "contacts[0].email",
        "message": "Invalid e-mail format.",
        "value": "f.novotny@seznam"
    }

Číselníky

HTTP status codes

POPIS ČÍSELNÍKU

Číselník HTTP kódu stavů v odpovědi na konkrétní požadavek.

Kód	Stav	Popis
200	OK	Požadavek úspěšně zpracován
400	Bad Request	Neplatný požadavek (chyba vstupních dat)
401	Unauthorized	Neautorizovaný požadavek (neplatný API klíč)
404	Not Found	Požadovaná metoda nebyla nalezena (chybná URL požadavku)
500	Internal Server Error	Vnitřní chyba aplikace (chyba na naší straně)

Carriers

POPIS ČÍSELNÍKU

Seznam kódu přepravních společností, které systém Zaslat.cz integruje.

Kód	Název
PPL	PPL
DPD	DPD
GLS	GLS
TOPTRANS	TOPTRANS
UPS	UPS
GLS_SK	GLS_SK
LIFTAGO	Liftago
TNT	TNT
FEDEX	FedEx
WEDO	WEDO
BALIKOVNA	Balikovna

Payment type

POPIS ČÍSELNÍKU

Číselník dostupných forem platby za dávku/objednávku. Platba na fakturu je dostupná pouze po předchozí domluvě pro firemní zákazníky s uzavřenou zasilatelskou smlouvou. Chcete také platit na fakturu? Kontaktujte nás.

Kód	Popis
ONLINE	Platba on-line bránou GoPay přes vrácenou URL
CREDIT	Úhrada z předplaceného kreditu na zákaznickém účtu
INVOICE	Platba na fakturu pouze pro smluvní zákazníky

Shipment Status

POPIS ČÍSELNÍKU

Číselník možných stavů v historii zásilky.

Kód	Popis
CREATED	Zásilka byla vytvořena
EXPORTED	Dopravce potvrdil přijetí dat o zásilce
ONPICKUP	Zásilka čeká na vyzvednutí kurýrem
INTRANSIT	Zásilka je na cestě do cílového depa
ONDELIVERY	Zásilka byla předána kurýrovi na rozvoz
DELIVERED	Zásilka byla doručena
CANCELLED	Zásilka byla stornována

Shipment Type

POPIS ČÍSELNÍKU

Číselník možných režimů svozu.

Kód	Popis
ONDEMAND	Jednorázový svoz - štítky tiskne dopravce.
OCCASIONAL	Příležitostný svoz - štítky si tiskne zákazník.
REGULAR	Pravidelný svoz - štítky si tiskne zákazník.

Shipment Category

POPIS ČÍSELNÍKU

Číselník možných kategorií zásilky.

Kód	Popis
domestic	Doruřování v rámci jedné země
exportEu	Export zásilky v rámci států EU
exportWorld	Export zásilky mimo státy EU
importEu	Import zásilky v rámci států EU
importWorld	Import zásilky mimo státy EU

Services

POPIS ČÍSELNÍKU

Číselník příplatkových služeb

Kód	Data	Popis
COD	object serviceCOD	Dobírka do vybraných států (CZ, SK)
INS	object money	Připojištění nad rámec základního pojištění
DSC	string(20)	Slevový kód

Příklad: dobírka

    {
        "code": "cod",
        "data": {
            "bank_currency": "CZK",
            "bank_account": "12-34567890",
            "bank_code": "0100",
            "bank_variable": "987654321",
            "value": {
                "value": 1500,
                "currency": "CZK"
            }
        }
    }

Příklad: připojištění

    {
        "code": "ins",
        "data": {
            "value": 500,
            "currency": "EUR"
        }
    }

Pickup Time Range

POPIS ČÍSELNÍKU

Číselník časových oken svozu

Kód	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

Příklady implementace

V této části budou uvedeny příklady implementace API rozhraní služby Zaslat.cz v programovacím jazyce PHP.

Získání nabídky přepravy

IMPLEMENTACE

Pro získání nabídky přepravy je potřeba odeslat POST požadavek na adresu https://www.zaslat.cz /api/v1/rates/get.

V těle požadavku je nutno uvést vstupní data tak, jak je to uvedeno v dokumentaci výše.

Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl.

Příklad: získání nabídky přepravy v jazyce PHP


// Nejprve je nutne poskladat data, ktera budou odeslana v tele pozadavku
// podle specifikace v dokumentaci.
$data = array(
    "from" => array(
        "country" => "CZ"
    ),
    "to" => array(
        "country" => "SK"
    ),
    "services" => array(
        array(
            "code" => "COD",
            "data" => array(
                "value" => array(
                    "value" => 1500,
                    "currency" => "CZK"
                )
            )
        )
    ),
    "packages" => array(
        array(
            "weight" => 1,
            "width" => 10,
            "height" => 20,
            "length" => 30
        )
    )
);
// Data musi byt v tele pozadavku odeslana ve formatu JSON,
// proto je nutno data do daneho formatu prevest.
$data = json_encode($data);

// Pro odeslani pozadavku pouzijeme PHP knihovnu cURL.
// Veskere moznosti nastaveni viz http://php.net/manual/en/book.curl.php
// 1. Inicializace knihovny
$ch = curl_init();
// 2. Nastaveni URL adresy API volani
curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.cz/api/v1/rates/get");
// 3. Urceni HTTP metody volani
curl_setopt($ch, CURLOPT_POST, 1);
// 4. Nastaveni hlavicek volani. Misto <VAS-API-KLIC> doplnte Vas API klic
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Accept: application/json",
    "Content-Type: application/json",
    "X-Apikey: <VAS-API-KLIC>"
));
// 5. Naplneni tela pozadavku daty
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
// 6. Nastaveni ulozeni odpovedi volani do promenne
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// 7. Zavolani API rozhrani Zaslat.cz se zvolenymi parametry
$response = curl_exec($ch);
// 8. Ukonceni relace a uvolneni zdroju
curl_close($ch);

// Promenna $response nyni obsahuje odpoved serveru ve formatu JSON.
// Prevedeme ji tedy do formatu asociativniho pole pro dalsi praci s daty
$response = json_decode($response, true);

Vytvoření nové objednávky

IMPLEMENTACE

Pro vytvoření nové objednávky je potřeba odeslat POST požadavek na adresu https://www.zaslat.cz /api/v1/shipments/create.

V těle požadavku je nutno uvést vstupní data tak, jak je to uvedeno v dokumentaci výše.

Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl.

Poznámka: pro detailní popis všech metod a volání v kódu se prosím podívejte na ukázku kódu pro získání nabídky přepravy, která je bohatě komentovaná.

Příklad: získání nabídky přepravy v jazyce PHP


// Seskladani dat
$data = array(
    "currency" => "CZK",
    "payment_type" => "online",
    "shipments" => array(
        array(
            "pickup_date" => "2017-02-10",
            "from" => array(
                "id" => 1001
            ),
            "to" => array(
                "firstname" => "Jaroslav",
                "surname" => "Novotný",
                "company" => "Zaslat s.r.o.",
                "street" => "Jindřišská 12/1027",
                "city" => "Praha 4",
                "zip" => "14000",
                "country" => "CZ",
                "phone" => "+420777152225",
                "email" => "novotny@dummymail.com"
            ),
            "packages" => array(
                array(
                    "weight" => 1,
                    "width" => 10,
                    "height" => 20,
                    "length" => 30
                )
            )
        )
    )
);
$data = json_encode($data);

// Vytvoreni cURL pozadavku
$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: <VAS-API-KLIC>"
));
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Odpoved serveru
$response = json_decode($response, true);

Získání seznamu kontaktů

IMPLEMENTACE

Pro získání nabídky přepravy je potřeba odeslat GET požadavek na adresu https://www.zaslat.cz /api/v1/contacts/list.

Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl.

Poznámka: pro detailní popis všech metod a volání v kódu se prosím podívejte na ukázku kódu pro získání nabídky přepravy, která je bohatě komentovaná.

Příklad: získání nabídky přepravy v jazyce PHP


$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: <VAS-API-KLIC>"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Odpoved serveru
$response = json_decode($response, true);