SFTP-SOAP-to-Shop (EN)
- Jennifer Pusch
- vTranslator
- Rainer Biedermann
General
This documentation describes the transfer method of the SOAP interface for the import of
Product and category data
Customer data
Voucher data
SFTP transfer
The import files themselves must first be transferred to the shop server via SFTP. You will receive an SFTP account from WEBSALE AG for this purpose. A common SFTP account for customer and voucher data. A separate SFTP account for product data.
Import of product data
Transfer the import files to the subdirectory "directimport" on the shop server and then start the import via the SOAP interface. If the directory does not exist, then you need to create it. As "Scope" (see below) "Products" will be sent. Format and content of the import files are described in the documentation
Format and content - WS-SFTP-Produkte PRO (EN)
Please note:
Before product or category data can be imported, the required subshops and free fields must be created using the WSPManager.
Import of customer data
Transfer the import files to the "customerimport" subdirectory on the shop server and then start the import using the SOAP interface. If the directory does not exist, then you need to create it. Send "customers" as the "scope" (see below). Format and content of the import files are described in the documentation
Format and content - WS-SFTP-Kunden PRO (EN)
Import of voucher data
Transfer the import files to the "voucherimport" subdirectory on the shop server and then start the import via the SOAP interface. As "Scope" (see below) "Vouchers" will be sent. Format and content of the import files are described in the documentation
Format and content - WS-SFTP-Gutscheindaten (to-Shop) (EN)
Starting the import (StartImport)
The "StartImport" command starts the import and returns a SessionID which is used for follow-up calls. The import starts asynchronously. Use the "GetProgress" function to query the progress of the import. By means of "GetResult" an error list is sent.
The import is still running if GetProgress returns "Finished=false".
The import is finished, if GetProgress returns "Finished=true". Afterwards an error list is requested with "GetResult" to check if all records were imported correctly.
Request parameters
Name | Description |
|---|---|
ShopID | The ID of the shop for which the import should be started |
Password | Password for the service |
Scope | Allows to limit the import to specific files "All" or empty: all files on the server "Products": Import products only "Customers": Import customer data only "Vouchers": Import voucher data only Multiple entries can be combined in a comma separated list, e.g. "Products,Vouchers". |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:StartImport>
<request>
<ShopID>testshop</ShopID>
<Password>xyz</Password>
<Scope>All</Scope>
</request>
</ns:StartImport>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Output parameters
Name | Description |
|---|---|
SessionID | The session ID for subsequent calls. |
Example of server response:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:StartImportResponse>
<response>
<SessionID>123</SessionID>
</response>
</ns:StartImportResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Query progress (GetProgress)
This command allows to query whether the import process is still running and how far it has progressed.
Input parameters
Name | Description |
|---|---|
ShopID | The ID of the shop |
Password | Password for the service |
SessionID | The SessionID supplied by "StartImport |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:GetProgress>
<request>
<ShopID>testshop</ShopID>
<Password>xyz</Password>
<SessionID>123</SessionID>
</request>
</ns:GetProgress>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Output parameter
Name | Description |
Finished | "true" if the import is finished, otherwise "false". |
Progress | A number from 0 to 100 indicating the progress of the import. "Progress" can have the value "100" even though the import is still running, so query "Finished" if you want to know if the process is finished. |
Example:
Query imported new customers (GetAddedCustomers)
With this command you can query the key fields UserIndex, CustomerId and EMail for the successfully created new customer records. Especially the query of the UserIndex is important, because this key field must be used for addressing in all following updates.
Input parameter
Name | Description |
|---|---|
ShopID | The ID of the shop |
Password | Password for the service |
SessionID | The SessionID supplied by "StartImport |
Example:
Output parameter
Name | Description |
|---|---|
Customers | A list of newly created customer records |
Customer | A record with the data of a customer |
UserIndex | The UserIndex assigned by the shop system |
CustomerID | The customer number specified in the import data |
The email address specified in the import data |
Example:
Query errors and warnings (GetResult)
This command can be used to query the warnings and errors that occurred during the import. This command should only be called after the process has finished, i.e. GetProgress has returned "Finished=true".
In response to this command the server returns a list of errors and warnings. If errors are returned, the import was aborted. If warnings are returned, but no errors, then the import could be completed, but parts of the data could not be imported without errors.
Input parameters
Name | Description |
|---|---|
ShopID | The ID of the shop |
Password | Password for the service |
SessionID | The SessionID supplied by "StartImport |
Example:
Output parameter
Name | Description |
|---|---|
Errors | A list of the errors that occurred |
Warnings | A list of the warnings that occurred |
Example:
Error handling
There are two types of errors in this SOAP interface:
Errors that occur during import
Errors occurring when calling SOAP commands
Errors of category (1) query after the end of the import with "GetResult".
When using the SOAP interface, the following errors can occur in addition to the "normal" import errors:
Error message | Description |
|---|---|
EI001 No import data available | There is no import data available on the shop server. |
EI002 Import already running | An import process is already running for the shop. |
EI003 Another process is already accessing the shop data | Another process is already writing or reading product data for the shop. Therefore, to avoid inconsistencies in the data, an import cannot be started. The following processes can cause this message: Export of data by the PricePush Feed Engine Data transfer by the WSPManager Update of glossary data |
EI004 Article Import Pro not enabled | Article import Pro is not enabled for the shop |
EI005 Invalid shop version (VX required) | Import is enabled, but the called SOAP interface does not match the shop version (e.g. V7 instead of V8) |
EI006 Customer data transfer not enabled | Import is enabled, but customer data transfer is not set up. |
EI007 Internal error | The import was aborted due to an exception error. Try again later or contact WEBSALE AG. |
Errors of category (2) are returned as "SOAP Faults" in the server's response. The following errors of the second category may occur:
Error message | Description |
|---|---|
ES001 Missing ShopID or password | The "ShopID" parameter or the "Password" parameter is missing in the sent command. |
ES002 Invalid ShopID or password | The command contained "ShopID" and "Password" parameters, but there is no matching shop or the password is wrong. |
ES003 Missing SessionID | A "GetProgress" or "GetResult" command was sent with an empty SessionID. |
ES004 Invalid SessionID | The SessionID sent with a "GetProgress" or "GetResult" command is invalid, e.g. because no "StartImport" was called before. |
ES005 Server initialization error | An error occurred while initializing the soap server. Try again later or contact WEBSALE AG. |
ES006 Import still running | When calling "GetResult" the import was not finished yet. |
ES007 SSL required | The call of the program must be done via an encrypted connection, a call with a normal "http" URL is not allowed. |
ES008 Wrong shop version | The SOAP interface for the V8 version of a shop was called, but no V8 shop exists. |
ES009 Invalid scope | An invalid value was passed in the scope field |
Error during customer data import:
Error message | Description |
|---|---|
EC001 | Neither 'UserIndex' nor 'CustomerID' available |
EC002 | Neither 'TableIndex' nor 'ExternalID' available |
EC003 | Both 'CustomerID' and 'UserIndex' are empty |
EC004 | Both 'ExternalID' and 'TableIndex' are empty |
EC005 | 'CustomerID' and 'UserIndex' empty or not present in the database |
EC006 | The specified TableIndex is already assigned |
EC007 | Record without email address |
EC008 | eMail address is already used |
EC009 | customerID' is already in use |
EC010 | CharsetImport without CharsetShop is ignored |
EC011 | CharsetShop without CharsetImport is ignored |
EC012 | Data set could not be converted to the target character set without errors |
EC013 | Invalid character set |
EC014 | Encrypted data as well as data transferred with SFTP are present |
EC015 | Field 'UserIndex' not present |
EC016 | UserIndex ... does not exist |
EC017 | TableIndex has been replaced |
EC018 | More than one billing address exists |
EC019 | The file is missing the mandatory field ... |
EC020 | The mandatory field ... is empty |
EC021 | Invalid data type ... in the field ... |
Example files
The following sample files are part of this documentation. You can download them from the subordinate page.
File name | Description |
|---|---|
startrequest.xml | Example of a "StartImport" command |
startresponse.xml | Response of the server to a "startimport" command |
getprogressrequest.xml | Example for a "GetProgress" command |
getprogressresponse.xml | Response of the server to a "GetProgress" command |
getresultrequest.xml | Example of a "GetResult" command |
getresultresponse.xml | Response of the server to a "GetResult" command |
getaddedcustomersrequest.xml | Example of a "GetAddedCustomers" command |
getaddedcustomersresponse.xml | Response of the server to a "GetAddedCustomers" command |
fault.xml | Example of an error message in response to a "StartImport" command with invalid credentials |
WSDL (Web Services Description Language)
On the subordinate page you will find a WSDL file (AIPController.wsdl) for download, which you can use to create the code for connecting the interface (at least partially) automatically. The prerequisite for this is that there is a suitable tool for the programming language you use.
Data import from different systems
In principle it is possible to import e.g. product data from one system and customer data from another system. However, it must be ensured that transfer and import do not take place simultaneously. Any attempt to start an import while another import is already running will result in an "EI002 Import already running" error.
More critical than the start of the import is the transfer of the data, since this is done via SFTP and no separation of the import directories for different systems is provided. The fact that the transfer is done via SFTP means that a simultaneous transfer from different systems cannot be prevented by the import software.
That the import directories are not separated means that one system may start importing data that another system has transferred.
URL
The current URL to call the SOAP interface for import is
https://secure.c1.websale.net/cgi/aipsoaptrigger/aipsoaptrigger.cgi
The URL may change in the future, so make sure it can be changed at your end without too much effort.