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.

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.

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.

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

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