Child pages
  • Import V2 (public API)
Skip to end of metadata
Go to start of metadata

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:

  1. Yoochoose triggers the export of the shop items into json files;
  2. After the export to files is ready, the external shop should trigger the Yoochoose API, providing the files location;
  3. 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:


and the mandatory {params} are:

parameterdescription
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:

AuthorizationTypeDescriptionExample
Bearer tokenHttp 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 TokenHttp Header

A custom HTTP Header. "YCAuth"

  • case sensitive

The value is the same as the previously described authorization(Bearer token)

"YCAuth":"7109257ab72e744f71794215791ddfa0"

Yoochoose custom token (as URL parameter)

URL parameter

ycauth=...

  • case sensitive

A parameter in the request URL. No need to have a HTTP Header.

The value is like the described authorization in Bearer token

http://shopware5.yoochoose.net/Ycexport?webHook=<theWebhook>&mandator=1234&size=100&transaction=20180328163300123&ycauth=15e1e24eb6088c52a0a8991a819bbcc1


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):

shopexport 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 formatExample
POST http://<customerShopHost>/api/<mandatorId>/items
POST http://shopware5.yoochoose.net/api/1324/items


Header FieldsDetailsExample
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 FieldsDetailsExample
transactionThe transaction defined in the previous GET request (in 1. Export shop items to file)
"transaction":20180328163300123
events.action"action":"FULL""action":"FULL"
events.formatThe 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.langthe language
"lang":"eng-GB"
events.credentialsa 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.uriArray with the URIs to the exported files
"uri":[ 
"http:\/\/shopware5.yoochoose.net\/media\/yoochoose\/1234\/aWQbbLa1xsvt4tJa6SO5.json",
"http:\/\/shopware5.yoochoose.net\/media\/yoochoose\/1234\/GpCFIphw9MqkJhwU3HWA.json"
]


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. 


  • No labels