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

:::info[Rozšířená specifikace]
Jedná se o rozšířenou specifikaci API dokumentace pro endpoint `shipments/create` — příznak
`label_less` v objektu [Shipment](/api-v1/~schemas#shipment) a pole `package_password`
v objektu [Package](/api-v1/~schemas#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](/api/v1/parcel_points).

## Objednávka

Do zásilky přidejte `label_less: true`:

```json
{
    "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](/api-v1/~schemas#package) v poli `package_password`:

```json
{
    "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](/api/v1/tracking).
- 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`.

## Š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).