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 who 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, that 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.7.js https://widget.packeta.com/v6/www/js/library-1.0.7.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, that 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 (that 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 that will be called when the user confirms or cancels pick-up point selection. The function will receive one argument, that will be either an Point object if pick-up point was selected, or null if selection was cancelled. To get selected pick-up 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 be always 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 pickup-point vendors. Only the specified vendors and their pickup-points will be displayed. If not present, all vendors and all pickup-points will be displayed. Available vendors respect the Allowed branch settings in the Packeta client section.
country string no 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 Packeta client section. Country restricts the list of pickup-point vendors. Consider using the vendors field.
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. Carriers restrict the list of pickup-point vendors. OBSOLETE - Use the field vendors instead
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, that provide the Claim Assistant (Return Parcel) service. If present and set to any other value, it will only display pick-up points that 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, that provide new parcel consignment service. If present and set to any other value, it will only display pick-up points that do not provide new parcel consignment service.
weight float no If present, it will only display pick-up points, that accept parcels of this weight in kilograms.
length integer no If present, it will only display pick-up points, that accept parcels of this length in centimeters.
width integer no If present, it will only display pick-up points, that accept parcels of this width in centimeters.
height integer no If present, it will only display pick-up points, that accept parcels of this height 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 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 pick-up point will be unavailable when the shipping date falls within the pick-up point´s holiday that lasts more than 3 days.
defaultPrice float no Default vendor's shipping price. If not specified, no shiping price will be displayed.
defaultCurrency string no Default vendor's currency. ISO 4217 currency alphabetic.
centerExternalId string no If present, centers the map to the pick-up point.

Vendor

  • Vendor of pickup 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 zpoint Group of the Packeta internal carrier. Either zbox or empty for zpoint.
selected boolean no If present and set to true, the vendor vill 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 alphabetic.

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 pick-up points: Branch ID. For external pick-up points: External carrier's pick-up point code. For external pickup-up points use fields carrierId and carrierPickupPointId instead.
name string Name that usually means city and street address. For large cities also includes city district.
nameStreet string Name that usually means city and street address. For large cities also includes city district. OBSOLETE - Use field name instead.
country string[2] Country code. ISO 3166-1 alpha-2 code in lower case.
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 pick-up 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 pick-up 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 pick-up 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
group string Only for Packeta internal pick-up points: Group of pick-up point. Either zbox or empty for zpoint.
externalId string Unique identifier

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 at URL https://widget.packeta.com/v6/api/pps/api/widget/v1/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.

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 Branch ID.OBSOLETE - Use ValidatedPoint instead
carrierId string for external points External carrier ID.OBSOLETE - Use ValidatedPoint instead
carrierPickupPointId string for external points External carrier's pick-up point code.OBSOLETE - Use ValidatedPoint instead
country string no Comma separated list of allowed countries, specified with ISO 3166-1 alpha-2 code in lower case.OBSOLETE - Use ValidatedOptions instead
carriers string no Comma separated list of allowed carriers, or string packeta for Packeta internal pick-up points.OBSOLETE - Use ValidatedOptions instead
claimAssistant boolean no If present and set to true, selected pick-up point must provide Claim Assistant service.OBSOLETE - Use ValidatedOptions instead
packetConsignment boolean no If present and set to true, selected pick-up point must provide new parcel consignment service.OBSOLETE - Use ValidatedOptions instead
weight float no If present, selected pick-up must accept parcels of this weight in kilograms.OBSOLETE - Use ValidatedOptions instead
livePickupPoint boolean no If present and set to true, selected pick-up point must provide age verification service.OBSOLETE - Use ValidatedOptions instead
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.OBSOLETE - Use ValidatedOptions 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 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.
vendors Array: ValidatedVendor no List of vendor options.

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 zpoint Group of the Packeta internal carrier. Either zbox or empty for zpoint.

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 pick-up point code.

Example

Example request body:

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

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.
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
country string yes if carrierId is not present Country of the Packeta internal carrier. ISO 3166-1 alpha-2 code. OBSOLETE - Use ValidPointAddress.country instead
group string yes if carrierId is not present and group is not zpoint Group of the Packeta internal carrier. Either zbox or empty for zpoint.

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 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.
HasClaimAssistant The pick-up point offers Complaints Assistant Service.
NoPacketConsignment The pick-up point is not drop-off point.
HasPacketConsignment The pick-up point is drop-off 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.
InvalidVendor The pick-up point has not allowed vendor.

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 pick-up point does not offer Age Verification Service."
    }
  ]
}