Jak implementovat zásilkovnu
do svého e-shopu
(2021)

Výhody zásilkovny: Zásilkovna je dopravní společnost, která nabízí e-shopům jeden z nejlevnějších způsobů dopravy zásilek na českém trhu a zároveň jednu z nejširších poboček výdejních míst (k dubnu 2021 byl jejich počet přes 6.500). Implementace modulu zásilkovny do e-shopu je poměrně jednoduchá (nejsložitější na tom je prokousat se zdrojovou dokumentací) a měl by ji zvládnout i méně zkušený programátor.

Registrace

V první řadě je potřeba se na webu zásilkovny zaregistrovat. Registrace probíhá tak, že si nejprve vyberete typ svého účtu (= Internetový obchod), a poté vyplníte název účtu (= obvykle název Vašeho e-shopu), e-mail, heslo a telefon. Po registraci Vám přijde uvítací e-mail, který Vás poinformuje o tom, že proces schvalování můžete urychlit, když po přihlášení do svého účtu (který je aktivní ihned po Vaší registraci) vyplníte v sekci Informace o uživateli všechny povinné údaje:

kontakty (jméno, telefon, e-mail)
fakturační adresy (název, IČO, číslo účtu, výdejní místo pro vratky atd.)
odesílatele (označení odesílatele, které zde zvolíte, se pak musí shodovat s označením, které budete používat v datovém souboru se zásilkami)

Dokud tyto údaje nevyplníte, registrace nebude schválena. Schvalovací proces trvá maximálně 3 pracovní dny (obvykle ale výrazně méně).

Přihlášení

Do webového rozhraní zásilkovny pro e-shopy se přihlásíte na adrese client.packeta.com po zadání svého e-mailu a hesla. Po schválení registrace můžete začít zásilkovnu používat naplno (tj. včetně podávání zásilek).

Klientská sekce Zásilkovny

Ceník

Samotné využívání služeb zásilkovny (vč. používání jejich webového widgetu) není nijak zpoplatněno. Jediné, za co se platí, je doprava zásilek. Aktuální ceník dopravy zásilek najdete v klientské sekci v oddíle Ceník.

CENÍK (4/2021):
  - zásilka do 5 kg [max. rozměry součet: 120 cm, max. rozměr nejdelší strany: 70 cm] = 47 Kč (bez DPH) = 57 Kč (vč. DPH)
  - zásilka do 10 kg = 128 Kč bez DPH = 155 Kč vč. DPH
  --- příplatek za platbu dobírky kartou = 1,40%
  --- příplatek za dobírku = 12 Kč (bez DPH) = 15 Kč (vč. DPH)

Implementace zásilkovny do e-shopu

VLASTNÍ INTEGRACE „Packeta API“ DO E-SHOPU:
  Modul pro výběr výdejního místa
    - Lze provést:
    --- buď pomocí speciálního widgetu (ideální pro menší e-shopy) → tuto možnost zde níže popisuji
    --- nebo pomocí vlastní aplikace s využitím „XML/JSON branch feed“
        (vyžaduje složitější programování a hodí se spíše pro e-shopy, které využívají vlastní seznam dopravců)

Widget v praxi:

Takto nějak může vypadat widget zásilkovny na Vašich stránkách (tj. ve Vašem košíku):

Vybraná pobočka:

Žádná

HTML kód:

Minimálně tento HTML kód (v kombinaci s JavaScript) je k tomu zapotřebí:

<!DOCTYPE html>
<html lang="cs">

<head>
  <meta charset="utf-8">
  <script src="https://widget.packeta.com/v6/www/js/library.js"></script>
</head>

<body>

<input type="button" class="packeta-selector-open" value="Vyberte pobočku...">
<table style="padding-top:.5em;">
  <tr>
    <td>Vybraná pobočka:</td>
    <td>
      <input type="hidden" id="packeta-point-id" class="packeta-selector-branch-id">
      <span id="packeta-point-info" class="packeta-selector-branch-name">Žádná</span>
    </td>
  </tr>
</table>

<script>
  var packetaSelectorOpen = '.packeta-selector-open';
  var packetaSelectorBranchName = '.packeta-selector-branch-name';
  var packetaSelectorBranchId = '.packeta-selector-branch-id';
  var packetaCountry = 'cz';
  var packetaWidgetLanguage = 'cs';
  var packetaPrimaryButtonColor = '#39b54a';
  var packetaBackgroundColor = '#ffffff';
  var packetaFontColor = '#555555';
  var packetaFontFamily = 'Arial';
</script>
<script src="https://widget.packeta.com/v6/www/js/packetaWidget.js" data-api-key="vás-vlastní-api-klíč"></script>

</body> 
</html>

Komentář k výše uvedenému kódu:

Do záhlaví dokumentu (tj. mezi tagy "head") je třeba vložit odkaz na skript "library.js" (ke stažení zde).
Do těla stránek (tj. mezi tagy "body") je třeba vložit kód pro zobrazení tlačítka pro výběr výdejního místa (<input type="button"…>) následovaný tabulkou (<table>…</table>), uvnitř které se nám bude vypisovat název vybraného výdejního místa, a skrytě i jeho kód (<input type="hidden" id="packeta-point-it"…>), který je pro nás nejdůležitější.

Poté, co uživatel vybere konkrétní výdejní místo, se do tagu (<input type="hidden" id="packeta-point-it"…>) vepíše kód vybraného výdejního místa v podobě nové hodnoty atributu "value":

<input type="hidden" id="packeta-point-id" class="packeta-selector-branch-id" value="578">

Tuto hodnotu (= kód vybraného výdejního místa) je pak třeba si uložit do databáze spolu s dalšími údaji z objednávkového formuláře (jako jsou jméno a příjmení uživatele, adresa, e-mail, telefon apod.). Dalším krokem pak bude vytvoření exportního skriptu, který nám bude z databáze generovat CSV soubor (ve formátu předepsaném zásilkovnou), pomocí něhož si pak můžeme významně usnadnit vkládání nových zásilek do systému zásilkovny.
Nakonec je třeba do těla stránek (před koncový tag "body") vložit ještě dva skripty:
1. Řádkový skript, v němž se definují jednak prvky, do nichž se nám budou vepisovat získané údaje (packetaSelector…), a jednak samotný vzhled widgetu zásilkovny (Country, Language, Color, Font).
2. Odkaz na skript "packetaWidget.js" (ke stažení zde), do něhož je třeba vepsat Váš vlastní „Klíč API“ (který najdete v klientské sekci v oddíle Klientská podpora).
  Správně pak tedy bude ten odkaz vypadat nějak takhle:
  
  <script src="js/packetaWidget.js" data-api-key="abcdef0123456789"></script>
  
  „Klíč API“ → viz kód v červeném rámečku, na nějž ukazuje žlutá šipka (uvedené kódy jsou smyšlené/nefunkční)
  Poznámka ke skriptu "packetaWidget.js":
  
  Zjistil jsem, že v některých případech může být text v okně widgetu pro výběr výdejních míst rozmazaný. Nepodařilo se mi sice přijít na to, čím je to způsobené, ale přišel jsem alespoň na to, že když upravím ve skriptu výšku rámce (v oddíle function addStylesToIframeWrap) a místo výchozí hodnoty "100%" zadám nějaký konkrétní rozměr (např. "650px"), rozmazání textu zmizí.
```
function addStylesToIframeWrap() {
    var iframeWrap = document.getElementById(idIframeWrap);

    var styles = {
        'border': 'none',
        'width': '100%',   // Zde je možné nastavit šířku rámce (iframe)
        'height': '650px', // Zde je možné nastavit výšku rámce (iframe)
                           // => Zjistil jsem, že pokud zde ponechám výchozí hodnotu (= 100%), tak je text v rámci rozmazaný !
        'max-width': '1000px',
        'position': 'fixed',
        'z-index': '999999',
        'left': '50%',
        'top': '50%',
        'transform': 'translate(-50%, -50%)',
        'background': 'transparent'
    };

    applyStyles(iframeWrap, styles);
}
```

Import zásilek

IMPORT DAT (zásilek)
  - Lze porovádět:
  --- buď manuálně:
  ------ a) vyplněním dat o zásilce přímo na stránkách zásilkovny v sekci „Podat zásilku“ (client.packeta.com/packet-drafts)
  ------ b) nahráním CSV [příp. XML] souboru na stránkách zásilkovny v sekci „Import zásilek“ (client.packeta.com/upload) → tuto možnost zde blíže popíšu
  --- nebo automatizovaně přes API

Hlavní PHP skript pro vygenerování CSV souboru z MySQL databáze:

Abyste mohli importovat zásilky do systému zásilkovny, potřebujete si nejprve vytvořit PHP skript, který vám z Vaší MySQL databáze (kam si ukládáte objednávky uživatelů) vygeneruje CSV soubor se seznamem zásilek pro zásilkovnu. Tento skript může vypadat třeba nějak takhle:

Poznámka: Jeho název může být libovolný, musí to však být soubor s příponou PHP (jinak to nebude fungovat).

<!DOCTYPE html>
<html lang="cs">

<head>
  <meta charset="utf-8">
</head>

<body>

  <form method='post' action='export-2.php'>
    <?php
    // Přihlašovací údaje k přihlášení k MySQL databázi:
    $dbhost = 'váš-host';
    $dbuser = 'vaše-uživatelské-jméno';
    $dbpass = 'vaše-heslo';
    $db = 'název-vaší-databáze';
    $dbc = mysqli_connect($dbhost, $dbuser, $dbpass, $db) or die($dbc);
    mysqli_set_charset($dbc,"utf8");

    $query = "SELECT * FROM `název-vaší-tabulky`";
    $result = mysqli_query($dbc,$query);
    $user_arr = array();
    while($row = mysqli_fetch_array($result)){
      // V tabulce objednávek mám následující sloupce: cislo, jmeno, prijmeni, email, telefon, cena_dobirka, cena_knihy, cena_celkem, zasilkovna
      // (ve sloupci "cislo" mám uložen variabilní symbol objednávky, ve sloupci "zasilkovna" je uložen kód výdejního místa)
      $empty = "";
      $cislo_obj = $row["cislo"];          // Číslo objednávky z e-shopu (což může být např. variabilní symbol)
      $jmeno = $row["jmeno"];              // Jméno příjemce
      $prijmeni = $row["prijmeni"];        // Příjmení příjemce
      $email = $row["email"];              // E-mail příjemce
      $telefon = "+420$row[telefon]";      // Telefon příjemce ve formátu +420xxxxxxxxx
      if($row["cena_dobirka"] > 0) { $doberecne = $row["cena_celkem"]; }
      else { $doberecne = 0; }             // Doběrečné (= částka, kterou má zaplatit příjemce zásilky; pokud zásilku uhradil předem na účet, doběrečné = 0)
      $mena = "CZK";
      $cena_knihy = $row["cena_knihy"];
      $hodnota = round($cena_knihy/50)*50; // Hodnota zásilky v celých Kč (zaokrouhleno nahoru na nejbližší násobek 50-ti)
      $vydejni_misto = $row["zasilkovna"]; // Kód výdejního místa zásilkovny
      $odesilatel = "golias.net";          // Označení odesílatele
                                           // => POZOR: Název se musí shodovat s tím, jak jste se pojmenovali (= hodnotou pole "Označení") 
                                           // na stránkách https://client.packeta.com/cs/senders/ v sekci "Informace o uživateli > Odesílatelé" !
      $user_arr[] = array($empty,$cislo_obj,$jmeno,$prijmeni,$email,$telefon,$doberecne,$mena,$hodnota,$vydejni_misto,$odesilatel);
    }
    ?>
    <input type='submit' value='Export' name='Export'>
    <?php
    $serialize_user_arr = serialize($user_arr);
    ?>
    <textarea name='export_data' style='display: none;'><?php echo $serialize_user_arr; ?></textarea>
  </form>

</body> 
</html>

Vedlejší skript pro vygenerování CSV souboru:

Po klepnutí na tlačítko "Export" se spustí další (pomocný) skript s názvem "export-2.php", který nám vygeneruje požadovaný CSV soubor:

<?php
  $filename = 'zasilkovna.csv';
  $export_data = unserialize($_POST['export_data']);
  $file = fopen($filename,"w");
  foreach ($export_data as $line){
    fputcsv($file,$line);
  }
  fclose($file);
  header("Content-Description: File Transfer");
  header("Content-Disposition: attachment; filename=".$filename);
  header("Content-Type: application/csv;"); 
  readfile($filename);
  unlink($filename);
  exit();
?>

Komentář k výše uvedeným skriptům:

První skript:

Nejprve je třeba vložit kód pro připojení k databázi. Zde si musíte doplnit vlastní údaje o svém hostiteli (obvykle mívá formát "mysql.domena.cz"), uživatelském jménu, heslu a názvu vaší hlavní databáze.
Poté je třeba upravit samotný SQL dotaz ("$query") tak, aby vám vracel seznam všech objednávek, u nichž byla vybrána doprava přes zásilkovnu. Máte-li např. ve své tabulce sloupec "zasilkovna", do něhož ukládáte kód výdejního místa, pak může správný dotaz vypadat třeba následovně:
$query = "SELECT * FROM `tabulka-objednavek` WHERE zasilkovna NOT LIKE ''";

Pomocí smyčky "while" pak projdeme jednotlivé objednávky, které splňují zadané parametry, připravíme si je do formátu, který vyžaduje zásilkovna, a uložíme si je do nových proměnných.

Pro úspěšný import zásilek do jejich systému vyžaduje zásilkovna CSV soubor v následujícím formátu:

Obecná struktura:


                    ,Číslo,Jméno,Příjmení,E-mail,Telefon,Dobírka,Měna,Hodnota,Kód,Odesílatel

Praktický příklad:

Takovouto podobu musí mít data ve výsledném CSV souboru:


                    ,1202102335,Petr,Kratochvíl,petr.kratochvil@seznam.cz,+420123456,739,CZK,650,578,golias.net
                    ,1202104029,Jana,Nováková,jana.novakova@seznam.cz,+420654321,0,CZK,300,4517,golias.net

Vysvětlivky:


                    
                      1 2 3 4 6 7 8 9 10 12 13
                            Číslo Jméno Příjmení E-mail Telefon Dobírka Měna Hodnota Výdejní místo Odesílatel
                      1202102335 Petr Kratochvíl petr.kratochvil@seznam.cz +420123456 739 CZK 650 578 golias.net
                      1202104029 Jana Nováková jana.novakova@seznam.cz +420654321 0 CZK 300 4517 golias.net

Sloupce:                                                                                                                                                            
 1) prázdný
 2) číslo objednávky (4-24 znaků) => povinné pole
 3) jméno příjemce (max. 32 znaků) => povinné pole
 4) příjmení příjemce (max. 32 znaků) => povinné pole
 5) firma příjemce (max. 32 znaků)
 6) email příjemce (platný email) => povinné, pokud není uveden telefon
 7) telefon příjemce (platné tel.číslo) => povinné, pokud není uveden email
 8) dobírka (pouze celá čísla, bez desetinných míst)
 9) měna (kód dle ISO 4217; je-li ponecháno prázdné, použije se kód cílové země)
10) hodnota zásilky (stejná pravidla jako pro dobírku) => povinné pole
11) váha (v kg)
12) výdejní místo (jedinečné ID výdejního místa) => povinné pole
13) označení odesílatele (max. 64 znaků) => povinné jen v případě, že zásilku odesíláte za více odesílatelů najednou
14) obsah jen pro dospělé (může mít hodnotu 0 nebo 1)
15) odložené dodání (datum ve tvaru d.m.Y; max. 14 dní ode dneška; odloží dodání zásilky tak, že zásilka není dodána před daným datem)
16) ulice (max. 32 znaků) => povinné, pokud je vybráno doručení na adresu
17) číslo popisné (max. 16 znaků) => povinné, pokud je vybráno doručení na adresu
18) město (max. 32 znaků) => povinné, pokud je vybráno doručení na adresu
19) PSČ (platné PSČ) => povinné, pokud je vybráno doručení na adresu
20) výdejní místo dopravce (jedinečné ID výdejního místa dopravce) => povinné, pokud to vyžaduje dopravce
21) šířka zásilky (v mm) => povinné, pokud to vyžaduje dopravce
22) výška zásilky (v mm) => povinné, pokud to vyžaduje dopravce
23) délka zásilky (v mm) => povinné, pokud to vyžaduje dopravce
24) poznámka odesílatele (max. 128 znaků, dopravce ji může omezit na 32 znaků)

Vybrané proměnné vložíme do pole "user_arr", které pak pomocí funkce "serialize" převedeme na textový řetězec.
Převedený řetězec dat (= zásilek) vložíme do skrytého pole "textarea", jehož obsah se nám po odeslání formuláře přehraje do druhého skriptu.

Druhý skript:

Ve druhém skriptu si nejprve definujeme název výstupního souboru (= jak se bude náš výstupní CSV soubor jmenovat).
Poté si textový řetězec dat z prvního skriptu znovu načteme do pole pomocí funkce "unserialize".
Pomocí funkce "fopen" si otevřeme nový soubor.
Pomocí funkce "foreach" si obsah pole převedeme na řádky, které uložíme do otevřeného souboru.
Pomocí funkce "fclose" soubor zavřeme.
Vyvoláme nové záhlaví dokumentu, čímž přinutíme prohlížeč, aby nám umožnil si nový soubor stáhnout.
Pomocí funkce "readfile" provedeme zapsání připraveného obsahu do nového souboru.
Pomocí funkce "unlink" soubor vymažeme z mezipaměti.

Skript pro vygenerování CSV souboru v praxi:

1	2	3	4	6	7	8	9	10	12	13
	Číslo	Jméno	Příjmení	E-mail	Telefon	Dobírka	Měna	Hodnota	Výdejní místo	Odesílatel
	1202102335	Petr	Kratochvíl	petr.kratochvil@seznam.cz	+420123456	739	CZK	650	578	golias.net
	1202104029	Jana	Nováková	jana.novakova@seznam.cz	+420654321	0	CZK	300	4517	golias.net

Antikvariát Goliaš