Standard Implementation Manual Widget v6

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:

  1. 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)
  2. 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.

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 If there is pick-up point vacation upcoming or in progress, this indicates when it starts. This will usually appear earlier than error=vacation.
holidayEnd 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.
wheelchairAccessible boolean Is the pick-up point accessible to people on wheelchairs?
url string: URL Address of pick-up point detail website.
photo Photo Provides thumbnail and full-size photos of pick-up point.
openingHours 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

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