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 sumbal@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 přepravců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 přepravců 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 přepravce -
service_id integer identifikátor konkrétní služby přepravce -
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 přepravce 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 Popis
GLS https://gls-group.eu/CZ/cs/home
DPD https://www.dpd.com/cz
PPL https://www.ppl.cz
UPS https://www.ups.com/
GEIS http://www.geis-group.cz/cz
TOPTRANS http://www.toptrans.cz
MESSENGER http://www.geis-group.cz/cz
MAPAKURYR http://www.mapakuryr.cz

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 Přepravce 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 přepravce.
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);