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

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

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

Příklad odpovědi

    {
        "status": 200,
        "message": "Order was successfully created",
        "data": {
            "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^**)

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

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

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: ACTIVE, DELIVERED	ne
offset	int	posunutí výsledků pro zobrazení starších zásilek	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": {
            "60500-ABZKNIHYAS": {
                "code": "60500-ABZKNIHYAS",
                "name": "ABZ knihy, OC Sfinx",
                "street": "Hrnčířská 573/6",
                "city": "Brno",
                "zip": "60500",
                "country": "CZ",
                "coords": "49.2103|16.601",
                "contact_name": "Zdena Kolblová",
                "contact_phone": "774 111 038",
                "opening_hours": {
                    "1": "10:00-17:00",
                    "2": "10:00-19:00",
                    "3": "10:00-19:00",
                    "4": "10:00-17:00",
                    "5": "10:00-17:00",
                    "6": null,
                    "7": 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)	-
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	-

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,
        "price": {
            "value": 98.35,
            "currency": "CZK"
        },
        "price_vat": {
            "value": 119,
            "currency": "CZK"
        }
    }

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

^*) 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ý
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	-
coords	string	gps souřadnice ve tvau "lat\|lng"	-
contact_name	string	jméno kontaktní osoby	-
contact_phone	string	kontaktní telefon	-
opening_hours	array	otevírací doba	-

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

Příklad

    {
        "code": "60500-ABZKNIHYAS",
        "name": "ABZ knihy, OC Sfinx",
        "street": "Hrnčířská 573/6",
        "city": "Brno",
        "zip": "60500",
        "country": "CZ",
        "coords": "49.2103|16.601",
        "contact_name": "Zdena Kolblová",
        "contact_phone": "774 111 038",
        "opening_hours": {
            "1": "10:00-17:00",
            "2": "10:00-19:00",
            "3": "10:00-19:00",
            "4": "10:00-17:00",
            "5": "10:00-17:00",
            "6": null,
            "7": 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	-
history	array of history	Pole typu history reprezentující historii stavů balíku	-

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

Příklad

    {
        "weight": 7.5,
        "width": 50,
        "height": 30,
        "length": 40,
        "value": {
            "value": 100,
            "currency": "EUR"
        },
        "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ý
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

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

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
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.

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);