Cloud Elements ecommerce Hub Provisioning Guide API Version 2.0 BETA Page 1
Introduction The ecommerce Hub provides a uniform API to allow applications to use various endpoints such as Shopify. The following illustration shows the overall flow of the ecommerce Hub Element provisioning process. In order to use one or more of the ecommerce Hub Elements in your application, via the uniform API, you have to first follow three steps: 1. Set up your application with the ecommerce Hub Element endpoint, e.g., Shopify, Ecwid, etc. 2. Sign up for the Cloud Elements Services. 3. Provision the ecommerce Hub Element. The following sections will guide you through this process. Cloud Elements uses OAuth to interact with many Elements in the ecommerce Hub during the provisioning process. For more information on OAuth see OAuth Overview in the Appendix. Page 2
Set up your Application with the Endpoint For this guide, we will use Shopify as the example to setup your application with the endpoint. For directions on how to set up a new Ecwid and Volusion Application, please refer to the Appendix of this document. For this example, let s assume that the URL for your application is https://www.demonstrab.ly. Via a web browser, go to: -http://www.shopify.com/ and sign up for a store. Your store name will be needed to provision the Shopify Element. If you are a developer building a store for a client, then you will need to acquire the shop name from your client. Next go to: https://app.shopify.com/services/partners/auth/login to become a Shopify Partner. Once signed up, from the Dashboard, click "Create App". Fill out the App Information and click "Create application" Page 3
Make note of the API key and secret as they will be needed in the provisioning process. Click on the secret field to reveal the value. The next step is to sign up for Cloud Elements Service. The Appendix contains instructions to set up your application with the Ecwid and Volusion Endpoints supported by the ecommerce Hub. Sign up for the Cloud Elements Service To sign up for the Cloud Elements service, using a web browser, go to https://console.cloudelements.com. You can create a new account with Cloud Elements using the Sign Up link shown here, or sign up for Cloud Elements servicing your Google or GitHub account. When signing up via GitHub, you must set a public email address in GitHub profile. Screen shots on how to set a public email are on the next page. If you choose to not use one of these services to sign up, you will be required to validate your new account, and will be then required to reset your password. Page 4
After completing this process, click "Secrets" in the top right corner. Make note of the Org and User secrets as they needed to provision an Element Instance. The Secrets option is available from the top ribbon at all times. You re now ready to start provisioning the ecommerce Hub Elements via the Cloud Elements Provisioning APIs. Provisioning documentation begins on the next page. Page 5
Provisioning the ecommerce Hub Elements Before we start provisioning Elements, we need to understand how your application will use the ecommerce Hub Elements. There are currently two provisioning models for all Elements: 1. Single Application User 2. Multiple Accounts and Users A diagram of the workflow for provisioning an element for a single user will be shown first. However, in the demonstration documentation, the multiple users provisioning flow will be shown. Single Application User The workflow for a single application user is shown below. Page 6
Multiple Accounts and Users This model allows you as the administrator to provision Elements on behalf of your customer s (account) users. The provisioning workflow for multiple users is the same as the single application user workflow. The following illustration shows how a fictitious application, demonstrab.ly, might access the various endpoints via the ecommerce Hub, via multiple users of the application. Before provisioning an element, the account and the account users need to be set up. The API to set up an account is POST /accounts. The full API documentation can be found at https:// api.cloud-elements.com/elements/api-docs/#!/accounts. Below are examples of how to create a new account, as well as a user for the newly created account. Create a new Account within your Organization POST /accounts Create an account within your organization (identified by your organization secret). The provided user secret must be that of the default admin user for the organization. This API call requires a JSON file with the required data to create your account. An example JSON file can be found below along with an example response from the API call. Page 7
create-account.json - these fields are required in your JSON file. "name": "<Name of the Account>", "description": "<Description of the Account>", "externalid": "<ID of the Account>" Example of Successful Response - object returned in JSON format "companyid": <The ID of the organization that owns the account>, "name": "<The name of the account>", "description": "<The description of the account>", "externalid": "<The external ID of the Account>", "id": <The CE assigned ID of the Account> Below is an example curl command demonstrating the API call and response with example data. POST /accounts curl -X POST \ -H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' \ -H 'Content-Type: application/json' \ -d @create-account.json \ 'https://api.cloud-elements.com/elements/api-v2/accounts' create-account.json "name": "Acme Data Services", "description": "The Acme Data Services Account", "externalid": "brie@acmedataservices.com" Example of Successful Response "companyid": 6523, "name": "Acme Data Services", "description": "The Acme Data Services Account", "externalid": "acmedataservices.com", "id": 8341 After successful creation of the account. You may now add users to that account. Below are examples of how to create a new user for the newly created account. POST /accounts/id/users Page 8
Create a new user for the newly created account. This API call requires a JSON file with the required data to create your user. An example JSON file can be found below along with an example response from the API call. create-account-user.json - JSON file needed to create user. "email": "<The user's email address>", "firstname": "<The user's first name>", "lastname": "<The user's last name>" Example of Successful Response - object returned from the API call "id": <The CE ID for the user>, "email": "<The user's email address>", "firstname": "<The user's first name>", "lastname": "<The user's last name>", "secret": "<The user's secret> Below is an example curl command demonstrating the API call and response with example data. POST /accounts/id/users curl -X POST \ -H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' \ -H 'Content-Type: application/json' \ -d @create-account-user.json \ 'https://api.cloud-elements.com/elements/api-v2/accounts/id/users' create-account-user.json "email": "brie@acmedataservices.com", "firstname": "Brie", "lastname": "Burns" Example of Successful Response - object returned from the API call "id": 12802, "email": "brie@acmedataservices.com", "firstname": "Brie", "lastname": "Burns", "secret": "KHh2387n2hk34/979283u012=" NOTE: There may be other fields in the Response JSON. Page 9
To provision Elements, use your Organization secret and the User Secret of the newly created account user. The provisioning flow will be the same using the /instances API. Element Provisioning is covered in the Create Instance section further down in this document. The Multiple Users and Accounts workflow gives you the flexibility to create instances for specific accounts. For example, if you wanted to create an instance for one of your customers, then you would create an account for that customer first. After the account has been successfully created for that customer, you may create individual users, and Element instances for those users under the newly created account, using your own Organization secret and your customer's new User secret. REST API Documentation Note: The complete documentation for the ecommerce Hub API can be found at: https://api.cloud-elements.com/elements/api-docs/#!/ecommerce The documentation for the Provisioning API can be found at: https://api.cloud-elements.com/elements/api-docs/#!/instances and https://api.cloud-elements.com/elements/api-docs/#!/accounts The following sections describe which APIs to use for each step in the above flowchart. Provisioning is done through a REST API. Each request is made using an HTTP verb and the requested URL. There are 5 parts to an HTTP request that are required by the Cloud Elements API. 1. HTTP Headers: headers that are required for each request 2. HTTP Verb: the verb that must be used in the request 3. Request URL: the form of the URL where to make the request 4. Request Body: the text of the request body in JSON format 5. Query Parameters: a query string that is appended to the URL Page 10
Get Elements OAuth Information (Shopify Only) HTTP Header: None HTTP Verb: GET Request URL: /elements/key/oauth/url Request Body: None Query Parameters: shop- substitute this for the name of the user s shop. apikey- the key obtained from registering your app with the provider apisecret- the secret obtained from registering your app with the provider scopes - (Optional) substitute this for a comma-separated list of scopes. An example for writing orders and reading customers is scope=write_orders,read_customers. callbackurl - the URL that you supplied to the provider when registering your app, state - any custom value that you want passed to the callback handler listening at the provided callback URL. Description: The result of this API invocation is an OAuth redirect URL from the endpoint. Your application should now redirect to this URL, which in turn will present the OAuth authentication and authorization page to the user. When the provided callback URL is executed, a code value will be returned, which is required for the Create Instance API. A sample request illustrating the API is shown below. Input Query Parameters Note: the state can be any custom value that you decide to pass in. The returned OAuth URL will contain the state query parameter set to your custom value that was passed in. GET /elements/key/oauth/url?apikey=<sample_api_key>&apisecret=<sample_api_secret>&callbackurl=https://www.cloudelements.com&scope=write_orders Successful Example Response "element": "shopify", "oauthurl": "https://shop_name.myshopify.com/admin/oauth/authorize? client_id=c8b8e2952fba6dca9e58753aedc9b669&scope=null&redirect_uri=www.examplecallbac kurl.com?state=shopify" Page 11
Example curl Request curl -X GET \ -H 'Content-Type: application/json' \ 'http://api.cloud-elements/elements/api-v2/elements/shopify/oauth/url? apikey=<sample_api_key>&apisecret=a<sample_api_secret>&callbackurl=www.examplecallbac kurl.com' Successful Example Response "element": "shopify", "oauthurl": "https://shop_name.myshopify.com/admin/oauth/authorize? client_id=sample_clien_id&scope=null&redirect_uri=www.examplecallbackurl.com? state=shopify" Handle Callback from the Endpoint Upon successful authentication and authorization by the user, the endpoint will redirect to the callback URL you provided when you setup your application with the endpoint, in our example, https://www.demonstrab.ly/authz. The endpoint will also provide two query string parameters: "state" and "code". The value for the "state" parameter will be the name of the endpoint, e.g., "shopify" in our example, or whatever value you sent initially. The value for the "code" parameter is the code required by Cloud Elements to retrieve the OAuth access and refresh tokens from the endpoint. If the user denies authentication and/or authorization, there will be a query string parameter called "error" instead of the "code" parameter. In this case, your application can handle the error gracefully. Once you ve gotten the "code" from the callback, your application can call the API described below to create the instance of the element. Create Instance HTTP Headers: Authorization- User <user secret>, Organization <organization secret> HTTP Verb: POST Request URL: /instances Request Body: Required - see below Query Parameters: None Description: An Element token is returned upon successful execution of this API. This token needs to be retained by the application for all subsequent requests involving this element instance. If creating an instance of an OAuth enabled element, use the code value that was returned on the callback URL. A sample request illustrating the POST /instances API is shown on the next page. Page 12
HTTP Headers Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET> Input JSON create-instance.json - JSON file needed to create instance. "element": "key": "shopify", "providerdata": "code": "Code on the Return URL", "configuration": "oauth.callback.url": "https://www.samplecallbackurl.com", "oauth.api.key": "<INSERT_SAMPLE_API_KEY>", "oauth.api.secret": "<INSERT_SAMPLE_API_SECRET>", "name": "<INSERT_INSTANCE_NAME>" If the user does not specify a required config entry, an error will result notifying her of which entries she is missing. Page 13
Successful Example Response in JSON format "id": 27, "name": "Peter", "token": "BUIWhN8NTPaeyKblo91CJ1PUonwnV/XJjy2A=", "element": "id": 14, "name": "Shopify", "key": "shopify", "description": "Shopify is everything you need to sell anywhere.", "active": true, "deleted": false, "typeoauth": true, "trialaccount": false, "existingaccountdescription": "Give your application access to your existing <br> Shopify account</br><span class=\"buttondescription\">enter your credentials and details for your <b>shopify Account</b></span>", "configdescription": "If you do not have an Shopify account, you can create one at <a href=\"www.shopify.com"", "signupurl": "www.shopify.com", "elementprovisiontype": "OAUTH_TEMPLATE", "tags": [ "id": 12, "name": "Peter" ], "provisioninteractions": [], "valid": true, "disabled": false Page 14
Example curl Command POST/instances API call Example Request curl -X POST \ -H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' \ -H 'Content-Type: application/json' \ -d @create-instance.json \ 'https://api.cloud-elements.com/elements/api-v2/instances' create-instance.json - JSON file needed to create instance. "element" : "key" : "shopify", "providerdata" : "code" : <Code on the Return URL>, "configuration" : "oauth.callback.url" : "https://www.cloud-elements.com", "oauth.api.key" : "fake_shopify_api_key", "oauth.api.secret": "fake_shopify_api_secret", "name" :"fake_instance_name" Example Successful Response in JSON format "id": 23, "name": "Peter", "token": "BUIWhN8NTPaeyKblo91CJ1PUonwnV/XJjy2A=, "element": "id": 14, "name": "Shopify", "key": "shopify", "description": "Shopify is everything you need to sell anywhere.", "active": true, "deleted": false, "typeoauth": true, "trialaccount": false, "existingaccountdescription": "Give your application access to your existing <br> Shopify account</br><span class=\"buttondescription\">enter your credentials and details for your <b>shopify Account</b></span>", "configdescription": "If you do not have a Shopify account, you can create one at <a href= \"www.shopify.com\"", "signupurl": "www.shopify.com", "elementprovisiontype": "OAUTH_TEMPLATE", "tags": [ "id": 12, "name": "Peter" ], "provisioninteractions": [], "valid": true, "disabled": false Page 15
Use The ecommerce Hub In Your Application Now that you have finished provisioning your Shopify Element, you are ready to use the ecommerce APIs to integrate it into your Application. Below are example API calls for the ecommerce Hub. Each object within the ecommerce Hub can be accessed and manipulated using the following HTTP verbs: POST, GET, PATCH, and DELETE The documentation examples will show the Orders object being used with each of the HTTP verbs. The workflow is similar for the other objects available in the ecommerce Hub. POST /orders Create a new order in the ecommerce system. Order creation will flow through Cloud Elements to your ecommerce service. With the exception of the 'id' field, the required fields indicated in the 'Order' model are those required to create a new order. Page 16
Create Order curl -X POST \ -H 'Authorization: Element <INSERT ELEMENT TOKEN>, User <INSERT_USER_SECRET>' \ -H 'Content-Type: application/json' \ -d @order.json \ 'https://api.cloud-elements.com/elements/api-v2/hubs/ecommerce/orders' order.json "line_items": [ "title": "Big Brown Bear Boots", "price": 74.99, "grams": "1300", "quantity": 3 ], "tax_lines": [ "price": 13.5, "rate": 0.06, "title": "State tax" ], "transactions": [ "kind": "sale", "status": "success", "amount": 238.47 ], "total_tax": 13.5, "currency": "EUR" Example of Successful Response - order object returned from API call. Page 17
"total_price_usd": "305.76", "order_number": 1121, "created_at": "2014-10-16T14:02:55-04:00", "source": "307455", "line_items": [ "variant_title": null, "fulfillment_status": null, "quantity": 3, "fulfillable_quantity": 3, "fulfillment_service": "manual", "gift_card": false, "taxable": true, "requires_shipping": true, "title": "Big Brown Bear Boots", "variant_inventory_management": null, "product_exists": false, "variant_id": null, "tax_lines": [], "price": "74.99", "vendor": null, "product_id": null, "name": "Big Brown Bear Boots", "id": 492050839, "grams": 1300, "sku": null, "properties": [] ], "taxes_included": false, "buyer_accepts_marketing": false, "confirmed": true, "total_weight": 0, "total_discounts": "0.00", "number": 121, "tax_lines": [ "rate": 0.06, "price": "13.50", "title": "State tax" ], "updated_at": "2014-10-16T14:02:55-04:00", "processed_at": "2014-10-16T14:02:55-04:00", "currency": "EUR", "id": 273562003, "email": "", "source_name": "307455", "subtotal_price": "224.97", "test": false, "total_price": "238.47", "total_line_items_price": "224.97", "total_tax": "13.50", "tags": "", "token": "c3269d66660e2bfbaefc2c80e0ed6d7d", "processing_method": "", "financial_status": "paid", "name": "#1121", "gateway": "" GET /orders Find orders in the ecommerce system, using the provided CEQL search expression. The search expression in CEQL is the WHERE clause in a typical SQL query, but without the WHERE keyword. For example, to search for all orders whose name contains the word 'data', the search expression parameter will be where=name like '%data%'. If a search expression is not provided, then the first 200 records will be returned. If a value of true is specified for the includedeleted flag, then any soft-deleted records will also be considered in the searched records. Page 18
Retrieve Order curl -X GET \ -H 'Authorization: Element <INSERT ELEMENT TOKEN>, User <INSERT_USER_SECRET>' \ -H 'Content-Type: application/json' \ 'https://api.cloud-elements.com/elements/api-v2/hubs/ecommerce/orders' Example of Successful Response Page 19
[ "total_price_usd": "305.76", "order_number": 1121, "created_at": "2014-10-16T14:02:55-04:00", "source": "307455", "line_items": [ "variant_title": null, "fulfillment_status": null, "quantity": 3, "fulfillable_quantity": 3, "fulfillment_service": "manual", "gift_card": false, "taxable": true, "requires_shipping": true, "title": "Big Brown Bear Boots", "variant_inventory_management": null, "product_exists": false, "variant_id": null, "tax_lines": [], "price": "74.99", "vendor": null, "product_id": null, "name": "Big Brown Bear Boots", "id": 492050839, "grams": 1300, "sku": null, "properties": [] ], "taxes_included": false, "buyer_accepts_marketing": false, "confirmed": true, "total_weight": 0, "total_discounts": "0.00", "number": 121, "tax_lines": [ "rate": 0.06, "price": "13.50", "title": "State tax" ], "updated_at": "2014-10-16T14:02:55-04:00", "processed_at": "2014-10-16T14:02:55-04:00", "currency": "EUR", "id": 273562003, "email": "", "source_name": "307455", "subtotal_price": "224.97", "test": false, "total_price": "238.47", "total_line_items_price": "224.97", "total_tax": "13.50", "tags": "", "token": "c3269d66660e2bfbaefc2c80e0ed6d7d", "processing_method": "", "financial_status": "paid", "name": "#1121", "gateway": "", "fulfillment_status": "partial", "total_price_usd": "10.00", "order_number": 1116, "created_at": "2014-10-10T12:03:19-04:00", "source": "307455", "line_items": [ "variant_title": null, "fulfillment_status": null, "quantity": 1, "fulfillable_quantity": 1, "fulfillment_service": "manual", "gift_card": false, "taxable": true, "requires_shipping": true, "title": "item1", "variant_inventory_management": null, "product_exists": false, Page 20
PATCH /orders/id Update an order associated with a given ID in the ecommerce system. The update API uses the PATCH HTTP verb, so only those fields provided in the order object will be updated, and those fields not provided will be left aloneupdating an order with a specified ID that does not exist will result in an error response. Page 21
Update Order by ID curl -X PATCH \ -H 'Authorization: Element <INSERT ELEMENT TOKEN>, User <INSERT_USER_SECRET>' \ -H 'Content-Type: application/json' \ -d @patch-order-shopify.json \ 'https://api.cloud-elements.com/elements/api-v2/hubs/ecommerce/orders/273562003' patch-order-shopify.json "email": "jon@acmedata.com", "total_price": "305.76", "line_items": [ "title": "Big Brown Bear Boots", "price": "74.99", "quantity": 3 ] Example of Successful Response - order object returned from API call. Page 22
"total_price_usd": "305.76", "order_number": 1121, "created_at": "2014-10-16T14:02:55-04:00", "source": "307455", "line_items": [ "variant_title": null, "fulfillment_status": null, "quantity": 3, "fulfillable_quantity": 3, "fulfillment_service": "manual", "gift_card": false, "taxable": true, "requires_shipping": true, "title": "Big Brown Bear Boots", "variant_inventory_management": null, "product_exists": false, "variant_id": null, "tax_lines": [], "price": "74.99", "vendor": null, "product_id": null, "name": "Big Brown Bear Boots", "id": 492050839, "grams": 1300, "sku": null, "properties": [] ], "taxes_included": false, "buyer_accepts_marketing": false, "confirmed": true, "total_weight": 0, "total_discounts": "0.00", "number": 121, "tax_lines": [ "rate": 0.06, "price": "13.50", "title": "State tax" ], "updated_at": "2014-10-16T15:04:31-04:00", "processed_at": "2014-10-16T14:02:55-04:00", "currency": "EUR", "id": 273562003, "email": "jon@acmedata.com", "source_name": "307455", "subtotal_price": "224.97", "test": false, "total_price": "238.47", "total_line_items_price": "224.97", "total_tax": "13.50", "tags": "", "token": "c3269d66660e2bfbaefc20ed6d7d", "processing_method": "", "financial_status": "paid", "name": "#1121", "gateway": "" Page 23
DELETE /orders/id Delete an order associated with a given ID from your ecommerce system. Specifying an order associated with a given ID that does not exist will result in an error message. Delete Order by ID curl -X DELETE \ -H 'Authorization: Element <INSERT ELEMENT TOKEN>, User <INSERT_USER_SECRET>' \ -H 'Content-Type: application/json' \ 'https://api.cloud-elements.com/elements/api-v2/hubs/ecommerce/orders/270108559' Example of Successful Response Return 200 Success GET /orders/id Retrieve an order associated with a given ID from the ecommerce system. Specifying an order with a specified ID that does not exist will result in an error response. Page 24
Retrieve Order curl -X GET \ -H 'Authorization: Element <INSERT ELEMENT TOKEN>, User <INSERT_USER_SECRET>' \ -H 'Content-Type: application/json' \ 'https://api.cloud-elements.com/elements/api-v2/hubs/ecommerce/orders/2762003' Example of Successful Response "total_price_usd": "305.76", "order_number": 1121, "created_at": "2014-10-16T14:02:55-04:00", "source": "307455", "line_items": [ "variant_title": null, "fulfillment_status": null, "quantity": 3, "fulfillable_quantity": 3, "fulfillment_service": "manual", "gift_card": false, "taxable": true, "requires_shipping": true, "title": "Big Brown Bear Boots", "variant_inventory_management": null, "product_exists": false, "variant_id": null, "tax_lines": [], "price": "74.99", "vendor": null, "product_id": null, "name": "Big Brown Bear Boots", "id": 492050839, "grams": 1300, "sku": null, "properties": [] ], "taxes_included": false, "buyer_accepts_marketing": false, "confirmed": true, "total_weight": 0, "total_discounts": "0.00", "number": 121, "tax_lines": [ "rate": 0.06, "price": "13.50", "title": "State tax" ], "updated_at": "2014-10-16T14:02:55-04:00", "processed_at": "2014-10-16T14:02:55-04:00", "currency": "EUR", "id": 2762003, "email": "", "source_name": "307455", "subtotal_price": "224.97", "test": false, "total_price": "238.47", "total_line_items_price": "224.97", "total_tax": "13.50", "tags": "", "token": "c3269d66660e2bfbaefc2c80e0ed6d7d", "processing_method": "", "financial_status": "paid", "name": "#1121", "gateway": "" Page 25
Appendix OAuth Overview (Shopify Only) OAuth is an open standard for authorization. Cloud Elements uses OAuth to interact with Elements in the ecommerce Hub during the provisioning process. Standard OAuth Exchange The diagram to the right shows a standard OAuth interaction with a service endpoint. An application user performs an action that requires access to a service endpoint. The application then redirects to a well-known OAuth URL for the service endpoint. The user logs in, if necessary, and grants access to the application. After access is granted, the service endpoint redirects to the URL configured in the "Set up your Application with the Endpoint" section. The redirect URL includes a code that the application exchanges for OAuth access and refresh tokens. These tokens are then used in subsequent API requests between the application and endpoint. Each endpoint has different expiration intervals for the tokens, which the application must manage. Page 26
OAuth with ecommerce Hub Element Provisioning The diagram to the right shows how Cloud Elements uses OAuth during element provisioning. An application user performs an action that requires access to a service endpoint. The application requests the OAuth URL for the service endpoint from Cloud Elements, then redirects. The user logs in, if necessary, and grants access to the application. After access is granted, the service endpoint redirects to the URL configured in the "Set up your Application with the Endpoint" section. The redirect URL includes a code that the application uses to create an element instance. Cloud Elements uses this code to exchange for OAuth access and refresh tokens. Cloud Elements stores these tokens before responding to the instance creation request with the element information, including an element instance token. The application then uses the element instance token to make Cloud Elements uniform API requests. Cloud Elements makes endpoint API requests using the OAuth tokens obtained from the endpoint. Each vendor's OAuth implementation varies slightly, but these details are handled by Cloud Elements. Cloud Elements also manages the app's OAuth access and refresh tokens internally. The user does not need to worry about storing these tokens or refreshing them when they expire. Page 27
Set up a new Volusion Application with the Endpoint Via a web browser go to: http://www.volusion.com/ and setup a store. Once setup, please login. From the Dashboard, click "Manage Store" Login to your storefront. Page 28
From the dashboard, click "Inventory" and then click "Import/Export". Click "Volusion API" Page 29
Make sure you enable public XML for both "Featured Products" and "All Products" and then click "Save". Next, scroll down to the Generic orders section, under Accounts and click "Run". Page 30
Click "Run" Copy the URL returned from the "Run" command. It will be needed to provision the Volusion Element. This will be shown below. Page 31
Below is an example of how to create an instance with the Volusion Element. The URL you copied from the step above is required to create an Instance. The create-instance file contains the data needed to create the Element Instance. In the case of Volusion, you will need to copy the encrypted password from the URL and insert it into the the JSON file. You will also need your Volusion store URL - this is located at the beginning section of the URL copied in the previous step. Lastly, you will need your Email Login. An example of the URL copied in the previous step can be seen below: http://otnqw.rakrt.servertrust.com/net/webservice.aspx? Login=volusion@acmedata.com&EncryptedPassword=64F3C0572DB54CB36951010E7200391 418E79AC678214B366FBD4E&EDI_Name=Generic\Orders The beginning portion of the URL is your store URL - 'http://otnqw.rakrt.servertrust.com'. Then the login email - volusion@acmedata.com, and finally the EncryptedPassword - 64F3C0572DB54CB36951010E7200391418E79AC678214B366FBD4E&EDI Below is an example JSON file. create-instance.json "name": "Test", "element": "key": "volusion", "configuration": "volusion.store.url": "http://otnqw.rakrt.servertrust.com/", "volusion.login.email": "<INSERT_VOLUSION_LOGIN_EMAIL>", "volusion.encrypted.password": "<INSERT_ECRYPTED_PASSWORD>" Next is an example of the create instance curl command and successful response. Page 32
Example Request curl -X POST \ -H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' \ -H 'Content-Type: application/json' \ -d @create-instance.json \ 'https://api.cloud-elements.com/elements/api-v2/instances' create-instance.json - JSON file needed to create instance. "name": "Test", "element": "key": "volusion", "configuration": "volusion.store.url": "http://otnqw.rakrt.servertrust.com/", "volusion.login.email": "<INSERT_VOLUSION_LOGIN_EMAILgt;", "volusion.encrypted.password": "<INSERT_ECRYPTED_PASSWORDgt;" Example Successful Response in JSON format "id": 13, "name": "Test", "token": "GUIWhK8NTPaeyKblo91CJ1PUonwnV/XJjRT6=, "element": "id": 14, "name": "Volusion", "key": "volusion", "description": "Volusion is everything you need to sell anywhere.", "active": true, "deleted": false, "typeoauth": true, "trialaccount": false, "existingaccountdescription": "Give your application access to your existing <br> Shopify account</br><span class=\"buttondescription\">enter your credentials and details for your <b>shopify Account</b></span>", "configdescription": "If you do not have a Volition account, you can create one at <a href= \"www.volusion.com\"", "signupurl": "www.volusion.com", "tags": [ "id": 13, "name": "Test" ], "provisioninteractions": [], "valid": true, "disabled": false Page 33
Set up a new Ecwid Application with the Endpoint Follow these steps to set up a new Ecwid Application for API integration. Via a web browser go to: https://my.ecwid.com/cp/#register and sign up. NOTE: It must be a paid account. Once setup, please login. Make note of your Store ID as it will be needed to create an Element Instance. Navigate to "System Settings" in the top right of your menu, underneath your username. Page 34
Make note of the Order API Secret and the Product API Secret as they will be needed to create an Element Instance. NOTE: Ecwid currently supports the the GET, PUT/PATCH, DELETE API calls. POST is not available at this time. In order to create an Ecwid instance, you will need the Store ID, Order API Key, and Product API Key. Below is an example JSON file. create-instance.json "name": "test", "element": "key": "ecwid", "configuration": "ecwid.order.key": "RpOSUQ94wtKk", "ecwid.product.key": "DQ9pLS98KhHg", "ecwid.store.id": "5938038" Next is an example of the create instance curl command and successful response. Page 35
Example Request curl -X POST \ -H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>' \ -H 'Content-Type: application/json' \ -d @create-instance.json \ 'https://api.cloud-elements.com/elements/api-v2/instances' create-instance.json - JSON file needed to create instance. "element": "key": "ecwid", "configuration": "ecwid.order.key": "<INSERT_API_ORDER_SECRET>", "ecwid.product.key": "<INSERT_API_PRODUCT_KEY>", "ecwid.store.id": "<INSERT_STORE_ID>", "name": "<INSERT_INSTANCE_NAME>" Example Successful Response in JSON format "id": 12345, "name": "test", "token": "dspr6ahelis8pt7rp8e81bsklunfgeekx9ftr+9y", "element": "id": 42, "name": "Ecwid", "key": "ecwid", "description": "Ecwid is everything you need to sell anywhere.", "image": "elements/provider_ecwid.png", "active": true, "deleted": false, "typeoauth": false, "trialaccount": false, "configdescription": "If you do not have a Ecwid account, you can create one at Ecwid Signup", "provisioninteractions": [], "valid": true, "disabled": false, "maxcachesize": 0, "cachetimetolive": 0, "cachingenabled": false END APPENDIX Page 36
This concludes the documentation for the ecommerce Hub. If you have any questions, please contact us at support@cloud-elements.com. Now what? Now you are ready to start integrating our ecommerce Hub Elements into your application. Give your customers access to their Shopify, etc. accounts right from your app. We will do our best to get back to you within 24 hours. Your success is our success. Thanks for reading. The Cloud Elements Team Page 37