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

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:

Přehled integrace​

  1. Získejte ID dopravce
  2. Vyberte cílové místo
  3. Vytvořte zásilku
  4. Získejte číslo zásilky u dopravce a štítek
  5. Zpracujte externí tracking (volitelné)
tip

Používáte Shoptet? Přejděte rovnou na  user guide

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 dopravceID dopravceMěna
🇬🇷 ŘeckoGR BOX NOW Box20409EUR
🇧🇬 BulharskoBG BOX NOW Box33777EUR
🇭🇷 ChorvatskoHR BOX NOW Box35319EUR
🇨🇾 KyprCY BOX NOW Box35369EUR
🇸🇮 SlovinskoSI BOX NOW Box40597EUR

Jednotlivá ID dopravců můžete získat jedním z následujících způsobů:

Datová struktura seznamu dopravců
[
{
"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:

  1. Použít Packeta Widget (mapový nástroj)
  2. Integrovat Packeta feedy (datový zdroj)

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
}
]
};
Sandbox

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

{
"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.

Použijte ID dopravce odpovídající cílové zemi

Hodnota addressId musí odpovídat zemi zvoleného boxu:

  • 20409 pro Řecko
  • 33777 pro Bulharsko
  • 35319 pro Chorvatsko
  • 35369 pro Kypr
  • 35369 pro 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ří.

<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>

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.

<packetCourierNumber>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4203422860</packetId>
</packetCourierNumber>

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.

<packetCourierLabelPdf>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4203422860</packetId>
<courierNumber>BOXNOW_COURIER_NUMBER</courierNumber>
</packetCourierLabelPdf>

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! :)

Label

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)

Shoptet

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.

Doručování do více zemí BOX NOW

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.

info

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