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:
- an approved Packeta account
- enabled delivery options in your client section
- API credentials
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:
| Argument | Type | Max-age | Description |
|---|---|---|---|
| branchId | string | 2147483647 | Stores 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-points | string | 2147483647 | Stores 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.
| Argument | Type | Required | Description |
|---|---|---|---|
apiKey | string[16] | yes | An identifier of your Packeta account, available at Packeta client section, or can be provided by your account manager. |
callback | function | yes | Function 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. |
options | Options JSON URL, or Object: Options | no | URL of a JSON file containing the Options object, or the Options object itself. |
inElement | DOM element | no | If 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
| Key | Type | Required | Description |
|---|---|---|---|
webUrl | string: URL | no | Provides your e-shop address, either a full URL, or at least top level domain. |
appIdentity | string | no | Provides the e-shop software name and version, and if applicable also Packeta module version. E.g. "prestashop-1.6-packeta-4.1" |
vendors | Array: Vendor | recommended | List 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. |
country | string | no | Shows 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. |
language | string[2] | recommended | Displays 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. |
claimAssistant | string | no | If 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. |
packetConsignment | string | no | If 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. |
weight | float | no | If present, it will only display PUDO points, that accept packets of this weight in kilograms. |
length | integer | no | If present, it will only display PUDO points, that accept packets of this length in centimeters. |
width | integer | no | If present, it will only display PUDO points, that accept packets of this width in centimeters. |
depth | integer | no | If present, it will only display PUDO points, that accept packets of this depth in centimeters. |
longitude | float | no | If web browser's location services are not allowed use longitude and latitude as current position. |
latitude | float | no | If web browser's location services are not allowed use longitude and latitude as current position. |
livePickupPoint | boolean | no | If present and set to true, only PUDO points where age 18+ verification service is available are displayed. |
expeditionDay | string: YYYY-MM-DD | no | Expected 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. |
defaultPrice | float | no | Default vendor's shipping price. If not specified, no shipping price will be displayed. |
defaultCurrency | string | no | Default vendor's currency ISO 4217 currency code. |
centerExternalId | string | no | If present, centers the map to the PUDO point. |
carriers | string | no | Deprecated. Use vendors instead. |
Vendor
- Vendor of PUDO points is an abstraction of a delivery method.
| Field Name | Type | Required | Description |
|---|---|---|---|
carrierId | string | yes if country and group is not specified | Carrier ID for an external carrier |
country | string | yes if carrierId is not specified | Country of the Packeta internal carrier ISO 3166-1 alpha-2 code. |
group | string | yes if carrierId is not specified and group is not Pick-up Point | Group of the Packeta internal carrier. Either zbox or empty for Pick-up Point. |
selected | boolean | no | If present and set to true, the vendor will be selected. |
price | float | no | Vendor's shipping price. If not present, the default price will be used. |
currency | string | no | If 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 Name | Type | Description |
|---|---|---|
id | string | Only for internal PUDO points: Branch ID. For external PUDO points use fields carrierId and carrierPickupPointId instead. |
name | string | Name that usually means city and street address. For large cities also includes city district. |
country | string[2] | Country code ISO 3166-1 alpha-2 code in lower case. |
currency | string[3] | ISO 4217 currency code |
place | string | Name of the business place |
special | string | Short additional information about the PUDO point place, e.g. "by the subway entrance" |
street | string | Street name and house number |
city | string | City name |
zip | string | Postal code |
gps | GpsCoordinates | GPS coordinates |
packetConsignment | boolean | Does the PUDO point allow consigning new packets? |
claimAssistant | boolean | Does the PUDO point accept Return Packets (paid by you / recipient)? |
maxWeight | integer | The maximum accepted weight of packet in kilograms. |
error | null / string | If 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: |
vacation | The PUDO point is temporarily closed due to staff vacation. The state persists at least for a week, typically 1 or 2 weeks. | |
full | The PUDO point is currently over maximum capacity. | |
closing | The 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. | |
technical | Various other reasons. | |
xxx | If an unknown string value occurs (new reason introduced in the future), treat it as technical. | |
warning | null / string | If not null, then it indicates that customers shall not select this PUDO point. Possible values are: |
almostFull | The PUDO point is approaching full capacity and it is possible that the customer may experience some wait time due to servicing others. | |
recommended | null / string | If not null, then it indicates that customers shall prefer this PUDO point over others. Possible values are: |
quick | The PUDO point is far below capacity and the customer can expect very quick service. | |
isNew | boolean | Promotes that the PUDO point is new and customers shall take a notice of it. |
creditCardPayment | null / boolean | Indicates (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. |
saturdayOpenTo | float | Indicates 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. |
sundayOpenTo | float | Indicates 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. |
businessDaysOpenUpTo | float | Indicates 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. |
businessDaysOpenLunchtime | boolean | Indicates if the PUDO point is open during lunch time (does not have a break during lunch time). Recommended as a filtering option. |
directions | string: HTML | Information about the PUDO point whereabouts. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>. |
directionsCar | string: HTML | Instructions 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. |
directionsPublic | string: HTML | Instructions 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. |
exceptionDays | Array: ExceptionDay | Contains holidays, exceptions or changes from opening hours. |
wheelchairAccessible | boolean | Is the PUDO point accessible to people on wheelchairs? |
branchCode | string | Only for internal PUDO points: Unique URL safe identifier to be used in an address of a PUDO point detail web page |
photo | Array: Photo | Provides thumbnail and full-size photos of PUDO point. |
openingHours | Object: PointHours | Provides HTML and structured information about PUDO point business hours. |
pickupPointType | string | Values to be provided are either "internal" (internal PUDO points) or "external" (external PUDO points). |
routingCode | string | Routing code of the branch. Used for custom labels. |
carrierId | string | Only for external PUDO points: External carrier ID |
carrierPickupPointId | string | Only for external PUDO points: External carrier's PUDO point code |
group | string | Only for Packeta internal PUDO points: Group of PUDO point. Either zbox or empty for Pick-up Point. |
externalId | string | Unique identifier |
nameStreet | string | Deprecated. Use name instead. |
holidayStart | null / string: YYYY-MM-DD | Deprecated. Use exceptionDays instead. |
holidayEnd | null / string: YYYY-MM-DD | Deprecated. Use exceptionDays instead. |
url | string: URL | Deprecated. Use branchCode instead. |
photos | Array: Photo | Deprecated. Use photo instead. |
GpsCoordinates
| Field Name | Type | Description |
|---|---|---|
lat | float | Latitude |
lon | float | Longitude |
ExceptionDay
| Field Name | Type | Description |
|---|---|---|
from | string: YYYY-MM-DD | start date |
to | null / string: YYYY-MM-DD | end date |
times | Array: Time |
Time
| Field Name | Type | Description |
|---|---|---|
open | string: HH:mm | open time |
close | string: HH:mm | close time |
Photo
| Field Name | Type | Description |
|---|---|---|
thumbnail | string: URL | Link to thumbnail-sized photo of PUDO point. |
normal | string: URL | Link to standard-sized photo of PUDO point. |
PointHours
| Field Name | Type | Description |
|---|---|---|
compactShort | string: HTML | The most compact version of business hours. May contain the following HTML: <br />, <strong>, <strong style='color: red;'> |
compactLong | string: HTML | Same as compactShort, more text may be used to explain upcoming changes. May contain the following HTML: <br />, <strong>, <strong style='color: red;'> |
tableLong | string: HTML | Provides 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'> |
regular | WeekHours | Provides structured information about current business hours. |
exceptions | Deprecated. Use exceptionDays instead. |
WeekHours
| Field Name | Type | Description |
|---|---|---|
monday | string: Hours | |
tuesday | string: Hours | |
wednesday | string: Hours | |
thursday | string: Hours | |
friday | string: Hours | |
saturday | string: Hours | |
sunday | string: 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 Name | Type | Required | Description |
|---|---|---|---|
X-Language | string | no | Language 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 Name | Type | Required | Description |
|---|---|---|---|
apiKey | string[16] | yes | An identifier of your Packeta account, available in Packeta client section, or can be provided by your account manager. |
options | Object: ValidatedOptions | no | |
point | Object: ValidatedPoint | yes | |
id | string | for internal points | Deprecated. Use ValidatedPoint instead. |
carrierId | string | for external points | Deprecated. Use ValidatedPoint instead. |
carrierPickupPointId | string | for external points | Deprecated. Use ValidatedPoint instead. |
country | string | no | Deprecated. Use ValidatedPoint instead. |
carriers | string | no | Deprecated. Use ValidatedPoint instead. |
claimAssistant | boolean | no | Deprecated. Use ValidatedPoint instead. |
packetConsignment | boolean | no | Deprecated. Use ValidatedPoint instead. |
weight | float | no | Deprecated. Use ValidatedPoint instead. |
livePickupPoint | boolean | no | Deprecated. Use ValidatedPoint instead. |
expeditionDay | string:YYYY-MM-DD | no | Deprecated. Use ValidatedPoint instead. |
ValidatedOptions
| Field Name | Type | Required | Description |
|---|---|---|---|
country | string | no | Comma separated list of allowed countries, specified with ISO 3166-1 alpha-2 code in lower case. |
carriers | string | no | Comma separated list of allowed carriers, or string packeta for Packeta internal PUDO points. |
claimAssistant | boolean | no | If present and set to true, selected PUDO point must provide Claim Assistant service. |
packetConsignment | boolean | no | If present and set to true, selected PUDO point must provide new packet consignment service. |
weight | float | no | If present, selected PUDO point must accept packets of this weight in kilograms. |
livePickupPoint | boolean | no | If present and set to true, selected PUDO point must provide age verification service. |
expeditionDay | string:YYYY-MM-DD | no | Expected date of the packet expedition. The selected PUDO point must not have a holiday of more than 3 days during this date. |
vendors | Array: ValidatedVendor | no | List of vendor options. |
cashOnDelivery | boolean | no | Whether cash on delivery is specified. |
width | integer | no | Width of the packet in centimeters. * |
length | integer | no | Length of the packet in centimeters. * |
depth | integer | no | Depth of the packet in centimeters. * |
* The dimensions are optional and can be specified in any order.
ValidatedVendor
| Field Name | Type | Required | Description |
|---|---|---|---|
carrierId | string | yes if country and group is not specified | Carrier ID for an external carrier |
country | string | yes if carrierId is not specified | Country of the Packeta internal carrier ISO 3166-1 alpha-2 code. |
group | string | yes if carrierId is not specified and group is not Pick-up Point | Group of the Packeta internal carrier. Either zbox or empty for Pick-up Point. |
ValidatedPoint
| Field Name | Type | Required | Description |
|---|---|---|---|
id | string | for internal points | Branch ID. |
carrierId | string | for external points | External carrier ID. |
carrierPickupPointId | string | for external points | External 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 code | Description |
|---|---|
| 200 | PUDO point was validated. Inspect response body to get validation status. |
| 400 | Missing or incorrect parameters. Inspect response body to get more error details. |
| 401 | Invalid API key. |
Response is returned as JSON object with following properties:
| Property Name | Type | Description |
|---|---|---|
isValid | boolean | true 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. |
point | Object: ValidPoint | |
errors | array | An array that contains all discovered validation errors with their error codes and descriptions. |
ValidPoint
| Field Name | Type | Present | Description |
|---|---|---|---|
name | string | yes | Name of the pickup point. |
address | Object: ValidPointAddress | ||
carrierId | string | yes if country and group is not present | Carrier ID for an external carrier |
group | string | yes if carrierId is not present and group is not Pick-up Point | Group of the Packeta internal carrier. Either zbox or empty for Pick-up Point. |
country | string | yes if carrierId is not present | Deprecated. Use ValidPointAddress.country instead. |
ValidPointAddress
| Field Name | Type | Description |
|---|---|---|
street | string | Street name and house number |
city | string | City name |
zip | string | Postal code |
country | string | Country code ISO 3166-1 alpha-2 code in lower case. |
Error codes
| Error code | Description |
|---|---|
NotFound | The PUDO point was not found. |
InvalidCarrier | The PUDO point has not allowed carrier. |
InvalidCountry | The PUDO point is not in allowed country. |
EmptyListOfAllowedCountries | Cannot perform country validation because the list of allowed countries is empty. |
NoClaimAssistant | The PUDO point does not offer Complaints Assistant Service. |
HasClaimAssistant | The PUDO point offers Complaints Assistant Service. |
NoPacketConsignment | The PUDO point is not drop-off point. |
HasPacketConsignment | The PUDO point is drop-off point. |
InvalidWeight | The PUDO point does not accept packets with given weight. |
NoAgeVerification | The PUDO point does not offer Age Verification Service. |
PickupPointVacation | The PUDO point currently does not accept any packets due to reported holiday. |
PickupPointClosing | The PUDO point does not accept new shipments because it will be closed soon. |
PickupPointIsFull | The PUDO point does not accept any packets at the moment due to its full capacity. |
PickupPointForbidden | The PUDO point cannot be selected. |
PickupPointTechnicalReason | The PUDO point cannot be chosen as a final destination of your packet due to technical reasons. |
InvalidVendor | The PUDO point has not allowed vendor. |
NoCashOnDelivery | The PUDO point does not accept cash on delivery. |
InvalidDimensions | The 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."
}
]
}