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

Jak integrovat HU FoxPost Box

FoxPost je externí dopravce poskytující PUDO (pick-up/drop-off) doručování do výdejních boxů.

Tento návod vás provede integrací FoxPostu 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​

First, obtain the FoxPost carrierID. ID dopravce můžete získat jedním z následujících způsobů:

Datová struktura seznamu dopravců


{
{
"id": "32970", // ID you are looking for
"name": "HU FoxPost Box",
"available": "true",
"pickupPoints": "true",
"apiAllowed": "true",
"separateHouseNumber": "false",
"customsDeclarations": "false",
"requiresEmail": "true",
"requiresPhone": "true",
"requiresSize": "false",
"disallowsCod": "false",
"country": "hu",
"currency": "HUF",
"maxWeight": "30",
"labelRouting": "H10-***-32970",
"labelName": "HU FoxPost Box"
},
{...}
}

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. Zápis níže ukazuje, jak zobrazit pouze HU FoxPost boxy v Maďarsku.

const packetaOptions = {
vendors: [
{
country: "hu",
carrierId: "32970" // HU FoxPost Box carrier ID
}
]
};
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 FoxPost boxy, použijte atribut ids: https://pickup-point.api.packeta.com/v5/__API_KEY__/carrier_point/json?ids[]=32970.

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": 32970,
"name": "HU Fox Post Box",
"points": [
{
"code": "hu5162", // ID FoxPost boxu
"coordinates": {
"latitude": "47.399867",
"longitude": "19.259464"
},
"street": "Erzsébet tér 4.",
"streetNumber": "",
"city": "Vecsés",
"zip": "2220",
"country": "HU",
"payment": "Card only",
"displayFrontend": 1 // respektujte tento atribut
},
...
]
}
]
}
FoxPost logo

Pro vaši implementaci front-endu poskytujeme logo FoxPost, které můžete libovolně využít ve svém projektu.

FoxPost logo horizontalFoxPost logo verticalFoxPost logo pin

Download FoxPostLogo.zip

Vytvořte zásilku​

Představme si, že zákazník vybral výdejní místo s ID hu5162.

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 boxu zadáte ID dopravce. Kód boxu následně vyplníte do atributu carrierPickupPoint.

<createPacket>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetAttributes>
<number>EshopOrderNumber</number>
<name>John</name>
<surname>Doe</surname>
<email>john.doe@example.com</email>
<phone>36701111111</phone>
<addressId>32970</addressId> // FoxPost carrier ID
<value>500</value>
<currency>HUF</currency>
<weight>2</weight>
<eshop>test</eshop>
<carrierPickupPoint>hu5162</carrierPickupPoint> // FoxPost point code
<note>Note on label</note>
</packetAttributes>
</createPacket>

Validace dopravců​

Jednotliví dopravci mohou mít vlastní validační pravidla. FoxPost vyžaduje telefonní číslo i e-mail, ale nevyžaduje uvedení velikosti zásilky. Plný seznam najdete ve validacích 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>CLFOX176821524885947</courierNumber>
</packetCourierLabelPdf>

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

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

<response>
<status>ok</status>
<result>
<branchId>32970</branchId>
<courierInfo>
<courierInfoItem>
<courierId>32970</courierId>
<courierName>HU FoxPost Box</courierName>
<courierNumbers>
<courierNumber>CLFOX176821524885947</courierNumber>
<!-- FoxPost packet ID -->
</courierNumbers>
<courierBarcodes>
<courierBarcode>Z4203422860</courierBarcode>
<!-- Displays the barcode value printed on the label -->
</courierBarcodes>
<courierTrackingNumbers>
<courierTrackingNumber>CLFOX176821524885947</courierTrackingNumber>
<!-- FoxPost 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í.

První pokus o doručení

Pokud chcete sledovat první pokus o doručení provedený externím dopravcem, je tato informace dostupná také v metodách packetTracking() a packetStatus(). Díky tomu můžete monitorovat kvalitu služeb, aniž byste potřebovali rozšíření pro externí sledování zásilek. Kód stavu je 25; viz seznam kódů stavů.

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: Zásilkovna+
  • Přepravní služba: HU FoxPost Box

Shoptet

Po uložení konfigurace se zobrazí sekce Ceník. Nastavte cenu dopravy pro danou zemi podle svých požadavků.

Payment Payment2

Pokladna​

Vaše pokladna nyní bude obsahovat možnost výběru výdejních boxů HU FoxPost. Checkout Widget

info

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