Cart Integration SDK

The Shopgate Cart Integration SDK is a compilation of classes to manage the communication between your shop system and Shopgate via the Shopgate Plugin API and the Shopgate Merchant API. The SDK provides methods for processing incoming and outgoing requests, configuration options and for handling errors. The SDK also offers container classes, which allow easy storage of order data, among other things. Better like to start coding immediately? Have a look at the sample plugin code and get going! You’re welcome to check back here anytime.

The most important functions are:

Shopgate Plugin API, i.e. the communication interface for Shopgate
implementation of the Shopgate Merchant API communication for your order management
workflow mapping (data export, order import, etc.)
an easy-to-use interface

Download

Requirements

Following requirements must be met in order to use the Shopgate Cart Integration SDK:

PHP version >= 5.2
The PHP max_execution_time setting must be at least 10 seconds (depending on the number of products).
The PHP memory_limit setting must be at least 20 MB (depending on the number of products).
The CURL library for PHP must be installed in order to send requests to the Shopgate Merchant API.

Layout for the Plugin

See chapter Incoming Requests to learn how calls to the Shopgate Plugin API can be dispatched to your plugin. Your plugin class extends the ShopgatePlugin class of the SDK and must implement its abstract callback methods. Use the PHP constant SHOPGATE_PLUGIN_VERSION to store the current versions number of your plugin in the 2.x.x format. The first two numbers must be identical with the version number of the Shopgate Library you are using.

Get the full plugin example code or have a look at the short example for a plugin class:

<?php require_once(dirname(__FILE__).'/vendor/shopgate/cart-integration-sdk/shopgate.php'); // adjust this path to your environment define('SHOPGATE_PLUGIN_VERSION', '2.9.0'); class ShopgatePluginMyShopSystem extends ShopgatePlugin { public function startup() { // ... } public function getCustomer($user, $pass) { // ... } public function registerCustomer($user, $pass, ShopgateCustomer $customer){ // ... } public function addOrder(ShopgateOrder $order) { // ... } public function updateOrder(ShopgateOrder $order) { // ... } public function getOrders($customerToken, $customerLanguage, $limit = 10, $offset = 0, $orderDateFrom = '', $sortOrder = 'created_desc') { // ... } protected function createItems($limit = null, $offset = null, array $uids = array()) { // ... } protected function createReviews($limit = null, $offset = null, array $uids = array()) { // ... } protected function createCategories($limit = null, $offset = null, array $uids = array()) { // ... } public function cron($jobname, $params, &$message, &$errorcount) { // ... } public function checkCart(ShopgateCart $shopgateCart) { // ... } public function checkStock(ShopgateCart $shopgateCart) { // ... } public function getSettings() { // ... } public function syncFavouriteList($customerToken, $items) { // ... } }

Configuration

Using the components of the Shopgate Cart Integration SDK depends on configuration settings in many parts. The class ShopgateConfig is responsible for loading and saving these. Advanced Implementation

To get all out of the new ShopgateConfig class you can extend it in order to add own validation rules, override the loading and saving procedures (e.g. to implement saving into a database instead of the file system) or define new default values.

A detailed description and examples can be found on the page Cart Integration SDK: Configuration. Quick Implementation

Create a file called myconfig.php inside the Shopgate Cart Integration SDK’s config folder and define the $shopgate_config variable with your settings as shown below:

<?php $shopgate_config = array ( 'customer_number' => '101459903', 'shop_number' => '11937', 'apikey' => '90d36a7cb039b23c21f6', 'alias' => 'myshop', 'cname' => '', 'server' => 'live', 'encoding' => 'UTF-8', 'plugin' => 'MyShoppingSystem', 'enable_ping' => '1', # ... more settings see also http://developer.shopgate.com/plugin_api );

Incoming Requests

The starting point for requests of the Shopgate Plugin API depends on the shopping system. The starting point can be an independent script (e.g. api.php), a controller of the shop system, a hook point or something similar. Parameters are transmitted via POST. To receive GET parameters please contact out tech support.

<?php ### Simple initialization ### require_once(dirname(__FILE__).'/plugin.php'); // adapt path to your environment $plugin = new ShopgatePluginMyShopSystem(); $response = $plugin->handleRequest($_POST); ### More complex initialization with own configuration class ### # require_once(dirname(__FILE__).'/plugin.php'); // adapt path to your environment # # $config = new ShopgateConfigMyShopSystem(); # $builder = new ShopgateBuilder($config, $_REQUEST); # $plugin = new ShopgatePluginMyShopSystem($builder); # $plugin->handleRequest($_POST); ?>

Outgoing Requests

In order to send a request, use the ShopgateMerchantApi object in your plugin class ($this->merchantApi) and run the required method. Parameters and response values can be found in the API documentation.

API methods will throw a ShopgateMerchantApiException or ShopgateLibraryException in case of an error. Errors at critical points (e.g. during the checkout process or while editing an order) must not abort the script execution in any case. Errors of that kind only need to be logged.

<?php require_once(dirname(__FILE__).'/vendor/shopgate/cart-integration-sdk/shopgate.php'); // Modify this path correspondingly define('SHOPGATE_PLUGIN_VERSION', '2.9.0'); class ShopgatePluginMyShopSystem extends ShopgatePlugin { // ... /** * Gets called when an order has been marked as "shipped" in the shop system. * * @param MyShopSystemOrder $shopOrder An object from the shop system which represents an order with your data. */ public function updateOrderStatus(MyShopSystemOrder $shopOrder) { try { $this->merchantApi->addOrderDeliveryNote($shopOrder->orderNumber, $shopOrder->shippingServiceId, $shopOrder->trackingNumber, true); $shopOrder->addComment('Shopgate has has marked the order as shipped.'); } catch (ShopgateMerchantApiException $e) { // Do not abort at this point as this would crash editing the order in the shop system's backend. // The ShopgateMerchantApiExceptions are logged automatically. $shopOrder->addComment('There was an error updating the order at Shopgate.'); } catch (ShopgateLibraryException $e) { // Do not abort at this point as this would crash editing the order in the shop system's backend. // The ShopgateLibraryExceptions are logged automatically. $shopOrder->addComment('There was an error updating the order at Shopgate.'); } } }

<?php require_once(dirname(__FILE__).'/vendor/shopgate/cart-integration-sdk/shopgate.php'); // Modify this path correspondingly define('SHOPGATE_PLUGIN_VERSION', '2.9.0'); // ... try { // create a new instance of ShopgateBuilder // it will load the configuration file automatically $shopgateBuilder = new ShopgateBuilder(); // get the ShopgateMerchantApi instance from the builder $merchantApi = $shopgateBuilder->buildMerchantApi(); // send requests to the Shopgate Merchant API $orders = $merchantApi->getOrders(array("limit" => 1)); } catch (ShopgateMerchantApiException $e) { // Do not abort at this point as this would crash editing the order in the shop system's backend. // The ShopgateMerchantApiExceptions are logged automatically. Logger::log($e); } catch (ShopgateLibraryException $e) { // Do not abort at this point as this would crash editing the order in the shop system's backend. // The ShopgateLibraryExceptions are logged automatically. Logger::log($e); } // ...