With this interface you can connect Xentral to Shopware 5 to import orders from there to Xentral and manage your products sold in the shop in Xentral. The connection is realized via an API interface (Shopimporter).
Note
Please note that it is no longer possible to connect new shops using the shopimporter interface. To connect a new shop to Xentral, use our modern Xentral Connect interface. Existing shops can still be run using the shopimporter interface.
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 products 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 notes in Xentral with your own number range. The documents are automatically created and sent during the shipping process or printed on the shipping printer.
The following shows how you can connect your Shopware 5 shop 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 user name freely.
Under Administration → Shop interface → Overview → NEW you can create a new shop and select the Shopware 5 module.
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 back-end 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 the systems by clicking Check connection. 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, you only need to define a few settings and actions. 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 shop 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 shop (will be e.g. displayed in the product 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 shop 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 shop are to be imported manually (by pressing a button) or automatically
-
Demo (for testing) → The order status in the shop is not converted, no products or stock numbers transferred
-
Manual (with import center) → The orders are only retrieved when the button Pick up orders is clicked
-
Automatically (via process starter) → The orders are picked up automatically by the shop. For this purpose, the process starter Shopimporter is required
-
-
Only 1 order per request→ Only 1 order is transferred per request from the shop
-
Orders in intermediate table→ When picking up the orders, the orders are not created directly but 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 log file and the information will be logged.
-
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 a product 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 shop are automatically assigned to the appropriate group. By checking the box, a new customer group is created in Xentral, if no match is 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 shop. 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 item tree from Xentral to the Shopware 5 store
-
Get item list→ Imports products from your Shopware 5 shop to Xentral. Shop items that were already present in Xentral will be updated, missing products will be created. The products will be gradually fetched by the Artikelimport 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 product free fields to transfer specific data during the product 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 location. 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 to Xentral, 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 a product to be able to select properties as well. In Xentral the property set is stored and then exported to Shopware. For variant/matrix products you have to create the properties set in the main product in Xentral. If you store a property set with the name "mainArticle_notification" and a value of "1" for a product, 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 and 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 product
-
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 product data to Xentral. Furthermore, properties are only transferred as PropertyValues if the product 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 realized 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 realized 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 Product. The configuration looks as follows in the Shopware interface in Xentral (Administration → Shop interface → *select Shopware* → Details → Group mapping):
You define groups in the module Groups (Administration → Settings → Accounting → Groups) and they are displayed as follows:
In Shopware itself you set them up like this:
You can learn more about using Smarty in this help center article: Smarty at Shopimporter.
Information about this tab can be found here.
It is possible to import products from Shopware5 to Xentral.
Note
The import of meta fields can currently only be used from Xentral to SW5. For this, the meta fields must be maintained in Xentral or only the stock number sync may be used.
When importing products, there are various functions that are pulled during the transfer.
These functions are available for main and variant articles:
-
Product description
-
Product 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 for the product if the product numbers / SKUs are identical to the product numbers in Shopware.
These functions are only available for parent products:
-
Graduated prices
-
Short text
-
Description
-
Remaining quantity/sale
-
Sales tax
-
Manufacturer
-
Manufacturer number
-
Features
-
Cross-selling
-
Categories, including item tree
-
Images
-
Variants
Regardless of the settings and whether the product already exists, the following data are always imported:
-
EAN
-
Active/Inactive
-
Graduated prices
-
Pseudo prices
The rest of the data is imported only for newly created products. Alternatively, the transfer will only take place if you have specified in the importer settings that existing products should be overwritten.
The product import from Shopware5 is only to be seen as a basis for an product base. Depending on your needs, you must enrich the product import accordingly via the import/export center .
To initially pick up products from Shopware5, open the Shopware5 module and execute the Pick up article list action:
For the import of the products you need the following process starter: Artikelimport/getarticles. You may need to activate it in the process starter module.
How to export products from Xentral to Shopware 5, you will learn here.
How you can synchronize the stock figures, you can learn here.
How to import orders from online shops is described in this article.
The Shopware interface also allows you to import old orders from the shop to Xentral. Before importing orders, Xentral checks if there are already orders with this shop order number and will not import existing orders again. In the shop 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 shop 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 → Most current document number in the shop up to which the orders are to be collected. If you leave the field empty, the last 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 performed gradually in the background. For this you need the process starter shopimport_auftragarchiv. The import may take longer depending on the amount of orders.
Shopware allows the import of up to 1000 orders at the same time. 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 shop 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 shop 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 shop interface prevent the retrieval, 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 shop. 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 fully settled by an incoming payment.
To report the payment status back, you need the process starter shop_rueckmeldungen.
The Shopware interface allows you to export product images from Xentral to the shop. The prerequisite is that the images in Xentral are stored in the product master under Files with the keyword "Standard product image (shop image)". Only images with this keyword will be exported to the shop. More information about the export of product images can be found in this article.
The shipping costs are automatically imported in Xentral. In Shopware you can set the shipping costs to free of charge for purchases above a certain amount. Orders with shipping costs will normally be imported 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 shipping of the order is 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 product number in Shopware. During the import it will be mapped to the product number in Xentral. Prerequisite for this is that there is a product with this number in Xentral or that the number is a external number.
Alternatively, if you have selected the "Create missing items" option in the shop interface, a missing product 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 product export to the designated field.
In connection with the app "Crossselling" it is possible to maintain crossselling links between two products in Xentral and to transfer them to Shopware. In the Crossselling app, you can link products bidirectionally.
If you save the settings like this, the products in Shopware5 will be assigned to each other as accessory items.
Note that cross-selling takes into account external numbers. That means, if you set an external number for the shop 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 shop. 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.