Doručení na Z-BOX
Pro vytvoření zásilky v rámci Zásilkovny je potřeba provést tyto kroky:
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í:
- Widget Zásilkovny (mapový nástroj)
- 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.
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"
}
]
};
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.
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.
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:

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>
Nenašli jste, co hledáte? Kontaktujte náš integrační support na integrations@packeta.com.