Standard Implementation Manual

This document contains information regarding standard implementation of Packeta Pick-Up point selection using embeddable application located at https://widget.packeta.com/.

Intended audience

This manual is intended for technically advanced internet stores, which require and are able to implement custom interaction with embeddable application located at https://widget.packeta.com/.

Specifically, the following skills are required:

  • basic JavaScript programming
  • basic HTML/CSS knowledge

For basic scenarios, there is also the possibility of using Simplified Implementation Manual using Widget Configurator application.

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/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)

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 you may mirror (without automatic updating) and/or use in any way:

The library provides following methods:

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

Display pick-up point selection application.

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

Package.Widget.close()

Close any previously displayed pick-up point selection application. Will succeed even if none is currently open.

There is no return value.

Data structures

  • fields marked with * are optional and may not be present
  • fields without * mark are mandatory and will be always present

Options

Key Type Description
webUrl* string: URL Provide your e-shop address, either a full URL, or at least top level domain.
appIdentity string Provide the e-shop software name and version, and if applicable also Packeta module version.
E.g. "prestashop-1.6-packeta-4.1"
country string[2] Show only pick-up points from country specified with ISO 3166-1 alpha-2 code. If not set, all pick-up points from all countries will be displayed.
language string[2] Display user interface in language specified with ISO 639-1 code. If not set, browser preference will be used.
claimAssistant string If present and set to "yes", will only display pick-up points, which provide the Claim Assistant (Return Parcel) service. If present and set to any other value, will only display pick-up points which do not provide the Claim Assistant (Return Parcel) service.
packetConsignment string If present and set to "yes", will only display pick-up points, which provide new parcel consignment service. If present and set to any other value, will only display pick-up points which do not provide new parcel consignment service.
weight float If present, will only display pick-up points, which accept parcels of this weight in kilograms.
primaryButtonColor string: CSS color specifications Change application appearance.
backgroundColor string: CSS color specifications Change application appearance.
fontColor string: CSS color specifications Change application appearance.
fontFamily string: CSS font specification Change application appearance.
cssUrl string: URL No longer supported. You could provide your own stylesheet to be used in the application. Please make use of the font/color specifiers, and if you need more style changes, please contact Packeta technical support to consult adding more options from our side.

ExtendedPoint

  • there is always at most one of "error", "warning", "recommended" and "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. The only possible values are 5 and 10.
error null | string If not null, then indicates that you must not allow this pick-up 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 pick-up in such 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 indicates that you must discourage the customer from selecting this pick-up point. Possible values are:
almostFull The pick-up 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 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 null ("not available"), even if the pick-up point allows card payments for other clients.
saturdayOpenTo float Indicates if it's 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 it's 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 it's open at 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>. May be 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>. May be 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 string Is the pick-up point accessible to people on wheelchairs? Possible values:
yes
no
onRequest Wheelchair access possible with the assistance of pick-up point staff.
url string: URL Address of pick-up point detail website.
photos Photos Provides thumbnail and full size photos of pick-up point.
openingHours PointHours Provides HTML and structured information about pick-up point business hours.

GpsCoordinates

Field Name Type Description
lat float Latitude
lon float Longitude

Photos

  • an array of Photo objects, at least one

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.
upcoming* WeekHours2 Provides structured information about planned change of business hours.
exceptions* DatesHours Provides structured information about known exceptions to regular business hours. Includes national holidays.

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

WeekHours2

  • this structure extends WeekHours with following fields:
Field Name Type Description
startDate string: YYYY-MM-DD Date starting at which the WeekHours2 object data will be valid.

DatesHours

DateHours

Field Name Type Description
date string: YYYY-MM-DD Date for which this structure is valid.
hours string: Hours Business hours for the given date.

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