Jak integrovat službu Pickup

Služba Pickup umožňuje doručení do jednoho z výdejních míst, které si příjemce zásilky vybere podle svého přání. Aby si zákazníci vašeho e-shopu mohli zvolit konkrétní Pickup, je potřeba integrovat nástroj pro vyhledávání. Nabízíme vám několik možností, jak nástroj pro vyhledávání výdejních míst přidat do formuláře vašeho e-shopu.

Možnosti integrace

Implementace DPD widgetu do vašeho e-shopu (doporučujeme)

Následující informace jsou technického charakteru a slouží především pro vaše IT oddělení, příp. správce vašeho e-shopu.

Demo aplikaci našeho widgetu výdejních míst naleznete zde:

https://api.dpd.cz/widget/latest/demo.html

Případně raw verze:

https://api.dpd.cz/widget/latest/index.html

Jak implementovat widget

Pro zobrazení widgetu na vašem webu vložte do kódu iframe s adresou: https://api.dpd.cz/widget/latest/index.html

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html"
  ></iframe>

Pro získání uživatelem vybraného výdejního místa, vložte do kódu input (ideálně skrytý) s id: DPDPickupPointResult, kam se při výběru výdejního místa vypíše ID výdejního místa a jeho celá adresa.

  <input id="DPDPickupPointResult" type="hidden"/>
  
  // tento kod vložte k inputu nebo do hlavičky () webu
  window.addEventListener("message", (event) => {
    if(event.data.dpdWidget) {
      document.getElementById("DPDPickupPointResult").value = event.data.dpdWidget.pickupPointResult
    } 
  }, false);

Pro složitější implementaci lze případně poslouchat na event (message) na objektu document, který vrátí v event.data.dpdWidget kompletní objekt výdejního místa:

  window.addEventListener("message", (event) => {
    if(event.data.dpdWidget) {
      console.log(event.data.dpdWidget);
    }
  }, false);

Pokud chcete mít možnost zavírat widget, tak se také posílá event (message) o kliknutí na křížek (pokud se uživatel bude snažit widget zavřít), zde je potřeba rozlišit že se jedná o správnou message pomocí (event.data.dpdWidget.message === “widgetClose”):

  window.addEventListener("message", (event) => {
    if(event.data.dpdWidget && event.data.dpdWidget.message === "widgetClose") {
      console.log("DPD pickup point widget is closed")
    } 
  }, false);

Pro zobrazení widgetu bez křížku vpravo nahoře, je potřeba nastavit query parametr hideCloseButton na true

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?hideCloseButton=true"
  ></iframe>

Pro zobrazení widgetu pouze s výdejními místy bez DPD boxů, je potřeba nastavit query parametr disableLockers na true

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?disableLockers=true"
  ></iframe>

Pro přednastavení některé z dostupných zemí použijte parametr ?countries= například

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?countries=SK"
  ></iframe>

Další způsoby integrace

Upozornění:

Naši síť jsme rozšířili o zahraniční výdejní místa. Aktuálně je zakázáno na zahraniční výdejní místa posílat zásilky s dobírkou. Dodržte prosím toto omezení. Pokud si zákazník vybere zahraniční výdejní místo, nepovolte mu vybrat možnost platby dobírkou. Všechny výstupy metod jsou nyní rozšířené o pole cod_allowed, kterým si můžete ověřit, zda je povolena možnost zaslání zásilky s dobírkou či nikoliv.

  • cod_allowed = 0 – dobírka je zakázána
  • cod_allowed = 1 – dobírka je povolena

Metodám, které slouží přímo k integraci do objednávkového formuláře jsme přidali parametr crossboarder. Tento parametr slouží pro omezení zobrazení výdejních míst následovně:

  • Parametr nepoužit – výsledek metod je omezen pouze na výdejní místa v České republice
  • crossboarder = 0 - výsledek metod je omezen pouze na výdejní místa v České republice
  • crossboarder = 1 - výsledek metod není omezen umístěním výdejního místa

Platné pro metody:

DPD Box

Pro zobrazení DPD boxů slouží následující parametr.

  • Parametr nepoužit – zobrazení výdejních míst Pickup i DPD boxů
  • dpd_box = 1 - zobrazí pouze DPD Boxy
  • dpd_box = 0 - zobrazí pouze výdejní místa Pickup

Ostatní Parametry

Níže uvedené parametry jsou použitelné u všech integračních metod a mají stejné použití i v případě přidání parametru do URL mapy [pickup.dpd.cz]

  • return_allowed = 0 – Vrácení balíku/RETURN zakázán
  • return_allowed = 1 – Vrácení balíku/RETURN povolen

  • dropoff_allowed = 0 - Podej balíku zakázán
  • dropoff_allowed = 1 - Podej balíku povolen

  • cardpayment_allowed = 0 – Platba dobírky kartou zakázána
  • cardpayment_allowed = 1 – Platba dobírky kartou povolena

  • openweekend_allowed = 0 – otevřeno o víkendu
  • openweekend_allowed = 1 – zavřeno o víkendu

- Použití přesměrování

Váš košík (objednávkový formulář) může přesměrovat zákazníka na https://pickup.dpd.cz/?address=Město, ulice, PSČ&return=https://example.com/objednavka, kde si může vybrat nejbližší výdejní místo. Po výběru místa bude zákazník přesměrován zpět na váš eshop. V POST parametrech jsou předány následující parametry podle toho, které výdejní místo si zákazník vybral.

parcelshop_id
ID vybraného výdejního místa, více informací lze získat pomocí API.
parcelshop_name
Jméno výdejního místa.
parcelshop_address
Adresa výdejního místa.
parcelshop_cod_allowed
Povolení / zakázání dobírky
parcelshop_cod_allowed = 1 – dobírka povolena
parcelshop_cod_allowed = 0 – dobírka zakázána

Pokud chcete mít možnost zobrazit i zahraniční výdejní místa a zároveň jste implementovali omezení na dobírku dle pole cod_allowed, pak nastavte parametr crossboarder = 1.

https://pickup.dpd.cz/api/get-parcel-shops-by-address?address=Mesto%2C+Ulice%2C+PSC&return=https%3A%2F%2Fexample.com%2Fobjednavka&crossboarder=1

- Použití Web service

Další varianta je pomocí Web service. Služba nabízí několik metod na její využití. Ukázku vlastní integrace v PHP lze stáhnout zde.

Pokud preferujete výstup metod v angličtině, tak využijte parametr lang=en

Parametr lang nepoužit – výstup metod bude v češtině
lang = eng - výstup metod bude v angličtině

například: https://pickup.dpd.cz/api/get-countries?lang=en

Pro získání seznamu zahraničních výdejních míst je nutné získat seznam dostupných zemí pomocí této metody.

{
  'status': [pokud se vše povedlo, hodnota je 'ok', jinak 'error'],
  'code': [návratový kód, 200 = ok, 1001 = neznámá adresa],
  'count': [počet vrácených zemí],
  'data': {
    'items': [list všech zemí]
  }
}

Ve výstupu je důležité pole id (ISO 3166-1 numeric), které umožňuje získat seznam zahraničních výdejních míst. pokud je hodnota pole id použita v parametru country v následujících metodách.

https://pickup.dpd.cz/api/get-all?country=203

Na této adrese lze stáhnout všechna výdejní místa. Vrácená data jsou ve formátu JSON. Bez uvedení parametru country se stáhne pouze seznam výdejních míst v České republice.

{
  'status': [pokud se vše povedlo, hodnota je 'ok', jinak 'error'],
  'code': [návratový kód, 200 = ok],
  'count': [počet vrácených výdejních míst],
  'hash': [stejná výdejní místa ve stejném pořadí mají stejný hash],
  'data': {
    'items': [list všech výdejních míst]
  }
}

https://pickup.dpd.cz/api/get-parcel-shop-by-id?id=CZ10190

Další možností je stažení jednoho konkrétního výdejního místa podle jeho ID.

{
  'status': [pokud se vše povedlo, hodnota je 'ok', jinak 'error'],
  'code': [návratový kód, 200 = ok, 404 = id nebylo nalezeno],
  'count': 1,
  'data': { [data výdejního místa] }
}

https://pickup.dpd.cz/api/get-parcel-shops-by-address?address=Mesto%2C+Ulice%2C+PSC&limit=5&crossboarder=0

Na této adrese lze stáhnout několik nejbližších výdejních míst podle adresy. Jejich počet lze změnit pomocí parametru limit. Maximální počet je 100.

Pokud chcete mít možnost zobrazit i zahraniční výdejní místa a zároveň jste implementovali omezení na dobírku dle pole cod_allowed, nastavte si parametr crossboarder = 1.

{
  'status': [pokud se vše povedlo, hodnota je 'ok', jinak 'error'],
  'code': [návratový kód, 200 = ok, 1001 = neznámá adresa],
  'count': [počet vrácených výdejních míst],
  'hash': [stejná výdejní místa ve stejném pořadí mají stejný hash],
  'data': {
    'items': [list všech výdejních míst]
  }
}

- Integrace do formuláře

Je možná také integrace přímo do vašeho formuláře pomocí Javascriptu. Script vyžaduje framework jQuery a jako vstupní parametry má políčko select boxu, kde chcete zobrazit výdejní místa a inputy, kde uživatel vyplňuje svoji adresu.

Pokud chcete mít možnost zobrazit i zahraniční výdejní místa a zároveň jste implementovali omezení na dobírku dle pole cod_allowed, nastavte si atribut crossBoarder objektu dpdShipping na 1 pomocí dpdShipping.setCrossBoarder(1).

Pokud chcete upřesnit výsledek, můžete použít nepovinný atribut country objektu dpdShipping a nastavit ho pomocí dpdShipping.setCountry(kód země numerická varianta (dle normy ISO 3166-1)).


<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script src="https://pickup.dpd.cz/api/formIntegration"></script>
<script>
$(document).ready(function() {
  dpdShipping.setBox($('select[name="odberne_misto"]'));
  dpdShipping.addField($('input[name="ulice"]'));
  dpdShipping.addField($('input[name="mesto"]'));
  dpdShipping.addField($('input[name="psc"]'));
  dpdShipping.setCrossBoarder(0);
});
</script>

Ulice <input type="text" name="ulice" value=""><br />
Město <input type="text" name="mesto" value=""><br />
PSČ <input type="text" name="psc" size="5" value=""><br />
Odběrné místo <select name="odberne_misto" id="dpd_shippingplace"></select>

- Vlastní řešení - stažení seznamu výdejních míst

Pro účely vlastního řešení integrace nebo pro vytvoření seznamu výdejních míst můžete využít stažení seznamu ve formátu CSV nebo XML. Pro zajištění aktuálnosti vám doporučujeme aktualizovat stažený seznam každý den. V případě použití neaktuálních informací může dojít ke zdržení v doručení zásilky, případně k jejímu vrácení odesilateli.

Aktuální seznam všech výdejních míst Pickup získáte na těchto adresách:

Výstup je možné upravit několika GET parametry:

  • country – kód země numerická varianta (dle normy ISO 3166-1), vrací výdejní místa dané země. Výchozí nastavení je country=203.
  • charset – kódování výstupu. Můžu mít následující podobu - UTF-8, windows-1250
  • output=file – parametr pro https://pickup.dpd.cz/export/xml. Výsledek volání je uložen do souboru.

například: https://pickup.dpd.cz/export/xml?country=703&charset=utf-8

- Informace pro zákazníky s vlastním software

Zákazníci, kteří používají pro tisk přepravních štítků a odesílání dat o zásilkách vlastní software, musí před využitím služby Pickup odpovídajícím způsobem upravit štítek a datovou větu.

U služby Pickup je ke standardnímu štítku (obsahuje adresu výdejního místa a jméno příjemce) potřeba tisknout i štítek dodatkový (obsahuje úplnou adresu příjemce).

MPSEXPDATA musí v řádku HEADER obsahovat adresu výdejního místa jako adresu příjemce a navíc musí být přidán řádek PERS s přepínačem 4 (doručení do výdejního místa Pickup) a adresou skutečného příjemce.

Více informací o vzhledu štítku a struktuře datové věty najdete na https://www.dpd.cz/dokumentace/.

- Možnost omezení vybraných výdejních míst

Chcete-li pro vaše zákazníky omezit výběr výdejních míst, je potřeba vytvořit seznam povolených (nebo zakázaných) PS ID (ParcelShop ID)  - záleží pouze na tom, zda filtrování (omezení) zakazuje nebo povoluje vybranou skupinu. Omezení nelze aplikovat na mapu.

Seznam povolených výdejních míst je ideální tvořit z kompletního seznamu PS, který je dostupný například na:

https://pickup.dpd.cz/export/csv a https://pickup.dpd.cz/export/xml

Aplikováním filtru na sloupec Company je možno získat seznam povolených ID (sloupec ID).

Příklad: Chci pouze výdejní místa DPD CZ. Stáhnu seznam PS, aplikuji filtr na sloupec Company, kde zobrazím pouze informace k těm PS, u kterých obsah pole Company začíná DPD CZ. Tím získám seznam povolených ID. Všechna ID mimo tento seznam pak ve všech návratových hodnotách skryji (nezobrazím).

Jelikož může docházet ke změnám PS ID, tak je potřeba počítat jak s aktualizací všech výdejních míst, tak i s aktualizací seznamu povolených PS.

- Možnost platby kartou u jednotlivých partnerů

V současné době lze platit dobírku platební kartou ve všech našich depech DPD. Platbu kartou nelze provádět v pobočkách SAZKA a.s.