Zásilky

Vytváření zásilek, štítky, seznam, detail, tracking, storno a manifest.

Vytvoření objednávky zásilek

POST

https://test.zaslat.cz/api/v1

/shipments/create

x-apikey (header)

Vytvoří jednu nebo více zásilek. Pokud nebude uvedena platba nebo měna, použijí se výchozí hodnoty účtu. Pokud je požadavek autentizován přes x-apikey, není nutné uvádět payer — plátcem se automaticky stává přihlášený uživatel.

Další průběh závisí na způsobu platby (PaymentType): u CREDIT a INVOICE se zásilky předají dopravci ihned, u ONLINE zůstávají ve stavu CREATED, dokud není objednávka zaplacena — teprve poté přejdou do EXPORTED a je dostupný štítek. Odpověď platební URL neobsahuje; stránku pro online platbu složíte z hodnoty data.order: https://www.zaslat.cz/cs/objednavka/{order} (na testovacím prostředí https://test.zaslat.cz/cs/objednavka/{order}).

Varianta podání musí odpovídat nabídce z /rates/get — pokud byla nabídka vrácena pouze s pickup_branch: true (typicky Balíkovna, Zásilkovna), uveďte pickup_branch: true i při vytvoření, jinak se pro zásilku nenajde žádná cenová nabídka (chyba 400). Podrobnosti v Doručení na výdejní místo.

Partnerské integrace (moduly pro e-shopy, pluginy, aplikace třetích stran) uvádějí v kořeni požadavku pole source s přiděleným identifikátorem integrace — viz Identifikace integrace.

Zásilku PPL v rámci ČR s jedním balíkem lze objednat bez štítku — příznakem label_less: true na zásilce. Místo štítku dopravce přidělí šestimístný kód (SmartPIN), který API po exportu vrací v packages[].package_password. Podrobnosti v Bezštítková zásilka PPL (SmartPIN).

Pro celní zásilky a svoz s vlastním tiskem štítků viz rozšířené specifikace výše.

Vytvoření objednávky zásilek › Request Body

ShipmentsCreateRequest

Shipment[] · required

currency

string

Kód měny objednávky. Pokud není uvedena, použije se výchozí měna účtu.

payment_type

PaymentType · enum

Způsob úhrady objednávky. Pokud není uveden, použije se výchozí způsob platby účtu (u nového účtu ONLINE). Neautentizované požadavky (bez platného x-apikey) mohou použít pouze ONLINE. CREDIT je dostupný každému přihlášenému účtu s nabitým kreditem; INVOICE pouze smluvním zákazníkům (aktivuje Zaslat na vyžádání). U CREDIT a INVOICE se zásilky předají dopravci ihned po vytvoření, u ONLINE až po zaplacení objednávky.

Enum values:

ONLINE

CREDIT

INVOICE

object

Kontakt plátce. Nepovinné, pokud je požadavek autentizován přes x-apikey — plátcem se pak stává přihlášený uživatel.

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

voucher

string

Slevový kód.

source

string

Identifikátor integrace (partnerského modulu, pluginu nebo aplikace), která objednávku vytváří. Slouží ke statistické evidenci zdroje objednávek na straně Zaslat. Hodnotu identifikátoru vám přidělíme při zavedení integrace; nezáleží na velikosti písmen a mezery se ignorují. Neznámá hodnota se tiše ignoruje a objednávka se eviduje jako běžná objednávka přes API. Pole se v odpovědích nevrací.

Pluginy Alsendo Connect uvádějí Alsendo Connect: <platforma>, kde platforma je PrestaShop, WooCommerce, OpenCart nebo Shopify.

Example: Alsendo Connect: PrestaShop

Vytvoření objednávky zásilek › Responses

Zásilky byly úspěšně vytvořeny.

Základní tvar odpovědi bez datové části.

status

integer

HTTP stavový kód odpovědi.

Example: 200

message

string

Textová zpráva k provedené akci.

Example: OK

Error[]

object

POST/shipments/create

curl https://test.zaslat.cz/api/v1/shipments/create \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-apikey: <api-key>' \
  --data '{
  "currency": "CZK",
  "payment_type": "ONLINE",
  "shipments": [
    {
      "pickup_date": "2026-07-10",
      "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"
      },
      "packages": [
        {
          "weight": 1,
          "width": 10,
          "height": 20,
          "length": 30
        }
      ]
    }
  ]
}'

Example Request Body

{
  "currency": "CZK",
  "payment_type": "ONLINE",
  "shipments": [
    {
      "pickup_date": "2026-07-10",
      "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"
      },
      "packages": [
        {
          "weight": 1,
          "width": 10,
          "height": 20,
          "length": 30
        }
      ]
    }
  ]
}

json

application/json

Example Responses

{
  "status": 200,
  "message": "Order was successfully created",
  "data": {
    "order": "2eb6987d41c8e6a5361f7e4b95c0f41bfd",
    "order_number": "OP23100000X",
    "shipments": [
      "IZ0123456789",
      "IZ1234567890"
    ]
  }
}

json

application/json

Získání štítků

POST

https://test.zaslat.cz/api/v1

/shipments/label

x-apikey (header)

Vrátí tiskové štítky pro vybrané zásilky, ve formátu PDF nebo jako URL ke stažení. Štítek je dostupný až poté, co dopravce potvrdí přijetí dat o zásilce (stav EXPORTED a novější). Zásilku ve stavu CREATED (např. objednávka s platbou ONLINE čekající na zaplacení) ani zásilku jiného účtu endpoint nenajde a vrátí 404 — stav zásilky ověřte přes /shipments/tracking. Pro zásilku, jejíž štítek přiveze kurýr (label_mode: CARRIER), endpoint žádný štítek nevrátí (400).

Zda a kdy štítek bude, poznáte předem z polí label_mode a label_status v odpovědi /shipments/detail — viz Štítky a jejich stavy.

U bezštítkových zásilek PPL (label_less: true) endpoint vrací A6 dokument s QR kódem a SmartPINem, který není nutné tisknout — slouží jen jako podklad pro odesílatele.

Endpoint vyžaduje platný x-apikey; s neplatným klíčem vrací 401.

Získání štítků › Request Body

shipments

string[] · required

Pole identifikátorů zásilek (tracking_number).

position

integer · min: 1 · max: 4

Pozice prvního štítku na tiskovém archu.

Default: 1

format

string · enum

Formát návratové hodnoty — pdf vrátí base64 zakódovaný soubor, url odkaz ke stažení, stream odpoví přímo binárním PDF (bez JSON obálky).

Enum values:

pdf

url

stream

Default: pdf

paper_size

string · enum

Formát papíru štítku.

Enum values:

Default: A4

Získání štítků › Responses

Štítek(y) byly vygenerovány.

status

integer

message

string

Error[]

data

string

Odkaz ke stažení (format=url) nebo base64 zakódovaný soubor (format=pdf).

POST/shipments/label

curl https://test.zaslat.cz/api/v1/shipments/label \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-apikey: <api-key>' \
  --data '{
  "shipments": [
    "IZ0123456789"
  ],
  "format": "url",
  "paper_size": "A4"
}'

Example Request Body

{
  "shipments": [
    "IZ0123456789"
  ],
  "format": "url",
  "paper_size": "A4"
}

json

application/json

Example Responses

{
  "status": 200,
  "message": "OK. Found 1 label(s).",
  "data": "https://www.zaslat.cz/labels/download/2eb6987d41c8e6a5361f7e4b95c0f41bfd"
}

json

application/json

Seznam zásilek

GET

https://test.zaslat.cz/api/v1

/shipments/list

x-apikey (header)

Vrátí stránkovaný seznam zásilek, který lze filtrovat podle stavu, data nebo identifikátorů.

Seznam zásilek › query Parameters

status

string · enum

Filtrace podle stavu zásilky.

Enum values:

OPEN

ACTIVE

DELIVERED

STORNO

offset

integer

Posun výsledků pro procházení starších zásilek.

limit

integer · min: 1 · max: 50

Maximální počet vrácených zásilek.

Default: 50

from_date

string · date

Počáteční datum filtru (od data vytvoření).

to_date

string · date

Koncové datum filtru.

reference_number

string

Filtrace podle vlastní reference zásilky (reference).

tracking_number

string

Filtrace podle identifikátoru zásilky.

search

string

Fulltextové vyhledávání v reference_number nebo tracking_number.

tracking

string

Přiložit ke každé zásilce pole tracking_information s tracking historií.

Seznam zásilek › Responses

Seznam zásilek.

ShipmentListResponse

status

integer

message

string

Error[]

object

Objekt zásilek klíčovaný identifikátorem zásilky (tracking_number).

GET/shipments/list

curl https://test.zaslat.cz/api/v1/shipments/list \
  --header 'x-apikey: <api-key>'

Example Responses

{
  "status": 200,
  "message": "OK. Found 2 of total 10 item(s).",
  "data": {
    "IZ076151CA1F": {
      "carrier": "GLS",
      "service_id": 7,
      "pickup_date": "2026-07-02",
      "delivery_date": "2026-07-03",
      "status": "INTRANSIT",
      "reference": "objednavka-2026-0001",
      "from": {
        "firstname": "František",
        "surname": "Novotný",
        "city": "Praha 4",
        "zip": "14000",
        "country": "CZ"
      },
      "to": {
        "firstname": "Karel",
        "surname": "Novotný",
        "city": "Brno",
        "zip": "60200",
        "country": "CZ"
      },
      "packages": [
        {
          "status": "INTRANSIT",
          "weight": 1,
          "width": 10,
          "height": 20,
          "length": 30
        }
      ]
    },
    "IZ1234567890": {
      "carrier": "DPD",
      "service_id": 8,
      "pickup_date": "2026-07-01",
      "delivery_date": "2026-07-02",
      "status": "DELIVERED",
      "from": {
        "firstname": "František",
        "surname": "Novotný",
        "city": "Praha 4",
        "zip": "14000",
        "country": "CZ"
      },
      "to": {
        "firstname": "Alena",
        "surname": "Šimková",
        "city": "Ostrava",
        "zip": "70200",
        "country": "CZ"
      },
      "packages": [
        {
          "status": "DELIVERED",
          "weight": 2,
          "width": 20,
          "height": 15,
          "length": 30
        }
      ]
    }
  }
}

json

application/json

Detail zásilek

POST

https://test.zaslat.cz/api/v1

/shipments/detail

x-apikey (header)

Vrátí podrobné informace k vybraným zásilkám. S query parametrem tracking odpověď u každé zásilky obsahuje navíc pole tracking_information s kompletní tracking historií (stejný tvar jako odpověď endpointu /shipments/tracking).

U zásilek do boxů / výdejních míst vybraných dopravců (Zásilkovna, Balíkovna) a u bezštítkových zásilek PPL obsahuje objekt Package v odpovědi navíc parametr package_password — heslo pro podání balíku/vratky, tj. kód, který odesílatel zadá při předání balíku na výdejním místě nebo do boxu (u PPL šestimístný SmartPIN). Heslo je dostupné až od stavu EXPORTED (po exportu zásilky k dopravci) a vrací se pouze vlastníkovi zásilky; stejné pole vrací i /shipments/list. Pole label_less v objektu Shipment říká, zda zásilka skutečně zůstala bezštítková.

Pole label_mode a label_status v objektu Shipment říkají, kdo štítek dodá (tisknete sami, přiveze kurýr, nebo stačí kód) a zda už je k dispozici. Podle label_status poznáte, kdy přestat na štítek čekat — NOT_APPLICABLE znamená, že štítek nikdy nebude (přiveze ho kurýr), FAILED, že se ho nepodařilo získat. Obě pole se vrací všem volajícím. Podrobnosti v Štítky a jejich stavy.

Kompletní údaje (ulice, telefon a e-mail odesílatele i příjemce, reference, poznámka) vrací endpoint pouze vlastníkovi zásilky — tj. při autentizaci klíčem účtu, pod kterým byla objednávka vytvořena. Ostatním (včetně nepřihlášených požadavků) se tato pole vrací jako null. Plný detail lze získat i bez přihlášení uvedením tokenu objednávky (data.order z odpovědi /shipments/create) v poli tokens na stejné pozici, jakou má identifikátor zásilky v poli shipments.

Detail zásilek › query Parameters

tracking

string

Přiložit tracking historii ke každé zásilce (stačí přítomnost parametru).

Detail zásilek › Request Body

shipments

string[] · required

Pole identifikátorů zásilek.

tokens

string[]

Tokeny objednávek (data.order z /shipments/create) na stejných pozicích jako identifikátory v shipments. Zpřístupní plný detail zásilky i bez přihlášení.

Detail zásilek › Responses

Detail zásilek.

ShipmentListResponse

status

integer

message

string

Error[]

object

Objekt zásilek klíčovaný identifikátorem zásilky (tracking_number).

POST/shipments/detail

curl https://test.zaslat.cz/api/v1/shipments/detail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-apikey: <api-key>' \
  --data '{
  "shipments": [
    "IZ076151CA1F"
  ]
}'

Example Request Body

{
  "shipments": [
    "IZ076151CA1F"
  ]
}

json

application/json

Example Responses

{
  "status": 200,
  "message": "OK. Found 1 item(s).",
  "data": {
    "IZ076151CA1F": {
      "carrier": "GLS",
      "service_id": 21,
      "pickup_date": "2026-07-02",
      "delivery_date": "2026-07-03",
      "status": "INTRANSIT",
      "reference": "objednavka-2026-0001",
      "from": {
        "firstname": "František",
        "surname": "Novotný",
        "street": "Jindřišská 12/1027",
        "city": "Praha 4",
        "zip": "14000",
        "country": "CZ",
        "phone": "+420777152225",
        "email": "novotny@dummymail.com"
      },
      "to": {
        "firstname": "Karel",
        "surname": "Novotný",
        "street": "Jánská 42",
        "city": "Brno",
        "zip": "60200",
        "country": "CZ",
        "phone": "+420603001552",
        "email": "karel.novotny@dummymail.com"
      },
      "services": [
        {
          "code": "ins",
          "data": {
            "value": 12000,
            "currency": "CZK"
          }
        }
      ],
      "packages": [
        {
          "status": "INTRANSIT",
          "weight": 1,
          "width": 10,
          "height": 20,
          "length": 30,
          "carrier_tracking": "https://gls-group.eu/CZ/cs/sledovani-zasilek?match=123456789"
        }
      ]
    }
  }
}

json

application/json

Tracking zásilek

POST

https://test.zaslat.cz/api/v1

/shipments/tracking

x-apikey (header)

Vrátí aktuální stav a historii tracking událostí vybraných zásilek.

Tracking zásilek › Request Body

shipments

string[] · required

Pole identifikátorů zásilek.

Tracking zásilek › Responses

Stav a historie zásilek.

TrackingResponse

status

integer

message

string

Error[]

object

Objekt klíčovaný identifikátorem zásilky (tracking_number).

POST/shipments/tracking

curl https://test.zaslat.cz/api/v1/shipments/tracking \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-apikey: <api-key>' \
  --data '{
  "shipments": [
    "IZ076151CA1F"
  ]
}'

Example Request Body

{
  "shipments": [
    "IZ076151CA1F"
  ]
}

json

application/json

Example Responses

{
  "status": 200,
  "message": "OK. Found 1 item(s).",
  "data": {
    "IZ076151CA1F": {
      "status": "INTRANSIT",
      "returned": false,
      "packages": [
        [
          {
            "date": "2026-07-04",
            "time": "15:00:00",
            "name": "Balík byl přijat pobočkou GLS.",
            "status": "INTRANSIT",
            "location": "Česká republika"
          },
          {
            "date": "2026-07-02",
            "time": "12:00:00",
            "name": "Údaje k balíku byly zadány do systému GLS.",
            "status": "EXPORTED"
          }
        ]
      ]
    }
  }
}

json

application/json

Storno zásilek

POST

https://test.zaslat.cz/api/v1

/shipments/storno

x-apikey (header)

Zruší vybrané zásilky, pokud ještě nebyly předány k přepravě.

Storno zásilek › Request Body

shipments

string[] · required

Pole identifikátorů zásilek ke stornování.

Storno zásilek › Responses

Zásilky byly stornovány.

Základní tvar odpovědi bez datové části.

StatusMessageResponse

status

integer

HTTP stavový kód odpovědi.

Example: 200

message

string

Textová zpráva k provedené akci.

Example: OK

Error[]

Předávací protokol (manifest)

POST

https://test.zaslat.cz/api/v1

/shipments/manifest

x-apikey (header)

Vygeneruje předávací protokol (soupiska) pro vybrané zásilky.

Předávací protokol (manifest) › Request Body

shipments

string[] · required

Pole identifikátorů zásilek.

format

string · enum

Formát výsledného manifestu.

Enum values:

pdf

url

Default: pdf

Předávací protokol (manifest) › Responses

Manifest byl vygenerován.

status

integer

message

string

Error[]

data

string

Odkaz ke stažení (format=url) nebo base64 zakódovaný soubor (format=pdf).

Nabídka přepravy Svozy