openapi: 3.0.3
info:
  title: clickouts api
  version: 0.0.1-dev
  description: Host API documentation Click-Out Statistics API.
servers:
- url: http://api.shopr.nl/stats
paths:
  /_internal_/ping:
    get:
      description: Ping in milliseconds.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsStatus'
  /_internal_/status:
    get:
      description: Current health check status.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsStatus'
  /_internal_/version:
    get:
      description: API version.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: string
  /{fingerprint}/clickouts:
    post:
      description: Create a new click-out. Requests are accepted for eventual processing.
      parameters:
      - name: fingerprint
        in: path
        description: User fingerprint used for correlation purposes.
        required: true
        schema:
          type: string
        example: cc7507cb65ffc750b298e722b34556c5
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsClickout'
        required: true
      responses:
        '202':
          description: Response 202
          content:
            application/json:
              schema:
                type: string
        '422':
          description: 'Example: lowestPrice is greater than highestPrice.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsErrorResponse'
components:
  schemas:
    ComShoprApiClickoutsApiV0ModelsErrorCode:
      type: object
      required:
      - code
      - localized_string_code
      properties:
        code:
          description: Machine readable code for this specific error message
          example: 100
          type: string
        localized_string_code:
          description: A localized description of the error code
          example: Lowest price cannot be bigger than highest price
          type: string
    ComShoprApiClickoutsApiV0ModelsClickout:
      description: 'Represents an Offer click-out. It contains all the information
        needed to properly identify the offer, trace it ot the user navigating from
        search page, and relevant information about the offer at the click-out moment
        (e.g.: price, lowest price among other offers, etc.)'
      type: object
      required:
      - productId
      - seller
      - sellerProductId
      - price
      - deepUrl
      - lowestPrice
      - highestPrice
      - offerCount
      - offerPosition
      - categoryId
      - tracking
      - creationTime
      properties:
        productId:
          description: Product identifier
          example: 584f4c7f4cedfd0005e17c19
          type: string
        seller:
          description: Seller/Retailer unique identifier
          example: klingel
          type: string
        sellerProductId:
          description: Product as identifier given by the seller/retailer
          example: SAND003
          type: string
        price:
          description: Offer price at the moment of the click-out
          example: 67.00
          type: number
        deepUrl:
          description: Full product URL at the retailer side
          example: http://www.klingel.nl/ProductDisplay?langId=31&catalogId=1000100000&storeId=100003&partNumber=460741&colorId=rood&attrId=G&vcp=gcqdjikm13m8iz&refID=Klingel_NL/Shopr/Dames/Schoenen/Pumps/Klassieke_pumps/04919/50X/&emsrc=Produktportale
          type: string
        lowestPrice:
          description: Lowest price among all offers
          example: 59.99
          type: number
        highestPrice:
          description: Seller/Retailer unique identifier
          example: 87.00
          type: number
        offerCount:
          description: Number of offers
          example: 5
          type: integer
          format: int32
          minimum: 1
        offerPosition:
          description: 'Offer position among other offers (e.g.: first, second, etc.)'
          example: 2
          type: integer
          format: int32
          minimum: 1
        categoryId:
          description: Category where the product was put into
          example: 1234
          type: string
        tracking:
          $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsTracking'
          description: Tracking information
        creationTime:
          description: When this click-out happened
          example: '2016-12-22T11:56:52Z'
          type: string
          format: date-time
    ComShoprApiClickoutsApiV0ModelsStatus:
      description: Response for ping, health check and version
      type: object
      required:
      - response
      properties:
        response:
          example: 100ms | healthy | 0.0.1
          type: string
    ComShoprApiClickoutsApiV0ModelsTracking:
      description: Series of attributes for tracking purposes
      type: object
      required:
      - ipAddress
      - origin
      properties:
        ipAddress:
          type: string
        origin:
          $ref: '#/components/schemas/ComShoprApiClickoutsApiV0EnumsClientOrigin'
          description: Client originating the order request essentially any of the
            values of the client_origin enum.
        userAgent:
          type: string
        referrer:
          description: Optional page referrer.
          type: string
    ComShoprApiClickoutsApiV0ModelsErrorResponse:
      type: object
      required:
      - error_codes
      properties:
        message:
          description: User-friendly message.
          type: string
        error_codes:
          description: List of errors that may happened all together.
          type: array
          items:
            $ref: '#/components/schemas/ComShoprApiClickoutsApiV0ModelsErrorCode'
        fingerprint:
          description: The request fingerprint associated with this error.
          type: string
    ComShoprApiClickoutsApiV0EnumsClientOrigin:
      description: Describes the client where the request for a clickout has originated.
      type: string
      enum:
      - shopr_website
      - shopr_mobile_web
      - shopr_iphone
      - shopr_ipad
      - shopr_android