Antikvariát

Marcel Goliaš

Přihlášení / Registrace

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

      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:

    12346789101213
         ČísloJménoPříjmeníE-mailTelefonDobírkaMěnaHodnotaVýdejní místoOdesílatel
    1202102335PetrKratochvílpetr.kratochvil@seznam.cz+420123456739CZK650578golias.net
    1202104029JanaNovákovájana.novakova@seznam.cz+4206543210CZK3004517golias.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:


Warning: mysqli_fetch_array() expects parameter 1 to be mysqli_result, bool given in /data/www/golias.net/www.golias.net/antikvariat/inc/export.php on line 7
  1. Klepněte na tlačítko „Export“
  2. Vyexportovaný soubor si uložte na pevný disk (a zapamatujte si kam)

Vytvoření vlastní importní šablony v systému zásilkovny:

  1. Přejděte na stránky zásilkovny do sekce Import zásilek > Šablony
  2. Klepněte na tlačítko „Vytvořit novou šablonu“
  3. Klepněte na tlačítko „Vybrat…“, vyberte CSV soubor, který jste si právě vygenerovali, a poté klepněte na tlačítko „Nahrát“
  4. Do pole „Název šablony“ zadejte libovolný název Vaší nové šablony (kterou budete odteď používat)
  5. Do pole „Počet vynechaných řádků“ nic nepište
  6. V tabulce s Vašimi načtenými zásilkami upravte záhlaví tak, aby odpovídalo tomu, co máte v jednotlivých sloupcích:

          Upravte záhlaví v tabulce tak, aby odpovídalo následujícím hodnotám: Číslo, Jméno, Příjmení, E-mail, Telefon, Dobírka, Měna, Hodnota, Kód, Odesílatel
  7. Klepněte na tlačítko „Uložit šablonu“

Import zásilek do systému zásilkovny:

  1. Přejděte do sekce Import zásilek > Importovat soubor zásilek
  2. Klepněte na tlačítko „Vybrat…“, vyberte Váš CSV soubor, z rozbalovací nabídky „Šablona“ vyberte svoji novou šablonu, zaškrtněte políčko „Souhlasím s VOP“, a pak klepněte na tlačítko „Nahrát“ (viz obrázek)

          Nahrajte svůj CSV soubor do systému zásilkovny

Kontrola naimportovaných zásilek:

  1. Po úspěšném nahrání Vašich zásilek do systému se automaticky přesunete do sekce Rozpracované zásilky, kde uvidíte přehlednou tabulku s Vašimi nově naimportovanými zásilkami (viz obrázek)

          Tabulka s nově naimportovanými (rozpracovanými) zásilkami
  2. Zásilky zkontrolujte a případně opravte.
  3. Poté zásilky označte (zatrhněte), z rozbalovací nabídky nad tabulkou vyberte příkaz „Podat vybrané“, a poté klepnutím na tlačítko „Provést“ zásilky podejte.
  4. Podané zásilky si můžete zobrazit v sekci Podané zásilky
  5. Dokud zásilky fyzicky nepodáte na některém výdejním místě nebo depu, můžete je zde ještě v případě potřeby stornovat

Tisk štítků

TISK ŠTÍTKŮ
  - Lze provádět:
  --- buď manuálně na stránkách zásilkovny v sekci „Podané zásilky“ (client.packeta.com/list)
  --- nebo automatizovaně (což se ale pro malý e-shop asi nevyplatí programovat/řešit)
          

Postup pro vygenerování štítků v systému zásilkovny:

  1. Přejděte do sekce Podané zásilky
  2. Všechny nově podané zásilky označte
  3. V poli „Hromadné akce“ vyberte vhodný formát štítků a klepnutím na tlačítko „Provést“ si štítky vyexportujte do souboru PDF
  4. Soubor PDF si vytiskněte (příp. uložte pro pozdější tisk)
  5. Štítky nalepte na zásilky
  6. Zásilky odneste na výdejní místo zásilkovny

HOTOVO

Marcel Goliaš © 2021