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

Widget

This document details the standard implementation of Packeta PUDO points (Pick-up points & Boxes) selection utilizing an embeddable application, Widget.

Intended audience​

This guide is intended for developers integrating the Packeta Widget into an e-commerce website or application.

The following knowledge is recommended:

  • Basic JavaScript
  • Basic HTML/CSS

Prerequisites​

Before implementing the Packeta Widget, ensure that you have:

important

The widget requires API key not API password. Do not fill the API password into your widget.

Getting started​

Use the Widget Configurator to:

  • generate an initial configuration
  • preview widget behaviour
  • obtain a code snippet for your integration

The generated snippet can be used as a starting point for implementing the widget in your checkout.

Always validate the selected PUDO point on the server side using the validation endpoint described in the validation section.

Supported browser versions​

List of minimal supported browser versions:

  • Google Chrome 79
  • Mozilla Firefox 79
  • Microsoft Edge 18
  • Internet Explorer 11
  • Safari 11
  • Opera 70

Functional cookies​

The widget stores the following functional cookies:

ArgumentTypeMax-ageDescription
branchIdstring2147483647Stores an identifier of the last selected PUDO point. When end user visits any eshop, the widget centers the map to the PUDO point.
favorite-pickup-pointsstring2147483647Stores identifiers of PUDO points marked as favorite. User can list his/her favorite PUDO points in the widget.

Widget architecture​

The embeddable application exists within an isolated iframe, which can only interact with your main webpage through sending messages via window.postMessage().

Permissions for Iframe​

  • Recommended: sandbox="allow-scripts allow-same-origin" allow="geolocation"
  • Minimal requirement: sandbox="allow-scripts"
  • Be aware that geolocation is only available if your online store operates over https (not just http)
  • Persistence of cookies

Operations within shopping cart​

There are two distinct possible modes of operation in the shopping cart:

  • the PUDO point selection is done in a modal dialog (that opens after the customer selects delivery to Packeta PUDO point, or by a button available next to such delivery method)
  • inline UI controls, part of delivery method selection

Both modes are supported by the application. When using the latter option, make sure to test on mobile phones and tablets.

Integration library – methods​

We provide an integration library available at this URL:

The library provides the following methods:

Packeta.Widget.pick(apiKey, callback, options*, inElement*)

This method launches the widget. There is no return value.

ArgumentTypeRequiredDescription
apiKeystring[16]yesAn identifier of your Packeta account, available at Packeta client section, or can be provided by your account manager.
callbackfunctionyesFunction that will be called when the user confirms or cancels PUDO point selection. The function will receive one argument, that will be either an Point object if PUDO point was selected, or null if selection was cancelled. To get selected PUDO point's vendor code, call the validation endpoint.
optionsOptions JSON URL, or Object: OptionsnoURL of a JSON file containing the Options object, or the Options object itself.
inElementDOM elementnoIf not null, application will be displayed inside the specified DOM element. We recommend that the element has dimensions specified.
Packeta.Widget.close()

Closes any previously displayed widget. This method will succeed even if none is currently open. There is no return value.

Data structures​

  • Fields marked with Required: yes are mandatory and will always be present.
  • Required: no are optional and may not be present
  • Required: recommended are strongly recommended to be used

Options​

  • Additional configuration options of the application
KeyTypeRequiredDescription
webUrlstring: URLnoProvides your e-shop address, either a full URL, or at least top level domain.
appIdentitystringnoProvides the e-shop software name and version, and if applicable also Packeta module version. E.g. "prestashop-1.6-packeta-4.1"
vendorsArray: VendorrecommendedList of PUDO point vendors. Only the specified vendors and their PUDO points will be displayed. If not present, all vendors and all PUDO points will be displayed. Available vendors respect the Allowed branches settings.
countrystringnoShows only PUDO points from particular countries, specified with ISO 3166-1 alpha-2 code in lower case and separated by comma (e.g.: au, be, gb). If not set, specific PUDO points configured in the client section will be displayed. Default value is based on the Allowed branches settings. Country restricts the list of PUDO point vendors. Consider using the vendors field.
languagestring[2]recommendedDisplays user interface in language specified with following options: ['en', 'cs', 'bg', 'hu', 'pl', 'ro', 'sk', 'fr', 'uk', 'de', 'sl', 'lv', 'it', 'hr', 'fi', 'et', 'da', 'es', 'el', 'lt', 'nl', 'pt', 'ru', 'sv']. If not set, browser preference will be used. Default value is "en" language.
claimAssistantstringnoIf present and set to "yes", it will only display PUDO points, that provide the Claim Assistant (Return Packet) service. If present and set to any other value, it will only display PUDO points that do not provide the Claim Assistant (Return Packet) service.
packetConsignmentstringnoIf present and set to "yes", it will only display PUDO points, that provide new packet consignment service. If present and set to any other value, it will only display PUDO points that do not provide new packet consignment service.
weightfloatnoIf present, it will only display PUDO points, that accept packets of this weight in kilograms.
lengthintegernoIf present, it will only display PUDO points, that accept packets of this length in centimeters.
widthintegernoIf present, it will only display PUDO points, that accept packets of this width in centimeters.
depthintegernoIf present, it will only display PUDO points, that accept packets of this depth in centimeters.
longitudefloatnoIf web browser's location services are not allowed use longitude and latitude as current position.
latitudefloatnoIf web browser's location services are not allowed use longitude and latitude as current position.
livePickupPointbooleannoIf present and set to true, only PUDO points where age 18+ verification service is available are displayed.
expeditionDaystring: YYYY-MM-DDnoExpected date of the packet expedition. A PUDO point will be unavailable when the shipping date falls within the PUDO point's holiday that lasts more than 3 days.
defaultPricefloatnoDefault vendor's shipping price. If not specified, no shipping price will be displayed.
defaultCurrencystringnoDefault vendor's currency ISO 4217 currency code.
centerExternalIdstringnoIf present, centers the map to the PUDO point.
carriersstringnoDeprecated. Use vendors instead.

Vendor​

  • Vendor of PUDO points is an abstraction of a delivery method.
Field NameTypeRequiredDescription
carrierIdstringyes if country and group is not specifiedCarrier ID for an external carrier
countrystringyes if carrierId is not specifiedCountry of the Packeta internal carrier ISO 3166-1 alpha-2 code.
groupstringyes if carrierId is not specified and group is not Pick-up PointGroup of the Packeta internal carrier. Either zbox or empty for Pick-up Point.
selectedbooleannoIf present and set to true, the vendor will be selected.
pricefloatnoVendor's shipping price. If not present, the default price will be used.
currencystringnoIf not present, the default currency will be used. If there is no currency and the price is not 0, the price will not be displayed. ISO 4217 currency code

Point​

  • There is always at least one of "error", "warning", "recommended" or "isNew" set (not null, not false).
Field NameTypeDescription
idstringOnly for internal PUDO points: Branch ID. For external PUDO points use fields carrierId and carrierPickupPointId instead.
namestringName that usually means city and street address. For large cities also includes city district.
countrystring[2]Country code ISO 3166-1 alpha-2 code in lower case.
currencystring[3]ISO 4217 currency code
placestringName of the business place
specialstringShort additional information about the PUDO point place, e.g. "by the subway entrance"
streetstringStreet name and house number
citystringCity name
zipstringPostal code
gpsGpsCoordinatesGPS coordinates
packetConsignmentbooleanDoes the PUDO point allow consigning new packets?
claimAssistantbooleanDoes the PUDO point accept Return Packets (paid by you / recipient)?
maxWeightintegerThe maximum accepted weight of packet in kilograms.
errornull / stringIf not null, then it indicates that customers must not select this PUDO point. However, the PUDO point is still displayed while it indicates its unavailability, because the state is usually only temporary. Possible values are:
vacationThe PUDO point is temporarily closed due to staff vacation. The state persists at least for a week, typically 1 or 2 weeks.
fullThe PUDO point is currently over maximum capacity.
closingThe PUDO point will be closed in near future. Displaying a PUDO point in such a case will help the customer understand why the PUDO point is not available anymore.
technicalVarious other reasons.
xxxIf an unknown string value occurs (new reason introduced in the future), treat it as technical.
warningnull / stringIf not null, then it indicates that customers shall not select this PUDO point. Possible values are:
almostFullThe PUDO point is approaching full capacity and it is possible that the customer may experience some wait time due to servicing others.
recommendednull / stringIf not null, then it indicates that customers shall prefer this PUDO point over others. Possible values are:
quickThe PUDO point is far below capacity and the customer can expect very quick service.
isNewbooleanPromotes that the PUDO point is new and customers shall take a notice of it.
creditCardPaymentnull / booleanIndicates (true/false) if the PUDO point allows cash on delivery payment via payment card. If you have disabled card payments for your Packeta client account, the return value will be always be null ("not available"), even if the PUDO point allows card payments for other clients.
saturdayOpenTofloatIndicates if the PUDO point is open on Saturday, and if so, until which hour. If it's closed, the value is 0. Recommended as a filtering option.
sundayOpenTofloatIndicates if the PUDO point is open on Sunday, and if so, until which hour. If it's closed, the value is 0. Recommended as a filtering option.
businessDaysOpenUpTofloatIndicates the latest hour until that the PUDO point is open on any single day of the week. E.g. if the opening hours are Mon-Thu 10:00-18:00, Fri 12:00-20:00, then the value would be 20. Recommended as a filtering option.
businessDaysOpenLunchtimebooleanIndicates if the PUDO point is open during lunch time (does not have a break during lunch time). Recommended as a filtering option.
directionsstring: HTMLInformation about the PUDO point whereabouts. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>.
directionsCarstring: HTMLInstructions for car access to the PUDO point, parking, etc. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>. This can be an empty string.
directionsPublicstring: HTMLInstructions for public transport access to the PUDO point, bus stop name, etc. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>. This can be an empty string.
exceptionDaysArray: ExceptionDayContains holidays, exceptions or changes from opening hours.
wheelchairAccessiblebooleanIs the PUDO point accessible to people on wheelchairs?
branchCodestringOnly for internal PUDO points: Unique URL safe identifier to be used in an address of a PUDO point detail web page
photoArray: PhotoProvides thumbnail and full-size photos of PUDO point.
openingHoursObject: PointHoursProvides HTML and structured information about PUDO point business hours.
pickupPointTypestringValues to be provided are either "internal" (internal PUDO points) or "external" (external PUDO points).
routingCodestringRouting code of the branch. Used for custom labels.
carrierIdstringOnly for external PUDO points: External carrier ID
carrierPickupPointIdstringOnly for external PUDO points: External carrier's PUDO point code
groupstringOnly for Packeta internal PUDO points: Group of PUDO point. Either zbox or empty for Pick-up Point.
externalIdstringUnique identifier
nameStreetstringDeprecated. Use name instead.
holidayStartnull / string: YYYY-MM-DDDeprecated. Use exceptionDays instead.
holidayEndnull / string: YYYY-MM-DDDeprecated. Use exceptionDays instead.
urlstring: URLDeprecated. Use branchCode instead.
photosArray: PhotoDeprecated. Use photo instead.

GpsCoordinates​

Field NameTypeDescription
latfloatLatitude
lonfloatLongitude

ExceptionDay​

Field NameTypeDescription
fromstring: YYYY-MM-DDstart date
tonull / string: YYYY-MM-DDend date
timesArray: Time

Time​

Field NameTypeDescription
openstring: HH:mmopen time
closestring: HH:mmclose time

Photo​

Field NameTypeDescription
thumbnailstring: URLLink to thumbnail-sized photo of PUDO point.
normalstring: URLLink to standard-sized photo of PUDO point.

PointHours​

Field NameTypeDescription
compactShortstring: HTMLThe most compact version of business hours. May contain the following HTML: <br />, <strong>, <strong style='color: red;'>
compactLongstring: HTMLSame as compactShort, more text may be used to explain upcoming changes. May contain the following HTML: <br />, <strong>, <strong style='color: red;'>
tableLongstring: HTMLProvides business hours in a table with row for each day of week. More text may be used to explain upcoming changes. May contain the following HTML: <br />, <strong>, <strong style='color: red;'>, <table class='packetery-hours'>, <tr>, <th>, <th style='color: red;'>, <td>, <td colspan='2' align='center'>
regularWeekHoursProvides structured information about current business hours.
exceptionsDeprecated. Use exceptionDays instead.

WeekHours​

Field NameTypeDescription
mondaystring: Hours
tuesdaystring: Hours
wednesdaystring: Hours
thursdaystring: Hours
fridaystring: Hours
saturdaystring: Hours
sundaystring: Hours

string: Hours​

  • The format for business hours is one, two or three blocks separated by a comma, e.g.:
    • 08:00–12:30
    • 08:00–12:30, 13:30–17:30
    • 08:00–12:30, 13:30–17:30, 18:30–21:00
  • Please note the dash (—), not hyphen (-), between open and close times

Validation of selected PUDO point​

Selection of PUDO is done entirely on end user's device. Technically skilled user is able to bypass our validation (allowed PUDO points, available capacity, etc.). To solve this issue we provide validation endpoint. The validation endpoint should be called with the same parameters that the widget was initialized with (see Data structures - Options).

The endpoint is available at URL https://widget.packeta.com/v6/pps/api/widget/v1/validate. HTTP method is POST.

Request​

Headers​

Header NameTypeRequiredDescription
X-LanguagestringnoLanguage code ISO 639-1 alpha-2 code. When specified, error messages are displayed in given language if the translation is available. Default language code is en.

Parameters​

Parameters are posted as a JSON object.

Field NameTypeRequiredDescription
apiKeystring[16]yesAn identifier of your Packeta account, available in Packeta client section, or can be provided by your account manager.
optionsObject: ValidatedOptionsno
pointObject: ValidatedPointyes
idstringfor internal pointsDeprecated. Use ValidatedPoint instead.
carrierIdstringfor external pointsDeprecated. Use ValidatedPoint instead.
carrierPickupPointIdstringfor external pointsDeprecated. Use ValidatedPoint instead.
countrystringnoDeprecated. Use ValidatedPoint instead.
carriersstringnoDeprecated. Use ValidatedPoint instead.
claimAssistantbooleannoDeprecated. Use ValidatedPoint instead.
packetConsignmentbooleannoDeprecated. Use ValidatedPoint instead.
weightfloatnoDeprecated. Use ValidatedPoint instead.
livePickupPointbooleannoDeprecated. Use ValidatedPoint instead.
expeditionDaystring:YYYY-MM-DDnoDeprecated. Use ValidatedPoint instead.

ValidatedOptions​

Field NameTypeRequiredDescription
countrystringnoComma separated list of allowed countries, specified with ISO 3166-1 alpha-2 code in lower case.
carriersstringnoComma separated list of allowed carriers, or string packeta for Packeta internal PUDO points.
claimAssistantbooleannoIf present and set to true, selected PUDO point must provide Claim Assistant service.
packetConsignmentbooleannoIf present and set to true, selected PUDO point must provide new packet consignment service.
weightfloatnoIf present, selected PUDO point must accept packets of this weight in kilograms.
livePickupPointbooleannoIf present and set to true, selected PUDO point must provide age verification service.
expeditionDaystring:YYYY-MM-DDnoExpected date of the packet expedition. The selected PUDO point must not have a holiday of more than 3 days during this date.
vendorsArray: ValidatedVendornoList of vendor options.
cashOnDeliverybooleannoWhether cash on delivery is specified.
widthintegernoWidth of the packet in centimeters. *
lengthintegernoLength of the packet in centimeters. *
depthintegernoDepth of the packet in centimeters. *

* The dimensions are optional and can be specified in any order.

ValidatedVendor​

Field NameTypeRequiredDescription
carrierIdstringyes if country and group is not specifiedCarrier ID for an external carrier
countrystringyes if carrierId is not specifiedCountry of the Packeta internal carrier ISO 3166-1 alpha-2 code.
groupstringyes if carrierId is not specified and group is not Pick-up PointGroup of the Packeta internal carrier. Either zbox or empty for Pick-up Point.

ValidatedPoint​

Field NameTypeRequiredDescription
idstringfor internal pointsBranch ID.
carrierIdstringfor external pointsExternal carrier ID.
carrierPickupPointIdstringfor external pointsExternal carrier's PUDO point code.

Example​

Example request body:

{
"apiKey": "<your-api-key>",
"point":
{
"id": "<id-of-selected-PUDO-point>"
},
"options":
{
"country": "cz,sk",
"carriers": "packeta",
"weight": 3.1,
"livePickupPoint": true,
"expeditionDay": "2022-08-31",
"vendors":
[
{
"country": "cz",
"group": "zbox"
}
],
"width": 40,
"length": 30,
"depth": 20
}
}

Response​

Possible HTTP status codes of the response:

Status codeDescription
200PUDO point was validated. Inspect response body to get validation status.
400Missing or incorrect parameters. Inspect response body to get more error details.
401Invalid API key.

Response is returned as JSON object with following properties:

Property NameTypeDescription
isValidbooleantrue means that the selected PUDO point meets all the criteria of the validation request and the e-shop settings. In case of false inspect errors property.
pointObject: ValidPoint
errorsarrayAn array that contains all discovered validation errors with their error codes and descriptions.

ValidPoint​

Field NameTypePresentDescription
namestringyesName of the pickup point.
addressObject: ValidPointAddress
carrierIdstringyes if country and group is not presentCarrier ID for an external carrier
groupstringyes if carrierId is not present and group is not Pick-up PointGroup of the Packeta internal carrier. Either zbox or empty for Pick-up Point.
countrystringyes if carrierId is not presentDeprecated. Use ValidPointAddress.country instead.

ValidPointAddress​

Field NameTypeDescription
streetstringStreet name and house number
citystringCity name
zipstringPostal code
countrystringCountry code ISO 3166-1 alpha-2 code in lower case.

Error codes​

Error codeDescription
NotFoundThe PUDO point was not found.
InvalidCarrierThe PUDO point has not allowed carrier.
InvalidCountryThe PUDO point is not in allowed country.
EmptyListOfAllowedCountriesCannot perform country validation because the list of allowed countries is empty.
NoClaimAssistantThe PUDO point does not offer Complaints Assistant Service.
HasClaimAssistantThe PUDO point offers Complaints Assistant Service.
NoPacketConsignmentThe PUDO point is not drop-off point.
HasPacketConsignmentThe PUDO point is drop-off point.
InvalidWeightThe PUDO point does not accept packets with given weight.
NoAgeVerificationThe PUDO point does not offer Age Verification Service.
PickupPointVacationThe PUDO point currently does not accept any packets due to reported holiday.
PickupPointClosingThe PUDO point does not accept new shipments because it will be closed soon.
PickupPointIsFullThe PUDO point does not accept any packets at the moment due to its full capacity.
PickupPointForbiddenThe PUDO point cannot be selected.
PickupPointTechnicalReasonThe PUDO point cannot be chosen as a final destination of your packet due to technical reasons.
InvalidVendorThe PUDO point has not allowed vendor.
NoCashOnDeliveryThe PUDO point does not accept cash on delivery.
InvalidDimensionsThe PUDO point does not accept packet with given dimensions.

Example​

Example response body:

{
"isValid": false,
"point":
{
"name": "Z-BOX",
"address": {
"street": "Českomoravská 2408",
"city": "Praha ",
"zip": "190 00",
"country": "cz"
},
"group": "zbox"
},
"errors":
[
{
"code": "NoAgeVerification",
"description": "The PUDO point does not offer Age Verification Service."
}
]
}