To trigger the import you only need to execute step 1. (Trigger import)
Introduction
The following import-flow describes the process of Importing products, (categories and vendors) into the YOOCHOOSE system. The main steps of the Import are:
- Yoochoose triggers the export of the shop items into json files;
- After the export to files is ready, the external shop should trigger the Yoochoose API, providing the files location;
- Yoochoose downloads the file and process the import.
1. Trigger import
Upon triggering the import, yoochoose will export your shop items into Json files in your shop installation directory.
To trigger the export, you need to invoke a GET request against your shop. Depending on the shop type, the request has the following format:
| shop | URL | Example (for mandatorId = 123) |
|---|---|---|
| Magento | GET <shop_url>/yoochoose/export?{params} | |
| Magento 2 | GET <shop_url>/rest/V1/yoochoose/export?{params} | |
Plentymarkets 7 | GET <shop_url>/yoochoose/export?{params} | |
| OXID | GET <shop_url>/Yoochoose/Export?{params} | |
| Shopware 5 | GET <shop_url>/Ycexport?{params} |
and the mandatory {params} are:
| parameter | description |
|---|---|
webHook¹ | the URI location on which the export items to file must be triggered. The webhook has the following format: https://admin.yoochoose.net/api/{mandatorId}/items ( you must replace {mandatorId} by your customerID) |
mandator | the yoochoose mandatorID (also known as customerID) |
size (or 'limit' for OXID shops) | maximum number of items per generated file. NOTE: The size of the generated files should be of maximum 50 MB each. If it's greater than 50MB, you need to reduce the 'size' parameter value accordingly (so it can generate several .part files with a size less than 50MB each). NOTE 2: the json item files will be generated in the a specific directory in the shop installation directory. They will be publicly available and will exist until they are (manually/explicitly) deleted or until the next export is triggered. For more details on the location of the files, see "2. After export is ready" below. |
transaction | the transaction timestamp (in format yyyyMMddHHmmssSSS) |
¹ For debugging purposes, the webhook can be replaced by another URL other than https://admin.yoochoose.net/api/{mandatorId}/items, but then the import won't be triggered automatically. It will just generate the json files.
Authorization
In order to be invoked, this request need authorization. There are several authorization options supported and they are verified in the following order. Just choose the one that suits your needs best:
| Authorization | Type | Description | Example |
|---|---|---|---|
| Bearer token | Http Header | This token is a md5 hash of the LicenseKey, except for Magento2 shops. The license key is displayed in the upper right corner in the Admin GUI (https://admin.yoochoose.net) after logging in with your registration credentials. For example, for the license: 1234-5678-1234-123456-12345, the md5 value is 7109257ab72e744f71794215791ddfa0. For Magento2 shops the value can be obtained/resetted in the shop backend in: Stores > Configuration > Yoochoose Recommendations > Configuration > Yoochoose Authorization > Authorization Token | "Authorization": "Bearer 7109257ab72e744f71794215791ddfa0" |
| Yoochoose custom Token | Http Header | A custom HTTP Header. "YCAuth"
The value is the same as the previously described authorization(Bearer token) | "YCAuth":"7109257ab72e744f71794215791ddfa0" |
| Yoochoose custom token (as URL parameter) | URL parameter | ycauth=...
A parameter in the request URL. No need to have a HTTP Header. The value is like the described authorization in Bearer token |
The export/import will be automatically executed. No more action needed from your side.
All the of the following text is merly informative on the internals of the import process.
2. After export is ready -> trigger Yoochoose on the shop/webHook
Depending on the shop, the files are exported to a specific directory (in the shop installation directory):
| shop | export directory |
|---|---|
Magento | <shop_dir>/media/yoochoose/<mandatorID> |
| Magento 2 | <shop_dir>/pub/media/yoochoose/<mandatorID> |
| Plentymarkets 7 | |
| OXID | <shop_dir>/out/yoochoose/<mandatorID> |
| Shopware 5 | <shop_dir>/media/yoochoose/<mandatorID> |
After the export to file(s) has finished a POST request with a BODY containing "import-events" with links to the exported files (generated in the previous step) will be invoked.
To perform the request, a Basic Authorization is required.
Example of a adequate POST request
| Request format | Example |
|---|---|
POST http://<customerShopHost>/api/<mandatorId>/items | POST http://shopware5.yoochoose.net/api/1324/items |
| Header Fields | Details | Example |
|---|---|---|
| Authorization | Type: Basic Authorization It is a base64 encoding of the string "<CustomerID>:<LicenseKey>" For example, "723:1234-54235-3123-3123" will be encoded to "Basic NzIzOjEyMzQtNTQyMzUtMzEyMy0zMTIz" | Basic NzIzOjEyMzQtNTQyMzUtMzEyMy0zMTIz |
Content-Type | "application/json" | application/json |
| Body Fields | Details | Example |
|---|---|---|
| transaction | The transaction defined in the previous GET request (in 1. Export shop items to file) | "transaction":20180328163300123 |
| events.action | "action":"FULL" | "action":"FULL" |
| events.format | The shop type (ex: magento) and file content type (ex: items). For more details, see the table below | "format":"MAGENTO2" |
| events.contentTypeId | "contentTypeId":"1" | "contentTypeId":"1" |
| events.lang | the language | "lang":"eng-GB" |
| events.credentials | a Json object with login and password. Both values can be null if no credential is required to download the file | "credentials":{
"login":"null",
"password":"null"
} |
| events.uri | Array with the URIs to the exported files | "uri":[ |
In the Body, the field format can have the following values, depending on the shop and the uri/file it refers:
| file/ shop | magento | magento2 | oxid2 | plenty markets 7 | shopware | woocommerce | eZ Publishing |
|---|---|---|---|---|---|---|---|
| ITEMS | MAGENTO | MAGENTO2 | OXID2 | PLENTY7 | SHOPWARE | WOOCOMMERCE | EZ |
| CATEGORIES | MAGENTO_CATEGORIES | MAGENTO2_CATEGORIES | OXID2_CATEGORIES | PLENTY7_CATEGORIES | SHOPWARE_CATEGORIES | ||
| VENDORS | MAGENTO_VENDORS | MAGENTO2_VENDORS | OXID2_VENDORS | PLENTY7_VENDORS | SHOPWARE_VENDORS |
Full example:
POST http://shopware5.yoochoose.net/api/1324/items
HEADERS:
Content-Type: application/json
Authorization: Basic NzIzOjEyMzQtNTQyMzUtMzEyMy0zMTIz
// Body of the POST request
{
"transaction":<transactionId>,
"events":[
{
"action":"FULL",
"format":"MAGENTO2",
"contentTypeId":"1",
"lang":"eng-GB",
"credentials":{ // can be null if no credentials needed for downloading files
"login":"user",
"password":"password"
},
"uri":[
"http://uri-to-items-file-1",
"http://uri-to-items-file-2"
]
},
{
"action":"FULL",
"format":"MAGENTO2_CATEGORIES",
"contentTypeId":"1",
"lang":"eng-GB",
"credentials":{ // can be null if no credentials needed for downloading files
"login":"user",
"password":"password"
},
"uri":[
"http://uri-to-categories-file-1",
"http://uri-to-categories-file-2"
]
},
{
"action":"FULL",
"format":"MAGENTO2_VENDORS",
"contentTypeId":"1",
"lang":"eng-GB",
"uri":[
"http://uri-to-vendors-file-1"
]
}
]
}
3. Yoochoose downloads the files
All files will be downloaded and inserted into the Yoochoose database.