Fishbowl POS Support API Help Page

Introduction

The Fishbowl POS Support HTTP Request Service has been created to provide access to the Fishbowl Promotions Manager resources through HTTP request services. The available services are limited to those described in this document.

Client Registration

Client Registration is required prior to initiating requests. This protocol requires confidential client types. Fishbowl will issue the client user id and client password pursuant to the Basic Authentication specification. As described below, these credentials are required when requesting access to API resources.

Authorization

The Basic Authentication specifications are adhered to explicitly as they pertain to the granting of authorization to access the API.

Http Request Authorization Header

Each resource request must contain an Authorization Header as defined by the Basic Authentication specification: RFC2617 - "HTTP Authentication: Basic and Digest Access Authentication".

The Authorization header defines the client authentication.
The Authorization header must include the "Basic" authentication scheme defined by encoding the client user id and client password (obtained through client registration as described above).
Format the basic credentials as follows: <client user id>:<client password> and encode the basic credentials string using Base64 (UTF-8) encoding.

Sample:

Authorization: Basic Nzg2MDA6NzQ0QkM3QjYtOTUzMy00RUM2LUIwNzktRDUyMzg4MkQyRjQ0

Authorization Error Response

If a request fails during the authorization process the client consumer will be notified via the response header as defined as follows.

Status Code - Contains a standard HTTP status code pertaining to the error.
Authentication Challenge – Contains a Www-Authenticate header that specifies an authentication scheme recognized by the server.

Sample:

HTTP/1.1 401 Invalid username or password
WWW-Authenticate: Basic realm="FishbowlPOSSupport"

POSSupport

The POS Support End Point. Unless otherwise stated, all requests require authorization through HTTP Basic Authentication.

API	Description
GET posSupportAPI/getInfo	The GetInfo method. This request returns the current API version and can be used for general service availability (ping/health check).
POST posSupportAPI/promotion/redeem	The Redeem Promotion method. This request applies Fishbowl promotions for the specified promotions code to the specified POS order. The API will validate and apply the discount based on the Promotion details and restrictions associated with the Promotions code.
POST posSupportAPI/promotion/void	The Void Promtion method. This request initiates a void for a previously successful redemption. The API will validate the redemption discount and void as appropriate.
POST posSupportAPI/promotion/commit	The Commit Promotion method. The Commit Promotion request initiates a commit for a previously successful authorized redemption. The API will validate the transaction and commit as appropriate.
POST posSupportAPI/promotion/update	The Update Promotion method. The Update Promotion request initiates an update for a previously committed redemption, applying the final check number to the successful transaction. The API will validate the transaction and update as appropriate.
POST posSupportAPI/promotion/flush	The Flush Cached Promotion method. The Flush Cached Promotion method is requested upon Offer Publishing. Flushes the cache for the given promotion id.
POST posSupportAPI/dataUpload/menu	The Data Upload Menu method. This request includes the store’s menu Major Groups, Minor Groups and Menu Items. Clients should make this request upon enabling changes to the store’s menu. It is also recommended that an initial menu upload be made when the store becomes “live” prior to any redeem promotion requests.
POST posSupportAPI/loyalty/posevent	The Loyalty POS Event method. This request initiates a Loyalty POS Event. Clients should make this request to initiate a Loyalty visit or spend transaction.
POST posSupportAPI/promotion/redeemOfferConnect	The Offer Connect Redeem method. This request applies Fishbowl promotions for the specified promotions code. The API will validate and apply the discount based on the Promotions code.
POST posSupportAPI/loyalty/checkRefund	The loyalty reward refund method. The loyalty reward refund request initiates a refund for a previously successfully redeemed reward. The API will validate the transaction and refund as appropriate.

ToastSupport

The Toast POS Support End Point.

API	Description
POST toastSupportAPI/promotionRequest	No documentation available.
POST toastSupportAPI/dataUpload/menu	The Data Upload Menu method. This request includes the store’s menu Major Groups, Minor Groups and Menu Items. Clients should make this request upon enabling changes to the store’s menu. It is also recommended that an initial menu upload be made when the store becomes “live” prior to any redeem promotion requests.

API

Description

POST toastSupportAPI/promotionRequest

No documentation available.

POST toastSupportAPI/dataUpload/menu

The Data Upload Menu method. This request includes the store’s menu Major Groups, Minor Groups and Menu Items. Clients should make this request upon enabling changes to the store’s menu. It is also recommended that an initial menu upload be made when the store becomes “live” prior to any redeem promotion requests.

XpientSupport

The Xpient POS Support End Point. This end point is limited to the implementation required for Xpient POS support. Unless otherwise stated, all requests require authorization through HTTP Basic Authentication.

API	Description
GET xpientSupportAPI/getInfo	The GetInfo method. This request returns the current API version and can be used for general service availability (ping/health check).
POST xpientSupportAPI/applyOffers	The ApplyOffers method. This request applies Fishbowl promotions for the specified promotions code to the specified POS order. The API will validate and apply the discount based on the Promotion details and restrictions associated with the Promotions code.
POST xpientSupportAPI/submitOrder	The SubmitOrder method. This request sends the finalized order details. The API will update the POS Business Date for the order and log the order details.
POST xpientSupportAPI/voidOrder	The VoidOrder method. This request is initiated when a manager voids (Over Ring) an order that has a loyalty discount applied. The API will validate the order discount and void as appropriate.

References

[RFC2617]
Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart,
"HTTP Authentication: Basic and Digest Access Authentication",
June 1999.