Standard Implementation Manual
This document contains information regarding standard implementation of Packeta pick-up point selection using an embeddable application located at https://widget.packeta.com/v6/.
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
Intended audience
This manual is intended for technically advanced internet stores which require and are able to implement custom interaction with an embeddable application located at https://widget.packeta.com/v6/.
Specifically, the following skills are required:
- basic JavaScript programming
- basic HTML/CSS knowledge
Important information
If you want to use external pick-up points:
- implementation is possible only via the Packeta library.js (= the functionality of external pick-up points is not supported in version 6 when using the configurator but only when using the library.js)
- once the v6 widget is successfully implemented, to display external pick-up points it is still necessary to turn this function on in the Packeta client section
- to see the pick-up points in a specific country, make sure the country is enabled
- once the country is newly enabled, the change will apply to your widget within maximum 90 minutes
What is important to know?
- Your widget (both v6 and older versions) will work correctly only if you have a correctly configured API key. Your key can be found in the Packeta client section
Cookies
| Argument | Type | Max-age | Description |
|---|---|---|---|
| branchId | string | 2147483647 | Stores the ID of the last selected pick-up point. When end user visits any eshop, widget centers the map on that pick-up point. |
Quick start – examples
We provide an integration library, which you may mirror (without automatic updating) and/or use in any way:
- https://widget.packeta.com/v6/www/js/library.js
- example using the library: simple, complex
- please note you have to provide your API key (search for
packetaApiKey) for the examples to work- API key is an identifier of your Packeta account, available in Packeta client section, or can be provided by your account manager
Basic application information
The embeddable application lives in an isolated iframe, which cannot interact with your main webpage in any other way than sending messages using window.postMessage().
Iframe permissions:
- recommended:
sandbox="allow-scripts allow-same-origin" allow="geolocation" - minimal required:
sandbox="allow-scripts" - please note that geolocation is only available if your internet store is served over https (not just http)
- cookies persistence
There are two distinct possible modes of operation in the shopping cart:
- the pick-up point selection is done in a modal dialog (which opens after the customer selects delivery to Packeta pick-up 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 doing the later, make sure to test on mobile phones and tablets.
Integration library – methods
We provide an integration library which should be called out via this URL:
The library provides 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 in Packeta client section, or can be provided by your account manager. |
callback |
function |
yes | Function which will be called when the user confirms or cancels pick-up point selection. The function will receive one argument, which will be either an ExtendedPoint object if pick-up point was selected, or null if selection was cancelled. |
options |
Options object |
no | May contain additional configuration options of the application, see below. |
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()
Close 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 be always present
- Required: No are optional and may not be present
- Required: Recommended are strongly recommended to be used
Options
| 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" |
country |
string |
Recommended | Shows only pick-up 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 pick-up points configured in the client section will be displayed. Default value is based on the Allowed branch settings in the client section (https://client.packeta.com/en/user-branch-settings/edit) |
carriers |
string |
no | This field should contain either carrier ID or string “packeta” for Packeta internal pick-up points. The list of carrier IDs is available in the XML feed.There can be more values added but must be separated by comma. |
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 pick-up points, which provide the Claim Assistant (Return Parcel) service. If present and set to any other value, it will only display pick-up points which do not provide the Claim Assistant (Return Parcel) service. |
packetConsignment |
string |
no | If present and set to "yes", it will only display pick-up points, which provide new parcel consignment service. If present and set to any other value, it will only display pick-up points which do not provide new parcel consignment service. |
weight |
float |
no | If present, it will only display pick-up points, which accept parcels of this weight in kilograms. |
longitude |
float |
no | If location is not allowed use longitude and latitude as current position. |
latitude |
float |
no | If location is not allowed use longitude and latitude as current position. |
ExtendedPoint
- there is always at least one of "error", "warning", "recommended" or "isNew" set (not null, not false).
| Field Name | Type | Description |
|---|---|---|
id |
integer |
Unique ID. |
name |
string |
Name which usually means city and street address. For large cities also includes city district. |
country |
string[2] |
Country code |
currency |
string[3] |
ISO 4217 currency alphabetic code |
place |
string |
Name of the business place |
special |
string |
Short additional information about the pick-up 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 pick-up point allow consigning new parcels? |
claimAssistant |
boolean |
Does the pick-up point accept Return Parcels (paid by you / receiver)? |
maxWeight |
integer |
The maximum accepted weight of parcel in kilograms. |
error |
null | string |
If not null, then it indicates that you must not allow this pick-up point to be selected by customer. However, you must display it and indicate its unavailability because this state is usually only temporary. Possible values are: |
vacation |
The pick-up point is temporarily closed due to staff vacation. The state persists at least for a week, typically 1 or 2 weeks. | |
full |
The pick-up point is currently over maximum capacity. | |
closing |
The pick-up point will be closed in near future. Displaying a pick-up point in such a case will help the customer understand why the pick-up 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 you must discourage the customer from selecting this pick-up point. Possible values are: |
almostFull |
The pick-up 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 you should promote this pick-up point over others. Possible values are: |
quick |
The pick-up point is far below capacity and the customer can expect very quick service. | |
isNew |
boolean |
Indicates if the pick-up point is new and if it is, you should promote it, so that customers take a notice of new pick-up points in their preferred areas. |
creditCardPayment |
null | boolean |
Indicates (true/false) if the pick-up point allows C.O.D. 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 pick-up point allows card payments for other clients. |
saturdayOpenTo |
float |
Indicates if the pickup 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 pickup 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 which the pickup 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 pick-up 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 pick-up point whereabouts. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>. |
directionsCar |
string: HTML |
Instructions for car access to the pick-up 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 pick-up point, bus stop name, etc. Possible tags: <p>, <b>, <a href target>, <i>, <em>, <strong>, <span>, <br>. This can be an empty string. |
holidayStart |
null | string: YYYY-MM-DD |
exceptionDays instead. |
holidayEnd |
null | string: YYYY-MM-DD |
exceptionDays instead. |
exceptionDays |
ExceptionDay |
Contains holidays, exceptions or changes from opening hours. |
wheelchairAccessible |
boolean |
Is the pick-up point accessible to people on wheelchairs? |
url |
string: URL |
OBSOLETE - Do not use. Address of pick-up point detail website. |
photo |
Object: Photo |
Provides thumbnail and full-size photos of pick-up point. |
openingHours |
Object: PointHours |
Provides HTML and structured information about pick-up point business hours. |
pickupPointType |
string |
Values to be provided are either "internal" (internal pick-up points) or "external" (external pick-up points). |
routingCode |
string |
Routing code of the branch. Used for custom labels. |
carrierId |
string |
Provides an ID of the carrier. |
carrierPickupPointId |
string |
Provides a carrier pick-up point ID. |
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 pick-up point. |
normal |
string: URL |
Link to standard-sized photo of pick-up 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. |
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
Return values
The return value depends on the input parameter version:
- version >= 3
| Value | Type | Description |
|---|---|---|
packetaWidgetMessage |
bool |
true |
packetaPoint |
Object: branchData |
Data about pick-up point |
- version >= 2
| Value | Type | Description |
|---|---|---|
packetaWidgetMessage |
bool |
true |
packetaPoint |
Object: branchData |
Data about pick-up point |
- no parameter version or version < 2
| Value | Type | Description |
|---|---|---|
packetaBranchName |
string |
Name which usually means city and street address. For large cities it also includes a city district. |
packetaBranchId |
string |
ID of pick-up point (without prefix) |
packetaBranchOpeningHours |
string: HTML |
compactShort The most compact version of business hours. May contain the following HTML: <br />, <strong>, <strong style='color: red;'> |
packetaBranchCreditCardPayment |
boolean |
Indicates if the pick-up point allows C.O.D. payment via payment card. If you have disabled card payments for your Packeta client account, the return value will always be null ("not available"), even if the pick-up point allows card payments for other clients. |
packetaBranchUrl |
string: URL |
OBSOLETE - Do not use. Provides your e-shop address: either a full URL, or at least top-level domain. |
packetaBranchPlace |
string |
Name of the business place |
packetaBranchZip |
string |
Postal code |
packetaSelectedId |
string |
ID of pick-up point (without prefix) |
packetaSelectedData |
Object: branchData |
Data about pick-up point |
packetaWidgetMessage |
boolean |
true |
branchData
Data about pickup point
| Value | Type | Description |
|---|---|---|
businessDaysOpenLunchtime |
boolean |
Indicates if the pick-up point is open during lunch time (does not have a break during lunch time). Recommended as a filtering option. |
businessDaysOpenUpTo |
float |
Indicates the latest hour until which the pickup 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. |
city |
string |
City name |
claimAssistant |
boolean |
If present and set to "yes", it will only display pick-up points, which provide the Claim Assistant (Return Parcel) service. If present and set to any other value, it will only display pick-up points which do not provide the Claim Assistant (Return Parcel) service. |
country |
string |
Shows only pick-up 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 pick-up points configured in the client section will be displayed. |
creditCardPayment |
boolean |
Indicates (true/false) if the pick-up point allows C.O.D. payment via payment card. If you have disabled card payments for your Packeta client account, the return value will always be null ("not available"), even if the pick-up point allows card payments for other clients. |
currency |
string[3] |
ISO 4217 currency alphabetic code |
directions |
string: HTML |
Information about the pick-up point whereabouts. |
directionsCar |
string: HTML |
Instructions for car access to the pick-up point, parking, etc. |
directionsPublic |
string: HTML |
Instructions for public transport access to the pick-up point, bus stop name, etc. |
error |
null | string |
If not null, then it indicates that you must not allow this pick-up point to be selected by customer. However, you must display it and indicate its unavailability because this state is usually only temporary. |
gps |
GpsCoordinates |
GPS coordinates |
holidayEnd |
null | string: YYYY-MM-DD |
If there is pick-up point vacation upcoming or in progress, this indicates when it starts. This will usually appear earlier than error=vacation. |
holidayStart |
null | string: YYYY-MM-DD |
If there is pick-up point vacation upcoming or in progress, this indicates when it ends. This will usually appear earlier than error=vacation. |
id |
string |
ID of pick-up point (without prefix) |
isNew |
boolean |
Indicates if the pick-up point is new and if it is, you should promote it, so that customers take a notice of new pick-up points in their preferred areas. |
maxWeight |
integer |
The maximum accepted weight of the parcel in kilograms. |
name |
string |
City name |
nameStreet |
string |
Street name and house number |
openingHours |
pointhours |
Provides HTML and structured information about pick-up point business hours. |
packetConsignment |
boolean |
Does the pick-up point allow consigning new parcels? |
photo |
Array: Photo |
OBSOLETE - Do not use. Provides thumbnail and full-size photos of pick-up points. |
photos |
Array: Photo |
Provides thumbnail and full-size photos of pick-up points. |
place |
string |
Name of the business place |
recommended |
null | string |
If not null, then it indicates you should promote this pick-up point over others. |
saturdayOpenTo |
float |
Indicates if the pickup 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 pickup point is open on Sunday, and if so, until which hour. If it's closed, the value is 0. Recommended as a filtering option. |
special |
string |
Short additional information about the pick-up point place, e.g., "by the subway entrance". |
street |
string |
Street name and house number |
url |
string: URL |
OBSOLETE - Do not use. Address of pick-up point detail website. |
warning |
null | string |
If not null, then it indicates that you must discourage the customer from selecting this pick-up point. |
wheelchairAccessible |
boolean |
Is the pick-up point accessible to people on wheelchairs? |
zip |
string |
Postal code |
pickupPointType |
string |
Values to be provided are either "internal" (internal pick-up points) or "external" (external pick-up points). |
carrierId |
string |
Only for external pick-up points: Provides an ID of the carrier. |
carrierPickupPointId |
string |
Only for external pick-up points: Provides a carrier pick-up point ID. |
routingCode |
string |
Routing code of the branch. Used for custom labels. |
routingName |
string |
Routing name of the branch. Used for custom labels. |