bloyal Integration and API Overview

Transcription

1 bloyal Integration and API Overview Last Updated: September 15, 2016 Helping you build loyal customers TM 1 of 10 Copyright bloyal.com. All Rights Reserved

2 1. Introduction bloyal is a cloud based omni-channel customer loyalty and order processing platform that works across channels and devices. A key part of being an omni-channel solution is integration with other systems. bloyal provides an open integration service to enable clients and partners to integrate bloyal with any system. Our goal is to make it easy for you to add bloyal services to your POS application, Ecommerce system, web site, or BackOffice system. This document provides a high level overview of the integration options provided by bloyal along with the integration scenarios they were intended for. For more detail please see one of the following detailed integration guides. Each are made available with a signed NDA with bloyal and can be found in the bloyal API support forum. bloyal-cart-rest-api-guide This document is intended for web designers/developers integrating bloyal into a client s web site. bloyal-pos-integration-guide - This document is intended for POS vendors or BackOffice application vendors developing a connector to bloyal. bloyal-ecommerce-integration-guide This document is intended for Ecommerce vendors developing a connector to bloyal. 2. Integration Use Cases The bloyal APIs were designed around the following primary users and use cases. Custom Web Designers/Developers Web developers either working for a bloyal client or on behalf of a bloyal client to integrate bloyal loyalty and order processing into a client s web site. This is typically a custom one-off integration. See the bloyal-rest-api-guide-v4 for more detailed information. POS Application Vendors POS application vendor integrating the bloyal Loyalty Engine with their POS application as a product integration that is intended to be reused across clients using the POS Application. This is to enable in-flow promotions, loyalty accruals and benefits, and (optionally) POS shipping and pick up orders. See the bloyal-pos-integration-guide for more detailed information. Ecommerce Application Vendors Ecommerce applications integrating bloyal into their ecommerce/web store system as a product integration intending to be reused as a product. This is to enable in-flow promotions, loyalty accruals and benefits within the Ecommerce system cart. Orders can also be submitted to bloyal for fulfillment via any of the bloyal integrated BackOffice applications and fulfillment houses. See the bloyal-ecommerce-integration-guide for more detailed information. BackOffice Application Vendors BackOffice applications or 3 rd party analytics systems needed to update data in bloyal or pull sales transactions from bloyal. 3. API Integration Options bloyal provides the following three integration options depending on your integration use case. 2 of 10 Copyright bloyal.com. All Rights Reserved

3 1. bloyal Snippets TM bloyal snippets provide a simple way to add bloyal functionality to any web site or POS system with minimal or no development. Snippets are mobile responsive and are designed to work with any web or POS system. The functionality of a snippet is fixed and part of the bloyal product but there is some configuration the client can do for enabling and disabling fields, etc bloyal provides the following two types of snippets: Web Snippets A web snippet can either be a snippet of HTML a designer adds to a web site or a link to a bloyal hosted page. The latter Hosted snippet provides advanced functionality without any programming while still enabling the web designer to have total control over the design of the snippet container. POS Snippets POS snippets provide an easy way to provide cashier specific bloyal functionality to a POS system with minimal development. This includes customer signup, global customer editing, club member signup, and support of POS shipping and pickup orders. The POS snippets work in consulting with the Loyalty Engine API. 2. bloyal Cart REST API The Cart API provides web developers with programmatic access to any data associated with snippets so that you have full control over the design, flow, and hosting of a client s web site while leveraging the bloyal platform for loyalty and order processing. 3. bloyal System API The bloyal System API are made up of the bloyal Loyalty Engine TM, bloyal Loyalty Grid TM and bloyal Payment Engine TM. The system API are intended to be used by application vendors to integrate bloyal into an application. The loyalty engine enables you to add the bloyal loyalty and promotions engine inflow of a transaction, process gift cards using the payment engine, and synchronize data between systems using the bloyal grid. Note: Integrations using the system API need to be certified with bloyal. 4. bloyal Cart REST API Overview The bloyal Cart REST API expose entities (resources) via standard URIs. You get an entity resource using an HTTP GET, update an entity using an HTTP PUT, and add a new entity using an HTTP POST. Most of the Cart API resources do not require a separate web service user account. They are limited by what an individual customer (e.g. shopper) can do. The Cart API are enabled for a client via snippet configuration in a client s Loyalty Director account and are accessed using the following URL, where the WebSnippetsApiUrl is from section 6.1 below: {WebSnippetsApiUrl}/[Company]/[SnippetCode] The REST API contain the following resources. Customer Resources The customer resources enable you to log in a customer (e.g. shoppers) and get and set customer data for the logged in customer. /CustomerSession The customer session resource is used to log in a customer and get some basic information about the customer (e.g. loyalty program and club memberships). /Customer The customer resource contains all the information about a customer. It requires that the customer be logged in to 3 of 10 Copyright bloyal.com. All Rights Reserved

4 access. /Balances Returns the gift and loyalty balances for a balance check page on a web site. Cart Resources The cart resources enable you to programmatically use the bloyal shopping cart without any of the cart snippet UI. I.e. you can leverage the bloyal cart processing with your own UI. /ShippingOptions Returns the shipping options available for the store or address. /Cart The cart resource contains all the entities related to a shopping cart (e.g. customer, products and shipments). 5. bloyal System API Overview The information outlined in the following sections is critical to achieving the desired results when integrating with the bloyal platform. 5.1 bloyal System API The System API provide programmatic access to the bloyal engines using RESTful API methods. These are used to develop certified application connectors for bloyal. To access the bloyal System API, an access key will be required for authentication. Please refer to section 3.1 below for information on generating an access key. Listed below are the 3 sets of API available for you to use depending on which part of the bloyal platform you wish to include with your application. The loyalty engine provides the resources necessary to incorporate the bloyal loyalty and promotions engine into any application. These API are exposed using the following base URI, where the LoyaltyEngineApiUrl is from section 6.1 below: {LoyaltyEngineApiUrl}/api/v4/ Loyalty Engine These API focus on providing the key functionality required to integrate in-flow of the transaction. Create and edit customers The loyalty engine allows you to create new customers and manage the information of existing customers. Calculate, Approve and Commit carts The loyalty engine enables you to embed the loyalty and promotions engines in-flow of the transaction for discounts, offers, and loyalty benefits. Visit Transactions The loyalty engine allows you to get the visit types available for a device (e.g. POS register or Ecommerce store) and record visit transactions with bloyal. 4 of 10 Copyright bloyal.com. All Rights Reserved

5 The bloyal grid is a highly scalable integration service provided by bloyal that synchronizes key data between bloyal and 3 rd party applications. The grid makes it easy for channel application vendors (e.g. POS and Ecommerce applications) to omni-channel enable their applications. The grid takes care of most of the heavy lifting required to synchronize data between systems and automatically handles resolutions utilizing bloyal s patent pending Dynamic Resolution Technology TM. These API are exposed using the following base URI, where GridApiUrl is from section 6.1 below: Loyalty Grid {GridApiUrl}/api/v4/ The data that can be synchronized includes, but is not limited to: Product and Inventory data Product Catalogs Customers Club Memberships Sales Transactions Orders Reference Entities - Various other entities Payment Engine The bloyal Payment Engine API expose the ability to integrate bloyal gift card and loyalty tender processing into your application. These API are exposed using the following service endpoint, where PaymentApiUrl is from section 6.1 below: {PaymentApiUrl}/ws35/PaymentEngine.svc 5.2 Key Concepts These are some key concepts/resources relating to the Loyalty Engine and Loyalty Grid APIs. These can also be referred to collectively as the bloyal System APIs. Client Login Domain This is the login domain of the bloyal account being targeted by the bloyal API. Connector Key This is a key value that identifies the specific application (i.e. system) that is issuing bloyal API requests. API Key This is a value used in the generation of an access key and is defined to be at either the Device, Store, or Client level. Access Key This is a key value that is generated from the combination of a connector key and an API key. It is used in conjunction with the client login domain to authenticate access to the bloyal System APIs. Session Key This is a key value that is generated from an access key. It is used to authenticate access to the bloyal POS snippets. System This is used to describe the source system that is being integrated with bloyal. A system could represent a single database, or a collection of databases. 5 of 10 Copyright bloyal.com. All Rights Reserved

6 IMPORTANT: When using the bloyal API, providing a null value or leaving a field out of the request entirely will result in that field being omitted from any entity updates. By contrast, providing an empty value for a field will erase whatever data might have been present in that field previously. Keeping this in mind will help ensure the desired results when using the Loyalty Engine and Grid APIs. 6. bloyal System API Access Information All of the information necessary to access and make use of the bloyal System API is provided below. 6.1 Obtaining bloyal Service URLs A critical requirement to the success of any integration with bloyal is to retrieve the clientspecific service URLs from bloyal. This will provide service endpoints for the bloyal Loyalty Engine, Grid, Payment Engine, and POS Snippets, among others. Retrieval of this information is achieved in one of two ways, depending on the use of bloyal web API or Nuget packages (described below): Using the bloyal web API, a GET request can be issued to the following endpoint: Using the bloyal Nuget packages, the GetServiceUrlsAsync() method is used. Once this information is retrieved, it should be cached in memory for quick access, as the integration components described in this document are directly dependent on the service URLs retrieved. The process to obtain service URLs from bloyal should be performed according to the following: 1. At startup of the integrated system Whenever the external system starts up, bloyal service URLs should be retrieved and cached in memory. 2. Prior to the start of a bloyal integration batch. 3. On a regular schedule (e.g. every 1 hour). If at any point while calling a bloyal service a ServiceRedirect error code is returned, this indicates that the client-specific service URL for that target service has changed and that the cached service URLs should be updated. It is recommended that one of the following happen: Restart the system Since bloyal service URLs should be obtained automatically at startup, restarting the external system will trigger an automatic update and should resolve the ServiceRedirect error. Automatically refresh the service URLs behind the scenes To avoid a system restart or if the external system is a web server that cannot reasonably be restarted, the service URLs could be refreshed automatically and then retry the bloyal communication. 6.2 Generating an Access Key To generate an access key, make a POST request to the following bloyal Grid resource, supplying the appropriate client login domain, connector key, and API key: 6 of 10 Copyright bloyal.com. All Rights Reserved

7 {GridApiUrl}/api/v4/KeyDispenser IMPORTANT: Once an access key has been generated, it should be stored securely and not exposed via any UI. This access key provides API access to the target bloyal account and it is important that this key remain confidential. 6.3 Reference URLs The following URLs provide a reference to the Loyalty Engine and Grid API structure. From these URLs, it is possible to determine the API request and response structure for each available API resource. Loyalty Engine API Reference: Grid API Reference: Identifying external entities When integrating with bloyal, a link is established and maintained between the external system s entities and the corresponding bloyal entities (e.g. a POS transaction or ecommerce order can be linked to a bloyal cart). This link can be in one of three forms: 1. ExternalId This is a globally unique identifier across the entire external system for a given bloyal client. Use this value if the entity has a unique identifier that is guaranteed never to be duplicated. 2. SourceExternalId This is an identifier that is unique only within a given store. 3. Uid This is bloyal s unique identifier for the entity. Use this value if the external system doesn t provide a unique identifier for the entity. The mechanism that is chosen to establish this link should be consistently supplied throughout the integration. Example: For in-flow discounting and customer signup, if ExternalId is chosen to be used as the unique identification field for the external system s transaction or order, then the appropriate ExternalId field will need to be provided when calling the calculate cart command resource. The same ExternalId field should also be provided when launching any bloyal POS snippets and within any backend data integration (i.e. submitting the sales transaction). 6.5 Web API vs. bloyal Nuget Packages The Loyalty Engine and Loyalty Grid are exposed via a set of RESTful API resources, as well as bloyal Nuget packages that provide method wrappers for those RESTful API resources. Both of which are available for use when integrating with bloyal. RESTful Web APIs: For integrations being implemented in non-.net environments, the web APIs can be called directly. These web APIs support standard HTTP request methods (GET, POST, etc.). bloyal Nuget Packages: For integrations being implemented in.net environments (or if this is the preferred method of implementation), bloyal offers Nuget packages for both the Loyalty Engine and Grid. These packages provide asynchronous method wrappers for their respective set of APIs. These Nuget packages can be found on the bloyal public MyGet feeds (see below). (Visual Studio 2015+) (Visual Studio 2012+) 7 of 10 Copyright bloyal.com. All Rights Reserved

8 6.6 SDK Sample Applications We provide two SDK sample applications as experimental tools for working with the bloyal System API. If a bloyal support center account has been provided, the applications can be downloaded from the API Support area of the Help Center forums. If no bloyal support center account has been provided, the applications will be provided separately. Loyalty Engine Sample Application: Both the executable (.exe) file as well as the source code are available for external use. This sample application makes use of the bloyal Loyalty Engine Nuget package (outlined in the above document) and allows for investigation of the Loyalty Engine APIs. Grid Sample Application: Both the executable (.exe) file as well as the source code are available for external use. This sample application makes use of the bloyal Grid Nuget package (outlined in the above document) and allows for investigation of the Grid APIs. 6.7 Examples The figures below demonstrate the structure for issuing calls to both the Loyalty Engine and Grid web API resources. Figure 1: Using the Loyalty Engine to signup a new customer 8 of 10 Copyright bloyal.com. All Rights Reserved

9 Figure 2: Using the Grid to save a product change When using the bloyal Nuget packages instead of issuing requests to the web API directly, the corresponding method wrappers in the Nuget packages for the above web API resources are: /customers/commands/signups SaveCustomerAsync() /Products/Changes SaveChanges<Product>() 9 of 10 Copyright bloyal.com. All Rights Reserved

10 7. bloyal Snippets POS Snippets To leverage existing bloyal API functionality within a fixed HTML framework, the bloyal POS snippets are available. The POS snippets provide basic functionality, such as finding an existing bloyal customer or creating a new customer, applying coupons, and recording a visit, as well as advanced order processing capabilities. All POS Snippets are launched in the same way by POSTing the query string parameters mentioned below to the following base URL, where the POSSnippetsUrl is from section 6.1 above: {POSSnippetsUrl}/POS 7.1 POS Snippet Protocol Use of the POS snippets require the following: 1. The ability to launch an HTML window within the external system 2. Three query string parameters: a. SessionKey This is obtained using an existing access key. b. LoginDomain This is the same as the one used for accessing the Loyalty Engine and/or Grid API. c. CartExternalId, CartSourceExternalId, or CartUid This is any one of the fields described in section 6.4 above. d. CashierCode This is the identifier of the current POS cashier or user. This is used by bloyal to enforce certain cashier vs. manager override configurations. 10 of 10 Copyright bloyal.com. All Rights Reserved