openapi: "3.0.0"


################################################################################
# General Information
# SYSTEM_05, 08: Retailer tool for ECO-accounting back-end
info:
  description: The ICT Platform Web Service for anonymous ECO-accounting back-end.
  version: 1.0.2
  title: ICT Platform Retailer Module Web Service
  contact:
    name: Miltiadis Koutsokeras
    email: miltos.koutsokeras@iccs.gr
    url: https://www.iccs.gr/

# Deployed server endpoints
servers:
  - url: https://circ4life.iccs.gr/RetailerModule
    description: CIRC4Life ICT platform.
  - url: http://127.0.0.1:8084/RetailerModule
    description: Local debugging standalone server.
################################################################################


################################################################################
# Components
components:
  schemas:
    EcoAccountAddPurchasesForm:
      type: object
      required:
        - consumerid
        - products
        - ecodebits
      properties:
        consumerid:
          $ref: "CommonOpenAPI.yaml#/components/schemas/AnonymousConsumerID"
        products:
          type: array
          items:
            $ref: "CommonOpenAPI.yaml#/components/schemas/Product"
        ecodebits:
          # This is the number of Eco-debits the retailer maps to the
          # consumer, due to his purchase list.
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoDebits"
        ecocredits:
          # Optional
          # This is the number of Eco-credits the consumer wishes to use
          # from his Eco-balance, as a credit for his purchases. This
          # amount cannot exceed the total number of Eco-credits in the
          # consumer's account and if the property is not set by the
          # retailer application during POST, the ICT Platform considers
          # it equal to zero.
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoCredits"

    EcoAccountBalanceUpdateForm:
      type: object
      required:
        - consumerid
        - ecodebits
        - ecocredits
      properties:
        consumerid:
          $ref: "CommonOpenAPI.yaml#/components/schemas/AnonymousConsumerID"
        ecodebits:
          # This is the number of Eco-debits the retailer maps to the
          # consumer, due to his purchases.
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoDebits"
        ecocredits:
          # This is the number of Eco-credits the consumer wishes to use
          # from his Eco-balance, as a credit for his purchases. This
          # amount cannot exceed the total number of Eco-credits in the
          # consumer's account.
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoCredits"

    EcoAccountBalance:
      type: object
      required:
        - firstname
        - lastname
        - ecodebits
        - ecocredits
      properties:
        firstname:
          type: string
        lastname:
          type: string
        ecodebits:
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoDebits"
        ecocredits:
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoCredits"

  requestBodies:
    EcoAccountAddPurchasesRequest:
     required: true
     description: List of purchased products plus the Eco-debits and optional Eco-credits
     content:
      application/json:
        schema:
          $ref: "#/components/schemas/EcoAccountAddPurchasesForm"

    EcoAccountBalanceUpdateRequest:
      required: true
      description: Eco-balance update with to be added Eco-debits and to be subtracted Eco-credits
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EcoAccountBalanceUpdateForm"

  responses:
    EcoAccountBalanceResponse:
      description: EcoAccount balance and user's name
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EcoAccountBalance"
################################################################################


################################################################################
# Resource path URI endpoints
paths:
  # Results can be returned in a specific language by using the Query parameter
  # 'locale' and set its value equal to the ISO 639 alpha-2 language code, e.g.
  # for Spanish: /purchase_history/12345678901?locale=es

  # USER_G_04: EcoAccount mapping to anonymous Consumer ID via consumer's
  # application code (QR code, Barcode)
  # End-users applications should be able to login to their EcoAccount and
  # present a consumer code ID to the retailer's application in order to
  # identify themselves without exposing private data. The consumerid parameter
  # that a Retailer application passes to this endpoint is provided by the user
  # from his End-users application. This endpoint should be a check if the
  # anonymous consumerid is valid (Response HTTP 200) or not (any other
  # Response). The user session for accessing all end points below is not for
  # an EcoAccount as in EndUserModule service, but an authorized Retailer
  # client user (allowed to access this service).
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /ecoaccount/{consumerid}:
    get:
      description: Get anonymous user id from consumer's application code
      operationId: EcoAccountAnonymousGET
      parameters:
        - in: path
          name: consumerid
          description: The anonymous consumer id to use for EcoAccount access
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/AnonymousConsumerID"
      responses:
        '200':
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultSuccess"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Get user's EcoAccount basic info and balance, in order to display them in
  # the Retailer application after the QR code scanning. This will validate that
  # the QR code was properly scanned as the user will revognize the his name and
  # balance numbers.
  /ecoaccount/ecobalance/{consumerid}:
    get:
      description: Get user's EcoAccount basic info and balance
      operationId: EcoAccountEcobalanceGET
      parameters:
        - in: path
          name: consumerid
          description: The anonymous consumer id to use for EcoAccount access
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/AnonymousConsumerID"
      responses:
        '200':
          $ref: "#/components/responses/EcoAccountBalanceResponse"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # USER_U_02: Post Eco-debit value and purchase transaction to EcoAccount using
  # Anonymous Consumer ID.
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /ecoaccount/add/purchases:
    post:
      description: Update user's EcoAccount by posting additional purchases and their corresponding retailer Eco-debits
      operationId: EcoAccountAddPurchasesPOST
      requestBody:
        $ref: "#/components/requestBodies/EcoAccountAddPurchasesRequest"
      responses:
        '200':
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultSuccess"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Update the user's Eco-balance with added Eco-debits and/or subtracted
  # Eco-credits. This endpoint allows a Retailer application to update the
  # Eco-balance without providing a list of purchased products.
  /ecoaccount/ecobalance/update:
    post:
      description: Update user's EcoAccount balance by posting the number of Eco-debits to add and the number of Eco-credits to subtract.
      operationId: EcoAccountBalanceUpdate
      requestBody:
        $ref: "#/components/requestBodies/EcoAccountBalanceUpdateRequest"
      responses:
        '200':
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultSuccess"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # USER_G_12: Product Master data mapping to Product ID (RFID, Barcode)
  # Use a product ID in order to retrieve all its Master Data information
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /product/{productid}:
    get:
      description: Get product Master data that correspond to a product ID
      operationId: ProductGET
      parameters:
        - in: path
          name: productid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/ProductID"
        - in: query
          name: locale
          required: false
          schema:
            description: ISO 639 alpha-2 language code for this locale
            type: string
            default: "en"
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: the product Master data in JSON-LD format
          content:
            application/json:
              schema:
                type: string
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Use a Barcode in order to retrieve all its Master Data information. The
  # supported Barcode formats are under discussion.
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /product/barcode/{barcode}:
    get:
      description: Get product Master data that correspond to a Barcode/RFID
      operationId: ProductBarcodeGET
      parameters:
        - in: path
          name: barcode
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/Barcode"
        - in: query
          name: locale
          required: false
          schema:
            description: ISO 639 alpha-2 language code for this locale
            type: string
            default: "en"
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: the product Master data in JSON-LD format
          content:
            application/json:
              schema:
                type: string
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # USER_G_12: Get Eco-point value from Product ID (RFID, Barcode)
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /product/ecopoints/{productid}:
    get:
      description: Get Eco-points that correspond to a product ID
      operationId: ProductEcoPointsGET
      parameters:
        - in: path
          name: productid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/ProductID"
      responses:
        '200':
          description: The product's Eco-points value.
          content:
            application/json:
              schema:
                $ref: "CommonOpenAPI.yaml#/components/schemas/EcoPoints"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Get Eco-point value from Barcode
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /product/ecopoints/barcode/{barcode}:
    get:
      description: Get Eco-points that correspond to a Barcode/RFID
      operationId: ProductEcoPointsBarcodeGET
      parameters:
        - in: path
          name: barcode
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/Barcode"
      responses:
        '200':
          description: The product's Eco-points value.
          content:
            application/json:
              schema:
                $ref: "CommonOpenAPI.yaml#/components/schemas/EcoPoints"
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"
################################################################################
