Dokumentace k API rozhraní Zaslat.sk

  • REST API Zaslat.sk je zdarma a využít jej může každý registrovaný zákazník
  • provozní API se nachází na adrese https://www.zaslat.sk/api/v1
  • testovací API je dostupné na adrese https://test.zaslat.sk/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.sk.

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.sk/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 podací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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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]
    }

Podací/výdejní místa

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

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

POPIS METODY

Získat seznam podacích/výdejních míst.

REQUEST

GET https://www.zaslat.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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.sk/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 podacím místě -
pickup_branch_required bool nutnost předat zásilku na podací 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
(deprecated)
string parcelPoint code kód podacího místa ne
delivery_branch
(deprecated)
string parcelPoint code kód výdejního místa ne
pickup_branch_location integer ID lokace podacího místa * ne
delivery_branch_location integer ID lokace 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 -

* ID lokace naleznete v mapě podacích a výdejních míst u každého místa v seznamu

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 podací 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/podacích míst.

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.sk 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 Balíkovna
ZASILKOVNA Zásilkovna

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.sk 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.sk /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.sk/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.sk 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.sk /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.sk/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.sk /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.sk/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);