1. Introduction

API for Self Scanning client

2. Access

  • HTTP Basic Authentication basicAuth

  • OAuth AuthorizationUrl: _, TokenUrl: _{protocol}://{systemId}:{port}/auth-service/tenants/{tenant}/oauth/token

3. Endpoints

3.1. EndOfTrip

3.1.1. endOfTrip

POST /self-scanning/v1/end-of-trip

adds a self-scanning transaction

Description

Adds a self-scanning transaction to the system

Parameters
Body Parameter
Name Description Required Default Pattern

EndOfTripRequest

Self-Scanning Transaction EndOfTripRequest

-
Header Parameters
Name Description Required Default Pattern

GK-Customer-Id

Customer identifier. When not defined anonymous customer is used.

-

null

GK-Anonymous-Profile-Id

Anonymous customer profile identifier.

-

null
Return Type

EndOfTripResponse

Content Type

  • application/json

Responses
Code Message Datatype

201

transaction created

EndOfTripResponse

401

Unauthorized

Problem

400

Provided transaction, or some of its parts, are not valid. Referenced data may be missing.

Problem

409

A transaction with the same ID has already been processed.

Problem

3.2. StartOfTrip

3.2.1. getBusinessUnit

GET /self-scanning/v1/business-units/{businessUnitId}

Parameters
Path Parameters
Name Description Required Default Pattern

businessUnitId

Business unit ID.

X

null
Return Type

BusinessUnit

Content Type

  • application/json

Responses
Code Message Datatype

200

Business unit details.

BusinessUnit

401

Unauthorized

Problem

404

Object was not found.

Problem

500

An unexpected server error.

Problem

3.2.2. getCustomer

GET /self-scanning/v1/customers/{customerId}

Parameters
Path Parameters
Name Description Required Default Pattern

customerId

X

null
Return Type

Customer

Content Type

  • application/json

Responses
Code Message Datatype

200

Customer details.

Customer

401

Unauthorized

Problem

404

Object was not found.

Problem

500

An unexpected server error.

Problem

4. Models

4.1. AuditEvent

Field Name Required Type Description Format

creationTimestamp

X

Date

Creation timestamp of the audit event

date-time

typeCode

X

String

S_\" + {process id} + {2 digits incremental number per process} - see documentation for details

content

String

Additional event content.

4.2. BusinessUnit

Business unit details.

Field Name Required Type Description Format

businessUnitId

X

String

A unique retailer assigned identifier for a retail store, distribution center or administration center (internal identifier).

businessUnitGroupId

String

A unique system assigned identifier for the group of business units.

name

String

Business unit name.

mainCurrency

Currency

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.3. Currency

Field Name Required Type Description Format

code

X

String

Unique identifier of the currency. ISO 4217 currency code.

name

String

A name of the currency.

symbol

String

National symbol for the main currency unit.

4.4. Customer

Field Name Required Type Description Format

customerId

X

String

Unique ID of a customer.

firstName

String

A person’s first name. In western cultures, this is the given name, in other cultures it may be the family name.

lastName

String

A person’s last name. In western cultures, this is the family (or patronymic) name, in other cultures it may be the given name.

salutation

String

Extra words that don’t form part of the person’s name but are normally printed before the first name as a courtesy title. This represents the primary salutation for this Person.

languageId

String

A combination of ISO-639-1 and ISO-3661-1 to denote a language as spoken in a particular country.

customerGroupIdList

List of [String]

paymentInAppAllowed

Boolean

Defines whether payment is allowed for the customer in BYOD application.

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.5. DepositAssociation

Field Name Required Type Description Format

toLineItemSequenceNumber

X

Integer

The sequence number of the linked line item.

int32

4.6. EndOfTripRequest

Field Name Required Type Description Format

selfScanningTransaction

SelfScanningTransaction

4.7. EndOfTripResponse

Field Name Required Type Description Format

operatorNecessary

X

Boolean

totals

Totals

transaction

EndOfTripResponseTransaction

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.8. EndOfTripResponseDepositAssociationItem

Field Name Required Type Description Format

toLineItemSequenceNumber

X

BigDecimal

The sequence number of the linked line item.

4.9. EndOfTripResponseExternalTransactionAssociation

Links to external transactions.

Field Name Required Type Description Format

associationTypeCode

X

String

* EMPT - link to empties receipt * SCAL - link to scale receipt

Enum: EMPT, SCAL,

toTransactionId

X

String

4.10. EndOfTripResponseFrequentShopperPointsModifier

Field Name Required Type Description Format

promotionId

BigDecimal

The unique identifier of the promotion.

priceDerivationRuleId

BigDecimal

The unique identifier of the price derivation rule.

priceDerivationRuleEligibilityId

BigDecimal

The unique identifier of the root eligibility.

frequentShopperPointsEarnedCount

X

BigDecimal

The number of frequent shopper points earned.

prorateFrom

BigDecimal

The points calculation rule to be applied, expressed as a percentage of the calculation base. Corresponds to ItemPriceDerivationRule.PriceModificationPercent if available.

4.11. EndOfTripResponseLoyaltyRewardLineItem

Field Name Required Type Description Format

pointsAwardedCount

BigDecimal

The number of loyalty points awarded.

promotionId

BigDecimal

The unique identifier of the promotion.

priceDerivationRuleId

BigDecimal

The unique identifier of the price derivation rule.

priceDerivationRuleEligibilityId

BigDecimal

The unique identifier of the root eligibility.

4.12. EndOfTripResponsePriceModificationLineItem

Field Name Required Type Description Format

promotionId

BigDecimal

The unique identifier of the promotion.

priceDerivationRuleId

BigDecimal

The unique identifier of the price derivation rule.

priceDerivationRuleEligibilityId

BigDecimal

The unique identifier of the root eligibility.

triggerSequenceNumber

BigDecimal

The ident of the manual trigger (because a transaction item can have more than one trigger) Needed for transaction preview.

4.13. EndOfTripResponseRetailPriceModifier

Field Name Required Type Description Format

promotionId

BigDecimal

The unique identifier of the promotion.

priceDerivationRuleId

BigDecimal

The unique identifier of the price derivation rule.

priceDerivationRuleEligibilityId

BigDecimal

The unique identifier of the root eligibility.

amount

X

BigDecimal

The total amount of the retail price modifier.

calculationMethodCode

String

A type code used to identity manual price overrides.

prorateFrom

BigDecimal

The sequence number of the PriceModificationLineItem. Only filled for discount shares of transaction related discounts.

4.14. EndOfTripResponseRetailTransaction

Field Name Required Type Description Format

retailTransactionLineItemList

List of EndOfTripResponseRetailTransactionLineItem

List of retail transaction line items.

totals

Totals

retailTransactionPromotionTriggerList

List of EndOfTripResponseRetailTransactionPromotionTriggerItem

List of promotion triggers.

retailTransactionCouponSummaryList

List of EndOfTripResponseRetailTransactionCouponSummaryItem

List of coupons.

retailTransactionPromotionPriceDerivationRuleList

List of EndOfTripResponseRetailTransactionPromotionPriceDerivationRuleItem

List of conditions.

4.15. EndOfTripResponseRetailTransactionCouponSummaryItem

Field Name Required Type Description Format

couponNumber

X

String

The coupon number.

inputCount

X

BigDecimal

Count of registered coupons.

appliedCount

X

BigDecimal

Number of used coupons.

customerRelated

Boolean

Defines, if a customer is related to the coupon. Will be used for valuephone coupons.

4.16. EndOfTripResponseRetailTransactionLineItem

Field Name Required Type Description Format

saleReturnLineItem

EndOfTripResponseSaleReturnLineItem

priceModificationLineItem

EndOfTripResponsePriceModificationLineItem

loyaltyRewardLineItem

EndOfTripResponseLoyaltyRewardLineItem

taxLineItem

EndOfTripResponseTaxLineItem

depositAssociationList

List of EndOfTripResponseDepositAssociationItem

externalTransactionAssociation

EndOfTripResponseExternalTransactionAssociation

4.17. EndOfTripResponseRetailTransactionPromotionPriceDerivationRuleItem

Field Name Required Type Description Format

promotionId

X

BigDecimal

The unique identifier of the promotion.

priceDerivationRuleId

X

BigDecimal

The unique identifier of the price derivation rule.

priceDerivationRuleEligibilityId

X

BigDecimal

The unique identifier of the root eligibility.

ReceiptPrinterName

String

Text to be printed on the receipt.

4.18. EndOfTripResponseRetailTransactionPromotionTriggerItem

Field Name Required Type Description Format

triggerSequenceNumber

X

BigDecimal

The ident of the trigger (because a transaction item can have more than one trigger).

triggerType

X

String

The type of the trigger (referencing to POS configuration).

triggerValue

X

String

The value of the trigger (referencing to POS configuration).

4.19. EndOfTripResponseSaleReturnLineItem

The sale return line item.

Field Name Required Type Description Format

posItemId

String

The ID used to identify the item.

itemType

String

The type code of the line item.

quantity

X

BigDecimal

The single quantity of a line item

units

String

The units of the line item.

extendedAmount

X

BigDecimal

The product of multiplying Quantity, Units and ActualUnitPrice.

manualWeightInputFlag

X

Boolean

Describes how the weight was registered. Might be needed for scale receipts.

receiptText

String

The receipt printout text.

registrationNumber

String

The complete number which was registered on the POS originally.

discountFlag

X

Boolean

A flag to indicate whether this ITEM can be discounted. (Corresponds to Item.DiscountFlag)

mainMerchandiseHierarchyGroupID

String

Unique system assigned identifier for the merchandise group.

retailPriceModifier

List of EndOfTripResponseRetailPriceModifier

List of line item discounts.

frequentShopperPointsModifier

List of EndOfTripResponseFrequentShopperPointsModifier

List of line item points discounts.

saleReturnLineItemPromotionTrigger

List of EndOfTripResponseSaleReturnLineItemPromotionTrigger

List of line item promotion triggers.

4.20. EndOfTripResponseSaleReturnLineItemPromotionTrigger

Field Name Required Type Description Format

privilegeType

String

Defines the method for price modification.

privilegeValue

String

Reduction amount, reduction percent or new price amount.

4.21. EndOfTripResponseTaxLineItem

Field Name Required Type Description Format

taxIncludedInPricesFlag

X

Boolean

A flag denoting that all applicable taxes are included in the prices for this line item, and that therefore this SaleReturnTaxLineItem is merely a summary of those taxes.

taxableAmount

X

BigDecimal

The monetary value of the transaction for which tax is being calculated.

taxPercent

X

BigDecimal

The percentage of the taxable amount that should is tax. Derived by applying the appropriate TaxGroupRule and TaxRateRule.

taxAmount

BigDecimal

The monetary amount of sales Tax calculated by applying the appropriate TaxGroupRule and TaxRateRule.

receiptPrintCode

String

short code that is printed on a receipt to denote items that are in this TaxableGroup.

4.22. EndOfTripResponseTransaction

Field Name Required Type Description Format

suspendNumber

X

String

retailTransaction

EndOfTripResponseRetailTransaction

4.23. ExternalTransactionAssociation

Links to external transactions.

Field Name Required Type Description Format

associationTypeCode

X

String

* EMPT - link to empties receipt * SCAL - link to scale receipt

Enum: EMPT, SCAL,

toTransactionId

X

String

4.24. Problem

A response object to describe the problem that has just happened.

Field Name Required Type Description Format

message

String

A human readlable description whats going wrong, and if possible how to handle / solve this error.

timestamp

X

Date

The current timestamp when the problem occurred.

date-time

url

X

String

The url that has just been called.

status

X

Integer

The original http statuscode which this error was rejected.

int32

4.25. PromotionTrigger

Line of line item promotion trigger which comes from a barcode.

Field Name Required Type Description Format

triggerType

X

String

The type of the trigger (referencing to POS configuration).

triggerValue

X

String

The value of the trigger (referencing to POS configuration).

sequenceNumber

X

Integer

The sequence number of promotion trigger within the containing context.

int32

privilegeType

X

String

Defines the method for price modification.

privilegeValue

X

BigDecimal

Reduction amount, reduction percent or new price amount.

reasonCode

String

Reason code for the manual discount.

4.26. RetailTransactionCouponSummary

Field Name Required Type Description Format

couponNumber

X

String

The coupon number.

inputCount

X

Integer

Count of registered coupons. It is used to know how many coupons were scanned.

customerRelated

X

Boolean

Flag if the coupon is customer related. If yes, it is related to the customer from the transaction.

4.27. RetailTransactionLineItem

Field Name Required Type Description Format

sequenceNumber

X

Integer

The sequence number of line item within the context of this RetailTransaction.

int32

beginDateTimestamp

X

Date

The start time of the retail transaction line item.

date-time

endDateTimestamp

X

Date

The end time of the retail transaction line item.

date-time

voidFlag

Boolean

A boolean indicator that tells if this line item is voided or not.

entryMethodCode

String

A retailer assigned code to denote how the RetailTransactionLineItem was entered at the Workstation.

Enum: Scanned, Keyed,

typeCode

X

String

* SR - SaleReturnLineItem * VL - VoidsLineItem

Enum: SR, VL,

voidTypeCode

String

* 00 - Immediate Void (last line-item) * 01 - Void (non-last line-item)

Enum: 00, 01,

saleReturnLineItem

X

SaleReturnLineItem

externalTransactionAssociation

ExternalTransactionAssociation

depositAssociationList

List of DepositAssociation

auditEventList

List of AuditEvent

List of line item audit events.

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.28. SaleReturnLineItem

Sale return line item.

Field Name Required Type Description Format

posItemId

X

String

The ID used to identify the item. Corresponds to simpleItemSO.posIdentity.

registrationNumber

String

The complete number which was registered on the POS originally.

quantity

X

Integer

The single quantity of a line item.

itemType

X

String

The type code of the line item > * CO - Common * ER - Empties Return * SC - Scale Receipt * DI - Deposit Item

Enum: CO, ER, SC, DI,

actualUnitPrice

BigDecimal

The actual per-unit price. Mandatory only if sellUnitRetailPriceEntryMethodCode = BARC

extendedAmount

BigDecimal

The product of multiplying Quantity, Units and ActualUnitPrice. Needed for entering weight or price coded barcodes. Mandatory if sellUnitRetailPriceEntryMethodCode = BARC

units

BigDecimal

The units of the line item. Mandatory if sellUnitRetailPriceEntryMethodCode = BARC

sellUnitRetailPriceEntryMethodCode

String

A code that describes how this line item’s retail selling unit price is being entered. * PRIC - not mandatory * BARC - must fill actualUnitPrice, extendedAmount, units

Enum: PRIC, BARC,

ageVerificationRequired

Boolean

Defines, if an age verification check is detected during scanning the item.

promotionTrigger

PromotionTrigger

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.29. SelfScanningTransaction

Field Name Required Type Description Format

businessUnitId

X

String

Store ID

beginDateTimestamp

X

Date

The time and date a transaction is initiated.

date-time

cancelledFlag

Boolean

A flag denoting that this entire transaction has been cancelled before it was completed at the Self Scanning Client.

lineItemList

X

List of RetailTransactionLineItem

List of line items

couponSummaryList

List of RetailTransactionCouponSummary

List of coupons

auditEventList

List of AuditEvent

List of audit events

promotionTriggerList

List of PromotionTrigger

List of promotion triggers.

selfScanningTransactionId

X

UUID

uuid

deviceId

X

String

allItemsEntered

X

Boolean

additionalProperties

Map of [String]

General key-value map for project extensibility.

4.30. Totals

Field Name Required Type Description Format

subtotal

X

BigDecimal

Subtotal without transaction discounts and without taxes.

subtotalDiscount

X

BigDecimal

Subtotal with transaction discounts and without taxes.

total

X

BigDecimal

Transaction total with - taxes that are not included in prices - transaction discounts - rounding