Getting started with uStore APIs

Introduction

uStore is a sophisticated eCommerce application that integrates with the uProduce server to provide customers with an ability to customize and/or personalize their document during the order process.

It is also extremely flexible, allowing developers to integrate uStore with many different 3rd party systems in several different ways.

Currently, uStore is undergoing a metamorphosis, changing from legacy ASP.NET to modern React JS development model. Some pages are fully React JS, while other pages load ASP.NET content into iframes in a React JS template. With each new version, more pages, features and content are moved to React JS. Because of this change, some older API interfaces are gradually being phased out as newer technology is introduced.

Licensing

Accessing the uStore API requires an optional license which is not included with all uStore configurations. However, license to use the uStore API can be purchased as an optional extra. Full documentation, SDKs and sample applications described below are available from XMPie Support only for customers who have purchased the uStore API license.

uStore NG themes

While it does not require the uStore API license, it is worthwhile to first mention uStore NG themes which allows administrators to customize the appearance of storefronts to suit their business (or their customer’s business) by using a browser-based theme editor in the uStore backoffice. When more structural changes are required, the uStore default theme can be downloaded and modified using React JS to create a totally custom theme.

uStore REST API

The uStore REST API is the recommended technology for developing new custom applications and integrations on the uStore platform. For applications that perform administrative tasks that would normally be performed in the backoffice, refer to the uStore Backoffice REST API.

To access the uStore REST API, developers must first use the store controller’s login action with the credentials of a store user who has access to the required store. A successful login action returns a token which is then used in the authorization request header for all other requests.

Documentation and information about using the uStore REST APIs is available by browsing to the uStore sever with this URL:

http://<your server IP address or hostname>/uStoreRESTAPI/

uStore backoffice REST API

A REST API for uStore backoffice tasks is currently in beta and is expected to be released later this year. Currently the backoffice REST API includes the following controllers:

Delivery

Orders

UserGroups

DeliveryProvider

Products

Users

DeliveryService

Stores

Widgets

uStore client-side API

The ASP.NET pages in uStore storefronts include a client-side JavaScript API that allows web developers to access key uStore information with JavaScript that can be injected into the page by using the Add JavaScript to Storefront feature. Note that this is not available on pages which are 100% React JS.

uStore WSAPI

The uStore Web Services API was the original way for external systems to interact with uStore. For example, it can be used when an ERP or MIS system wants to get order information from uStore, or when a shopping experience should seamlessly traverse from an external eCommerce site to uStore and back.

When using the Web Services API, the programmer is referencing a web service and calling its web methods. All the web methods require authentication of the calling user (username and password). This user must have permissions to call the Web Services API.

For instructions for granting permissions to a specific user, refer to uStore help, and the Access Web Service API permission.

Available web service classes include:

ActualDelivery

FileSubmission

ProductProperty

Address

Localization

Product

AssetSource

OrderProduct

Proxy

Asset

Order

RecipientList

CircleAnalytics

PaperSize

Store

Culture

Permissions

Tax

Currency

ProductGroup

TentativeDelivery

Customization

ProductInventory

Trigger

Document

Production

UserGroup

Customers with the uStore API license can request the full WSAPI SDK and documentation from XMPie Support.

uStore Connect

uStore Connect is a type of store that can be created with uStore. uStore Connect is designed to offer customers who already have a different eCommerce solution, to add dynamic or customizable products to their existing platform.

While a regular uStore B2C or B2B store type includes a catalog of products, the product customization form, shopping cart, clearing, and other sections, the uStore Connect store type includes only the product customization form component. The 3rd party eCommerce solution provides the catalog, cart, clearing and other sections.

When a customer in the 3rd party eCommerce solution selects a dynamic product, uStore Connect is opened either in a separate popup page, or in an iframe. The dynamic product is displayed, and user can make customization changes. When done, the item is passed to the cart on the 3rd party system and the customer can continue shopping or check out in the 3rd party system.

More information on uStore Connect.

Customers with the uStore API license can request the uStore Connect Sample Application from XMPie Support. The sample application includes a Visual Studio solution simulating a custom eCommerce solution that opens dynamic products from a uStore Connect store.

uStore Plugin API

uStore uses a plugin mechanism that enables developers to extend uStore functionality at several points in the application.

The plugins that uStore provides are:

  • Clearing: Used to add more clearing or payment methods to uStore. For example, to integrate with other credit card clearing companies or implement other types of payment.

  • Document Repository: Can make documents or products in another system available for uStore customers to order. For example, documents from a CRM or cloud storage provider.

  • Order management task: Used to add actions to the order list page in the uStore back office. For example, to send data to a procurement system, aggregate orders, or dispatch a production request to an external system.

  • Pricing: This plugin can pass information about uStore products to an external system to return product pricing to the storefront.

  • Recipient List: Can be used to get recipient list data from 3rd party systems to use to personalize products ordered in uStore. For example, to rent data from digital marketing companies.

  • Trigger: uStore’s trigger mechanism can be extended with actions to interact with external systems. For example, informing an MIS about an order being submitted, or updating a CRM when a new customer is registered.

  • User interaction control: The dial user control is used on the customization page and allows customers to enter or select a value that will be used to customize a dynamic product, or configure the property of a product. For example, a custom user control could allow users to select an image from an asset management system, or select a product information from a 3rd party web service.

Customers with the uStore API license can request the full uStore Plugin Base API SDK and documentation from XMPie Support.

uStore extensions

Tax webhook

Out-of-the-box uStore provides a tax calculator which is suitable for simple taxation use cases. When taxation is more complex, you can integrate an external tax service by using the tax webhook. This webhook allows the developer to get the order data, pass the required information to the tax service of their choice, and return the correct tax to the storefront. More information on the tax webhook.

Order approval webhook

uStore provides several options for order approval, but when the required order approval cannot be fulfilled by the available methods, you can integrate an external service or use custom logic with the Order Approval webhook. More information on the order approval webhook.

Manufacturer webhook

An external manufacturer can be defined on individual products in uStore. If you wish to set a specific manufacturer for each item in the shopping cart, you can use an external service, or custom logic by using the Manufacturer webhook. More information on the Manufacturer webhook.

Cart Export webhook

The Cart Export webhook provides developers with the ability to export cart item information to an external service for additional processing like backup, analysis, integration, or more. The uStore Connect Enterprise store type uses the Export webhook to get a URL to the custom checkout page. More information on the Cart Export webhook.

Widgets (beta)

Widgets are pieces of code that can be injected to specific locations in the uStore theme to allow the storefront to support new functionality. Developers can create their own custom widgets, or use one of the beta widgets provided by XMPie. More information on Widgets.