Difference between revisions of "LiveCatalog XML-RPC API"

From Opentaps Wiki
Jump to navigationJump to search
m
(→‎Overview)
 
(2 intermediate revisions by one other user not shown)
Line 3: Line 3:
 
== Overview ==
 
== Overview ==
  
−
... description text ...
+
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 ==
 
== Methods ==
Line 115: Line 121:
 
:* QuantityInStock - ''<double>'' Product Quantity In Stock
 
:* QuantityInStock - ''<double>'' Product Quantity In Stock
 
:* DaysToShip - '' <double>'' Days to Shipping Availability
 
:* 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 ====
 
==== catalogexport.getProductContent ====
Line 302: Line 315:
 
:# ''<string>'' catalogId
 
:# ''<string>'' catalogId
 
:# ''<string>'' productStoreId
 
:# ''<string>'' productStoreId
−
:# ''<struct>'' cartItems of product Id - ''<double>'' quantity
+
:# ''<struct>'' cartItems of product Id - ''<double>'' quantity (note that virtual products will be ignored)
 
: Return''<struct>''
 
: Return''<struct>''
 
:* ExternalLoginKey - ''&lt;string&gt;'' Key to be provided to Opentaps in the request querystring<br />
 
:* ExternalLoginKey - ''&lt;string&gt;'' Key to be provided to Opentaps in the request querystring<br />

Latest revision as of 23:22, 14 November 2007

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)


Retrieved from "https://docs.opentaps.org/docs/index.php?title=LiveCatalog_XML-RPC_API&oldid=1562"