introduction - freelance.f-control.eufreelance.f-control.eu/cvapiconnect.pdfintroduction dear user,...

of 17

Introduction Dear user, Thank you for purchasing the API connect module for Opencart. We are glad to present you the result of our dedicated efforts. We value our customers very high, and every feedback from them will be highly appreciated. We always look to provide the best products and support. If you have any idea, or just you feel that we can do something more for you – Please, feel free to contact us and share it.

CEO of MDS development team : Martin Georgiev

Table of contents : Nr Chapter Page 1 End User License 1 2 Product description 2 3 Installation 3 4 Setting of the import module 5 5 Manual import and Cron Jobs 12 6 Shipping modules 14 7 Setting FTP connection in your store 17

Chapter 1 : End user license By purchasing and/or installing “Chinavasion API connect opencart module” (further called “The product”) you agree to the following terms :

- The product can be installed only at one domain, and one opencart store. - You cannot modify the original code, copy it, and/or use any part of the code in any other products.. - You cannot distribute the product no matter commercial or free. - Any action and usage connected with the product cannot be different than its original purpose.

Any violation of those terms will lead to immediate pursuit in all legal forms. The purchase gives you the right to receive all future versions, designed for Opencart 2.x free of charge.

of 17

Chapter 2 : Product description This module is developed to maintain connection to chinavasion.com via API key. Main features

• Full Chinavasion API support, including – o Getting product and category information; o Updating of prices, descriptions, stock status and everything provided in the API; o Intelligent reaction to all changes; o Sending to China and monitoring your orders directly from your admin interface in opencart; o Getting the shipping cost from Chinavasion via the API; o Support for scheduled cronjobs to keep your shop up to date.; o Flexible price calculation; o Tracking information about your ChinaVasion credit in all supported currencies;

System requirements

• PhP version 5.2 or higher; • mySql database; • OpenCart versioin 2.x ; • FTP account set in the store for the OCmod version.;

of 17

Chapter 3 : Installation of the product IMPORTANT : Before you install the product : You need to make sure that your shop has working FTP connection. If not you can follow the instructions in chapter 7 of this document. Do not follow this lines if you already have installed copy of the product. For update just upload the content of the “Install” folder and overwrite the files. This tips are only for initial installation.

First you need to unzip the package to some folder of your choice. It will contain three files :

1. APIconnectCV_manual.pdf (this document); 2. License.txt; 3. APIConnectCV.install.ocmod.zip;

File Nr3 (the zip file) contains installation package for opencart. Do not unzip it before you proceed to install. It works as is it, and no other steps are required to install it, except the described below. Log in to your shop admin interface. On the left side menu go to “Extensions”, then click on “Extension installer”.

of 17

The interface of the extension installer will open. You can see it at the picture below :

Click on the “Upload” button. A standard file open dialog will appear. Find the folder, where you extracted the module package, select the installation zip file (APIConnectCV.install.ocmod.zip) and click the “Open” button. If you are not doing that for first time you may see a list of files that will be overwritten. This doesn’t concerns you so just ignore it – the product will not overwrite any core file, and will not harm the shop functionality In any way. If there is overwritten files it will be it’s own files. After that click on the “Continue” button. The installation will start and you will see the progress bar moving. When the installation is complete you should get success message and the progress bar will become green, as you can see in the picture below.

of 17

Chapter 4 : Setting of the import module From the shop administration interface go to “Extensions” then “Modules” in the left side menu. You will see a list of the installed modules in your shop. First you need to activate it. Find in the list where is located module named “API connect – Chinavasion”. It will be easy to locate it because of the big Chinavasion logo. On the right side of the same row you will see 2 buttons – Install (green) and “Edit” (blue color). Click on the “Install” button. The page will reload and this button will become red. You will get success message on the top of the list saying “Success: You have modified modules!” Your module should look like that :

of 17

Now find your module again and click the blue “Edit” button at the right side of it’s line. On the first run you will see almost empty interface, with only one field, where you must enter your API key, previously acquired from www.chinavasion.com. It will look as the picture below :

Here you need to enter your API key, then click on the “Save” button, which is located at the top/right side of your screen.

If the API key that you entered is valid all the controls will appear and you can proceed to set up the module. On the top you will see blue button “Import now”. Clicking on it will start importing all products and categories. At this moment do not click it yet – you need to enter your desired settings before you proceed. We will return to this button later. The interface is split in 4 tabs :

‐ General settings; ‐ Categories; ‐ Orders; ‐ Chinavasion credit;

We will describe of each one of them separately.

of 17

GENERAL SETTINGS tab.

On the first line is your API key. You don’t need to do anything with it. ChinaVasion supports multiple API keys per user, so you can use each one of them. If you decide to change it you just need to enter the new key and save. Next field – “Price request currency” is not editable. The module makes smart decision which currency to select to extract and calculate the prices. If your shop main currency is one of the Chinavasion supported currencies (USD, EUR, GBP, AUD, CAD, CHF, HKD, CNY, NZD), the module will ask the prices in your main currency. If not it will ask the prices in USD, and calculate them to your main currency according the current rate set in the shop. In this case the interface will contain one more field, where you can enter alternative rate to calculate the prices. Some times the shop automated currency rate is not the rate that you want, so you can set your own. “General price markup” – here you can add some profit over the original prices. You can enter numeric value, in percents. This percentage will be added to the product prices after the currency calculation. „Substitute CHINAVASION” – Whatever you enter here it will replace the text “Chinavasion” in all product and category descriptions. We recommend you to put here your store or company name. If you leave the field empty no changes will be made, and you will have the original text everywhere. “Category description import” – Here you can choose to import the full or the short category description. The full description takes 2 pages in some cases, and you may not like to have all this text before your products. In this case simply select the short description option. “Allocation to categories” – You can select between two options – to add the product both to the master and sub-category, or add it in the sub category only. If you choose to be added to the both all products, located in the sub categories will appear when you enter the master category. If not, on the master category you will see only the list if it’s subcategories. “Video settings” – Some of the products contain a video. You can choose to add the videos to your shop products description or not. “Cronjob economic mode” – Some of the hosts provide a limited resources. In some cases the import of all products at once will not run. It will be interrupted due to low memory, or server timeout. When the economic mode is active the import will get only one category per run – the oldest one. In this case you can enable it, and set your cronjobs to call the import at short intervals of time (recommended 30 to 60 minutes). More details about the cronjobs and the import procedure will be explained in chapter 5.

of 17

New controls added in version 1.1 : “Root category” – if you don’t want to upload the products in the main category you can create new one (for example “Electronics” -> “Electronic gadgets” -> “China”), and import everything under it. From this selector you can select the main category for the Chinavasion products.

“Store” – If you are using multi-store OpenCart installation from here you can chose to which store the products will go. If you want specific product or category to be shown also in other stores just set them manually. This option makes sure that the product is in this store, but it’s not modifying the other stores information.

“New product status” – Some shop admins may want to review the products before they put them on sale. This selector choices the status for the newly arrived product. If you pick “Disabled” all new products will come with disabled status, then you can filter and edit/review before enabling.

“Update category texts” – If you don’t want the category text content as description and meta words to be updated after the initial import set this control to disabled. This will allow you to edit the text and keep it static. If you want to restore it to the original Chinavasion text just enable it and do manual import.

“Update product text” – Same as the previous one, but acts for the product import. It disables the import of the product name, description, meta description, and meta keywords, allowing you to edit them. The other updates such as prices will still run.

of 17

CATEGORIES tab

As you can see on the picture the Categories tab contains a table view of all categories in the shop. From here you can change 2 things for each category and sub‐category. First, you can specify a markup in percents. If you enter some markup, different than the one, entered in the “General settings” tab it will apply instead the general markup only for this category (or sub category). If you enter markup on a master category only it will applied to all products in its subcategories. If you enter to a subcategory it will take effect only for this specific subcategory and ignore the markup settings of the master category and the general markup. The other thing that you can do is to set the category to be imported or not by clicking on the green check symbol in the “Importing” column. The products in the disabled categories will not be imported to your shop.

IMPORTANT : All categories settings will not be saved with the general “Save” button of the module. If you want to save the changes that you made in this tab, you need to click on the “Save category settings” – a big blue button, located on the top/right

side before the categories table.

of 17

ORDERS tab

In this tab you can see a table with all orders in your shop which include at least one product from Chinavasion. From here you can take a quick look of your orders, send them directly to Chinavasion, or observe the status the orders that you already sent. The information is organized in a table. The table is separated by two main column groups – Your store (left side), and Chinavasion on the right. On Your shop section you can see your unique order ID, date, the name of the customer, number of products included in the order, the cost of the products and the shipping separately and the total cost. If you want to see a more detailed information you can click on the small blue button next to the product number. The order details box will appear. There you can see the model code, quantity, prices in the original currency of the order, and also the totals in the shop original currency. You can close it by clicking on the “Close” button at the top right side of the box, or clicking anywhere on the screen outside the box.

If the order has not been sent to Chinavasion yet the cells on the left section of the table will be empty, including 2 thing s only – a text, informing that the order is not sent, and blue button “Send now”. Clicking it will send your order directly into Chinavasion database. It will send also information about the shipping method, add the customer address from the original order to the address book of your Chinavasion account. The payment method will be set to “PayPal” by default, and the order will acquire status “Awaiting your payment”. If you want to change the payment method you should log in to your Chinavasion account and edit the order.

of 17

When you login to your Chinavasion account you will see your recently sent orders as in the screenshot below : After you finally confirm and pay your orders you can view their status development in the same tab.

of 17

CHINA VASION CREDIT tab

This tab has information purpose only. It changes nothing, only shows information about the available funds in your Chinavasion credit.

of 17

Chapter 5 : Manual import and cron jobs The APIconnect module can import the Chinavasion product stream by two ways – Automated and Manual. The Automated import is possible thru setting a cronjobs. For those who are not specialist we will give a short description what is cronjobs : It is time-based job scheduler, maintained by the Unix-like operating systems. It is used to schedule jobs (commands or shells scripts) to run periodically at fixed times, dates or intervals. It typically automates the system maintenance or administration. Thought its general purpose nature makes useful for things like connecting internet and downloading emails, data streams or other content at regular intervals. We cannot give you exact instructions how to set it, because we don’t know what is your operating system, and it’s specific settings. To set up a cron job you need to contact your server administrator and ask him to set it. The PhP script, which should be set for the cronjobs is located in the ADMIN folder of your shop. It’s name is apiconnectcv_cronjob.php If your system is low on resources you better the module to economic mode, and set the cron job to run at every 30 minutes. If not in economic mode you can set it to run once or twice per day (12 or 24 hour interval). The other way to import the products is manual. You need only to go to the control interface of the module. If the API key that you set is valid you will see a blue button with text “Import now”. Just click it, and the import procedure will start at new browser tab. You must be patient, especially on the first run – It will take about 2 minutes to extract all needed information from Chinavasion site. During this time you will see nothing in your browser. After that you it will start showing information of each imported product line by line. If you import for a first time the script execution will take more time because it will copy the pictures from Chinavasion, and this may take longer. It the script is being interrupted at some point just refresh the screen. If the script doesn’t start showing the products imported, and shows error message instead try to set the module to economic mode and run it again. When in economic mode it will import only one category per run which will take about 20 time less resources (like memory and execution time), but you have to run it as many times as you need to import every categories. If the script not runs whatever you try – please feel free to contact us. We will do everything necessary to adapt it to your system, or return your money.

of 17

Chapter 6 : Shipping modules Chinavasion offers five shipping methods, and there is no clue how much will cost each of them until you don’t make an order. Many shops encountered this problem – they just can’t calculate the shipping cost before the order is sent. The shipping rates are not hard defined, and there is no base to calculate the cost. For this reason Chinavasion provided opportunity to query for shipping with a list of a products. In this package are included five shipping modules that take the shipping cost directly from Chinavasion and show them to your customers. Few words for the shipping specifics. There are three possible cases for one order. First is if it contains only Chinavasion products. In this case the shipping module gets the price directly from them and shows it to your customers. The second case is when you have mixed order – formed by Chinavasion and other products. For this specific case the shipping modules allows the shop owner to specify alternative shipping calculation. You can choose between flat rate, value based rate, weight based and item count based calculation. The other products shipping will be calculated according your settings, and this cost will be added to the shipping cost for the Chinavasion products. If there are at least one Chinavasion product in that order all other shipping methods set in the shop will be suppressed, and the customer will get shipping quote only from the Chinavasion shipping module plus the alternative calculated cost. If there are no Chinavasion products in the order the Chinavasion shipping will be suppressed and all other shipping methods will be shown. Installing the shipping modules. On the initial installation the Chinavasion dedicated shipping modules will be disabled. You need to enable and set them. First, on the left side menu in the administration section you need to go to the Extensions, then Shipping.

of 17

You will see the shipping modules list as shown on the image below:

As you can see all five of them are present, but not installed into opencart, and not yet enabled. To install you need to click the green button at the end of the line for each one of them. When you click it the button will become red, and then you need to click on the “Edit” button (the blue one) to set up the module. On the next screenshot you can see the DHL module installed, and ready to set up.

of 17

Now you need to edit the module settings by clicking on the blue pencil button at the end of the module line. You will see the settings screen for the shipping module like this :

On the first row you can set up some markup in percents, which will be added to the original shipping cost. You just need to fill a numeric value in that field. Next two lines contain the settings for your alternative shipping calculation. On the first you can see five buttons, used to set which method will be applied for products which don’t come from Chinavasion. On the second row (“Alternative shipping value”) you must enter the value for the specified alternate method. The value stands for different things, depend on the method that you have picked. If you choose Flat rate, the entered value, in your shop main currency will be added the whole order shipping cost, no matter how many products it contains. If you choose weight based, the entered value will stand for price per kilogram, again in your shop main currency. If you choose “Per item” the alternative value will be multiplied by the non‐Chinavasion items count, then added to the whole shipping cost. If you choose “% from the total value” the alternative value will stand for percent, and the shipping cost for the non‐Chinavasion products will be calculated by percentage of their value. (For example if you enter 10, and the products total is $250 the added cost will be 10% of $250 or $25). The next field is sort order, it sets the shipping methods sorting. If you want this method to be lower in the list set bigger value. If you leave it empty the sort will be alphabetiacal. And the last field, the most important one is the module status. You need to set it to “Enabled” to have this module running. When you finish with your settings just click the blue “Save” button at the top right side of your screen.

of 17

Chapter 7 : Setting FTP connectioin As we mentioned in the beginning, you need active FTP connection to be able to install this product if you have purchased the OCmod version. If not you can skip this chapter. We recommend that you create separate FTP account for your shop, and restrict it to the shop main folder. The following instructions will be made, assuming that you already have such account. We can’t instruct you how to create the account because we don’t know the specifics of your server settings and operating system. First you need to go to the store main settings. In the admin interface look the left‐side menu. Go to “System”, the click on “Settings”. You will enter the “Stores” module, where all stores in you OpenCart will be listed. In the common case you will have only one line. Find the blue “Edit” button at the right side and click it. Now you will see the store setting panel. Go to the “FTP” tab. First field is “FTP host”. Enter the hostname for your FTP account (usually it is like ftp.yourdomain.com). Then enter the FTP port. By default it’s 21, but if your server settings are different you need to enter your actual port number. Next fields are the username of your FTP account, and the password. In the “FTP root” field enter a single slash (“/”). Again, we assume that the ftp connection is set to your store main folder. If not you need to enter here the actual path to the store main folder. Then you need to set “Enable FTP” to “Yes” and save the settings, using to blue “Save” button at the top/ right corner of your screen. If the settings are correct you should have working FTP connection set in your store.

introduction - freelance.f-control.eufreelance.f-control.eu/cvapiconnect.pdfintroduction dear user,...

Documents