com.bookpac.server.shop
Interface IWSShopMgmt

All Superinterfaces:

IWS

public interface IWSShopMgmt
extends IWS

Shop management interface for managing baskets and checking out.

Author:

rvuine

Method Summary

void	__addTestPositionToBasket(String token, String basketID) Non-public API method for adding a test position to a basket.
WSTBasket	changeBasketPositionQuantity(String token, String basketID, int positionIndex, long quantity) Changes the quantity of a basket position.
WSTCheckoutResult	checkoutBasket(String token, String basketID, WSTPaymentMethod paymentMethodPreference, WSTMap checkoutProperties) Checks out a basket, performs the actual payment and fulfillment, and, depending on basket items, provides the caller with delivery information.
WSTBasket	getBasket(String token, String basketID) Gets the given basket of the current user.
WSTBasket	getNewBasket(String token, String basketMarker) Creates a new, empty basket, and returns it.
WSTBasket	getValidationBasket(String token, String basketMarker) Returns a validation basket.
void	refundCheckoutTransaction(String token, String transactionID, String comment) Refunds the WSTCheckoutTransaction with the given ID.
void	refundReceipt(String token, String receiptIdentifier, String comment) Refunds the receipt with the given identifier.
void	removeAllBasketPositions(String token, String basketID) Removes all basket positions from a basket.

Method Detail

getBasket

WSTBasket getBasket(String token,
                    @Nullable
                    String basketID)
                    throws WSException

Gets the given basket of the current user. Callers may pass null as basket ID, in which case the default basket will be returned. The default basket will change on every checkout (the old default basket will be replaced with a new, empty basket.)

Parameters:

token - the session ID, must be != null and valid

basketID - the basket ID, may be null to get the default basket

Returns:

a basket for the current user, never null

Throws:

WSException - in an error occurs

getNewBasket

WSTBasket getNewBasket(String token,
                       String basketMarker)
                       throws WSException

Creates a new, empty basket, and returns it.

Parameters:

token - the session ID, must be != null and valid

basketMarker - a basket marker, describing the client that wants to use the basket (i.e. "txtr-reader-basket")

Returns:

a basket for the current user, never null

Throws:

WSException - in an error occurs

getValidationBasket

WSTBasket getValidationBasket(String token,
                              String basketMarker)
                              throws WSException

Returns a validation basket. A validation basket is a basket that contains only one dummy article. Use the validation basket's payment properties for submitting payment data, then use checkoutBasket with the validation basket's ID to make sure the data is valid.

Parameters:

token - the session ID, must be != null and valid

basketMarker - a basket marker, describing the client that wants to use the basket (i.e. "txtr-reader-basket")

Returns:

the validation basket

Throws:

WSException - in an error occurs

changeBasketPositionQuantity

WSTBasket changeBasketPositionQuantity(String token,
                                       @Nullable
                                       String basketID,
                                       int positionIndex,
                                       long quantity)
                                       throws WSException

Changes the quantity of a basket position. Setting the quantity to null will remove that position from the basket.

Parameters:

token - the session ID, must be != null and valid

basketID - the basket ID, may be null to get the default basket

positionIndex - the index of the position to be modified, starting with 0

quantity - the new quantity, only 0 and 1 are supported. Set to 0 to remove the position

Returns:

the modified basket

Throws:

WSException - in an error occurs

removeAllBasketPositions

void removeAllBasketPositions(String token,
                              @Nullable
                              String basketID)
                              throws WSException

Removes all basket positions from a basket.

Parameters:

token - the session ID, must be != null and valid

basketID - the basket ID, may be null to get the default basket

Throws:

WSException - in an error occurs

checkoutBasket

WSTCheckoutResult checkoutBasket(String token,
                                 @Nullable
                                 String basketID,
                                 @Nullable
                                 WSTPaymentMethod paymentMethodPreference,
                                 @Nullable
                                 WSTMap checkoutProperties)
                                 throws WSException

Checks out a basket, performs the actual payment and fulfillment, and, depending on basket items, provides the caller with delivery information.

Parameters:

token - the session ID, must be != null and valid

basketID - the basket ID, may be null to check out the user's default basket

paymentMethodPreference - if non-null, payment will be attempted with the stated method. If null, checkout will use the authorized payment method of the user. If more than one payment methods are authorized, the checkout process will choose one of these. If no payment method is authorized, or the preferred payment method is not authorized, checkout will fail.

checkoutProperties - see WSTCheckoutProperty

Returns:

a WSTCheckoutResult object describing if the checkout was successful and if not, where it failed and why.

Throws:

WSException - in an error occurs

__addTestPositionToBasket

void __addTestPositionToBasket(String token,
                               String basketID)
                               throws WSException

Non-public API method for adding a test position to a basket. This will add a test article, 42 €, to the given basket. If you're silly enough to check this out on a live system, you'll have bought the equivalent of 42 € of pure nothingness. You have been warned. Do not complain. This is a good way of wasting money, though. If you're into the wasting money business, why not buy a txtr test position? It's fun!

Parameters:

token - the session ID, must be != null and valid

basketID - the basket ID, may be null to get the default basket

Throws:

WSException - in an error occurs

refundReceipt

void refundReceipt(String token,
                   String receiptIdentifier,
                   String comment)
                   throws WSException

Refunds the receipt with the given identifier.

Parameters:

token - a valid token

receiptIdentifier - the identifier of the receipt to refund

comment - an arbitrary comment, e.g. the refund reason, may be null

Throws:

WSException - if the user does not have the WSTRight.REFUND_RECEIPTS to refund receipts, the receipt identifier is invalid or the receipt with the given identifier is not a WSTCheckoutTransaction or is already refunded

refundCheckoutTransaction

void refundCheckoutTransaction(String token,
                               String transactionID,
                               String comment)
                               throws WSException

Refunds the WSTCheckoutTransaction with the given ID.

Parameters:

token - a valid token

transactionID - the ID of the WSTCheckoutTransaction to refund

comment - an arbitrary comment, e.g. the refund reason, may be null

Throws:

WSException - if the user does not have the WSTRight.REFUND_RECEIPTS to refund receipts, the transaction ID is invalid or the transaction with the given ID is not a WSTCheckoutTransaction or is already refunded