With this interface you can connect Xentral to Shopware 5, to import orders from there to Xentral and manage your items sold in the store in Xentral. The connection is done via an API interface (Shopimporter).
Note
Xentral is compatible with all Shopware versions lower than 6.5.
-
Pick up orders from Shopware
-
Change order status on shipping incl. reporting tracking number to Shopware
-
Transfer articles from Xentral to Shopware or from Shopware to Xentral
-
Reporting of current stock figures in case of stock changes
You can create invoices and delivery bills in Xentral with your own number range. The documents are automatically created and sent in the shipping process or printed on the shipping printer.
The following shows how you can connect your Shopware 5 store to Xentral.
First, you need to create an API user in Shopware under Settings → User Management → Add User. Add an API user. This user will be used specifically for the Xentral interface. You have to set the API access to "activated". You can choose the username freely.
Under Administration → Shop interface → Overview → NEW you can create a new store and select the Shopware 5 module.
Note
Until version 21.1 it's via Administration → Online Shops / Marketplaces → NEW.
After you have selected Shopware 5, you can enter the necessary data for the connection of the two systems in the next step. You received the API key in the Shopware backend when you created the user for the interface.
-
API User → username of the user in Shopware, that was created for the interface
-
API Key → Generated API Key from User Management from Shopware
-
API URL → Shop URL + /api/, e.g. http://www.meinshop.de/api/
As soon as you have entered the data, you can test the connection between both systems by clicking the Check connection button. If the connection is successful, the message 'Connection: success' appears or, if the the interface recognizes subshops, a list of the recognized 'subshops' and their subshop IDs.
Note
You can access the API URL directly in your browser and enter the access data there.
If the connection fails, you can also authenticate via Digest.
To get started as quickly as possible, only a few settings and actions are required. What is necessary for a quick start with order import, stock number reconciliation and confirmation tracking numbers you can find out here.
This section explains the possible settings in the store interface.
When you open the settings of the Shopware5 interface, you will first land in the tab Details → Interface.
Settings:
-
Designation→ Name freely selectable for the store (will be e.g. displayed in the article and in the import menu)
-
Active→ Check to make sure the interface is active. You can set interfaces that are no longer needed to inactive.
-
Project→ Linking the store to a project. In the project you can use the logistics settings
-
Pickup mode→ With Shopware5 you can go according to a certain status or pick up from a number
-
Import mode→ Defines whether the orders from the store are to be imported manually (by pressing a button) or automatically
-
Demo (for testing) → The order status in the store not converted, no articles or stock numbers transferred
-
Manual (with import center) → The orders are only picked up, when the button Pick up orders is clicked
-
Automatically (via process starter) → The orders are picked up automatically by the store. For this purpose, the process starter Shopimporter is required
-
-
Only 1 order per request→ Only 1 order is transferred per request from the store
-
Orders in intermediate table→ When picking up the orders, the orders are not created directly, but are first stored in an intermediate table. Here you can decide which orders should be created and which should be imported later.
-
Limit number of pickups→ Option to limit incoming orders at once. If there is nothing (0) in it, the default limit of of 100
-
Logging in the logfile→ By setting the check mark you activate the logfile and the information will be logged in it.
-
API User → username of the user in Shopware, that was created for the interface
-
API Key → Generated API Key from User Management from Shopware
-
API URL → Shop URL + /api/, e.g. http://www.meinshop.de/api/
-
Canceled Status ID → 4 is entered here by default. The easiest way to find the ID is to perform a data export of a canceled order
-
ID Standard price group → 1 is entered here by default. To get the ID you have to output an article from the standard price group output
-
Limit to subshop → Here you have the possibility to to set up the interface for one subshop only, by entering the respective subshop ID in the field. The IDs will be displayed when you click on Check connection
-
Adopt user groups from store → Customer groups created in Shopware are taken over, for which a customer group mapping must be must be available. In combination with the following option. Create new user groups can also be used in Xentral to create new customer groups in Xentral
-
Create new user groups → Due to the customer group mapping new addresses from the store are automatically assigned to the appropriate group. By checking the box, a new customer group is created in Xentral, if no match could be found. Without the check mark users without a match will be assigned to the default user group in Xentral.
-
Create vouchers as stock items → Ordered vouchers are created as stock items (important, if they are sent physically e.g. as a voucher card)
-
Root category name → The categories are exported from Xentral to this root category
-
Use order ID instead of order number → This option may be useful if you cannot import orders by status or by order number. One reason for this could be that the order number changes from numeric to alphanumeric. The order ID is an internal database ID from Shopware 5
-
Pick up unpaid orders → Set check mark so that unpaid orders are picked up by Shopware.
-
Authentication via Digest → Check to perform an authentication via Digest (if the connection to the store fails).
Action
-
Check connection→ Checks the connection between both systems
-
Pick up orders→ Pickup orders from your store
-
Shopimport intermediate table→ Jumps to the intermediate table of orders from the store. The intermediate table is only filled in manual import mode and if the 'Orders in intermediate table' option is enabled. In the intermediate table you can choose in the left column between "Import", "Garbage" and "Later".
-
Import: Job is imported directly
-
Garbage: Job ends up in the garbage and cannot be imported a second time.
-
Later: Job can be imported at a later time
-
-
Transfer article tree → Transfers the article tree from Xentral to the Shopware 5 store
-
Get item list→ Imports items from your Shopify store to Xentral. Store items that were already present in Xentral will be updated, missing items will be created. The articles will be gradually fetched by the article import process starter after the action is executed.
-
Import old orders → Old orders will be loaded into the intermediate table, where you can decide if the requests should be imported or not.
Information about this tab can be found here.
Information about this tab can be found here.
Information about this tab can be found here.
For Shopware it is possible to use a "direct mapping" of article free fields to transfer specific data during the article export. For this purpose, the mapping of the free fields, and/or with the name of the characteristics the text modules "mainArticle_", or "mainDetail_" are prefixed to the mapping of the free fields or the names of the properties. Data, which is transferred, is passed over the API directly to the respective place. This allows you to address special fields for which there is no counterpart in Xentral or which were added by a plugin.
The free field mapping of the Shopware interface works in this extent only in one direction, namely for the export from Xentral to Shopware. When importing of free fields from Shopware toXentral, only fields starting with "attr" are considered and taken into account.
Scheme
Examples: Properties with the name "mainArticle_filterGroup" can address the properties set in Shopware. In Shopware you have to create an article to be able to select properties as well. In xentral, the property set is then stored and then exported to Shopware. For variant/matrix articles you have to create the properties set in the main article in Xentral. If you store a property set with the name "mainArticle_notification" and a value of "1" for an article, this will activate the field for email notification in Shopware.
The mapping of the free fields in the importer settings would ensure, that the data for the basic price calculation, as well as the publication date, the value for free shipping, as well as the value for the e-mail notification are transferred.
Possible fields under mainArticle
-
taxId - ID of the tax group
-
priceGroupId - ID of the price group
-
filterGroup - special field. Instead of the filtergroupid you can also specify the name of the filter group. If the name is the same as the one in Shopware the filter group id can be determined this way
-
filterGroupId - ID of the filter group
-
configuratorSetId - ID of the configurator set
-
pseudoSales - number of pseudo sales
-
priceGroupActive - Indicates whether price group is active.
-
notification - Allow email notification on article
-
availableFrom - Available from
-
availableTo - Available until
Possible fields under mainDetail
-
additionalText - additional info
-
stockMin - minimum quantity
-
purchasePrice - purchase price
-
position - position
-
minPurchase - minimum sales quantity
-
purchaseSteps - Sales steps
-
maxPurchase - maximum sale quantity
-
purchaseUnit - sales unit
-
referenceUnit - item unit
-
packUnit - ID packing unit
-
shippingFree - Free Shipping
-
releaseDate - release date
Note
If you use a direct mapping for a field that is already taken into account (for example, mainDetail_number for the article number, or mainArticle_name for the name), the value from the property or the field will override the actual value to be transferred from the item data to Xentral. Furthermore, properties are only transferred as PropertyValues if the item has a filter groupid. Otherwise PropertyValues are not transferred. All possible fields can be viewed directly via the API at under: shopurl/api/articles/ArticleIDofArticle.
If you have different subshops in Shopware 5, these can be mapped in the tab Subshop. Subshops are used e.g. for the separation by language or domain (e.g. meinshop.de and meinshop.com).
Note
The subshop mapping only works if you have set the subshops in Shopware as subshops and not as language stores!
Information about subshops can be found here.
Information about this tab can be found here.
Note
In Shopware 5 group prices for variant products can only be realised using the matrix product. Graduated prices cannot be transferred in Shopware 5, as no "valid to" can be defined.
The import of multiple graduated prices from Xentral to Shopware 5 can be realised using the price group mapping. In order to transfer graduated prices, the option Transfer graduated prices in the Settings must be activated. Please make sure that the customer group mapping is correct and that abbreviations within the shop and Xentral are identical. It is obligatory to enter the role customer. The configuration looks as follows in the Shopware interface in Xentral (Administration → Shop interface → *select Shopware* → Details → Group mapping, until version 21.1: Administration → Online shops / market places → *select Shopware* → Details → Group Mapping):
You define groups in the module Groups (Administration → Settings → Accounting → Groups) and they are dsiplayed as follows:
In Shopware itself you set them up like this:
You can learn more about using Smarty in this helpdesk article: Smarty in Shopimporter.
Information about this tab can be found here.
It is possible to import articles from Shopware5 to Xentral.
Note
The import of metafields can currently only be used from Xentral to SW5. For this, the metafields must be maintained in Xentral or only the stock number sync may be used.
When importing articles, there are various functions that are pulled during the transfer.
These functions are available for main and variant articles:
-
Article description
-
Item number, if set
-
Standard UK price
-
Pseudo prices
-
Active/Inactive
-
Delivery time
-
Weight
-
EAN
-
Free field, if mapping is set
Note
No foreign numbers are needed in the article if the article numbers / SKUs are identical to the article numbers in Shopware.
These functions are only available for main articles:
-
Graduated prices
-
Short text
-
Description
-
Remaining quantity/sale
-
Sales tax
-
Manufacturer
-
Manufacturer number
-
Features
-
Cross-selling
-
Categories, including article tree
-
Images
-
Variants
When importing, regardless of the settings and whether the item already exists, the following functions are always imported:
-
EAN
-
Active/Inactive
-
Graduated prices
-
Pseudo prices
The rest of the data is imported only for newly created items. Alternatively, the transfer will only take place if you have specified in the importer settings that existing articles should be overwritten.
The article import from Shopware5 is only to be seen as a basis for an article base. Depending on your needs, you must enrich the article import accordingly via the import-export center.
To pick up articles initially from Shopware5, open the Shopware5 module and execute the Pick up article list action:
For the import of the articles you need the following process starter: Articleimport/getarticles. You may need to activate it in the process starter module.
How to export articles from Xentral to Shopware 5, you will learn here.
How you can synchronize the stock figures, you can learn here.
Importing orders from online stores is described in this article.
The Shopware interface also allows you to import old orders from the Store to Xentral. Before importing the orders, Xentral checks if there are already orders with this store order number and does not fetch these orders again. In the store interface in Xentral you use the button Import old orders.
Once you have clicked on the button, you can specify in the dialog box, based on the the Shopware order numbers to specify which old orders should be picked up.
-
Number from → Oldest document number in the store from which the orders are to be collected. If you leave the field empty, orders will be picked up from the oldest order
-
Number to → Last document number in the store up to the orders that are to be collected. If you leave the field empty the latest order will be picked up
-
Complete job → The imported job is set to status "completed" status
-
Pick up canceled orders → Pick up orders that have the status "canceled" in the shop.
Click on the Pickup button to start the import. The import is then performed gradually in the background. For this you need the process starter shopimport_auftragarchiv. The import can take a longer time depending on the amount of orders.
Shopware allows the import of up to 1000 orders at once. Depending on the order quantity it is therefore not possible to import orders from previous years. Ideally, you should only import old orders that are absolutely necessary.
From the store you can also select individual orders directly by the order number in Shopware.
To do this, you need to set the following:
-
Pickup mode → From number (status)
-
from number → order number (for order numbers the letters in the string contain the ID of the order) enter
-
Only 1 order per request → Set check mark
The store status and in some cases also the payment status of the order must be be open in Shopware so that the order can be imported to Xentral. If settings in the store interface prevent fetching, it is sometimes faster to directly convert orders via the Shopware batch processing (order status → "open"). These orders will then be picked up during import and the status will be changed by the interface in Shopware from "open" to "in process". In the pickup mode "from number" you can pick up a specific order. Otherwise, only the pickup of the oldest, open order would be possible. Note that in a store where the order numbers do not consist of alphanumeric characters, the pickup from number will be automatically changed to the ID of the record of the order or must be converted.
The payment status of the orders can be reported directly back to the store. To do this, one of these requirements must be met:
-
The linked invoice to the order was set to paid manually.
-
The invoice linked to the order was completely settled by an incoming payment.
So that the payment status can be reported back, you need the process starter Store feedback.
The Shopware interface allows you to export item images from Xentral to the store. The prerequisite is that the images in Xentral are stored in the article master under Files with the keyword "Standard article image (store image)". Only images with this keyword will be exported to the store. Information about the export of article images you can find in this article.
The shipping costs are automatically imported to Xentral. In Shopware you can set the shipping costs to free of charge for purchases above a certain set. The orders with postage costs will be imported normally with a postage item and its price to Xentral. Postage free orders are imported with the postage item, but it is listed with 0,00 EUR, so the order is postage free for the customer.
If a subshop mapping exists and a translation of the free fields exists, the translation will be exported to Shopware.
From version 19.4 Xentral can process vouchers from Shopware. For this you have to create the voucher with article number in Shopware. During the import it will be mapped to the article number in Xentral. Prerequisite for this is that there is an article with this number in Xentral or that the number is a foreign number.
Alternatively, if you have selected the "Create missing items" option in the store interface, a missing item will be created automatically.
The option Transfer vouchers must be activated.
If the name of a property in Xentral is prefixed with articleAttribute_, you can export them directly as attributes to Shopware.
Example: The price history property is now created as "articleAttribute_PriceHistory" (instead of just "PriceHistory"). (instead of just "price history").
In Shopware's free text field management, the field is created with the appropriate name in the articles_attributes table.
The value of the property is then transferred from Xentral to Shopware during the article export to the designated field.
In connection with the app "Crossselling" it is possible to maintain crossselling links between two articles in Xentral and to transfer them to Shopware. In the Crossselling app, you can link articles bidirectionally.
If you save the settings like this, the items in Shopware5 will be assigned to each other as accessory items.
Note that cross-selling takes into account foreign numbers. That means, if you set a foreign number for the store it will try to use it.
Customer group mapping works in conjunction with the option "Assign new customers automatically". That means, if there is a mapping with activated option new addresses will be automatically assigned to the corresponding group. You can take over customer groups from the store. To do this, the abbreviation (the code number) must match exactly. If you have activated the option in the importer and there is a match, the address will be assigned to the group. Additionally, you can activate the checkbox "Create new user groups" in the importer settings. Then a new customer group will be created in Xentral if no match could be found.
Note that the group mapping in customer groups for Shopware currently does not work for the automatic mapping of groups.