openapi: 3.0.0
servers:
  - url: "/services/rest"
  - url: "{protocol}://{host}:{port}/self-scanning-service/tenants/{tenant}/services/rest"
info:
  description: API for Self Scanning client
  version: "1.5"
  title: Self Scanning Service API
security:
  - basicAuth: []
  - oAuth2Password: [GK]
paths:
  /self-scanning/v1/business-units/{businessUnitId}:
    get:
      tags:
        - Start of Trip
      operationId: getBusinessUnit
      parameters:
        - in: path
          name: businessUnitId
          description: "Business unit ID."
          example: "9090"
          required: true
          schema:
            type: string
            maxLength: 32
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BusinessUnit"
          description: "Business unit details."
        "401":
          $ref: "#/components/responses/unauthorized"
        "404":
          $ref: "#/components/responses/notFound"
        "500":
          $ref: "#/components/responses/internalServerError"
  /self-scanning/v1/customers/{customerId}:
    get:
      tags:
        - Start of Trip
      operationId: getCustomer
      parameters:
        - in: path
          name: customerId
          schema:
            $ref: "#/components/schemas/CustomerId"
          required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
          description: "Customer details."
        "401":
          $ref: "#/components/responses/unauthorized"
        "404":
          $ref: "#/components/responses/notFound"
        "500":
          $ref: "#/components/responses/internalServerError"
  /self-scanning/v1/end-of-trip:
    post:
      tags:
        - End of Trip
      summary: adds a self-scanning transaction
      operationId: endOfTrip
      description: Adds a self-scanning transaction to the system
      responses:
        '201':
          description: "transaction created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndOfTripResponse"
        "401":
          $ref: "#/components/responses/unauthorized"
        '400':
          description: "Provided transaction, or some of its parts, are not valid. Referenced data may be missing."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        '409':
          description: "A transaction with the same ID has already been processed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
      parameters:
        - in: header
          name: GK-Customer-Id
          schema:
            $ref: "#/components/schemas/CustomerId"
          required: false
          description: "Customer identifier. When not defined anonymous customer is used."
        - in: header
          name: GK-Anonymous-Profile-Id
          schema:
            $ref: '#/components/schemas/CustomerId'
          required: false
          description: "Anonymous customer profile identifier."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndOfTripRequest'
        description: Self-Scanning Transaction
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    oAuth2Password:
      type: oauth2
      flows:
        password:
          tokenUrl: '{protocol}://{systemId}:{port}/auth-service/tenants/{tenant}/oauth/token'
          scopes:
            GK: Scope for internal entities.
  schemas:
    BusinessUnit:
      type: object
      description: "Business unit details."
      required:
        - businessUnitId
      properties:
        businessUnitId:
          type: string
          maxLength: 32
          example: "9090"
          description: "A unique retailer assigned identifier for a retail store, distribution center or administration center (internal identifier)."
        businessUnitGroupId:
          type: string
          example: "100000000000000005"
          pattern: "^\\d{1,18}$"
          description: "A unique system assigned identifier for the group of business units."
        name:
          type: string
          maxLength: 40
          example: "Store 9090"
          description: "Business unit name."
        mainCurrency:
          $ref: "#/components/schemas/Currency"
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    Currency:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          maxLength: 3
          example: "EUR"
          description: "Unique identifier of the currency. ISO 4217 currency code."
        name:
          type: string
          maxLength: 40
          example: "Euro"
          description: "A name of the currency."
        symbol:
          type: string
          maxLength: 40
          example: "€"
          description: "National symbol for the main currency unit."
    Customer:
      type: object
      required:
        - customerId
      properties:
        customerId:
          $ref: "#/components/schemas/CustomerId"
        firstName:
          type: string
          maxLength: 40
          example: "James"
          description: "A person's first name. In western cultures, this is the given name, in other cultures it may be the family name."
        lastName:
          type: string
          maxLength: 40
          example: "Smith"
          description: "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:
          type: string
          example: "Mr., Ms., Miss, Dr., Prof."
          description: "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:
          type: string
          example: "en_GB, en_US, de_DE, cs_CZ"
          description: "A combination of ISO-639-1 and ISO-3661-1 to denote a language as spoken in a particular country."
        customerGroupIdList:
          type: array
          items:
            type: string
            maxLength: 40
            example: "group-01"
        paymentInAppAllowed:
          type: boolean
          description: "Defines whether payment is allowed for the customer in BYOD application."
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    EndOfTripRequest:
      type: object
      properties:
        selfScanningTransaction:
          $ref: '#/components/schemas/SelfScanningTransaction'
    SelfScanningTransaction:
      type: object
      required:
        - businessUnitId
        - beginDateTimestamp
        - lineItemList
        - selfScanningTransactionId
        - deviceId
        - allItemsEntered
      properties:
        businessUnitId:
          type: string
          maxLength: 32
          example: 9090
          description: Store ID
        beginDateTimestamp:
          type: string
          format: date-time
          description: The time and date a transaction is initiated.
        cancelledFlag:
          type: boolean
          default: false
          description: A flag denoting that this entire transaction has been cancelled before it was completed at the Self Scanning Client.
        lineItemList:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RetailTransactionLineItem'
          maxItems: 500
          description: List of line items
        couponSummaryList:
          type: array
          items:
            $ref: '#/components/schemas/RetailTransactionCouponSummary'
          maxItems: 500
          description: List of coupons
        auditEventList:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
          maxItems: 500
          description: List of audit events
        promotionTriggerList:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/PromotionTrigger'
          maxItems: 500
          description: List of promotion triggers.
        selfScanningTransactionId:
          maxLength: 128
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        deviceId:
          type: string
          maxLength: 255
        allItemsEntered:
          type: boolean
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    RetailTransactionLineItem:
      type: object
      required:
       - sequenceNumber
       - beginDateTimestamp
       - endDateTimestamp
       - typeCode
       - saleReturnLineItem
      properties:
        sequenceNumber:
          type: integer
          format: int32
          description: The sequence number of line item within the context of this RetailTransaction.
        beginDateTimestamp:
          type: string
          format: date-time
          description: The start time of the retail transaction line item.
          example: 2019-08-14T07:21:59.921+0200
        endDateTimestamp:
          type: string
          format: date-time
          description: The end time of the retail transaction line item.
          example: 2019-08-14T07:22:08.662+0200
        voidFlag:
          type: boolean
          default: false
          description: A boolean indicator that tells if this line item is voided or not.
        entryMethodCode:
          type: string
          maxLength: 20
          description: A retailer assigned code to denote how the RetailTransactionLineItem was entered at the Workstation.
          enum: [Scanned, Keyed]
          default: Scanned
        typeCode:
          type: string
          enum: [SR, VL]
          maxLength: 2
          description: >
             * `SR` - SaleReturnLineItem
             * `VL` - VoidsLineItem
        voidTypeCode:
          type: string
          enum: ["00", "01"]
          maxLength: 2
          description: >
             * `00` - Immediate Void (last line-item)
             * `01` - Void (non-last line-item)
        saleReturnLineItem:
            $ref: '#/components/schemas/SaleReturnLineItem'
        externalTransactionAssociation:
            $ref: '#/components/schemas/ExternalTransactionAssociation'
        depositAssociationList:
          type: array
          items:
            $ref: '#/components/schemas/DepositAssociation'
          maxItems: 500
        auditEventList:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
          maxItems: 500
          description: List of line item audit events.
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    DepositAssociation:
      type: object
      required:
        - toLineItemSequenceNumber
      properties:
        toLineItemSequenceNumber:
          type: integer
          format: int32
          description: The sequence number of the linked line item.
    SaleReturnLineItem:
      description: Sale return line item.
      type: object
      required:
        - posItemId
        - quantity
        - itemType
      properties:
        posItemId:
          type: string
          maxLength: 128
          description: The ID used to identify the item. Corresponds to simpleItemSO.posIdentity.
        registrationNumber:
          type: string
          maxLength: 255
          description: The complete number which was registered on the POS originally.
        quantity:
          type: integer
          description: The single quantity of a line item.
        itemType:
          type: string
          enum: [CO, ER, SC, DI]
          maxLength: 4
          default: CO
          description: The type code of the line item >
             * `CO` - Common
             * `ER` - Empties Return
             * `SC` - Scale Receipt
             * `DI` - Deposit Item
        actualUnitPrice:
          type: number
          description: The actual per-unit price. Mandatory only if sellUnitRetailPriceEntryMethodCode = BARC
        extendedAmount:
          type: number
          description: The product of multiplying Quantity, Units and ActualUnitPrice. Needed for entering weight or price coded barcodes. Mandatory if sellUnitRetailPriceEntryMethodCode = BARC
        units:
          type: number
          description: The units of the line item. Mandatory if sellUnitRetailPriceEntryMethodCode = BARC
        sellUnitRetailPriceEntryMethodCode:
          type: string
          enum: [PRIC, BARC]
          default: PRIC
          maxLength: 4
          description: 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
        ageVerificationRequired:
          type: boolean
          description: Defines, if an age verification check is detected during scanning the item.
        promotionTrigger:
          $ref: '#/components/schemas/PromotionTrigger'
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    PromotionTrigger:
      description: Line of line item promotion trigger which comes from a barcode.
      type: object
      required:
        - triggerType
        - triggerValue
        - sequenceNumber
        - privilegeType
        - privilegeValue
      properties:
        triggerType:
          type: string
          description: The type of the trigger (referencing to POS configuration).
          maxLength: 2
        triggerValue:
          type: string
          description: The value of the trigger (referencing to POS configuration).
          maxLength: 255
        sequenceNumber:
          type: integer
          format: int32
          description: The sequence number of promotion trigger within the containing context.
        privilegeType:
          type: string
          description: Defines the method for price modification.
          maxLength: 2 
        privilegeValue:
          type: number
          description: Reduction amount, reduction percent or new price amount.
        reasonCode:
          type: string
          description: Reason code for the manual discount.
          maxLength: 20
    RetailTransactionCouponSummary:
      type: object
      required:
        - couponNumber
        - inputCount
        - customerRelated
      properties:
        couponNumber:
          type: string
          maxLength: 40
          description: The coupon number.
        inputCount:
          type: integer
          description: Count of registered coupons. It is used to know how many coupons were scanned.
        customerRelated:
          type: boolean
          description: Flag if the coupon is customer related. If yes, it is related to the customer from the transaction.
    AuditEvent:
      type: object
      required:
        - creationTimestamp
        - typeCode
      properties:
        creationTimestamp:
          type: string
          format: date-time
          description: Creation timestamp of the audit event
          example: 2019-08-14T07:21:59.921+0200      
        typeCode:
          type: string
          maxLength: 20
          description: 'S_" + {process id} + {2 digits incremental number per process} - see documentation for details'
        content:
          type: string
          maxLength: 1024
          description: Additional event content.
    ExternalTransactionAssociation:
      type: object
      description: Links to external transactions.
      required: 
       - associationTypeCode
       - toTransactionId
      properties:
        associationTypeCode:
          type: string
          enum: [EMPT, SCAL]
          maxLength: 4
          description: >
             * `EMPT` - link to empties receipt
             * `SCAL` - link to scale receipt
        toTransactionId:
          type: string
          maxLength: 128
    EndOfTripResponse:
      type: object
      required: 
        - operatorNecessary
      properties:
        operatorNecessary:
          type: boolean
          default: false
        totals:
          $ref: '#/components/schemas/Totals'
        transaction:
          $ref:  '#/components/schemas/EndOfTripResponseTransaction'
        additionalProperties:
          description: "General key-value map for project extensibility."
          type: object
          additionalProperties:
            type: string
    Totals:
      type: object
      required:
       - subtotal
       - subtotalDiscount
       - total
      properties:
        subtotal:
          description: Subtotal without transaction discounts and without taxes.
          type: number
        subtotalDiscount:
          description: Subtotal with transaction discounts and without taxes.
          type: number
        total:
          description: Transaction total with
            - taxes that are not included in prices
            - transaction discounts
            - rounding
          type: number
    EndOfTripResponseTransaction:
      type: object
      required:
       - suspendNumber
      properties:
        suspendNumber:
          type: string
        retailTransaction:
          $ref: '#/components/schemas/EndOfTripResponseRetailTransaction'
    EndOfTripResponseRetailTransaction:
      type: object
      properties:
        retailTransactionLineItemList:
          description: List of retail transaction line items.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseRetailTransactionLineItem'
        totals:
          $ref: '#/components/schemas/Totals'
        retailTransactionPromotionTriggerList:
          description: List of promotion triggers.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseRetailTransactionPromotionTriggerItem'
        retailTransactionCouponSummaryList:
          description: List of coupons.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseRetailTransactionCouponSummaryItem'
        retailTransactionPromotionPriceDerivationRuleList:
          description: List of conditions.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseRetailTransactionPromotionPriceDerivationRuleItem'
    EndOfTripResponseRetailTransactionLineItem:
      type: object
      properties:
        saleReturnLineItem:
          $ref: '#/components/schemas/EndOfTripResponseSaleReturnLineItem'
        priceModificationLineItem:
          $ref: '#/components/schemas/EndOfTripResponsePriceModificationLineItem'
        loyaltyRewardLineItem:
          $ref: '#/components/schemas/EndOfTripResponseLoyaltyRewardLineItem'
        taxLineItem:
          $ref: '#/components/schemas/EndOfTripResponseTaxLineItem'
        depositAssociationList:
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseDepositAssociationItem'
        externalTransactionAssociation:
          $ref: '#/components/schemas/EndOfTripResponseExternalTransactionAssociation'
    EndOfTripResponseSaleReturnLineItem:
      description: The sale return line item.
      type: object
      required:
        - quantity
        - extendedAmount
        - manualWeightInputFlag
        - discountFlag
      properties:
        posItemId:
          description: The ID used to identify the item.
          type: string
        itemType:
          description: The type code of the line item.
          type: string
        quantity:
          description: The single quantity of a line item
          type: number
        units:
          description: The units of the line item.
          type: string
        extendedAmount:
          description: The product of multiplying Quantity, Units and ActualUnitPrice.
          type: number
        manualWeightInputFlag:
          description: Describes how the weight was registered. Might be needed for scale receipts.
          type: boolean
        receiptText:
          description: The receipt printout text.
          type: string
        registrationNumber:
          description: The complete number which was registered on the POS originally.
          type: string
        discountFlag:
          description: A flag to indicate whether this ITEM can be discounted. (Corresponds to Item.DiscountFlag)
          type: boolean
        mainMerchandiseHierarchyGroupID:
          description: Unique system assigned identifier for the merchandise group.
          type: string
        retailPriceModifier:
          description: List of line item discounts.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseRetailPriceModifier'
        frequentShopperPointsModifier:
          description: List of line item points discounts.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseFrequentShopperPointsModifier'
        saleReturnLineItemPromotionTrigger:
          description: List of line item promotion triggers.
          type: array
          items:
            $ref: '#/components/schemas/EndOfTripResponseSaleReturnLineItemPromotionTrigger'
    EndOfTripResponseRetailPriceModifier:
      type: object
      required:
        - amount
      properties:
        promotionId:
          description: The unique identifier of the promotion.
          type: number
        priceDerivationRuleId:
          description: The unique identifier of the price derivation rule.
          type: number
        priceDerivationRuleEligibilityId:
          description: The unique identifier of the root eligibility.
          type: number
        amount:
          description: The total amount of the retail price modifier.
          type: number
        calculationMethodCode:
          description: A type code used to identity manual price overrides.
          type: string
        prorateFrom:
          description: The sequence number of the PriceModificationLineItem. Only filled for discount shares of transaction related discounts.
          type: number
    EndOfTripResponseFrequentShopperPointsModifier:
      type: object
      required:
        - frequentShopperPointsEarnedCount
      properties:
        promotionId:
          description: The unique identifier of the promotion.
          type: number
        priceDerivationRuleId:
          description: The unique identifier of the price derivation rule.
          type: number
        priceDerivationRuleEligibilityId:
          description: The unique identifier of the root eligibility.
          type: number
        frequentShopperPointsEarnedCount:
          description: The number of frequent shopper points earned.
          type: number
        prorateFrom:
          description: The points calculation rule to be applied, expressed as a percentage of the calculation base. Corresponds to ItemPriceDerivationRule.PriceModificationPercent if available.
          type: number
    EndOfTripResponseSaleReturnLineItemPromotionTrigger:
      type: object
      properties:
        privilegeType:
          description: Defines the method for price modification.
          type: string
        privilegeValue:
          description: Reduction amount, reduction percent or new price amount.
          type: string
    EndOfTripResponsePriceModificationLineItem:
      type: object
      properties:
        promotionId:
          description: The unique identifier of the promotion.
          type: number
        priceDerivationRuleId:
          description: The unique identifier of the price derivation rule.
          type: number
        priceDerivationRuleEligibilityId:
          description: The unique identifier of the root eligibility.
          type: number
        triggerSequenceNumber:
          description: The ident of the manual trigger (because a transaction item can have more than one trigger) Needed for transaction preview.
          type: number
    EndOfTripResponseLoyaltyRewardLineItem:
      type: object
      properties:
        pointsAwardedCount:
          description: The number of loyalty points awarded.
          type: number
        promotionId:
          description: The unique identifier of the promotion.
          type: number
        priceDerivationRuleId:
          description: The unique identifier of the price derivation rule.
          type: number
        priceDerivationRuleEligibilityId:
          description: The unique identifier of the root eligibility.
          type: number
    EndOfTripResponseTaxLineItem:
      type: object
      required:
        - taxIncludedInPricesFlag
        - taxableAmount
        - taxPercent
      properties:
        taxIncludedInPricesFlag:
          description: 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.
          type: boolean
        taxableAmount:
          description: The monetary value of the transaction for which tax is being calculated.
          type: number
        taxPercent:
          description: The percentage of the taxable amount that should is tax. Derived by applying the appropriate TaxGroupRule and TaxRateRule.
          type: number
        taxAmount:
          description: The monetary amount of sales Tax calculated by applying the appropriate TaxGroupRule and TaxRateRule.
          type: number
        receiptPrintCode:
          description:  short code that is printed on a receipt to denote items that are in this TaxableGroup.
          type: string
    EndOfTripResponseDepositAssociationItem:
      type: object
      required:
        - toLineItemSequenceNumber
      properties:
        toLineItemSequenceNumber:
          description: The sequence number of the linked line item.
          type: number
    EndOfTripResponseExternalTransactionAssociation:
      type: object
      description: Links to external transactions.
      required:
        - associationTypeCode
        - toTransactionId
      properties:
        associationTypeCode:
          type: string
          enum: [EMPT, SCAL]
          maxLength: 4
          description: >
            * `EMPT` - link to empties receipt
            * `SCAL` - link to scale receipt
        toTransactionId:
          type: string
          maxLength: 128
    EndOfTripResponseRetailTransactionPromotionTriggerItem:
      type: object
      required:
        - triggerSequenceNumber
        - triggerType
        - triggerValue
      properties:
        triggerSequenceNumber:
          description: The ident of the trigger (because a transaction item can have more than one trigger).
          type: number
        triggerType:
          description: The type of the trigger (referencing to POS configuration).
          type: string
        triggerValue:
          description: The value of the trigger (referencing to POS configuration).
          type: string
    EndOfTripResponseRetailTransactionCouponSummaryItem:
      type: object
      required:
        - couponNumber
        - inputCount
        - appliedCount
      properties:
        couponNumber:
          description: The coupon number.
          type: string
        inputCount:
          description: Count of registered coupons.
          type: number
        appliedCount:
          description: Number of used coupons.
          type: number
        customerRelated:
          description: Defines, if a customer is related to the coupon. Will be used for valuephone coupons.
          type: boolean
    EndOfTripResponseRetailTransactionPromotionPriceDerivationRuleItem:
      type: object
      required:
        - promotionId
        - priceDerivationRuleId
        - priceDerivationRuleEligibilityId
      properties:
        promotionId:
          description: The unique identifier of the promotion.
          type: number
        priceDerivationRuleId:
          description: The unique identifier of the price derivation rule.
          type: number
        priceDerivationRuleEligibilityId:
          description: The unique identifier of the root eligibility.
          type: number
        ReceiptPrinterName:
          description: Text to be printed on the receipt.
          type: string
    CustomerId:
      type: string
      description: Unique ID of a customer.
      minLength: 1
      maxLength: 40
    Problem:
      type: object
      required:
        - status
        - timestamp
        - url
      properties:
        message:
          type: string
          example: "Problem description."
          description: "A human readlable description whats going wrong, and if possible how to handle / solve this error."
        timestamp:
          type: string
          format: date-time
          example: 2019-02-21T09:10:54.060+0100
          description: "The current timestamp when the problem occurred."
        url:
          type: string
          example: "https:// ...... /path/to/requested/resource"
          description: "The url that has just been called."
        status:
          type: integer
          format: int32
          example: 400, 401, 500
          description: "The original http statuscode which this error was rejected."
      description: "A response object to describe the problem that has just happened."
  responses:
    badRequest:
      description: "Invalid or missing parameter/s in the request."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"
    notFound:
      description: "Object was not found."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"
    unauthorized:
      description: "Unauthorized"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"
    internalServerError:
      description: "An unexpected server error."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"