[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.
Plugin: 1.17.0 - 20.06.2024r
https://inpost.pl/sites/default/files/2024-06/Magento-2-ver-1.17.0.zip
Changelog:
On this page:
- 1 Authorization
- 2 Installation
- 3 Configuration
- 4 Configure delivery methods
- 5 Checkout
- 6 Transactional emails
- 7 Order preview in the administrator panel
- 8 Generating an InPost parcel
- 9 Generate InPost Parcel for multiple orders
- 10 Shipment list
- 11 Contact
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
The module files should be copied to the /app/code/Smartmage/Inpost directory
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
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
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
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