# Mapový widget v2.1

Mapový widget je mapa podacích a výdejních míst, kterou vložíte do své stránky, typicky do
košíku e-shopu v kroku výběru dopravy. Zákazník na jedné mapě vidí výdejní boxy a pobočky
všech podporovaných dopravců, vybere si místo jedním klepnutím a vaše aplikace dostane
vybrané místo zpět. Mapu načtete jedním skriptem; dopravce, jazyk, ceny i vzhled si
nastavíte podle svého.

Mapu si s vlastními parametry vyzkoušíte v interaktivní ukázce. Vložení skriptu,
konfiguraci a všechny možnosti mapy popisuje technická dokumentace na webu widgetu
(v angličtině).

<CardGrid>
  <LinkCard
    to="https://map.zaslat.cz/v2/1/configurable.html"
    icon="mouse-pointer-click"
    color="purple"
    title="Interaktivní ukázka"
    description="Nastavte parametry, otevřete mapu a vyzkoušejte si výběr místa přímo v prohlížeči."
  />
  <LinkCard
    to="https://map.zaslat.cz/v2/1/docs.html"
    icon="book-open-text"
    color="blue"
    title="Technická dokumentace"
    description="Vložení skriptu, konfigurace, možnosti otevření mapy a příklady kódu."
  />
</CardGrid>

Níže je náhled mapy: stejná mapa, jen bez tlačítka pro výběr místa. Tlačítkem v pravém
horním rohu ji otevřete přes celou stránku.

<MapV2Preview
  city="Brno"
  carriers={["gls", "gls-sk", "dpd", "zasilkovna", "balikovna", "ppl", "wedo"]}
/>

## Vložení do stránky

Celá integrace je jeden skript:

```html
<script type="module">
  import { ZaslatMap } from 'https://map.zaslat.cz/v2/1/sdk/main.js'

  const map = new ZaslatMap()
  const point = await map.open({ country: 'cz' })
</script>
```

Volání `open()` otevře mapu přes celou stránku a vrátí vybrané místo. Když zákazník mapu
zavře křížkem nebo klávesou Escape, vrátí `null`.

Mapa se nastavuje na dvou místech:

- **Konfigurace** (`config`) je argument `new ZaslatMap(config)`. Platí po celou dobu života
  mapy a říká, jak mapa u vás funguje: jazyk rozhraní, ceny výdeje u jednotlivých dopravců,
  případně vlastní vzhled dopravců.
- **Možnosti otevření** (`openOptions`) jsou argument `map.open(openOptions)`. Platí pro jedno
  otevření a říkají, co má mapa právě ukázat: zemi, povolené dopravce, jen boxy nebo jen
  pobočky, adresu, na které se mapa otevře, nebo dříve vybrané místo.

Obojí je nepovinné. Úplný výčet polí najdete v technické dokumentaci:
[konfigurace](https://map.zaslat.cz/v2/1/docs.html#config) a
[možnosti otevření](https://map.zaslat.cz/v2/1/docs.html#open-options).

## Jak zapadá do Zaslat

Vybrané místo se vrací jako objekt s kódem místa (`code`) a kódem dopravce
(`carrierCode`), spolu s názvem, adresou a souřadnicemi. Tyto dva údaje předáte při založení
zásilky přes [API v2](/api/v2/content): endpoint `cart/create` je přijímá v parametrech
`deliveryBranch` a `carrierCode`. Podací místo, kam odesílatel zásilku odnese, se předává
stejně v parametru `pickupBranch`. Popis endpointu je v [API Referenci v2](/api-v2/cart).

## Verze 2.1

Tato stránka popisuje **verzi 2.1**. Widget je verzovaný a číslo verze je součástí adresy,
ze které se skript načítá:

```
https://map.zaslat.cz/v2/1/sdk/main.js
```

Část `/v2/1/` znamená verzi 2.1. Opravy v rámci této verze vycházejí na stejné adrese, vaše
integrace je tedy dostává bez zásahu do kódu. Každá další vedlejší verze má vlastní adresu,
takže integrace zůstává na verzi, na kterou odkazuje, dokud adresu sami nezměníte.