API Reference - Sale

API Reference - Sale

 

 URL  https://{bluehub_host}:{rest_api_port}/rest/sale/
 Headers Supported  Accept: application/xml or Accept: application/json
 Authentication: OAuth...
 Methods Supported   GET, POST
 Description  Retrieve or Post Sales

 

GET Sale

HTTP response codes:

 Success HTTP Status Code  200 OK
 Not Found HTTP Status Code  204 No Content
 Parameter 'where' has incorrect query  400 Bad Request
 OAuth Authentication HTTP error codes  see OAuth wiki

 

Optional parameters :

WHERE Filter by:
  • transactionCode
  • storeCode
  • terminalCode
  • endDateTime
Example: where=storeCode = 1 or storeCode = 2.
Note: the endDateTime must be in the format YYYY-MM-DD hh:mm:ss TZ, where YYYY - four-digit year, MM - two-digit month, DD - two-digit day; hh, mm and ss - two-digit hour, minute and second correspondingly; TZ - time zone in any of standard general or RFC 822 formats. For example if time zone is Eastern Daylight Time then the following formats are supported: EDT, Eastern Daylight Time, GMT-04:00, Etc/GMT+4 and -0400. Other standard time zone formats such as America/Los_Angeles are also supported.

Operators Allowed in the WHERE Clause

With the WHERE clause, the following operators can be used:

OperatorDescription

= Equal
<> Not equal
> Greater than
< Less than
>= Greater than or equal
<= Less than or equal
LIKE Search for a pattern

 

Example response for GET Sales

Example 1
Return sales where storeCode is 4 and transactionCode is 1209091537370004000042

Request:

GET https://127.0.0.1:9001/rest/sale/?where=storeCode%3D4%20and%20transactionCode%3D1209091537370004000042
Accept: application/xml
Authorization: OAuth...

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sales ver="1.0">
    <sale>
        <transactionCode>1209091537370004000042</transactionCode>
        <orderCurrencyCode>GBP</orderCurrencyCode>
        <totalAmount>
            <amount>4.99</amount>
            <currencyCode>GBP</currencyCode>
        </totalAmount>
        <amountExclTax>4.99</amountExclTax>
        <totalTax>0.83</totalTax>
        <baseAmountIncludesTax>true</baseAmountIncludesTax>
        <userNickName>jsmith</userNickName>
        <displayUserName>Jane Smith</displayUserName>
        <terminalTransactionNumber>2</terminalTransactionNumber>
        <initiatorPOSName>Terminal 4</initiatorPOSName>
        <initiatorCode>2</initiatorCode>
        <initiatorNickName>jsmith</initiatorNickName>
        <initiatorDisplayName>Jane Smith</initiatorDisplayName>
        <initiatorPOSCode>4</initiatorPOSCode>
        <startDate>2014-06-09 15:37</startDate>
        <endDate>2014-06-09 15:38</endDate>
        <timezoneId>Europe/London</timezoneId>
        <storeName>London Store</storeName>
        <storeCode>4</storeCode>
        <enterpriseCode>482</enterpriseCode>
        <trainingMode>false</trainingMode>
        <customer>        
            <countryCode>GB</countryCode>
            <customerCode>116</customerCode>
            <email>test@test.com</email>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <postalZipCode>TX99 9ZZ</postalZipCode>
            <street1>Street 1</street1>
            <street2>Street 2</street2>
            <street3>Street 3</street3>
            <telephone1>020 8999 9999</telephone1>
            <telephone2>010 8999 9999</telephone2>
            <title>Mr</title>
            <townCity>London</townCity>
            <stateRegion>Devon</stateRegion>
        </customer>
        <items> <item> <productCode>10040</productCode> <productName>Plain t-shirt blue L</productName> <productCategoryCode>11</productCategoryCode> <productCategoryName>Clothing</productCategoryName> <unitOfMeasure>EA</unitOfMeasure> <price>4.99</price> <currencyCode>GBP</currencyCode> <finalPriceAmount>5.15</finalPriceAmount>
               <quantity>1.00</quantity> <finalAmount>4.99</finalAmount> <finalAmountExclTax>4.99</finalAmountExclTax> <productTaxClassCode>PTX</productTaxClassCode> <productTaxClassName>Taxable</productTaxClassName> <taxes> <tax> <taxCode>UK1</taxCode> <taxCodeName>VAT 20%</taxCodeName> <rate>20.00</rate> <baseAmount> <amount>4.99</amount> <currencyCode>GBP</currencyCode> </baseAmount> <effectiveAmount>0.83</effectiveAmount> </tax> </taxes> <discounts/> <charges/> </item> </items> <payments> <payment> <tenderType>CARD</tenderType> <tenderCode>11</tenderCode> <tenderName>Credit Card</tenderName> <value> <amount>4.99</amount> <currencyCode>GBP</currencyCode> </value> </payment> </payments> </sale> </sales>

 

 

POST Sale

Multiple sales can be sent in the same request using the API Inbound request structure. TransactionSale tags are contained within <Transaction> elements in the Inbound structure. The Inbound Response structure is returned (see API Post Request Format)..

Request format for Sale:

Level

Tag

Mandatory

Optional

Type

Comments

1

transactionSales

 

 

 

2

transactionSale  docNo=""

M

 

Repeatable with an Inbound document. Represents a single sale transaction.

docNo is an integer incrementing from 1 within each <Batch> tag.

3

postStockMovements

O

Boolean

Default is ‘true’ if omitted. If true then post stock movements for the sale.

3

saleHeader

M

 

Header tag for a sale. One tag per sale transaction.

4

terminalTransactionNo

M

VarChar(50)

Non-unique external reference for the sale. This is usually an incremented integer unique to the terminal on which it was generated. It is saved as the last terminal ref so that it can be interrogated later.

The TRANSACTIONCODE in the bluehub db is saved by concatenating end date time, store code, terminal code andTransactionRef

4

transactionNote

O

VarChar(255)

 

4

storeCode

M

VarChar(50)

Bluestore store code

4

terminalCode

O

VarChar(50)

Bluestore code for the terminal being posted from

4

startDateTime

O

DateTime

Format YYYY-MM-DD HH:MM:SS TZ

4

endDateTime

M

DateTime

As above

4

sessionID

O

VarChar(50)

Optional external session reference for grouping sales e.g. day or shift

4

userCode

O

VarChar(50)

 

4

userName

O

VarChar(255)

 

4

userFullName

O

VarChar(255)

 

4

originalTxnCode

O

VarChar(50)

 Used when a transaction is recalled and voided.

4

orderCurrencyCode

M

CurrencyCode

Bluestore currency code GBP , USD, EUR etc

4

saleAmount

M

CurrencyValue

Can be zero.

Includes tax if AmountIncludesTax is set for the store.

4

totalTax

M

CurrencyValue

Can be zero but not null.

4

amountsIncludeTax

O

Boolean

If omitted assumes true.

4

stockStoreCode

O

VarChar(50)

This allows stock to be delivered from a different store to the one the sale is attributed to.

3

customer

O

   

4

customerCode

 

M

 

VarChar(50)

 

 

4

title

 

O

 

VarChar(255)

 

 

4

firstName

 

M

 

VarChar(255)

 

 

4

lastName

 

M

 

VarChar(255)

 

 

4

street1

 

O

 

VarChar(50)

 

 

4

street2

 

O

 

VarChar(50)

 

 

4

street3

 

O

 

VarChar(50)

 

 

4

townCity

 

O

 

VarChar(50)

 

 

4

stateRegion

 

O

 

VarChar(50)

 

 

4

postalZipCode

 

O

 

VarChar(50)

 

 

4

countryCode

 

O

 

VarChar(50)

 

 

4

telephone1

 

O

 

VarChar(50)

 

 

4

telephone2

 

O

 

VarChar(50)

 

 

4

email

 

O

 

VarChar(50)

 

 

3

saleItems

M

 

 

4

saleItem

M

 

Sale item details. 1 or many per sale transaction.

 

4

itemNumber

M

Integer

 

Integer indicating the item number within the sale.

Must be greater than 0

5

productCode

M

VarChar(50)

Product to which the sale is attributed.

Must be a valid Bluestore product code

5

productDescription

O

Char(255)

If omitted, the Bluestore product description will be used.

 

5

categoryCode

O

VarChar(50)

If omitted, the Bluestore category code for the product will be used.

5

categoryDescription

O

VarChar(255)

If omitted the Bluestore category description will be used

 

5

productTaxClassCode

O

VarChar(50)

If omitted the tax class code assigned to the product in bluestore will be used

 

5

productTaxClassDescription

O

VarChar(255)

If omitted the Bluestore tax class description will be used

 

5

voucherNo

O

VarChar(50)

If omitted the Bluestore tax class description will be used.

 

5

price

M

CurrencyValue

The base price of the item

 

5

currencyCode

O

CurrencyCode

If omitted the sale transaction currency will be used.

 

5

finalPriceAmount

O

CurrencyValue

The final unit price of the item. It contains the original price (same as price) if there was no override, or the override unit price if the user has entered a price override. If omitted then value of price field is used.

 

5

quantity

M

Number


 

5

unitOfMeasure

M

UnitCode

Must be a valid Bluestore unit code

5

finalAmount

M

CurrencyValue

Item amount after discounts and charges have been applied

 

5

saleItemDiscounts

O

 

   

 

6

saleItemDiscount

O

 

Discount details for a line item. 1 or many per SaleItem.

7

saleItemDiscountNo

M

Integer

Counter for discount line on the item

7

discountCode

M

DiscountCode

Must be a valid Bluestore discount code. 

7

discountDescription

O

Char(255)

If omitted the discount code description from Bluestore will be used

 

7

level

O

Integer

1 = header, 0 = item

 

7

type

O

Integer

0 = Percentage, 1 = price override, 2 = fixed amount, 3 = manual percentage, 4 = manual amount

7

percentage

O

Percentage

If type = 0 or type = 3 then percentage is required

7

fixedAmount

O

CurrencyValue

If type = 2 or type = 4 then fixed amount is required

 

7

fixedAmountCurrency

O

CurrencyCode

If omitted use the sale currency.

Must be a valid Bluestore currency code.

 

7

baseAmount

M

CurrencyValue

Amount to which the discount is going to be applied

 

7

baseAmountCurrency

O

CurrencyCode

If omitted use the sale currency.

Must be a valid currency code.

 

7

amount

M

CurrencyValue

Amount (value) of the discount

 

5

saleItemCharges

O

 

 

6

saleItemCharge

M

 

Charge details for a line item. 1 or many per SaleItem.

7

saleItemChargeNo

M

Integer

 

Counter for сharge line on the item

7

chargeCode

M

ChargeCode

 

7

chargeDescription

O

Char(255)

Charge code description from Bluestore will be used if omitted.

7

level

O

Integer

1 = header, 0 = item

 

7

type

O

Integer

0 = Percentage, 1 = price override, 2 = fixed amount, 3 = manual percentage, 4 = manual amount

 

7

percentage

O

Percentage

If type = 0 or type = 3 then percentage is required

7

fixedAmount

O

CurrencyValue

If type = 2 or type = 4 then fixed amount is required

7

fixedAmountCurrency

O

CurrencyCode

If omitted use sale currency code

 

7

baseAmount

M

CurrencyValue


 

7

baseAmountCurrency

O

CurrencyCode

If omitted use sale currency code

 

7

amount

M

CurrencyValue

Amount of charge

 

5

saleItemTaxes

M

 


 

6

saleItemTax

M

 

Tax details for a line item. 1 or many per SaleItem.

7

saleItemTaxNo

M

Integer

Counter for tax line on the item

7

taxCode

O

TaxCode

Must be a valid bluestore tax code.

If omitted then we perform tax code determination for the product/store.

Due to the unknown nature of the data model in the calling system, multiple tax code determination is not supported. The tax rule with the highest priority for the product / store will be determine in all cases.

If multiple tax lines with different tax codes are required then the tax code must be specified on each tax item.

7

taxCodeDescription

O

Char(255)

If omitted the Bluestore tax code description is used

 

7

baseAmount

M

CurrencyValue

Can be zero but not null

 

7

currencyCode

O

CurrencyCode

If omitted sale currency is used 

7

taxRate

O

Percentage

If omitted rate from taxCode is used

 

7

taxAmount

M

CurrencyValue

Amount of tax applied

 

3

payments

O

 

Only fully paid sales are supported at present so this tag should be included.

4

payment

M

 

Payment for sale. 1 or many per sale transaction.

5

paymentNo

M

 

Counter for payment items

5

tenderType

O

Integer

1 = CASH, 2 = CARD, 3 = VOUCHER

If omitted the tenderType assigned to the paymentMethodCode in Bluestore is used

5

paymentMethodCode

M

VarChar(50)

Must be a valid Bluestore payment method code.

5

paymentMethodDescription

O

Char(255)

If omitted the description of the payment method in Bluestore is used

5

amount

M

CurrencyValue

Amount of the payment item

 

5

currencyCode

O

CurrencyCode

If omitted the sale transaction currency is used

 

5

voucherNo

O

VarChar(50)

External reference for voucher used as payment method

 

 

       

 

Example POST xml...

 

<?xml version="1.0"?>

<inbound lang="en" requestNo="1">

    <batch batchNo="1">

        <transactionSales>

            <transactionSale docNo="1">

                <postStockMovements>true</postStockMovements>

                <saleHeader>

                    <terminalTransactionNo>15</terminalTransactionNo>

                    <storeCode>1</storeCode>

                    <terminalCode>5</terminalCode>

                    <startDateTime>2013-09-23 22:53:00.10</startDateTime>

                    <endDateTime>2013-09-23 22:53:05.05</endDateTime>

                    <sessionID>2013081600003</sessionID>

                    <userCode>2</userCode>

                    <userName>jsmith</userName>

                    <userFullName>Jane Smith</userFullName>

                    <orderCurrencyCode>GBP</orderCurrencyCode>

                    <saleAmount>122.30</saleAmount>

                    <totalTax>20.38</totalTax>

                    <amountsIncludeTax>true</amountsIncludeTax>

                </saleHeader>

                <customer>

                    <customerCode>116</customerCode>

                    <title>Mr</title>

                    <firstName>John</firstName>

                    <lastName>Smith</lastName>

                    <street1>Street 2</street1>

                    <townCity>London</townCity>

                    <postalZipCode>TX99 9ZZ</postalZipCode>

                    <countryCode>GB</countryCode>

                    <telephone1>020 8999 9999</telephone1>

                    <email>test@test.com</email>

                </customer>

                <saleItems>

                    <saleItem>

                        <itemNumber>1</itemNumber>

                        <productCode>20000</productCode>

                        <productDescription>Roast lamb and mint brown</productDescription>

                        <categoryCode>10</categoryCode>

                        <categoryDescription>Cold Sandwiches</categoryDescription>

                        <productTaxClassCode>PTX</productTaxClassCode>

                        <productTaxClassDescription>Taxable</productTaxClassDescription>

                        <voucherNo></voucherNo>

                        <price>30</price>

                        <currencyCode>GBP</currencyCode>

                        <finalPriceAmount>30.5</finalPriceAmount>

                        <quantity>4</quantity>

                        <unitOfMeasure>EA</unitOfMeasure>

                        <finalAmount>120</finalAmount>

                        <saleItemTaxes>

                            <saleItemTax>

                                <saleItemTaxNo>1</saleItemTaxNo>

                                <taxCode>UK1</taxCode>

                                <taxCodeDescription>VAT 20%</taxCodeDescription>

                                <baseAmount>120</baseAmount>

                                <currencyCode>GBP</currencyCode>

                                <taxRate>20</taxRate>

                                <taxAmount>20</taxAmount>

                            </saleItemTax>

                        </saleItemTaxes>

                    </saleItem>

                    <saleItem>

                        <itemNumber>2</itemNumber>

                        <productCode>10005</productCode>

                        <productDescription>Assam Tea</productDescription>

                        <categoryCode>2</categoryCode>

                        <categoryDescription>Tea</categoryDescription>

                        <productTaxClassCode>PTX</productTaxClassCode>

                        <productTaxClassDescription>Taxable</productTaxClassDescription>

                        <voucherNo></voucherNo>

                        <price>2.30</price>

                        <currencyCode>GBP</currencyCode>

                        <quantity>1</quantity>

                        <unitOfMeasure>EA</unitOfMeasure>

                        <finalAmount>2.30</finalAmount>

                        <saleItemTaxes>

                            <saleItemTax>

                                <saleItemTaxNo>1</saleItemTaxNo>

                                <taxCode>UK1</taxCode>

                                <taxCodeDescription>VAT 20%</taxCodeDescription>

                                <baseAmount>2.30</baseAmount>

                                <currencyCode>GBP</currencyCode>

                                <taxRate>20</taxRate>

                                <taxAmount>0.38</taxAmount>

                            </saleItemTax>

                        </saleItemTaxes>

                    </saleItem>

                </saleItems>

                <payments>

                    <payment>

                        <paymentNo>1</paymentNo>

                        <tenderType>2</tenderType>

                        <paymentMethodCode>11</paymentMethodCode>

                        <paymentMethodDescription>Credit Card</paymentMethodDescription>

                        <amount>122.30</amount>

                        <currencyCode>GBP</currencyCode>

                        <voucherNo></voucherNo>

                    </payment>

                </payments>

            </transactionSale>

        </transactionSales>

    </batch>

</inbound>

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk