[ENG] Magento 2.0

 

 

Below you will find the plugin and documentation on our proprietary InPost plugin for Magento 2.

The documentation describes the installation of the module, configuration and discusses the various functionalities of the module such as creating shipments and generating labels.

 

Changelog:

1.17.0 - 20.06.2024

  • New: new delivery method "Smart Courier"

1.16.1 - 18.04.2024

  • FIX: improvement of the reading of the date and time from the server in case of parcel settings at the weekend

1.16.0 - 07.03.2024

  • New: the ability to assign a specific size (A/B/C) to a product that assigns itself to an order automatically

1.15.2 - 08.02.2024

  • FIX: tokens for sandbox environment

  • FIX: limit the number of generated logs

1.14.5

  • FIX: correction of the operation of the Refund module

1.14.4

  • New: delete shipments in → Sales - InPost Shipments List → Operations: Delete InPost shipments

1.14.1

  • New: A6 labels for InPost Paczkomat® 24/7 shipments

  • New: remove +48 prefix when creating an order

 


Authorization

Production environment

You must have access credentials to connect to the ShipX API before installation:

  • Access Token (key)

  • ID organization

and

  • Access Token for Geowidget

Download a tutorial explaining how to quickly create access to the ShipX API and Geowidget on your own:

https://inpost.pl/sites/default/files/2022-03/instrukcja-konfiguracji-api-shipx.pdf

Test environment

Access generation

https://sandbox-manager.paczkomaty.pl/ > tab Moje konto > API

To generate a Token and an organization ID, you need to complete all the data, including billing details under My Account > Data. In order to create a Parcel Locker® shipment you need funds in your account, you will top up your account virtually in the Payments tab

Geowidget:

  • Access Token do Geowidget > tab Moje konto > API > Geowidget






Installation

The module should be installed first on a development or test installation and only after testing on a production store. The installation and enabling of the module should be done by a developer experienced with Magento 2 system

  1. The module files should be copied to the /app/code/Smartmage/Inpost directory

  2. Then run the following commands in the console, in the main Magento directory:

  • php bin/magento module:enable Smartmage_Inpost

  • php bin/magento setup:upgrade

  • php bin/magento setup:di:compile

  • php bin/magento setup:static-content:deploy pl_PL

  • php bin/magento cache:flush


 

Configuration

  1. The configuration of the module is divided into two areas visible in the Magento admin panel:

  • Stores → Configuration → Sales → Delivery settings → InPost section - here you can configure all general settings of the module and default values

  • Stores → Configuration → Sales → Delivery methods → InPost - Parcel Post section and InPost - Courier Delivery section - here you can configure all available delivery methods

 

  1. After installing the module, the configuration should start from:

→ Stores → Configuration → Sales → Delivery settings → InPost section

Here you need to fill in the fields "Organization ID" and "Access Token" and save the configuration. Only after completing and saving the data to the API can you configure the other fields from this section

 

Mode

Allows you to set the module in test or production mode. In test mode, you should have separate (intended only for the test environment) organization ID and Access Token access data. In test mode, a very small number of Parcel Machines are available for order processing, but all services work properly and do not incur costs. Under this field you can also check the currently installed version of the module.

Enable debugging

Setting this field to Yes will generate a log file in the /var/log/inpost/ folder with current information regarding communication with the ShipX API

Organization ID

The value needed to communicate with the InPost API. It can be downloaded from Parcel Manager

Access token

The value needed to communicate with the InPost API. It can be downloaded from Parcel Manager

Geowidget token

Since version 1.5.0 of the module, in order for the geowidget with the map of reception points to work properly, the geowidget token must also be specified

Economic package variant

In this field you need to complete the ID of the variant of the economic parcel given in the contract. Products ordered under the provided InPost Parcel® Economy Parcel service gain an attractive delivery price.

Label format

Allows you to specify the format in which labels will be downloaded. Available formats are PDF, EPL and ZPL.

Parcel locker shipment label size

Allows you to specify the size of the paper on which the label from the parcel locker shipment will be taken. Available sizes are A4 and A6. For courier shipments it is always A6, hence there is no separate selection

Automatically create order shipment

Setting this field to Yes will create a shipment for the order every time the InPost shipment receives a tracking number. If there is already a shipment for the order, another tracking number will be added to it

Notify the customer order shipment

If set to Yes, the customer will be notified by e-mail each time a shipment is created for the order or a tracking number is added to an existing shipment for the order. The field is visible if "Automatically create order shipment" is set to Yes

After creating the order shipment change order status to

Allows you to select what status the order will receive after creating the shipment for the order by this module. Here you should select the status that is available in a given store for the appropriate order status. The field is visible if "Automatically create order shipment" is set to Yes

Changing the sender's address

If set to Yes, fields will appear below allowing you to enter other sender data that will appear on the shipping label. It is important to fill out all the fields that appear

Sender

Fill in the data - it will appear on the sending label. The field is visible if "Change sender address" is set to Yes

Become a Partner (SzybkieZwroty.pl)

Link to the registration form in the SzybkieZwroty.pl system, which facilitates the handling of returns by store customers

URL address to dobrezwroty.pl

After registering in the dobrezwroty.pl system, you can enter the URL address in the customer form here. The value from this field is used as a link in the administration panel to handle returns for parcel locker shipments. The value from this field can also be used to display to customers in a place where they can decide to return the purchased goods, e.g. in the order preview. Such an individual modification in your store should be made by your developer

Product feature code with weight

Here you can enter the product feature code from which the weight of the products in the basket will be taken. By default, this is the “weight” feature

Weight unit

Allows you to select the unit in which product weights are given

Default dimensions

Allows you to set default dimensions for Courier shipments

Default dimensions (parcel lockers)

Allows you to set the default size for parcel shipments. The value from this field is used as the selected gab size when generating a shipment in the form from the order preview and when generating multiple shipments in the order list in the admin panel. If you select the "Use product feature" option, the largest gab size among the products in the order will be selected based on the product feature "InPost gabarit".

Automatically insure generated shipments

If set to Yes, the generated shipments will be insured by default for an amount equal to the total value of the order. If the setting is No, the shipments will not be insured by default or the insurance value will be taken from the default field below

Default insurance value

Allows you to define the default value that will be given in the shipment insurance field when it is generated. The field is only visible if the "Insure automatically generated shipments" field is set to "No

Pickup address

Pickup address from which parcels are to be collected when ordering collection by courier

Download shipments from x days ago

In this field, set the number of days for which the list of shipments will be updated. For example: if 60 days is set (default value), only shipments from the last 60 days will be updated, older ones will not

 


 

Configure delivery methods

In the next step, configure and enable the selected delivery methods in:

→ Stores → Configuration → Sales → Delivery methods → InPost - Parcel Machines section and InPost - Courier Delivery section

 

InPost Parcel Machine method configuration section

In the Magento admin panel, in:

Stores → Configuration → Sales → Delivery Methods → InPost - Parcel Machines section → you will find the following configuration fields regarding Parcel Machines delivery methods

Enabled - this field allows you to enable Parcel Machines delivery methods. Each of the Parcel Machines delivery methods also has its own field to be enabled, and in order to be visible in the order process they must both be set to Yes

Only show delivery on the weekend when active - if set to Yes then while the weekend Parcel Machine delivery is active the regular Parcel Machine delivery method is not visible in the order process. If set to No then while the Parcel Machine delivery method is active it is visible in the order process along with the regular Parcel Machine delivery method.

Title - the title of the delivery method

 

image-20240208-105130.png

Below are the groups for each of the Parcel Machine delivery methods:

InPost Paczkomat® 24/7

In this section you will find the configuration fields for the Parcel Machine delivery method (the service in the API is inpost_locker_standard):

 

Enabled

allows you to enable the delivery method to be visible in the order process

Method name

the name under which the delivery method will be visible in the order process

Price

price of the delivery method

Enable free shipping threshold

 if set to "Enable", a field will appear below which allows you to set the minimum order amount for which shipping using this method will be free

Free shipping threshold

the field is visible if "Enable free shipping attempts" is set to "Yes". Allows you to enter the amount above which orders will be eligible for free delivery using the current method

Whether the free shipping threshold includes tax

allows you to determine whether the value of the field above, from which free shipping starts for a given delivery method, is a net or gross amount

Position

allows you to enter a number that will be used to sort delivery methods in the order process

Logo in the order process

allows you to select a file with the delivery method logo that will appear in the order process

Maximum basket weight

allows you to determine the maximum weight of the products in the customer's basket so that the current delivery method is available in the order process. To determine the weight of products, the value of the feature whose code is entered in the "Product feature code with scale" field in the general configuration of the module and the unit of this weight specified in the "Weight unit" field are taken

Default shipping method

allows you to define the default shipping method for the current delivery method. The value from this field is used as the default value in the form for generating a shipment from the order preview (then it can be changed) and when creating multiple shipments on the order list in the administrator panel for orders that have the current delivery method selected

Default shipping point

if "Sending at a Parcel Locker" or "Sending at a POP" is set in the field above, the value from this field will be the selected shipping point. The value from this field is used when generating shipments

Shipping to selected countries

allows you to choose whether a given delivery method is available for all countries allowed in the ordering process or only for selected ones that can be set in the field below

Selected countries

the field is available if "Selected countries" is set in the field above. Here you can indicate for which countries the current shipping method will be available. Only Poland is selected by default

PaczkoPunkty available

allows you to decide whether the so-called PaczkoPunkty. Even if the availability of PaczkoPunkt is disabled here, the so-called SuperPOP points


InPost Paczkomat® 24/7 - cash on delivery

This section contains the same fields as the one described above.

They concern the delivery method to the Parcel Machine on delivery (the service in the API is inpost_locker_standard).

If you have selected this delivery method in the order process, the amount of COD will be automatically set equal to the order total when creating the shipment


InPost Paczkomat® 24/7 - weekend delivery + payment on delivery

This section contains the same fields as in the InPost Paczkomat® 24/7 section, plus some additional ones described below. Here you can enable the delivery method for Parcel Machines with weekend delivery

This method can be visible in the order process only during the set time interval because parcels will be delivered to customers on the weekend

When configuring the time frame for the activity of this delivery method, so remember that it is the moment of sending and not the moment of placing the order by the customer that is important

 

The fields that allow you to configure the time interval are as follows:

Weekday of the week for weekend delivery - allows you to select on which day of the week the weekend delivery method will start to be active

Weekend delivery start time - allows you to select at what time on the day set in the earlier field the weekend delivery method will start to be active

Weekday of the weekend delivery end - allows you to select on which day of the week the weekend delivery method will cease to be active

Weekend delivery end time - allows you to select at what time on the day set in the earlier field the weekend delivery method will cease to be active


InPost Paczkomat® 24/7 - Paczka Ekonomiczna + cash on delivery

This section contains the same fields as the one described above. They concern the delivery method to the Parcel Machine in the option "Economy Parcel".

When enabling this delivery method in the ordering process, make sure that after selecting it, the corresponding payment method will be available which is not part of this module


 

InPost Courier method configuration section

In the Magento admin panel, in:

Stores → Configuration → Sales → Delivery Methods → InPost - Courier Delivery section, you will find the following configuration fields regarding courier delivery methods.

Enabled - the field allows you to enable courier delivery methods. In addition, each delivery method has its own field to be enabled, and in order for it to be visible in the order process they must both be set to Yes

Title - the title of the delivery method

Below are the groups for each courier delivery method separately. You can enable and configure the selected ones

 


InPost przesyłka kurierska standardowa

 

Enabled

allows you to enable the delivery method to be visible in the order process

Method name

the name under which the delivery method will be visible in the order process

Price

price of the delivery method

Enable free shipping threshold

 if set to "Enable", a field will appear below which allows you to set the minimum order amount for which shipping using this method will be free

Free shipping threshold

the field is visible if "Enable free shipping attempts" is set to "Yes". Allows you to enter the amount above which orders will be eligible for free delivery using the current method

Whether the free shipping threshold includes tax

allows you to determine whether the value of the field above, from which free shipping starts for a given delivery method, is a net or gross amount

Position

allows you to enter a number that will be used to sort delivery methods in the order process

Logo in the order process

allows you to select a file with the delivery method logo that will appear in the order process

Maximum basket weight

allows you to determine the maximum weight of the products in the customer's basket so that the current delivery method is available in the order process. To determine the weight of products, the value of the feature whose code is entered in the "Product feature code with scale" field in the general configuration of the module and the unit of this weight specified in the "Weight unit" field are taken

Default shipping method

allows you to define the default shipping method for the current delivery method. The value from this field is used as the default value in the form for generating a shipment from the order preview (then it can be changed) and when creating multiple shipments on the order list in the administrator panel for orders that have the current delivery method selected

Default shipping point

if "Sending at a Parcel Locker" or "Sending at a POP" is set in the field above, the value from this field will be the selected shipping point. The value from this field is used when generating shipments

Shipping to selected countries

allows you to choose whether a given delivery method is available for all countries allowed in the ordering process or only for selected ones that can be set in the field below

Selected countries

the field is available if "Selected countries" is set in the field above. Here you can indicate for which countries the current shipping method will be available. Only Poland is selected by default


InPost przesyłka kurierska standardowa - cash on delivery

In this section you will find the same fields as in the one described above

If you have selected this delivery method in the order process, then when you create the shipment, the collection amount equal to the order total will be automatically set. When enabling this delivery method in the order process, make sure that after selecting it, the corresponding payment method which is not part of this module will be available

 


InPost - Kurier C2C + cash on delivery

In this section you will find the same fields as in the one described above

Cash on delivery - If you have selected this delivery method in the order process, the amount of cash on delivery equal to the order total will be automatically set when creating the shipment. When enabling this delivery method in the order process, make sure that after selecting it, there will be an appropriate payment method available which is not part of this module

 


InPost - Przesyłka kurierska 10:00/12:00/17:00

Service for delivery of shipments to the specified time

Here you will find the same fields as described in the section InPost standard Kurier delivery and have analogous purpose


InPost - Smart Courier

A service combining delivery of goods with electronic document circulation. The service is dedicated to the delivery of goods that require personal delivery with confirmation of recipient data. The delivery process requires verification of the addressee with such data as name, surname, age.

The service is available after enabling this method in a specific product.

 

 


Checkout

The module is adapted to the standard order process available in the default Magento 2 Luma template. Therefore, if your store uses a different store template or order process, it may require adjustment to function properly. First of all, you should pay attention to ensuring the validation of the Parcel Locker selection for Parcel Locker delivery methods and the correct operation of the selected Parcel Locker record

In the ordering process, after configuring the module and enabling selected services, the currently active delivery methods will appear

Depending on the configuration, delivery methods to the Parcel Locker may be visible both in the standard version and with weekend delivery, or alternatively - either standard or weekend delivery. For each delivery method to the Parcel Locker, there is a button that allows you to open a map (Geowidget) to search for a selected point

 

  • Courier delivery methods do not have any additional options - they are simply available if you have enabled them in the configuration

  • In addition, each delivery method displays the logo corresponding to the type of service


 

Transactional emails

After placing the order, the customer receives only the name of the selected delivery method in the standard e-mail template with order confirmation, e.g. "InPost Kurier - Kurier - delivery until 12:00". However, you can add information about the selected Parcel Locker to the email template using the following code in the template content:

{{trans "Parcel locker number: %paczkomat" paczkomat=$order.inpost_locker_id}}

However, remember to add conditions checking whether the appropriate delivery method has been selected in which the Parcel Locker has been selected


 

Order preview in the administrator panel

In the administrator panel, in the order preview, there is a new section "Przesyłki InPost" which displays a drop-down list with available InPost services and a button that takes you to the shipment generation form

The service that was selected by the customer in the ordering process (if it was a service provided by this module) is selected by default in the drop-down list

 

 

If there are already generated shipments for a given order, a table with a list and details of the shipments will appear in the "InPost Shipments" section

Right after generating the shipments, the data in this table may be incomplete due to the asynchronous process of assigning tracking numbers in the API ShipX

As a result, tracking numbers will appear with a delay. The shipment list in Magento is refreshed cyclically every 30 minutes or can be manually refreshed by clicking the "Refresh list" button in the admin panel in Sales → InPost Shipment List.

For parcels delivered to a Parcel Locker, the table allows you to preview the selected Parcel Locker or POP point on the map after clicking the "Show on map" link

 

Additionally, for each shipment it is possible to download the shipment label by clicking the "Print label" button - the label generated for a given shipment will be downloaded in the size and format set in the configuration

The last column also shows the "Return" button - for courier shipments, it generates a return label that will be downloaded after clicking it. For parcel locker shipments, clicking it redirects you to https://szybkiezwroty.pl/

The button is unavailable for the "Standard courier delivery for individual customers" services (inpost_courier_c2c and inpost_courier_c2ccod)

If a link to this website is set in the configuration, it will be used for redirection


Generating an InPost parcel

In the order preview in the admin panel by clicking on the "Send" button in the "InPost shipments" section, you will be redirected to the shipment generation form which will look different depending on the selected service

For courier services it will look as follows:

 

The following fields are located here:

 

Order number

Numer zamówienia dla którego jest generowana przesyłka. Zaraz obok wyświetlana jest suma zamówienia

Service

Wybrana usługa dla której tworzona jest przesyłka

Shipping method

Symbol Paczkomat lub punkt POP. Domyślnie to pole jest wypełnione symbolem wybranym przez klienta

Width, length, height

Sposób w jaki przesyłka będzie nadana. Domyślnie wybrana wartość z konfiguracji aktualnej usługi

Weight

Gabaryt w jakim zmieści się przesyłka. Domyślnie wybrany jest gabaryt który ustawiono w konfiguracji modułu

Insurance value

Suma na jaką będzie ubezpieczona przesyłka. Jeśli w konfiguracji modułu zaznaczono aby przesyłki były automatycznie ubezpieczane to tutaj domyślnie wstawiona zostanie suma zamówienia

Reference number

Informacja tekstowa która zostanie umieszczona na etykiecie nadawczej przesyłki. Domyślnie wstawiony jest tutaj numer zamówienia

"Address data" section

W przypadku Paczkomat tutaj potrzebny jest tylko adres email (pobrany z zamówienia) oraz numer telefonu (pobrany z adresu dostawy zamówienia)

After filling in all the data, click the "Create shipment" button which will redirect to the order preview with the corresponding message

If any errors occur during shipment generation, the operator will be returned to the shipment generation form with the information provided and a message describing the error:

 

If the "Automatically create shipment to order" box is checked to "Yes" in the module configuration, then after the InPost shipment is created and the tracking number is downloaded to it, a shipment to order will be created for the corresponding order

 


 

Generate InPost Parcel for multiple orders

In the list of orders in the admin panel, it is possible to generate shipments for multiple orders at once. This can be done by selecting the selected orders and selecting "Create InPost shipments" or "Create InPost shipments and print" from the "Operations" drop-down list (which will print the labels right away).

 

The mechanism of generating multiple shipments at the same time is based on the following assumptions:

  • InPost shipments are generated only for orders that have one of the delivery methods provided by this module selected (if the operator would like to generate an InPost shipment for an order that has a different delivery method selected, it is still possible to do so individually in the order preview)

  • For each order, a shipment is generated using the service selected by the customer

  • All data needed to generate a shipment are taken from the order or from the module's default settings, so you must first configure all the default settings of the module and delivery methods

  • If errors occur when creating a shipment for any of the orders, that particular order will be omitted, but subsequent orders will still have shipments created.

  • If any errors occur while generating the shipment, they will all be listed in messages after the process is completed

 

After completing the process of generating shipments, appropriate messages will appear with information about the generated shipments and the reasons why others were not generated:


 

 

Shipment list

 

The administrator panel contains a list of shipments that are available to the operator after configuring API access data in the module configuration.

The list is available in the Sales menu → InPost Shipments List

The table visible in this view is refreshed by a cron job (which should be properly configured for the Magento system) every 30 minutes. Additionally, you can use the “Refresh List” button to update it.

The table contains the following columns:

Identifier

Internal identifier of the shipment

Shipment number

This is the number from the InPost system

Tracking number

Tracking number which is also a link that opens the shipment tracking page in a new tab, e.g. https://inpost.pl/sledzenie-przesylek?number=603422536921560020496431 (tracking on the InPost website does not work for shipments in test mode)

Order number

The order number to which this shipment is associated, which is a link to the preview of this order. If the shipment was created outside the current module, the value in this column will be empty

Status

Shipment status, which is a link that opens the tracking page in a new tab

Service

Name of the service under which a given shipment was created

Features of the shipment

Declared dimensions and weight of the shipment

Shipping method

Tthe method in which the shipment will be sent

Recipient's details

Address details of the recipient of the shipment

Reference number

The reference number that will appear on the label. By default, this is the order number from Magento, but you can change this field when creating a label from the order preview

Collection order number

For shipments for which a collection order has been created, its number will be displayed here

 

After selecting the appropriate shipments with the checkbox in the first column, the following operations will also be available:

 

Print label

Will download a file for printing the shipping label in the format set in the module configuration

Print return label

For courier shipments (except "Standard courier shipment for individual customers") will download a label file that can be used to return the shipment in the format set in the module configuration

Order collection order

Will generate a collection order for the selected shipments

Print the collection order label

For shipments that have already generated a collection order, it allows you to print a document confirming receipt by the courier

Delete InPost shipments

After additional confirmation, it allows you to delete selected shipments from the database. Please remember that during the next synchronization, shipments from the specified period of time (see the "Download shipments from x days ago" field) will be added to the database again.

 


 

Contact

If you have any questions, please use the Integration Department's contact form, which is available here: https://inpost.pl/formularz-wsparcie  

 After entering the form, just select "Wsparcie Klienta” from the list, in the category select: Moduł InPost, and in the field "Proszę podać nazwę modułu” enter: Magento