# Importní soubor a seznam polí

Tato stránka popisuje, jak má vypadat soubor pro
[hromadný import objednávek](/integrations/hromadny-import-objednavek) a která pole v něm
můžete použít. Samotné nahrání souboru do Manažeru zásilek popisuje hlavní stránka návodu.

## Příprava importního souboru

Připravte soubor ve formátu **CSV, XLS, XLSX nebo ODS** (nejčastěji v Excelu
či jiném tabulkovém editoru) s informacemi o příjemcích, který poté nahrajete do administrace
[Zaslat.cz](https://www.zaslat.cz). Soubor si připravíte následovně:

- Do prvního řádku tabulky zadejte názvy polí (viz [Seznam možných polí](#seznam-možných-polí)
  níže). Do každé buňky zadejte jedno pole. Názvy pište přesně, malými písmeny.
- Každý další řádek je jedna zásilka.
- **Povinná pole** (v seznamu označená ✓) musíte vyplnit vždy, ostatní záleží na typu zásilky.
- Pořadí sloupců je libovolné. Sloupce s neznámým názvem import ignoruje, můžete si tedy
  v souboru nechat i vlastní poznámky.
- Takto připravenou tabulku uložte ve formátu **CSV, XLS, XLSX nebo ODS** — konkrétně v Excelu
  soubor uložíte jako **„CSV (textový soubor s oddělovači)“**.

:::caution[Na co si dát pozor v tabulkovém editoru]

- Telefonní čísla a PSČ ukládejte jako **text**, aby editor nesmazal úvodní znak `+` nebo nulu.
- Desetinná čísla v polích `packages`, `cod` a `ins` zadávejte **s tečkou** (`1.5`).
- Kódy dopravců v poli `carrier` pište **malými písmeny** (`ppl`), měny **velkými** (`CZK`).
- U souborů XLS, XLSX a ODS se načte pouze **první list**.

:::

## Seznam možných polí

V tabulce najdete všechna pole, která lze v importním souboru použít. **Povinná pole** jsou
označena ✓ ve sloupci Povinné; ostatní jsou volitelná podle typu zásilky.

| Pov. | Pole | Datový typ | Popis | Poznámka |
| :---: | --- | --- | --- | --- |
|  | `reference` | String | Váš identifikátor zásilky (např. číslo objednávky) | Doporučujeme vyplnit; podle reference zásilku v Manažeru zásilek dohledáte |
|  | `carrier` | Enum | Preference dopravce: `balikovna`, `dpd`, `fedex`, `gls`, `gls-sk`, `ppl`, `tnt`, `toptrans`, `ups`, `wedo`, `zasilkovna` | Malými písmeny. Omezí nabídku služeb na dopravce. Povinné spolu s `pickup_branch_code` a `delivery_branch_code` |
|  | `packages` | String | Balíky v zásilce oddělené lomítkem. Každý balík jako `hmotnost` nebo `hmotnost[šířka x výška x délka]` (hmotnost v kg, rozměry v cm) | Např. `1.5/3/3.5` (3 balíky) nebo `2.5[30x20x15]`. Minimální hmotnost 0,1 kg. Prázdné pole = výchozí balík integrace |
|  | `shipment_type` | Enum | Typ zásilky: `default`, `envelope`, `envelope_documents`, `tire`, `tire_disc`, `pallet` | Platí pro všechny balíky v řádku. Prázdné = běžný balík |
|  | `cod` | Float | Dobírka | Desetinná tečka |
|  | `cod_currency` | Enum `CZK` \| `EUR` | Měna dobírky | Prázdné = výchozí měna vašeho účtu (CZK na Zaslat.cz, EUR na Zaslat.sk) |
|  | `cod_variable` | Integer | Variabilní symbol dobírky |  |
|  | `cod_account_number` | String | Číslo účtu pro výplatu dobírky v CZK | Spolu s `cod_bank_code`. Prázdné = účet pro CZK z nastavení účtu |
|  | `cod_bank_code` | String | Kód banky k `cod_account_number` |  |
|  | `cod_iban` | String | IBAN pro výplatu dobírky v EUR | Prázdné = účet pro EUR z nastavení účtu |
|  | `ins` | Float | Připojištění (hodnota zásilky) | Desetinná tečka |
|  | `ins_currency` | Enum `CZK` \| `EUR` | Měna připojištění | Prázdné = výchozí měna vašeho účtu |
|  | `from_date` | Date `yyyy-mm-dd` | Datum vyzvednutí | U pravidelného svozu irelevantní |
|  | `from_address_id` | Integer | ID svozové adresy odesílatele | ID najdete v Manažeru zásilek v detailu svozové adresy ([Svozy → Svozové adresy](/mz/svozy#svozové-adresy)). Při zadání se ignorují pole `from_*` |
|  | `from_company` | String | Firma odesílatele | Při nezadání se převezme výchozí adresa \* |
|  | `from_firstname` | String | Jméno odesílatele | Při nezadání se převezme výchozí adresa \* |
|  | `from_surname` | String | Příjmení odesílatele | Při nezadání se převezme výchozí adresa \* |
|  | `from_street` | String | Ulice s číslem popisným | Při nezadání se převezme výchozí adresa \* |
|  | `from_city` | String | Město | Při nezadání se převezme výchozí adresa \* |
|  | `from_zip` | String | PSČ | Při nezadání se převezme výchozí adresa \* |
|  | `from_country` | Enum `CZ` \| `SK` \| … | ISO kód státu (2 znaky) | Při nezadání se převezme výchozí adresa \* |
|  | `from_email` | String | E-mail odesílatele pro oznámení o stavu přepravy | Při nezadání se převezme výchozí adresa \* |
|  | `from_phone` | String | Telefon odesílatele s předvolbou (+420xxxxxxxxx) | Při nezadání se převezme výchozí adresa \* |
|  | `to_address_id` | Integer | ID adresy příjemce z adresáře Zaslat.cz | Při zadání se ignorují pole `to_*` |
|  | `to_company` | String | Firma příjemce |  |
| ✓ | `to_firstname` | String | Jméno příjemce |  |
| ✓ | `to_surname` | String | Příjmení příjemce |  |
| ✓ | `to_street` | String | Ulice příjemce vč. čísla popisného | \*\* |
| ✓ | `to_city` | String | Město příjemce | \*\* |
| ✓ | `to_zip` | String | PSČ příjemce | \*\* |
| ✓ | `to_country` | Enum `CZ` \| `SK` \| … | ISO kód státu příjemce (2 znaky) |  |
| ✓ | `to_email` | String | E-mail příjemce pro oznámení o stavu přepravy | \*\* |
| ✓ | `to_phone` | String | Telefon příjemce s předvolbou (+420xxxxxxxxx) | Pro zahraničí vždy lokální telefonní číslo \*\* |
|  | `pickup_branch_code` | String | Kód podacího místa dopravce | Vyžaduje `carrier`. Viz [Podací a výdejní místo](/integrations/hromadny-import-objednavek/podaci-a-vydejni-misto) |
|  | `delivery_branch_code` | String | Kód výdejního místa dopravce | Vyžaduje `carrier` |
|  | `auto_delivery_branch_location` | Integer | `1` = doručit na nejbližší výdejní místo k adrese příjemce | Použije se, pokud není zadán `delivery_branch_code` |

<span className="text-muted-foreground">_\* Pokud jsou všechna pole `from_*` prázdná, použije se výchozí adresa odesílatele integrace, případně výchozí adresa odesílatele vašeho účtu._</span>

<span className="text-muted-foreground">_\*\* Kontrola souboru vyžaduje pole `to_street`, `to_city`, `to_zip`, `to_email` a `to_phone` (nebo `to_address_id`); bez nich se soubor nenahraje. Ostatní povinná pole doplníte nejpozději před objednáním v detailu zásilky._</span>

- Kódování souboru CSV: **UTF-8** (jiná kódování se import pokusí rozpoznat automaticky).
- Oddělovač: **středník** (`;`). Import rozpozná i čárku, tabulátor a svislou čáru; textové
  hodnoty mohou být v uvozovkách.
- Názvy polí v prvním řádku pište přesně podle tabulky, malými písmeny. Pořadí sloupců je
  libovolné, neznámé sloupce se ignorují.

## Vzorové importní soubory

Vzorové importní soubory si můžete stáhnout přímo v aplikaci — v dialogu **Nahrát zásilky**
v části **Vzorový soubor Zaslat.cz** (postup popisuje sekce
[Nahrání importního souboru](/integrations/hromadny-import-objednavek#nahrání-importního-souboru-do-zaslatcz)).
Jsou k dispozici ve formátech XLSX, ODS a CSV a obsahují správné názvy polí i ukázková data,
podle kterých si svůj soubor snadno připravíte. Hotové soubory pro konkrétní situace — zásilku
ze svozové adresy, z podacího místa na výdejní místo a zásilku se Zásilkovnou — najdete na
stránce [Příklady importních souborů](/integrations/hromadny-import-objednavek/priklady).