Magento

The Magento module allows a shop owner to implement the creation of orders in Boekuwzending.

Prerequisites

The minimum requirements for running this module in Magento are:

  • Magento 2.3
  • PHP 7.4
  • Composer < 2 (e.g. 1.10.19)

And all transitive dependencies specified in the composer.json which will be installed during the module installation.

Retrieve your credentials

To let the module communicate securely with the Boekuwzending API, you will need to request credentials. These credentials can be retrieved via the Mijn Boekuwzending platform. When logged in click on your username, navigate to "Integraties" and click the "Integratie starten" button next to Magento.

Enter your Shop URL and choose the default sender address. You can change this address when processing the imported orders.

After submitting with "Koppelen" you will be shown your credentials. Keep these credentials safe, you will need them later to configure the Magento module.

Installation

Magento Marketplace

Not yet supported.

Manual installation

To install the module in your Magento installation you need shell access (SSH) to the server. Assuming Composer is already present, in the Magento directory, execute the following commands:

bin/magento maintenance:enable 
composer require boekuwzending/magento 
bin/magento module:enable Boekuwzending_Magento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean
bin/magento maintenance:disable 

This is a common workflow for many Magento modules. First, the maintenance mode is enabled, ensuring no visitors of the site will encounter any errors. Then the module is downloaded from GitHub using Composer. Note that you'll need access keys for the Composer directory of Magento, available through https://marketplace.magento.com/customer/accessKeys/.

The Composer installation may take a while, as Composer carefully calculates all dependencies that are currently required and whether there will be any conflicts with the requirements of the module to be installed.

Then some Magento commands are run, which enable the module, upgrade the configuration and database, compile the classes for dependency injection (DI) and finally to clean the cache and disable the maintenance mode again.

Database

The setup:upgrade command utilizes the db_schema.xml of the module to create a new database table boekuwzending_order, which allows linking one Magento order to zero or more Boekuwzending orders.

Updating

When a new version of the module is released, you can update it using the following commands in the Magento directory:

bin/magento maintenance:enable 
composer update boekuwzending/magento 
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean
bin/magento maintenance:disable 

The same information as mentioned at the installation applies.

Composer can cache packages quite aggressively, so if you're trying to update to a version that was released recently, you might need to bypass the cache in the second command, replacing it with:

composer update boekuwzending/magento --no-cache

After running the composer command, you can verify the proper verison was installed using:

composer show | grep boekuwzending

You should see the expected version:

boekuwzending/magento     v1.0.1

Configuration

The module is configured from the Admin interface. You can find the settings under Stores -> Configuration -> Sales -> Delivery methods.

Boekuwzending for Magento: Configure the module
SettingDescriptionValues
Show delivery method in checkoutWhen enabled, customers can choose this delivery method. Whether this configuration value is enabled or not, the module will send all orders to Boekuwzending, whichever delivery method was chosen.Yes | No
TitleThe default title displayed for this shipping method, see also Usage below.Any string
Method NameThe default name of this shipping method, see also Usage below.Any string
Shipping cost without matrixA fixed shipping fee for shipments that don't use the shipping matrixNumeric with decimals, in the currency of the store.
Client IDThe id belonging to the integration you want to link to this shop.Any string
Client SecretThe secret belonging to the integration you want to link to this shop.Any string
Test modeWhen "Yes", orders are created in the staging environment of Boekuwzending. When Test mode is disabled, orders will be created in the live environment.Yes | No
Ship to Applicable CountriesIdentifies the countries where you offer this shipping method.All Allowed Countries - Customers from any country specified in the store configuration can use this shipping method.
Specific Countries - Customers from only specific countries (see option below) can use this shipping method.
Ship to Specific CountriesWhen the Ship to Applicable Countries option is set to "Specific Countries", you can select which countries here.Country selection
Show Method if Not ApplicableWhether this method should be shown if it can't be selected for the current order.No | Yes
Sort OrderAt which position to show this shipping methods. Only applicable if multiple shipping methods can be selected.Numeric

Usage

When configured, the shipping method looks like this:

Boekuwzending for Magento: Use the shipping method

Users can now select this shipping method. When placing the order, it is immediately forwarded through the Boekuwzending API, making it known in Imported Shipments at https://mijn.boekuwzending.com/.

Management

An order that is not linked to Boekuwzending looks like this:

Boekuwzending for Magento: Order not linked

Orders are usually linked on a one-to-one basis:

Boekuwzending for Magento: One order linked

It's also possible to click "Create new order" and split an order into multiple orders at Boekuwzending:

Boekuwzending for Magento: Multiple linked orders