> ## Documentation Index
> Fetch the complete documentation index at: https://api.basetools.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# Přepravní štítky a čísla zásilek

> createPackageManual vs. createPackage + getOrderPackages + getLabel, a jak čísla zásilek putují zpět do zdroje objednávky

Běžný požadavek: dostat přepravní (trackovací) číslo zásilky do Base, aby ho Base mohlo předat zpátky zdroji objednávky (marketplace, e-shop). Existují dva základní přístupy a v praxi se často kombinují.

## Přístup A — vlastní přepravní integrace, do Base jen zapsat číslo

Pokud štítek vytváříte mimo Base (vlastní napojení na GLS, DPD, ČP apod. ve vašem WMS), do Base jen zapíšete hotové trackovací číslo metodou [`createPackageManual`](https://api.baselinker.com/index.php?method=createPackageManual).

| Parametr          | Typ         | Popis                                                                                                                                |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `order_id`        | int         | ID objednávky v Base.                                                                                                                |
| `courier_code`    | varchar(20) | Kód dopravce ze seznamu [`getCouriersList`](https://api.baselinker.com/index.php?method=getCouriersList), nebo vlastní název kurýra. |
| `package_number`  | varchar(40) | Trackovací (přepravní) číslo zásilky.                                                                                                |
| `pickup_date`     | int (unix)  | Datum odeslání.                                                                                                                      |
| `return_shipment` | bool        | Nepovinné, výchozí `false`. Označí zásilku jako vratkovou.                                                                           |

```json theme={null}
{
  "order_id": 6910995,
  "courier_code": "dhl",
  "package_number": "622222044730624327700197",
  "pickup_date": 1487006161,
  "return_shipment": false
}
```

`courier_code` je důležitý i v tomto scénáři — díky němu Base ví, jakého dopravce jste použili, a může tuto informaci správně předat marketplace.

## Přístup B — přepravní integrace přímo v Base

Používá se nejčastěji u kanálů s vlastní dopravou typu Allegro (Wysyłam z Allegro) nebo Alza Shipping. Předpokladem je mít danou přepravní integraci v Base připojenou a nakonfigurovanou. Pak potřebujete tři metody:

1. [`createPackage`](https://api.baselinker.com/index.php?method=createPackage) — vytvoří samotný štítek u dopravce.
2. [`getOrderPackages`](https://api.baselinker.com/index.php?method=getOrderPackages) — načte ID jednotlivých štítků k objednávce. Potřeba jen u vícekusových zásilek; u jednokusové dostanete ID rovnou v odpovědi `createPackage`.
3. [`getLabel`](https://api.baselinker.com/index.php?method=getLabel) — stáhne samotný štítek (base64, formát PDF/ZPL/EPL/DPL/HTML/GIF dle nastavení dopravce v Base).

### createPackage — parametry

| Parametr       | Typ         | Popis                                                                                                                                                                                                                |
| -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id`     | int         | ID objednávky.                                                                                                                                                                                                       |
| `courier_code` | varchar(20) | Kód dopravce. Pro Allegro dopravu vždy `"allegrokurier"`.                                                                                                                                                            |
| `account_id`   | int         | Nepovinné. ID konkrétního přepravního účtu ([`getCourierAccounts`](https://api.baselinker.com/index.php?method=getCourierAccounts)); pokud nevyplníte, použije se první nalezený.                                    |
| `fields`       | array       | Formulářová pole konkrétního dopravce ([`getCourierFields`](https://api.baselinker.com/index.php?method=getCourierFields) / [`getCourierServices`](https://api.baselinker.com/index.php?method=getCourierServices)). |
| `packages`     | array       | Rozměry (cm) a hmotnost (kg) balíku/balíků. Pro více balíků přidejte další objekt do pole.                                                                                                                           |

```json theme={null}
{
  "order_id": 123456789,
  "courier_code": "allegrokurier",
  "account_id": 12123,
  "return_shipment": false,
  "fields": [
    { "id": "courier", "value": "detect" },
    { "id": "insurance", "value": "276.76" },
    { "id": "package_type", "value": "PACKAGE" }
  ],
  "packages": [
    { "length": 20, "height": 10, "width": 30, "weight": 3 }
  ]
}
```

<Warning>
  Pokud je zásilka na dobírku, musíte do `fields` přidat i `{"id": "cod", "value": "123.40"}` — pozor na desetinnou **tečku**, ne čárku.
</Warning>

Odpověď obsahuje `package_id`, `package_number` (trackovací číslo) a `courier_inner_number`.

### getOrderPackages a getLabel

```json title="getOrderPackages" theme={null}
{ "order_id": "12345678" }
```

```json title="getLabel" theme={null}
{
  "courier_code": "allegrokurier",
  "package_id": 12345678
}
```

`getLabel` přijímá buď `package_id`, nebo `package_number` — stačí jedno z toho. V odpovědi je `extension` (pdf/html/gif/png/epl/zpl/dpl) a `label` jako base64.

## Jak se číslo zásilky dostane zpátky do zdroje objednávky

Podle nastavení konkrétní integrace v Base se trackovací číslo předá zdroji objednávky buď:

* okamžitě po přidání čísla, nebo
* při přepnutí objednávky do konkrétního statusu — pozor, přenos neprobíhá instantně, ale v dávkách, typicky kolem 9:00, 10:00, 13:00, 16:00 a 23:00 (± pár minut). U Alza integrace navíc hraje roli nastavení uzávěrky (COT — cut-off time).

## Mazání zásilky

Vytvořenou zásilku lze smazat metodou `deleteCourierPackage`. U Alza integrace ale platí přísné pravidlo: pokud už byl štítek odeslaný do Alzy (proběhl tzv. Shipment Departure), **zásilku už nikdy nemažte** — místo toho nastavte objednávce status Zamítnuto (viz [Statusy](/cs/objednavky/statusy#stornované-objednávky)). Mazání je bezpečné jen dokud štítek ještě nebyl do marketplace odeslán.

<Tip>
  V praxi se oba přístupy často kombinují — vlastní integrace na standardní kurýry (GLS, DPD, PPL...) a Base integrace na marketplace-specifickou dopravu (Alza, Allegro).
</Tip>