Zaslat API v1

Bezštítková zásilka PPL (SmartPIN)

Rozšířená specifikace

Jedná se o rozšířenou specifikaci API dokumentace pro endpoint shipments/create — příznak label_less v objektu Shipment a pole package_password v objektu Package.

Zásilku PPL lze objednat bez štítku. Dopravce místo štítku přidělí šestimístný kód (SmartPIN, např. AFF330), který odesílatel napíše na balík nebo ukáže jako QR kód při podání na výdejním místě PPL. Odesílatel tak nepotřebuje tiskárnu.

Podmínky

Podmínka	Hodnota
dopravce	PPL (`carrier: PPL` nebo `service_id` služby PPL)
počet balíků	právě jeden (`packages` s jednou položkou)
trasa	odesílatel i příjemce v ČR
ceník / účet	bez omezení

Kód je určen pro podání balíku na výdejním místě PPL (ParcelShop / ParcelBox). Variantu podání (pickup_branch, pickup_branch_location) uveďte podle nabídky z /rates/get, viz Doručení na výdejní místo.

Objednávka

Do zásilky přidejte label_less: true:

Code
{
    "currency": "CZK",
    "payment_type": "CREDIT",
    "shipments": [
        {
            "carrier": "PPL",
            "label_less": true,
            "pickup_date": "2026-07-10",
            "from": { "id": 1001 },
            "to": {
                "firstname": "Jaroslav",
                "surname": "Novotný",
                "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 }]
        }
    ]
}

Při nesplnění podmínek endpoint vrátí 400 s chybou u pole shipments[n].label_less:

Chyba	Příčina
`Labelless shipment is available only for PPL.`	jiný dopravce než PPL
`Labelless shipment must contain exactly one package.`	více balíků v zásilce
`Labelless shipment is available only within the Czech Republic.`	odesílatel nebo příjemce mimo ČR

Získání kódu SmartPIN

Kód vzniká až při exportu zásilky k dopravci, v odpovědi shipments/create proto ještě není. Po přechodu zásilky do stavu EXPORTED ho vrací POST /shipments/detail a GET /shipments/list v objektu Package v poli package_password:

Code
{
    "tracking_number": "IZ076151CA1F",
    "status": "EXPORTED",
    "label_less": true,
    "packages": [
        {
            "number": "80012345678",
            "status": "EXPORTED",
            "package_password": "AFF330"
        }
    ]
}

Pole se vrací pouze vlastníkovi zásilky (klíč účtu, pod kterým vznikla objednávka) nebo při uvedení tokenu objednávky v poli tokens; ostatním se vrací null.
Export probíhá asynchronně — stav zásilky sledujte pollingem, viz Sledování zásilek a stavy.
Pole label_less v odpovědi potvrzuje, že zásilka bezštítková skutečně zůstala. Pokud dopravce bezštítkový export odmítne, zásilka se automaticky vytvoří s klasickým štítkem, label_less je false a package_password zůstane null — štítek pak získáte přes /shipments/label.
Bezštítková zásilka má v odpovědi label_mode: CODE; jakmile je kód k dispozici, label_status je READY. Po odmítnutí dopravcem se label_mode změní na PRINT. Význam obou polí popisuje stránka Štítky a jejich stavy.

Štítek

Endpoint /shipments/label u bezštítkové zásilky vrací A6 dokument s QR kódem a SmartPINem. Není nutné ho tisknout, slouží jen jako podklad pro odesílatele (např. k přeposlání e-mailem).

Last modified on October 6, 2026

Doručení na výdejní místo Štítky a jejich stavy