Standard Implementation Manual

This document contains information regarding standard implementation of Packeta pick-up point selection, using an embeddable application (widget) 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 the widget.

Specifically, the following skills are required:

  • Basic JavaScript programming
  • Basic HTML/CSS knowledge

Important information

If you want to use external pick-up points:

  • Once the widget is successfully implemented, using the Packeta integration library library.js as mentioned below, to display external pick-up points it is still necessary to turn this option on at Packeta client section
  • To see the pick-up points in a specific country, make sure the country is enabled at Packeta client section
  • Once the country is newly enabled, the change will apply to your widget within maximum 90 minutes

What is important to know?

  • Your widget will work correctly only if you have a correctly configured API key. Your key can be found at Packeta client section, or it can be provided by your account manager.

Functional cookies

Argument Type Max-age Description
branchId string 2147483647 Stores and identifier of the last selected pick-up point. When end user visits any eshop, the widget centers the map to the pick-up point.
favorite-pickup-points string 2147483647 Stores identifiers of pick-up points marked as favorite. User can list his/her favorite pick-up points in the widget.

Quick start – examples

We provide an integration library, which you may mirror (without automatic updating) and/or use in any way:

Name Link Description Expiration
library.js https://widget.packeta.com/v6/www/js/library.js For e-shops that do not verify file integrity. permanently
library-1.0.1.js https://widget.packeta.com/v6/www/js/library-1.0.1.js For e-shops that verify file integrity. last version
  • Example using the library: configurator
  • Please note you have to provide your API key, for the example to work correctly.

Basic embedable application implementation details

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

You can find the integration library as defined at the Quick start – examples paragraph.

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 at 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 Object: Options 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()

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 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.
livePickupPoint boolean no If present and set to true, only pick-up points where age 18+ verification service is available are displayed.
expeditionDay string: YYYY-MM-DD no Expected date of the parcel expedition. A pickup point will be unavailable when the shipping date falls within the pickup point´s holiday that lasts more than 3 days.

ExtendedPoint

  • There is always at least one of "error", "warning", "recommended" or "isNew" set (not null, not false).
Field Name Type Description
id string For internal pick-up points: Branch ID; For external pick-up points: External carrier's pick-up point code.
name string Name which usually means city and street address. For large cities also includes city district.
nameStreet string Name which usually means city and street address. For large cities also includes city district. OBSOLETE - Use field name instead.
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. OBSOLETE - Use the field exceptionDays instead
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. OBSOLETE - Use the field exceptionDays instead
exceptionDays Array: ExceptionDay Contains holidays, exceptions or changes from opening hours.
wheelchairAccessible boolean Is the pick-up point accessible to people on wheelchairs?
url string: URL Address of pick-up point detail web page OBSOLETE - Use field branchCode instead.
branchCode string Only for internal pick-up points: Unique URL safe identifier to be used in an address of a pick-up point detail web page
photo Array: Photo Provides thumbnail and full-size photos of pick-up point.
photos Array: Photo Provides thumbnail and full-size photos of pick-up point. OBSOLETE - Use field photo instead.
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 Only for external pick-up points: External carrier ID
carrierPickupPointId string Only for external pick-up points: External carrier's pick-up point code

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.
exceptions OBSOLETE - Use field 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 pick-up point

Selection of pick-up is done entirely on end user's device. Technically skilled user is able to bypass our validation (allowed pick-up 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 on URL https://widget.packeta.com/v6/api/pps/api/widget/validate. HTTP method is POST.

Request

Headers

Header Name Type Required Description
X-Language string no Language code in format ISO 639-1. 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.

Property 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.
id string yes ID of selected pick-up point.
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 pick-up points.
claimAssistant boolean no If present and set to true, selected pick-up point must provide Claim Assistant service.
packetConsignment boolean no If present and set to true, selected pick-up point must provide new parcel consignment service.
weight float no If present, selected pick-up must accept parcels of this weight in kilograms.
livePickupPoint boolean no If present and set to true, selected pick-up point must provide age verification service.
expeditionDay string:YYYY-MM-DD no Expected date of the parcel expedition. The selected pick-up point must not have a holiday of more than 3 days during this date.

Example

Example request body:

{
    "apiKey": "<your-api-key>",
    "id": "<id-of-selected-pick-up-point>",
    "country": "cz,sk",
    "carriers": "packeta",
    "weight": 3.1,
    "livePickupPoint": true,
    "expeditionDay": "2022-08-31"
}

Response

Possible HTTP status codes of the response:

Status code Description
200 Pick-up 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 pick-up point meets all the criteria of the validation request and the e-shop settings. In case of false inspect errors property.
errors array An array which contains all discovered validation errors with their error codes and descriptions.

Error codes

Error code Description
NotFound The pick-up point was not found.
InvalidCarrier The pick-up point has not allowed carrier.
InvalidCountry The pick-up point is not in allowed country.
EmptyListOfAllowedCountries Cannot perform country validation because the list of allowed countries is empty.
NoClaimAssistant The pick-up point does not offer Complaints Assistant Service.
NoPacketConsignment The pick-up point is not submission point.
InvalidWeight The pick-up point does not accept packets with given weight.
NoAgeVerification The pick-up point does not offer Age Verification Service.
PickupPointVacation The pick-up point currently does not accept any packets due to reported holiday.
PickupPointClosing The pick-up point does not accept new shipments because it will be closed soon.
PickupPointIsFull The pick-up point does not accept any packets at the moment due to its full capacity.
PickupPointForbidden The pick-up point cannot be selected.
PickupPointTechnicalReason The pick-up point cannot be chosen as a final destination of your packet due to technical reasons.

Example

Example response body:


{
    "isValid": false,
    "errors": [
        {
            "code": "NoAgeVerification",
            "description": "The pick-up point does not offer Age Verification Service."
        }
    ]
}