LiveCatalog XML-RPC API

Opentaps LiveCatalog XML-RPC API

Overview

The opentaps Live Catalog is a set of tools designed to help you build a store using a different framework or language which can access the products, customers, and order management services that opentaps offers in the back end. It can be used to build online stores in PHP, Ruby On Rails, Perl, or another Java framework.

The live catalog relies on a set of services which can be called remotely with either XML-RPC or SOAP protocols to retrieve product catalog information, including products, prices, and categories. You can either build your store by retrieving this information live from opentaps or cache in your store and periodically ask opentaps for updates.

When your customer is ready to checkout, you would call the opentaps live catalog with this map. opentaps live catalog initiates a session on opentaps and passes the login credentials back in the form of an externalLoginKey to your store. You can then re-direct your user to the opentaps site with this externalLoginKey, and the user would already be logged in and ready to checkout.

Your front end store could maintain a fairly simple shopping cart which is a map of productIds and quantities. When it is time for checking out, the opentaps catalogexport.security.initializeCheckout service will persist your map of productIds and quantities into a ShoppingList, and the opentaps online store should automatically restore your cart from this shopping list when you re-direct your visitors to the opentaps online store. You should set your ProductStore's "Auto Save Cart" feature to "Y" when you configure it in opentaps for this feature to work.

Methods

Catalog Export Methods

catalogexport.getProductCatalogIds

Starting point

Arguments

1. <string> systemId
   '
2. <string> productStoreId

Return<array> CatalogIds

catalogexport.getBrowseRootCategoryId

Get the root categoryId for a catalog

Arguments

1. <string> systemId
   '
2. <string> catalogId

Return<string> CategoryId

catalogexport.getSpecialCategoryIds

To get IDs for special categories like Default Search, Most Popular, etc.

Arguments

1. <string> systemId
   '
2. <string> catalogId

Return<struct> CategoryIds

• productCategoryTypeId => <string> productCategoryId
• ...

catalogexport.getCategory

Retrieve data for a category, including its product or category children.

Arguments

1. <string> systemId
2. <string> productStoreId
3. <string> catalogId
4. <string> categoryId
5. <string> userLocale

Return<struct> Category Data

• Name - <string> Category Name
• Description - <string> Category Description
• LongDescription - <string> Long category Description
• CategoryImageURL - <string> Category image URL
• CategoryImageAltText - <string> Alt text for category image
  
• ProductData => <array> of <struct> of type:
  • ProductId - <string> Product ID
  • Name - <string> Product Name
  • Description - <string> Product Description
  • ImageURL - <string> Product image URL
  • ImageAltText - <string> Product image alt text
  • PriceCurrencyCode - <string> Product price currency
    
  • IsSale - <boolean> Is the product on sale?
  • Price - <double> Product Price
  • ListPrice - <double> List Price
• ChildData => <array> of <struct> of type:
  • CategoryId - <string> Category ID
  • Name - <string> Category Name
  • Description - <string> Category Description
  • CategoryImageURL - <string> Child category image URL
  • CategoryImageAltText - <string> Child category image alt text

catalogexport.getCategoryContent

Retrieve content for a category

Arguments

1. <string> systemId
2. <string> productStoreId
3. <string> catalogId
4. <string> categoryId
5. <string> userLocale

Return<struct> Category Data

• Name - <string> Category Name
• Description - <string> Category Description
• LongDescription - <string> Long category Description
• CategoryImageURL - <string> Category image URL
• CategoryImageAltText - <string> Alt text for category image

catalogexport.getProduct

Retrieve data for a product.

Arguments

1. <string> systemId
2. <string> productId
3. <string> productStoreId
4. <string> catalogId
5. <string> userLocale

Return<struct> Product Data

• ProductId - <string> Product ID
• Name - <string> Product Name
• Description - <string> Product Description
• LongDescription - <string> Long product Description
• SmallImageURL - <string> URL for thumbnail image
• MediumImageURL - <string> URL for medium image
• LargeImageURL - <string> URL for large image
• DetailImageURL - <string> URL for detail image
• SmallImageAltText - <string> Alt text for thumbnail image
• MediumImageAltText - <string> Alt text for medium image
• LargeImageAltText - <string> Alt text for large image
• DetailImageAltText - <string> Alt text for detail image
• PriceCurrencyCode - <string> Price Currency Code
• Price - <double> Product Price
• IsSale - <boolean> Is product on sale?
• ListPrice - <double> Product List Price
• RequireInventory - <boolean> Require Inventory for sale?
• IntroductionDate - <dateTime> Timestamp of product introduction
• DiscontinuationDate - <dateTime> Timestamp of product discontinuation
• ProductType - <string> Product Type
• QuantityInStock - <double> Product Quantity In Stock
• DaysToShip - <double> Days to Shipping Availability
• Variants - <struct> If variants exist for the product it can not be added to the cart (one of the listed variant products should be added)
  • feature type description (eg. 'Size') => <array> Feature/Variant Product combinations
    • <struct> Feature/Variant Product combination
      • FeatureDescription - <string> (eg. 'Large', 'Small')
      • ProductId - <string> Variant product ID
      • ProductName - <string> Variant product name
      • ...

catalogexport.getProductContent

Retrieve content for a product.

Arguments

1. <string> systemId
2. <string> productId
3. <string> userLocale

Return<struct> Product Data

• Name - <string> Product Name
• Description - <string> Product Description
• LongDescription - <string> Long product Description
• SmallImageURL - <string> URL for thumbnail image
• MediumImageURL - <string> URL for medium image
• LargeImageURL - <string> URL for large image
• DetailImageURL - <string> URL for detail image
• SmallImageAltText - <string> Alt text for thumbnail image
• MediumImageAltText - <string> Alt text for medium image
• LargeImageAltText - <string> Alt text for large image
• DetailImageAltText - <string> Alt text for detail image

catalogexport.getProductKeywords

Retrieve keywords for a product.

Arguments

1. <string> systemId
2. <string> productId

Return<struct> Keywords

• keyword - <i4> weight
• ...

catalogexport.getAssociatedProducts

Retrieve associated products (eg: cross-sell, upgrade, etc) to a given product.

Arguments

1. <string> systemId
2. <string> productId
3. <string> productStoreId
4. <string> catalogId
5. <string>

Return<struct> AssociatedProducts

• associationType => <array> products
  • <struct> Product Data
    • ProductId - <string> Product ID
    • Name - <string> Product Name
    • Description - <string> Product Description
    • ImageURL - <string> Image URL
    • ImageAltText - <string> Image alt text
    • IsSale - <boolean> Is the product on sale?
    • Price - <double> Product Price
    • ListPrice - <double> List Price
    • PriceCurrencyCode - <string> Currency

catalogexport.getAvailablePromotions

Provides a list of descriptions of promotions available. If a userId and password are specified, the promotions will be filtered accordingly.

Arguments

1. <string> systemId
2. <string> productStoreId
3. <string> userLoginId
4. <string> password

Return<struct>

• AvailablePromotions - <array> Descriptions of available promotions

catalogexport.getCategoryHierarchy

Provides a full representation of the category data structure, considering the top level as the given categoryId. Category names will be based on userLocale.

Arguments

1. <string> systemId
2. <string> categoryId
3. <string> userLocale

Return<struct>

• CategoryId - <string> The argument categoryId
• CategoryImageURL - <string> URL of the image for the argument category
• Name - <string> Name of the argument category
• ProductCount - <i4> Number of products in the argument category
• ChildData - <array> Child categories of the argument category. Each array member mirrors the return structure of the procedure (CategoryId, CategoryImageURL, Name, ProductCount, ChildData)

catalogexport.getProductTypes

Provides a list of all product types.

Arguments

1. <string> systemId
2. <string> userLocale

Return<struct> ProductTypes

• productType => <struct>
  • Description - <string> Product type description
  • IsPhysical - <boolean> Product is a physical product
  • IsDigital - <boolean> Product is a digital product

Catalog Export Helper Methods

catalogexport.getProductPrices

Retrieve prices for a product.

Arguments

1. <string> systemId
2. <string> productId
3. <string> productStoreId
4. <string> catalogId

Return<struct>

• PriceCurrencyCode - <string> Price Currency Code
• Price - <double> Product Price
• IsSale - <boolean> Is product on sale?
• ListPrice - <double> Product List Price

catalogexport.getProductName

Simple product name retrieval.

Arguments

1. <string> systemId
2. <string> productId
3. <string> userLocale

Return<string> Name

catalogexport.getCategoryName

Simple category name retrieval.

Arguments

1. <string> systemId
2. <string> categoryId
3. <string> userLocale

Return<string> Name

catalogexport.getProductDescription

Simple product description retrieval.

Arguments

1. <string> systemId
2. <string> productId
3. <string> userLocale

Return<struct>

• Description - <string> Product Description
• LongDescription - <string> Long Product Description

catalogexport.getCategoryDescription

Simple category description retrieval.

Arguments

1. <string> systemId
2. <string> categoryId
3. <string> userLocale

Return<struct>

• Description - <string> Category Description
• LongDescription - <string> Long Category Description

Membership Methods

catalogexport.security.getAuthenticatedUser

Authenticate a user/member and return simple member data.

Arguments

1. <string> systemId
2. <string> userLoginId
3. <string> password

Return<struct>

• FirstName - <string> User first name
• LastName - <string> User last name
• FullName - <string> User full name
• Suffix - <string> User suffix (eg. Jr)
  
• Title - <string> User form of address
  
• Email - <string> User email
• Locale - <string> User's last locale
  

catalogexport.security.performExternalLogin

Authenticates a user and stores an external login key.

Arguments

1. <string> systemId
2. <string> userLoginId
3. <string> password

Return<struct>

• ExternalLoginKey - <string> Key to be provided to Opentaps in the request querystring
  

catalogexport.security.initializeCheckout

Authenticate a user, set up a shopping cart, and return an external login key which can be used to redirect the user to the Opentaps checkout. (IE: http://demo1.opentaps.org/ecommerce/control/showcart?externalLoginKey=EL7429384 )

Arguments

1. <string> systemId
2. <string> userLoginId
3. <string> password
4. <string> catalogId
5. <string> productStoreId
6. <struct> cartItems of product Id - <double> quantity (note that virtual products will be ignored)

Return<struct>

• ExternalLoginKey - <string> Key to be provided to Opentaps in the request querystring
  

Search Methods

catalogexport.search.getAvailableProductFeatures

Get available product features for populating a search form

Arguments

1. <string> systemId
2. <string> userLocale

Return<struct> AvailableFeatures

• featureTypeDescription => <struct>
  • <struct>
    • FeatureTypeID - <string> Product feature type ID
      
    • Features - <struct> Features available
    • <struct>
      • featureDescription - <'struct'>
      • <'struct'>
        • FeatureID - <string> Product feature ID
        • ...

catalogexport.search.getSortOrders

Get available sort orders for populating a search form

Arguments

1. <string> systemId
2. <string> userLocale

Return<struct> SortOrders

• sort order key - <string> Sort order description
• ...'
  

catalogexport.search.searchProducts

Search the catalog for products

Arguments

1. <string> systemId
2. <string> catalogId
3. <string> productStoreId
4. <string> countryCode
5. <string> categoryId
6. <string> sortOrder
7. <string> keywordString
8. <string> searchOperator
9. <boolean> searchSubcategories
10. <'boolean'> ascendingSort
11. <array> includeFeatureIds
12. <'array'> excludeFeatureIds
13. <double> priceRangeLow
14. <'double'> priceRangeHigh

Return<array> ProductIds'

catalogexport.search.findProductsByKeyword

Simplified access to the searchProducts method, specifying only a keyword string and using all default settings.

Arguments

1. <string> systemId
2. <string> catalogId
3. <string> productStoreId
4. <string> keywordString
5. <string> userLocale

Return<array> of <struct> of product data (see catalogexport.getProduct)

catalogexport.search.findRecentProducts

Default product search limited to most recent products, ordered by creationDate descending. Limit, fromDate and toDate arguments are optional - if none are specified the entire catalog will be returned.

Arguments

1. <string> systemId
2. <string> catalogId
3. <string> productStoreId
4. <int> limit
5. <dateTime.iso8601> fromDate
6. <dateTime.iso8601> toDate

Return<array> of <struct> of product data (see catalogexport.getProduct)