Přeskočit na hlavní obsah
For any questions, feel free to contact our integrations team at integrations@packeta.com

Doručení na Z-BOX

Pro vytvoření zásilky v rámci Zásilkovny je potřeba provést tyto kroky:

  1. Vybrat cíl zásilky
  2. Získat ID Z-BOXU
  3. Vytvořit zásilku
  4. Stáhnout štítek
  5. Sledování zásilky (volitelné)

Níže projdeme každý z těchto kroků podrobně.

Výběr cíle​

Aby vaši zákazníci viděli dostupné Z-BOXy, musíte implementovat Zásilkovnu jednou z možností:

  1. Widget Zásilkovny (mapový nástroj)
  2. Feedy Zásilkovny (zdroj dat)

Integrace widgetu​

Widget je mapový nástroj, který umožní vašim zákazníkům snadno vybrat cílový Z-BOX přímo na mapě. Jedná se o hotové řešení od Packeta se zaměřením na jednoduchost a známé uživatelské prostředí. Nejnovější verzi lze vidět na https://widget.packeta.com/v6/#/.

Implementace výběru Z-BOXů přes widget je otázkou konfigurace.

Konfigurátor widgetu

Můžete použít náš konfigurátor widgetu na https://configurator.widget.packeta.com/. Jednoduše vyplňte požadované nastavení do polí a implementujte vygenerovaný kód do svého řešení.

Jakmile máte widget integrován ve svém řešení, můžete specifikovat, které Z-BOXy se mají pro každou zemi zobrazit. Můžete povolit více Z-BOXů pro jednu zemi nebo žádný. Pro zobrazení pouze Z-BOXů použijte pole group v poli vendors. V tomto příkladu používáme CZ Z-BOX.

const packetaOptions = {
vendors: [
{
country: "cz",
group: "zbox"
}
]
};
Testovací prostředí

K testování různých konfiguračních možností máme k dispozici také testovací prostředí na https://codepen.io/Packeta/pen/xxNRWEN

Integrace feedu​

Feed je zdroj dat (JSON), který můžete čerpat, abyste získali informace o Z-BOXech. Je ideální pro ty, kdo chtějí mít plnou kontrolu nad integrací a přijmout za ni odpovědnost.

V zásadě vše, co je potřeba pro získání informací o Z-BOXech, je volání: https://pickup-point.api.packeta.com/v5/__API_KEY__/box/json?lang=__LANGUAGE__. Nahraďte __API_KEY__ vlastním API klíčem z Klientské sekce na https://client.packeta.com/support/

Po obdržení dat dbejte na atribut "displayFrontend": 1. Ten říká, zda je Z-BOX dostupný pro koncového zákazníka. Hodnota 1 znamená, že zákazník může vybrat daný Z-BOX.

Frekvence aktualizace

Nepravidelná aktualizace dat Z-BOXů může způsobit problémy při vytváření zásilky nebo při doručování.

Doporučená frekvence aktualizace dat Z-BOXů je třikrát denně.
V období vysoké sezóny (listopad - leden) doporučujeme stahovat data jednou za hodinu.

Optimalizace rychlosti zpracování

Volání feedu provádějte v časech „mezi“, například 6:13 | 6:28 | 6:47, místo přes celé hodiny.

Volat feed častěji než jednou za hodinu není nutné, protože data jsou uložena v cache po dobu jedné hodiny.


Získání ID Z-BOXu​

ID Z-BOXu můžete získat z:

Ve widgetu obdržíte atribut <id> v objektu point:

{
"id": "18579", // ID Z-BOXu
"isNew": false,
"maxWeight": 15,
"name": "Z-BOX Praha 9, Libeň, Českomoravská 2408",
"nameStreet": "Z-BOX Praha 9, Libeň, Českomoravská 2408",
...
}

Ve feedu obdržíte atribut <id>:

{
"id": "18579", // ID Z-BOXu
"type": "zbox",
"name": "Z-BOX Praha 9, Libeň, Českomoravská 2408",
"place": "Z-BOX",
"street": "Českomoravská 2408",
"city": "Praha",
"zip": "190 00",
"country": "cz",
"currency": "CZK",
"status": {
"statusId": "1",
"description": "V provozu"
},
"displayFrontend": "1", // respektujte tento atribut
...
}

Vytvoření zásilky​

V tomto kroku vyplníte údaje, které zákazník poskytl. ID Z-BOXu patří do atributu <addressId>.
Podrobnosti o vytvoření zásilky naleznete zde.

Žádost bude vypadat následovně:

<!--request-->
<createPacket>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetAttributes>
<number>orderNumber</number>
<name>Joe</name>
<surname>Doe</surname>
<company>Company</company>
<email>example@packetatest.com</email>
<phone>+420777777777</phone>
<addressId>18579</addressId> <!-- Z-BOX ID -->
<cod>0</cod>
<value>115</value>
<currency>CZK</currency>
<weight>2.5</weight>
<eshop>{{INDICATION}}</eshop> <!-- Pole z Klientské sekce/Odesílatel/Indikace -->
</packetAttributes>
</createPacket>

<!--response-->
<response>
<status>ok</status>
<result>
<id>4376064580</id>
<barcode>Z4376064580</barcode>
<barcodeText>Z 437 6064 580</barcodeText>
</result>
</response>

Stažení štítku​

Jakmile úspěšně vytvoříte zásilku, je potřeba vygenerovat štítek. Protože zásilku budete posílat přes síť Zásilkovny, můžete pokračovat jednou z dostupných metod generování štítků.
V tomto příkladu použijeme <packetLabelPdf>.

<!--request-->
<packetLabelPdf>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>4376064580</packetId>
<format>A6 on A6</format>
<offset>0</offset>
</packetLabelPdf>

<!--response-->
<response>
<status>ok</status>
<result>JVBERi0xLjcKJeLjz9MKNyAwIG9iago8P.....NDU1PiBdID4+CnN0YXJ0eHJlZgo4ODE1NwolJUVPRgo=</result>
</response>

V odpovědi obdržíte štítek ve formátu .xml. Po jeho dekódování do .pdf můžete štítek zobrazit například takto:

Z-BOX label


Sledování zásilky​

Pro sledování vaší zásilky po předání do sítě Zásilkovny můžete použít packetTracking(). Zobrazíte tak chronologický přehled stavů, kterými zásilka prošla a současný stav.
Zde naleznete seznam dostupných stavů.

Příklad:

<!--request-->
<packetTracking>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4376064580</packetId>
</packetTracking>

<!--response-->
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>ok</status>
<result>
<record>
<dateTime>2025-06-30T11:28:59</dateTime>
<statusCode>1</statusCode>
<codeText>received data</codeText>
<statusText>O zásilce víme a čekáme, až nám ji odesílatel předá.</statusText>
<branchId>0</branchId>
<destinationBranchId>0</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-06-30T12:20:32</dateTime>
<statusCode>2</statusCode>
<codeText>arrived</codeText>
<statusText>Zásilka dorazila na Praha 9, Libeň, Ocelářská 1018/3.</statusText>
<branchId>8993</branchId>
<destinationBranchId>0</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-06-30T12:22:14</dateTime>
<statusCode>3</statusCode>
<codeText>prepared for departure</codeText>
<statusText>Zásilka byla připravena k odeslání z Praha 9, Libeň, Ocelářská 1018/3 do DEPO, Praha - Štěrboholy, K Hrušovu 292/4.</statusText>
<branchId>8993</branchId>
<destinationBranchId>13497</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-06-30T17:54:05</dateTime>
<statusCode>2</statusCode>
<codeText>arrived</codeText>
<statusText>Zásilka dorazila na depo. Praha-Štěrboholy, K Hrušovu 292/4</statusText>
<branchId>13497</branchId>
<destinationBranchId>0</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-07-01T04:59:58</dateTime>
<statusCode>3</statusCode>
<codeText>prepared for departure</codeText>
<statusText>Zásilka byla připravena k odeslání z DEPO, Praha - Štěrboholy, K Hrušovu 292/4 do Z-BOX Praha 9, Libeň, Českomoravská 2408.</statusText>
<branchId>13497</branchId>
<destinationBranchId>18579</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-07-01T12:09:15</dateTime>
<statusCode>4</statusCode>
<codeText>departed</codeText>
<statusText>Zásilka byla odeslána do Z-BOX Praha 9, Libeň, Českomoravská 2408.</statusText>
<branchId>13497</branchId>
<destinationBranchId>18579</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
<record>
<dateTime>2025-07-01T14:34:42</dateTime>
<statusCode>7</statusCode>
<codeText>delivered</codeText>
<statusText>The parcel is with you. Thank you, and we look forward to next time.</statusText>
<branchId>18579</branchId>
<destinationBranchId>0</destinationBranchId>
<externalTrackingCode></externalTrackingCode>
</record>
</result>
</response>
info

Nenašli jste, co hledáte? Kontaktujte náš integrační support na integrations@packeta.com.