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:
- 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
First, obtain the FoxPost carrierID.
ID dopravce 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": "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:
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
}
]
};
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
- JSON
{
"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
},
...
]
}
]
}
Pro vaši implementaci front-endu poskytujeme logo FoxPost, které můžete libovolně využít ve svém projektu.
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.
- Request
- Response
<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>
<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. 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.
- Request
- Response
<packetCourierNumber>
<apiPassword>{{API_PASSWORD}}</apiPassword>
<packetId>Z4203422860</packetId>
</packetCourierNumber>
<response>
<status>ok</status>
<result>CLFOX176821524885947</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>CLFOX176821524885947</courierNumber>
</packetCourierLabelPdf>
<response>
<status>ok</status>
<result>JVBERi0xLjcKJeLjz9MKNSAwIG9iago8PC.......</result>
</response>
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! :)

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í.
- Příklad úspěšného doručení: Z1906917004
- Příklad nedoručené zásilky: Z1594282914
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

Po uložení konfigurace se zobrazí sekce Ceník. Nastavte cenu dopravy pro danou zemi podle svých požadavků.
Pokladna
Vaše pokladna nyní bude obsahovat možnost výběru výdejních boxů HU FoxPost.

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

