Jak integrovat BOX NOW
BOX NOW je externí dopravce poskytující PUDO (pick-up/drop-off) doručování do výdejních boxů ve více zemích:
Tento návod vás provede integrací BOX NOW do Zásilkovny. Dozvíte se, jak získat dostupná výdejní místa, umožnit zákazníkům vybrat cílový box, vytvořit zásilky, generovat štítky dopravce a zpracovávat trasování. Stejný postup lze použít i pro další externí dopravce změnou ID dopravce a ID výdejních míst.
Než začnete
Než začnete odesílat zásilky se Zásilkovnou, potřebujete:
- schválený účet
- povolené způsoby doručení v klientské sekci
- API přístupové údaje
Přehled integrace
- Získejte ID dopravce
- Vyberte cílové místo
- Vytvořte zásilku
- Získejte číslo zásilky u dopravce a štítek
- Zpracujte externí tracking (volitelné)
Získejte ID dopravce
BOX NOW doručuje do několika zemí a každá země má vlastní ID dopravce. Neexistuje jedno univerzální ID. Vždy používejte ID dopravce odpovídající cílové zemi zásilky.
| Země | Název dopravce | ID dopravce | Měna |
|---|---|---|---|
| 🇬🇷 Řecko | GR BOX NOW Box | 20409 | EUR |
| 🇧🇬 Bulharsko | BG BOX NOW Box | 33777 | EUR |
| 🇭🇷 Chorvatsko | HR BOX NOW Box | 35319 | EUR |
| 🇨🇾 Kypr | CY BOX NOW Box | 35369 | EUR |
| 🇸🇮 Slovinsko | SI BOX NOW Box | 40597 | EUR |
Jednotlivá ID dopravců můžete získat jedním z následujících způsobů:
- Najdete je v Klientské sekci → Podat zásilku

- Získáte je prostřednictvím seznamu dopravců
Datová struktura seznamu dopravců
- JSON
[
{
"id": "33777", // ID you are looking for (differs per country)
"name": "BG BOX NOW Box",
"available": "true",
"pickupPoints": "true",
"apiAllowed": "true",
"separateHouseNumber": "false",
"customsDeclarations": "false",
"requiresEmail": "true",
"requiresPhone": "true",
"requiresSize": "false",
"disallowsCod": "false",
"country": "bg",
"currency": "EUR",
"maxWeight": "30",
"labelRouting": "R01-*BG-33777",
"labelName": "BG BOX NOW Box"
},
{
"id": "20409",
"name": "GR BOX NOW Box",
"available": "true",
"pickupPoints": "true",
"apiAllowed": "true",
"separateHouseNumber": "false",
"customsDeclarations": "false",
"requiresEmail": "true",
"requiresPhone": "true",
"requiresSize": "false",
"disallowsCod": "false",
"country": "gr",
"currency": "EUR",
"maxWeight": "30",
"labelRouting": "R01-*GR-20409",
"labelName": "GR BOX NOW Box"
},
{
"id": "35319",
"name": "HR BOX NOW Box",
"available": "true",
"pickupPoints": "true",
"apiAllowed": "true",
"separateHouseNumber": "false",
"customsDeclarations": "false",
"requiresEmail": "true",
"requiresPhone": "true",
"requiresSize": "false",
"disallowsCod": "false",
"country": "hr",
"currency": "EUR",
"maxWeight": "30",
"labelRouting": "C65-***-35319",
"labelName": "HR BOX NOW Box"
},
{
"id": "35369",
"name": "CY BOX NOW",
"available": "true",
"pickupPoints": "true",
"apiAllowed": "true",
"separateHouseNumber": "false",
"customsDeclarations": "false",
"requiresEmail": "true",
"requiresPhone": "true",
"requiresSize": "false",
"disallowsCod": "false",
"country": "cy",
"currency": "EUR",
"maxWeight": "30",
"labelRouting": "R01-*GR-35369",
"labelName": "CY BOX NOW"
},
{...}
]
Vyberte cílové místo
Pro zobrazení dostupných výdejních míst zákazníkům máte dvě možnosti:
Widget
Nejjednodušší způsob implementace výběru výdejního místa je widget Zásilkovny. Jedná se o připravené řešení, které lze snadno vložit do vašeho košíku.
Výhody:
- rychlá implementace
- minimální potřeba přizpůsobení
Podrobnosti implementace naleznete v dokumentaci widgetu.
Při implementaci widgetu můžete pomocí atributu vendors určit, zda a které externí dopravce zobrazovat v jednotlivých zemích.
Protože BOX NOW používá v každé zemi jiné ID dopravce, je potřeba přidat jednu položku pro každou zemi, do které doručujete. Níže uvedený příklad omezuje zobrazení pouze na BOX NOW ve všech zemích.
Pokud doručujete pouze do některých z uvedených zemí, ponechte jen odpovídající položky.
const packetaOptions = {
vendors: [
{
country: "gr",
carrierId: "20409" // GR BOX NOW Box
},
{
country: "bg",
carrierId: "33777" // BG BOX NOW Box
},
{
country: "hr",
carrierId: "35319" // HR BOX NOW Box
},
{
country: "cy",
carrierId: "35369" // CY BOX NOW
}
{
country: "si",
carrierId: "" // SI BOX NOW
}
]
};
Různé možnosti konfigurace si můžete vyzkoušet v našem konfigurátoru.
Integrace feedu
Pokud si chcete vytvořit vlastní výběr výdejních míst, můžete použít naše feedy a pracovat přímo s daty o lokalitách.
Datové feedy použijte, pokud:
- chcete mít plnou kontrolu nad uživatelským rozhraním
- vytváříte vlastní frontendové řešení
- potřebujete přizpůsobit způsob zobrazení nebo filtrování lokalit
Výdejní místa externích dopravců jsou dostupná ve feedu Carrier PUDO. Pokud chcete zobrazit pouze BOX NOW boxy, použijte atribut ids s ID dopravců pro požadované země. Odpověď následně obsahuje samostatný objekt dopravce pro každou požadovanou zemi spolu s příslušným seznamem výdejních míst.
Jednotlivá země (e.g. Greece):
https://pickup-point.api.packeta.com/v5/__API_KEY__/carrier_point/json?ids[]=20409
Všechny BOX NOW boxy najednou:
https://pickup-point.api.packeta.com/v5/__API_KEY__/carrier_point/json?ids[]=20409&ids[]=33777&ids[]=35319&ids[]=35369
Implementaci feedu naleznete v tomto návodu. Po stažení feedu vždy respektujte atribut "displayFrontend": 1. Tento atribut určuje, zda je výdejní místo dostupné koncovému zákazníkovi. Pokud má hodnotu 1, můžete výběr tohoto místa zákazníkovi umožnit.
Datová struktura Carrier PUDO feedu
- JSON
{
"carriers": [
{
"id": 20409,
"name": "GR BOX NOW Box",
"points": [
{
"code": "10043", // code you are looking for
"coordinates": {
"latitude": "37.926172",
"longitude": "23.744002"
},
"street": "Λεωφόρος Βουλιαγμένης 500",
"streetNumber": "",
"city": "Αθήνα",
"zip": "17456",
"country": "GR",
"payment": "Card only",
"displayFrontend": 1 // respect this attribute
},
...
]
},
{
"id": 33777,
"name": "BG BOX NOW Box",
"points": [ ... ]
},
...
]
}
Vytvořte zásilku
Představme si, že zákazník v Řecku vybral BOX NOW box s kódem 10043.
Vytvoření zásilky na externí výdejní místo se mírně liší od výdejního místa Zásilkovny, ale stále je velmi jednoduché. Používáte metodu createPacket() s drobnou úpravou.
Místo vyplnění addressId kódem BOX NOW boxu zadáte ID dopravce. Kód BOX NOW boxu následně vyplníte do atributu carrierPickupPoint.
Hodnota addressId musí odpovídat zemi zvoleného boxu:
20409pro Řecko33777pro Bulharsko35319pro Chorvatsko35369pro Kypr35369pro Slovinsko
Nejjednodušší je převzít ID dopravce přímo z výsledku widgetu nebo z objektu feedu, ke kterému vybrané výdejní místo patří.
- Request
- Response
<createPacket>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetAttributes>
<number>EshopOrderNumber</number>
<name>John</name>
<surname>Doe</surname>
<email>john.doe@example.com</email>
<phone>306912345678</phone>
<addressId>20409</addressId> // GR BOX NOW Box carrier ID
<value>20</value>
<currency>EUR</currency>
<weight>2</weight>
<eshop>test</eshop>
<carrierPickupPoint>10043</carrierPickupPoint> // BOX NOW point code
<note>Note on label</note>
</packetAttributes>
</createPacket>
<response>
<status>ok</status>
<result>
<id>1927098495</id>
<barcode>Z4203422860</barcode>
<barcodeText>Z 420 3422 860</barcodeText>
</result>
</response>
Validace dopravců
Jednotliví dopravci mohou mít vlastní validační pravidla a ta se mohou mezi jednotlivými BOX NOW zeměmi lišit. Před spuštěním do produkce si zkontrolujte požadavky (například telefonní číslo, e-mail, velikost zásilky nebo hmotnostní limit) pro každé používané BOX NOW ID v sekci validace dopravců.
Získání štítku dopravce
Při využívání služeb externího dopravce musíte používat také jeho štítek (tzv. přímý štítek). Tento štítek je generován v systému dopravce a je poskytován prostřednictvím Packeta API.
Číslo zásilky dopravce
Před tiskem štítku musíte nejprve získat číslo zásilky u dopravce. Jedná se o identifikační číslo zásilky v systému dopravce.
Obě metody vracejí stejné číslo zásilky dopravce. Verze V2 však navíc obsahuje ID a název dopravce.
- Request
- Response
<packetCourierNumber>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4203422860</packetId>
</packetCourierNumber>
<response>
<status>ok</status>
<result>BOXNOW_COURIER_NUMBER</result>
</response>
Získání štítku dopravce
Jakmile máte k dispozici číslo zásilky dopravce, můžete požádat o štítek pomocí některé z následujících metod:
Stejně jako Packeta štítky jsou i PDF a PNG štítky poskytovány v podobě zakódované pomocí Base64, a proto je nutné je před použitím dekódovat.
- Request
- Response
<packetCourierLabelPdf>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4203422860</packetId>
<courierNumber>BOXNOW_COURIER_NUMBER</courierNumber>
</packetCourierLabelPdf>
<response>
<status>ok</status>
<result>JVBERi0xLjcKJeLjz9MKNSAwIG9iago8PC.......</result>
</response>
BOX NOW štítek
Pokud vše proběhne správně a štítek dekódujete, měl by výsledný štítek vypadat podobně jako na ukázce níže. Skvělá práce! :)
Zpracování zásilky ve vašich systémech
Pro další zpracování zásilky ve vlastních systémech použijte metodu packetInfo(). Poskytuje základní informace potřebné pro trasování, ověření a synchronizaci dat mezi systémy.
Hodnoty atributů courierNumber, courierBarcodes a
courierTrackingNumbers se mohou lišit, protože dopravce může pro štítek, interní zpracování a tracking používat různé identifikátory.
Atributy courierId a courierName odpovídají konkrétní BOX NOW službě pro danou zemi, pro kterou byla zásilka vytvořena, viz. příklad níže.
<response>
<status>ok</status>
<result>
<branchId>20409</branchId>
<courierInfo>
<courierInfoItem>
<courierId>20409</courierId>
<courierName>GR BOX NOW Box</courierName>
<courierNumbers>
<courierNumber>BOXNOW_COURIER_NUMBER</courierNumber>
<!-- BOX NOW packet ID -->
</courierNumbers>
<courierBarcodes>
<courierBarcode>BOXNOW_COURIER_BARCODE</courierBarcode>
<!-- Displays the barcode value printed on the label -->
</courierBarcodes>
<courierTrackingNumbers>
<courierTrackingNumber>BOXNOW_TRACKING_NUMBER</courierTrackingNumber>
<!-- BOX NOW tracking number for the packet -->
</courierTrackingNumbers>
</courierInfoItem>
</courierInfo>
</result>
</response>
Sledování zásilky
Zásilkovna poskytuje dva typy trasování:
- Packeta tracking
- externí tracking (události poskytované externím dopravcem)
Ve chvíli, kdy je zásilka fyzicky předána do sítě dopravce, trasování Zásilkovny končí stavem statusCode: 6 - handed to carrier (stavové kódy)
a další informace o pohybu zásilky jsou dostupné v trasování dopravce.
Po doručení nebo vrácení zásilky se tyto informace zobrazí také v Packeta trasování. Implementaci externího trasování tak lze považovat za užitečné rozšíření, které zákazníkům poskytne více detailů a lepší přehled o průběhu doručení.
Návod pro Shoptet
Pro nastavení pluginu Zásilkovna+ v Shoptetu postupujte podle uživatelského návodu. Návod obsahuje i kroky popsané níže, pouze pro jiného dopravce (CZ výdejní místa). Proces nastavení je pro všechny stejný. Liší se pouze konfigurace konkrétního dopravce popsaná níže.
Nastavení dopravce
Klíčová pole konfigurace:
- Přepravní společnost: vyberte Zásilkovna+
- Přepravní služba: vyberte službu BOX NOW pro příslušnou zemi:
- GR BOX NOW Box (Řecko)
- BG BOX NOW Box (Bulharsko)
- HR BOX NOW Box (Chorvatsko)
- CY BOX NOW Box (Kypr)
- SI BOX NOW Box (Slovinsko)

Po uložení konfigurace se zobrazí sekce Ceník. Nastavte cenu dopravy pro danou zemi podle svých požadavků. Ve vašem e-shopu se následně BOX NOW boxy zobrazí jako možnost doručení zákazníkům ve všech nakonfigurovaných zemích.
Každá země BOX NOW představuje samostatnou dopravní službu. Opakujte nastavení země a způsobu dopravy pro každou zemi, ve které chcete BOX NOW nabízet.
Nenašli jste, co hledáte? Kontaktujte náš integrační support na integrations@packeta.com.