Circles.png

  until the 2018 eoStar User Forum and Technology Conference (August 13-16)
Click here for details

Customer Web Service Programmer API

From Wiki-eostar.com
Jump to: navigation, search

This is the API reference for Web Application developers desiring to interface with the eoStar system for the purposes of creating application for a distributor's customer to place orders, view information and provide a web-based self-service experience.

Current Version: 12.3.16 Structures and programming models are subject to change. Please bookmark this page and reference from release to release to get a summary of material changes to the structures used.

Contents

Customer Web Ordering System

The Customer Web Service is a component of the eoStar Customer web ordering system. The entire customer-web experience however, is three components

  1. The web application (your application or Rutherford's Customer Web Application)
  2. The Customer Web service (This document)
  3. The eoStar Customer Web Plugin (a plugin that is a part of the distributor's eoStar system)

But more than just a web-based ordering mechanism, the eoStar customer web service opens up many more items that just placing orders online.


Terminology used in this document

Distributor 
The eoStar customer, the wholesale distributor running the eoStar system
Customer 
The wholesale distributor's customer. That is, the retailer doing business with the distributor.
Web Service
The component of the eoStar system which this document highlights


Installation

This document only covers installation of the web service component. The CustomerWebPlugin is installed by the distributor and behaves like the other eoStar plugins.

The web service is installed using the CustomerWebServiceSetup.msi available from the distributor, or from Rutherford once your interface account is supported. The web service operates with IIS as the hosting process. Specifically, IIS7 or better is recommended. The examples and screen clips used in this document will be with IIS7 based systems.

The published virtual directory can be on any IP port of your choosing and on any virtual service public name desired. For our samples, we will use the defaults that ship with the CustomerWebServiceSetup.msi which has the following properties

  1. Uses the default CustomerWebService public name
  2. Loaded into the default web site physical path (typically c:/intepub/wwwroot/CustomerWebService)
  3. Communicates via TCP port 80

However, for production systems, it is highly recommended that you place the web service on a secured TCP port (such as 447, so https can be used). The samples shown here will use the defaults and will be clipped from a developer's machine where the web service is loaded onto the localhost

To check the installation, navigate to this address http://localhost/CustomerWebService/login.asmx

Cws01.png


Configuration

The web service itself has no configurable components, however the hosting IIS server does need to have connection information defined to connect the web service to the distributor's eoStar database. The Web.Config_and_Handheld_Connections_For_eoMobile_2009 connection configuration used by eonetservice web service is performed. It is not required that eonetservice (the mobile eostar communication mechanism) is installed on the same host as the customer web service portal. In fact, these machines may be located at a hosting provider.

To configure a connection, you must have admin access to the IIS server. We recommend adding a connection to the connection strings of the IIS server. For our samples we will use the connection named "demo"

Cws02.png

This architecture allows for a single web service to service multiple eoStar databases. Likewise, multiple web applications may use a single web service. Most customers will have a single eoStar database, but there may be eoStar deployments with multiple databases. Please consult with the distributor as to the proper connection. The Customer Web Service will be making SQL calls into the eoStar database on behalf of the web application. The web service manages all of the information needed for the web application. It is also web-farm enabled as session cart information is stored in the actual eostar databases enabling a secured session recovery model for web applications.

Process Flow

Design

The web service runs a RESTful API (non-state machine), but does have an implicit and expected process flow. For our purposes here, we will outline a typical session to look something like this:

Cws03.png

Service Points

The web service has service entry points supporting the various activities. These service pages each contain methods that are called to perform functions to get information, process carts and place orders

Cws04.png

  1. Login.asmx is the login page and used for security information between the web application and the web service - The rest of the service entry points depends on the security tokens received from this service point.
  2. Access.asmx is the service entry point that defines the security particulars for any given web login
  3. Brands.asmx is the service entry point used to get information about brands.
  4. Cart.asmx is the service entry point used to manage web shopping cart information. This is the web service point you will use for all shopping cart activity
  5. Items.asmx is the service entry point used to retrieve item master and item detail information
  6. Customer.asmx is the service entry point used to retrieve customer level information for the login. It would include master information for the account(s), but also has access to historical orders delivered and basic reporting.

Please note there is no logout functionality. It is not required by the web service and this is discussed further in the security section of this document

High-level data structures

The web service returns high-level strongly typed objects as a basis of its operation.

PlusOption

Most every high-level data element contains the following common item, this is called a PlusOption and is a base class

  1. RecNid is the unique numerical identifier of the record
  2. RecKey is the distributor's unique record number
  3. RecName is the distributor's description of the record

As an example, an item may be RecNid=10, RecKey="9402", RecName="Bill's Best Beer". The RecKey would correspond to how the distributor identifies the item (i.e., product number 9402). The RecName is the name of the item. The RecNid is the unique identifier for that exact product in the distributor's database. No two records of the same type ever have the same RecNid.

Brand

This is an item's brand identifier (this is a PlusOption class)

WebDescription
long string description about this brand. It is typically the official branding marcom info
IsWine
This flag indicates if this brand is a Wine (true) brand or not
IsStrongBeer
This flag indicates if this brand is a strong beer
BrandLogo
official logo of the brand (in a base64 encoded string)
BrandUrl
The URL referring to more information about the brand. Typically this is off-site URL to the brand marketing web site


Category

This is an item's category (this is a #PlusOption class)


Cust

This is a customer record (this is a #PlusOption class)

MailAdr1
1st Mailing address line
MailAdr2
2nd Mailing address line
MailCity
City mailing address
MailState
State mailing address
MailZip
ZIP mailing address
ShipAdr1
1st Ship-to address line
ShipAdr2
2nd Ship-to address line
ShipCity
City ship-to address
ShipState
State ship-to address
ShipZip
ZIP ship-to address
AccountStatusMessages
Array of strings corresponding to some information about this customer. Typically service messages
HoldCodeRecKey
If this customer has been placed on an accounting hold (no orders), then this is filled out with the code#
HoldCodeRecName
If this customer has been placed on an accounting hold (no orders), then this is filled out with the code name
HoldCodeIsNoSell
Hold codes may or may not be no-sell codes. If this field is true, no web orders for this outlet will be allowed
FutureDeliveryDates
Array of the next scheduled delivery dates. A shipping date on a web order has to be one of these
AccountBalance
Current balance of this outlet
SalesRepName
Sales rep name responsible for this outlet
SalesRepPhone
Sales rep phone number
PaypalPayNowURL
If paypal option is turned on in the distributors database, this is the PayNowURL for paypal payments
HasExpiredLiquorLicense
True of this outlet's permits or licenses have expired.
IsOverCreditLimit
True if outlet is over their credit limit. Web orders may or may not be accepted, based on distributor policies


CustomerCanBuy

This is how for a particular account, you can determine what items are sellable to them

SellableItem
Array of #SellableItem


CustReceivable

This is a customer's receivable record (past-dues, etc)

CusNid
Unique customer identifier for this receivable line, points to a #Cust record
CusRecKey
Unique customer record number (the customer number the distributor would see)
CusRecName
Customer name
RecvDate
This receivable entry date
BillToNid
If this recivables is a different bill-to, this is the unique id for that account, and it points to a #Cust record
OriginalAmount
Original amount of this receivable item
TotalOwed
Total still owed on this item
DueByDate
The date it is due by
PastDueAmount
The past-due amount (not all of this receivable may be past-due)
OpenCredit
The amount of credit left
FullDescription
Full description about this receivable
ReceivablesNote
Any special note entered by accountants about this receivable
OrderNumber
If this receivable is about a past-due invoice, this is the order/invoice number
CusPaymentNid
Unique identifier of the CusPayment (internal use)
CusChargeNid
Unique identifier of the CusCharge (internal use)
PaymentTermsNid
Unique identifier of this transaction's payment terms (internal use)
CusPaymentTermsNid
Unique identifier of this account's payment terms (internal use)


HistoricalOrder

This is a historical order going to a customer

OrderedDate
Date order was placed
CartId
The unique web shopping cart id it was a part of at that time
ToCusNid
The #Cust record to which this order was shipped-to
DeliveryDate
The date of the delivery
SpecialInstructions
Special delivery instructions (if any)
XUnitDeposit
Extended unit deposit (USD$)
XUnitDisc
Extended unit discount (USD$)
XUnitFreight
Extended unit freight (USD$)
XUnitPrice
Extended unit price (USD$)
TotalAllFrieghtAndDeliveryCharges
Total of all freight and delivery charges
XUnitPriceLesDiscPlusDepositPlusSalesTax
Extended unit price, less total discount, plus total deposit, plus sales tax (i.e., Net invoice total)
SalesTax
Sales tax charged on this order (USD$)
PONumber
Customer's PO Number, if any, for this order
TotalWeight
Total weight of this order
Lines
Array if #OrderHistoryLine (it is an array of each line on the order)


OrderHistoryLine

This is a historical order's detail line. It is based on and contains members of a #ShoppingCartLine and adds these members

FullDescription
The item's full description
RecName
The item's regular description
PackName
Indicator of the package name (Typically 'Case', or 'Keg', etc.). This is not a name of a Package Record


Item

This is an item. An item is a #PlusOption based record and adds these fields

AltPackFamilyNid
A pointer to another #Item record which indicates the family of products this is a part of. For example, a particular product offered in Cases as well as 6-Packs for sale, would be a part of the same AltPackFamilyNid, with this member being set to the main selling unit
FullDescription
The item's full description
BrandNid
The #Brand record to which this item is associated with
PackageNid
The #Package record to which this item is associated with
CategoryNid
The #Category record to which this item is associated with
PackName
Indicator of the package name (Typically 'Case', or 'Keg', etc.). This is not a name of a Package Record
HasImage
True if this item has an image available for the web


ItemAddError

This is a result class when attempting to add item(s) to a web shopping cart. There are many checks in eostar when adding an item to a web shopping cart. For example, the item may not be allowed to be sold to a particular customer.

ItemNid
A pointer to the #Item record which indicates the item
ErrorMessage
If this is filled out (non-blank), then there was a problem adding this item to the web shopping cart. This is the text reason why.


ItemPhoto

This is an item's photo. This is based on a PlusOption record. The RecNid in this record points to an #Item record

JpegPhotoBytes
this is an array of binary data that is a JPG image of the item
NewestRowVersion
this is the newest version identifier in eostar.

It should be noted that eostar bumps the NewestRowVersion when an image changes in the database. That way, photo images can be cached for a particular row version. When that row version changes, images should be removed and re-cached


MoreItemInfo

This is an extension class to item, and contains highly valuable information about a particular #Item

WebUrl
This is a URL to more information about this item
CaseUPC
This is the UPC for the Case level of this item
RetailUPC
This is the retail UPC for this item
BrandName
This is the brand name for this product
IsWine
True if this item is wine (the Wine fields will be important)
BrandWebUrl
The URL corresponding to the brand information.
BrandDescription
Marketing information about the brand
WineVintage
Vintage of the wine
WineRegion
Region it came from
WineVarietal
The varietal of the wine
WineClassification
The wine classfication
WineAppellation
The appellation of the wine
WineType
The type of wine
WineCharacter
The wine's character
WineColor
The wine's color
WineCountry
Country of origin of the wine
WineScoringSystem1
1st wine scoring system name used to score the wine
WineScore1
The wine's score in the first system of scoring
WineScoringSystem2
2nd wine scoring system name used to score the wine
WineScore2
The wine's score in the second system of scoring
AlcoholByVolume
The %ABV of the beer
IBUValue
The international bitterness units of the beer
ColorValue
The beer's color value
UnitCalories
The beer's unit calories
UnitCarbs
The beer's unit carbs
FoodPairings
Food pairing for this item
Proof
Proof value of this item


Package

This is a package identifier record for an item. This is a #PlusOption record and adds the following fields

PackageTypeNid
Unique identifier pointing to a #PackageType record


PackageType

This is a package type record for a package. This is a #PlusOption record


PromoData

This is promotional information for an account. It is a #PlusOption record and contains promotional information as follows

PromoName
Name of the promotion
SectionDescription
Description about the deal name
SectionFromDate
Date from which the promotion starts
SectionThruDate
Date thru which the promotion applies
SectionStatus
text status about this promotion
PromoNote
Any special note information about this promotion
ItemPackName
Pack-name of the item this promo applies (Case, 4Pak, etc)
ItemRecName
RecName of the #Item to which this applies
ItemRecKey
The RecKey of the #Item to which this applies
ItemRecNid
The RecNid of the #Item to which this applies
PromoDescription
The full description about this promotion
TriggersGroup
If there is a trigger group, to which group does this belong to


SellableItem

This is a Sellable item record. It gives information about which items can be purchased for an account

RecNid
The RecNid of the #Item to which this applies
FrontLinePrice
The front-line price of this item (no discounts applied, USD$)
DiscountsAvailable
True if there are promotions available for this item (see #PromoData


WebCatalog

Distributors may organize items into web catalogs. These are targeted marketing campaigns. A Webcatalog is a #PlusOption record

FromDate
Start date of this web catalog
ThruDate
End date of this web catalog
Description
Description of this web catalog
ItemNids
An array of RecNid which point to #Item records that belong to this catalog
CusNids
And array of RecNid which point to #Cust records that take part in this catalog


WebLogin

From the access service point, a particular web login may have extended information. This is a #PlusOption record and adds the following fields

ShipToCusNids
This is an array of RecNid which point to #Cust records that this web login is can take orders for. A single web login may take orders for 1 or more customer ship-to outlets.
PaypalPluginInstalled
True if the distributor's system is able to handle payments via paypal
HasWebInvoiceFormat
True if there is a web invoice format available
AdCatalogNid
A recnid pointing to a #WebCatalog which indicates the specials the distributor wants this web login to take note of


Connecting to the web service

You can use any WSDL compliant browsing service to connect to the web service and obtain service methods and data contracts from it. In this screen example, I have a demo web application and I am adding a web reference to the login entry point

Cws05.png

To add the web reference, place in the service entry point. Of course, you can specify your own desired entry alias. Here, CusWeb.Login is used

Cws06.png

This will create (in an ASP.NET application) a service proxy to the customer web service login service entry point. You would similarly do so for the other service entry points in for the web service.

Acceptable and enabled protocols are HTTP POST as well as SOAP 1.1 and SOAP 1.2 calls into all web service points. We strongly recommend using SOAP 1.2 protocol. WCF services are not provided at this time, but are planned for a future release. Our examples will be shown with SOAP 1.2 protocols

Services

Best Practices

For any access to the web service entry points, we suggest a robust recoverable interface. In particular, the web service is designed to throw exceptions to any web application when unexpected or incorrect conditions are encountered. When a web service service point encounters a fault or failure, an eostar "MessageException" is thrown to the web application:

SOAP protocol rules stipulate that all web service exceptions must be wrapped in a SOAP envelope. This will require a slight amount of work for the web application developer to determine the proper error, the developer will need to unwrap the exception a little bit.

Best pattern for web applications (C#)

Cws09.png

This sample performs sync calls into the web service, however the web service is fully capable of servicing calls asynchronously and async calls are recommended (for example, SilverLight applications perform all service calls asynchronously)

Since the SoapException is the normal wrapper, to discover the eoStar generated MessageException, you will need to examine the exact error. Highlighted is the SoapMessageExtractor method to do this. Boilerplate code for MessageException extraction is provided here:


Cws10.png

You may use this C# code in your web application. If an eostar.MessageException is discovered, then it is a fault generated by the web service. Other exception types may not always be related to the web service (connectivity failures, for instance).

Also, many service entries provide a "RefreshData" method. You may call this at your convenience, however other service calls should automatically refresh the data store the web service uses, and thus not strictly needed.

Login.asmx

PerformLogin

The is the call needed to establish a session, and verify credentials. The successful response is a security token used for all of the rest of the service points.

Request

login.asmx performlogin soap 1.2 call

The PerformLogin has three parameters, "Company", "Login" and "Password" - these are all cleartext

  1. Company: The connection name in at the web service which is the connectionstring name created at install or created by the distributor
  2. Login: The customer web login. This is assigned by the distributor.
  3. Password: the customer login password. Cleartext

Sample successful response:

Cws08.png

This response from the PerformLogin is critical for the web application programmer to maintain from call-to-call into the web service. While the user's web browser may not support cookies, the web application will need this security token to perform actions. Some technical notes about this security token

  1. Strong 256 bit encryption (private key by the web service)
  2. Encoded for web storage (base64) for compatibility with browsers that do support cookies
  3. Embedded session hijack prevention information (private data stored by the web service)
  4. Strict 2 hour life. There is no renewal process for a token, the programmer will need to go get a new one by calling login again after stale


Access.asmx

GetWebLoginInfo

Gets extended information about a particular web login

Request

Cws11-2.jpg

Response

Cws12-2.jpg

When the GetWebLoginInfo is performed, a #WebLogin object is returned


Customers.asmx

GetCustomers

Gets customer/outlet information

Request

Cws40-1.jpg

Response

Cws40-2.jpg

The result is a list of #Cust records for the particular login


GetFutureDeliveryDates

Gets a particular customer's/outlet's future scheduled delivery dates

Request

Cws13.png

Input is the security token from login and a single CusNid (from the list of customers obtained in the GetCustomers call into Access

Response

Cws14.png

The return values are an array of DateTime objects which correspond to valid delivery dates as determined by the distributor for the specific customer account. Each customer may have different sets of delivery dates due to scheduling and licensing issues. For example, a distributor handling both alcoholic products and non-alcoholic products may have different delivery fulfilment dates depending on the driver, which must be licensed to carry alcoholic products.


GetOpenChargesAndCredits

Returns a detail of a particular customer's/outlet's outstanding open charges and open credits

Request

Cws40-3.jpg

Response

Cws40-4.jpg

The return value is an array of #CustReceivable


GetOrder

Returns detail for a particular order shipped to the customer

Request

Cws40-5.jpg

Response

Cws40-6.jpg

The return value is a #HistoricalOrder


GetOrderHistory

Returns the full detail of one shipped order for a customer. This method also returns hyperlinks for invoice review where PDFs of the invoice can be saved (The URL to do this is in the "DoStuff" member of the data returned

Request

Cws40-7.jpg

Response

Cws40-8.jpg

The return value is an array of #OrderHistoryLine


GetOrderReport

This method returns a PDF of a given invoice. Note the response is a byte stream, not a url.

Request

Cws40-9.jpg

Response

Cws40-10.jpg


ResendPassword

This emails the web login password to the main contact for the account.

Request

Cws40-11.jpg

Company = connection string alias Email = web login email that password should be emailed to (verification is performed)

ContactInfo = Text information to go at the bottom of the reminder email. Typically, this is the company's phone or email address

LogoURL = URL that the company logo can be located on the web


Response

Cws40-12.jpg


SignupOrReset

This is the mechanism in which a customer can self-signup for a web account with the distributor. If successful, then the email and password specified here can immediately be used to place orders with the distributor. It is ALSO used to change a web login password. The distributor may have this function disabled as it is controlled by the distributor. In that case, the distributor's personnel are the only ones that can create a web account.

Request

Cws40-13.jpg

It is very convenient for the customer account to self-signup. The input parameters found here are used to verify the customer's identity.

Company = String alias for the server connection

InvoiceNumber = Any invoice number from the customer's past. This must be a valid invoice number and ship-to location

Email = The desired email to use

Password = The desired password to use (or password to which an existing account will be reset to)

InvoiceNetTotal = The net total (in USD$) of the invoice number referenced above

ContactInfo = Text information about the distributor, which will be emailed to the new user

LogoURL = Web URL of the distributor's logo, which will be a part of the email sent to the new user


Response

Cws40-14.jpg


Items.asmx

GetBusinessReviews

This service returns summary about the account's business, including Top10, Prior sales, YTD, MTD sales

Request

Cws40-15.jpg

Response

Cws40-16.jpg


GetItemPhoto

This returns a JPG byte array of a product photo (if one is available)

Request

Cws40-17.jpg

Response

Cws40-18.jpg


GetItemPhotos

Returns all the item photos available, given a RowVersion. RowVersion is how eoStar keeps track of versions of a group a files. Pass in "0" to get all latest

Request

Cws40-19.jpg

Response

Cws40-20.jpg


GetItemsPurchasedInPast90Days

Returns a list of #Item records purchased in the past 90 days

Request

Cws40-21.jpg

Response

Cws40-22.jpg


GetMasterBrands

Returns a list of #Brand records corresponding to the ones sold by the distributor

Request

Cws40-23.jpg

Response

Cws40-24.jpg


GetMasterCategories

Returns all of the #Category of products the distributor sells

Request

Cws40-25.jpg

Response

Cws40-26.jpg


GetMasterItems

Returns a list of all the #Item records the distributor sells

Request

Cws40-27.jpg

Response

Cws40-28.jpg


GetMasterPackageTypes

Returns a list of #PackageType items the items come in

Request

Cws40-29.jpg

Response

Cws40-30.jpg


GetMasterPackages

Returns a list of #Package records that the items come in

Request

Cws40-31.jpg

Response

Cws40-32.jpg


GetMoreItemInfo

Request

Cws15.png

The input is the security token from Login and a single CusNid

Response

Cws16.png

The response is a list of #MoreItemInfo objects


GetPromotions

Given a particular Customer/Outlet, returns all of the available promotional prices on the products in a #PromoData format

Request

Cws40-33.jpg

Response

Cws40-34.jpg


GetSellableItemNids

Given an array of Customers/Outlets, returns items than can be purchased from the list of ALL the items. Returns in a #CustomerCanBuy format

Request

Cws40-35.jpg

Response

Cws40-36.jpg


GetWebCatalogs

Returns a list of #WebCatalog records. These records correspond to a grouping of items of which the distributor would like to promote. There may or may not be promotions on these items. The grouping is akin to a catalog of items for consideration. These are date sensitive

Request

Cws40-37.jpg

Response

Cws40-38.jpg


Cart.asmx

The web shopping cart

The web service manages orders via a web shopping cart. The web shopping cart is in one of three states

  1. An open cart
  2. A closed (submitted) cart
  3. A finalized cart

The only cart the web application developer is able to manipulate is the Open cart. There is for any single login, only ONE open cart at any time. When a cart is submitted or posted, then it becomes a closed cart. That cart can no longer be manipulated or accessed from the web application. A closed cart has been submitted, but has not yet been processed by the distributor. A finalized cart is one in which the distributor has accepted into their system and is scheduled to be processed with all of the other orders for the day.

Depending on the process flows of the distributor, a closed cart becoming a finalized cart may take only seconds, but in some cases requiring manual review, then it may be several minutes. The web application is not blocked from creating new open carts while there may be several closed carts not yet reviewed by the distributor

See #Cart or the #GetOpenCart section for review of the contents of a cart


AddOnCart

Adds a particular item and qty of that item to an open cart. If there is no currently open shopping cart, this will create one automatically

Request

Cws40-39.jpg

Response

Cws40-40.jpg

The response is a blank string if everything is okay. If there is any message, then the items could not be added to the cart.

Programming notes on this method:

If there is no open cart, this will create one
If there is an open cart, and the customer id is different than the prior call to additem, this call will CHANGE the customer target
If there is an open cart, and the Delivery Date is different than the prior call to additem, this method will CHANGE the requested delivery date


AddOnCartMultiple

Adds multiple items and qtys to an open cart. Like #AddOnCart if there is no currently open shopping cart, this will create one automatically

Request

Cws40-41.jpg

Response

Cws40-42.jpg

The response is a blank string if everything is okay.

Programming notes on this method:

If there is no open cart, this will create one
If there is an open cart, and the customer id is different than the prior call to additem, this call will CHANGE the customer target
If there is an open cart, and the Delivery Date is different than the prior call to additem, this method will CHANGE the requested delivery date


GetCartTextSummary

Returns a text summary of the cart contents

Request

Cws40-43.jpg

Response

Cws40-44.jpg

The text contents is generally one of the following

"There are no items in your shopping cart"

"The requested delivery date for your current shopping cart is in the past. Please review your cart and adjust the delivery date"

"There are nnnn items in your shopping cart. The total is $$$$"

Programming notes on this method:

If there is no open cart, this will create one
If there is an open cart, and the customer id is different than the prior call to additem, this call will CHANGE the customer target
If there is an open cart, and the Delivery Date is different than the prior call to additem, this method will CHANGE the requested delivery date


GetOpenCart

Request

Cws40-45.jpg

Response

Cws40-46.jpg

Get open cart returns the one open cart for the particular login. It may be completely empty (meaning, no open cart) For details on the cart lines, see the web cart section above.


GetOpenCartDeliveryDate

Returns the open cart's shipping date

Request

Cws22.png

Response

Cws40-48.jpg

The response is a DateTime of the desired delivery date for the open cart. If there is no cart, there is no datetime which is returned


GetOpenCartItemCount

Returns the number of lines in the shopping cart. This is not the total qty of items, but the number of different itemlines

Request

Cws23.png

Response

Cws40-50.jpg

This method always returns a non-negative number.


GetOpenCartItemCustomer

Request

Cws24.png

Response

Cws25.png

The response is the CusNid to which the open cart is going to. It may be null if there is no open cart


PostOpenCart

This submits a cart and places an order

Request

Cws26.png

Response

Cws27.png

The response is a boolean indicating if the open cart was able to be submitted sucessfully. Unsuccessful posting WILL generate an exception. That is, the programmer will never see a "false" response from this method EXCEPT when trying to post an open cart with no items in it.

Once an open cart is posted, the web application is free to create a new cart. A new cart is created when a product is added.


RemoveItemOnCart

Removes a particular Item from the open shopping cart

Request

Cws40-51.jpg

Response

Cws40-52.jpg


ReviseOpenCartDeliveryDate

This changes the ship date on an open shopping cart. Please see #GetFutureDeliveryDates for a list of valid dates for a particular ship-to

Request

Cws40-53.jpg

Response

Cws40-54.jpg


ReviseOpenCartShipTo

This changes the ship-to customer for an open web cart. A web login may be responsible for placing orders to more than a single outlet, but a web cart can only take one ship-to at a time. This is how the target outlet is set. See #GetCustomers for more info

Request

Cws40-59.jpg

Response

Cws40-60.jpg


ReviseQtyOnCart

This changes the order qty on a web cart for a particular item

Request

Cws40-55.jpg

Response

Cws40-56.jpg


SetCartPONum

A web cart may have a customer designated PO number. Call this to set the PO number

Request

Cws40-57.jpg

Response

Cws40-58.jpg


Brands.asmx

BrandLogin

Cws28.png

The PerformLogin has three parameters, "Company", "Login" and "Password" - these are all cleartext

  1. Company: The connection name in at the web service which is the connectionstring name created at install or created by the distributor
  2. Login: The login for the brand info web methods is the RecKey of the brand web login entry
  3. Password: the brand login password. Cleartext

Sample successful response:

Cws08.png

This response from the BrandLogin is critical for the web application programmer to maintain from call-to-call into the web service. While the user's web browser may not support cookies, the web application will need this security token to perform actions. Some technical notes about this security token

  1. Strong 256 bit encryption (private key by the web service)
  2. Encoded for web storage (base64) for compatibility with browsers that do support cookies
  3. Embedded session hijack prevention information (private data stored by the web service)
  4. Strict 2 hour life. There is no renewal process for a token, the programmer will need to go get a new one by calling login again after stale

GetBrandInfo

Request

Cws29.png

Response

Cws30.png

The response includes all of the brands set up for the given brand login. The brand logo is included as a base64 encoded string which contains a JPG image.


Example

This example is a service call patterns in a pseudo-code style format

How to place an order

  1. Call Login.asmx/PerformLogin (returns a login token)
  2. Call Access.asmx/GetWebLoginInfo, which returns a [[#WebLogin] that contains all the ship-to customers that an order can be placed for under this particular web login
  3. Pick out a particular Ship-to CusNid to place an order for
  4. Call Items.asmx/GetMasterItems, which returns all the items in the distributors sell book
  5. Call Items.asmx/GetSellableItemNids, which returns the subset of items from GetMasterItems that can be sold to your particular CusNid
  6. Call Customer.asmx/GetFutureDeliveries, which returns valid ship-to dates for a particular customers
  7. Call Cart.asmx/AddOnCartMultiple, adding the ItemsNids and Qtys desired to be ordered
  8. Call Cart.asmx/ReviseOpenCartShipTo, specifying the customer you want to ship-to
  9. Call Cart.asmx/ReviseCartDeliveryDate, specifying the delivery date from the Future Deliveries
  10. Call Cart.asmx/PostOpenCart, to actually place the order