Packeta API

Documentation

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:

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)
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.
`depth`	`integer`	no	If present, it will only display pick-up points, that accept parcels of this depth 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/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.
`cashOnDelivery`	`boolean`	no	Whether cash on delivery is specified.
`width`	`integer`	no	Width of the parcel in centimeters. `*`
`length`	`integer`	no	Length of the parcel in centimeters. `*`
`depth`	`integer`	no	Depth of the parcel in centimeters. `*`

* The dimensions are optional and can be specified in any order.

`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"
      }
    ],
    "width": 40,
    "length": 30,
    "depth": 20
  }
}

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.
`NoCashOnDelivery`	The pick-up point does not accept cash on delivery.
`InvalidDimensions`	The pick-up point does not accept parcel with given dimensions.

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."
    }
  ]
}

Packeta API

Documentation

Standard implementation manual

Supported browser versions

Intended audience

Important information

Functional cookies

Quick start – examples

Basic embedable application implementation details

Integration library – methods

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

Packeta.Widget.close()

Data structures

Options

Vendor

Point

GpsCoordinates

ExceptionDay

Time

Photo

PointHours

WeekHours

string: Hours

Validation of selected pick-up point

Request

Headers

Parameters

ValidatedOptions

ValidatedVendor

ValidatedPoint

Example

Response

ValidPoint

ValidPointAddress

Error codes

Example

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

`Packeta.Widget.close()`

`Options`

`Vendor`

`Point`

`GpsCoordinates`

`ExceptionDay`

`Time`

`Photo`

`PointHours`

`WeekHours`

`string: Hours`

`ValidatedVendor`

`ValidatedPoint`

`ValidPoint`

`ValidPointAddress`