api_pos.yaml

swagger: '2.0'
info:
  title: Stampay API
  description: Loyalty as a service
  version: 2.1.7
  license:
    name: Stampay GmbH
    url: https://stampay.com/
host: api.staging.stampay.com
schemes:
  - https
basePath: /v2/pos
produces:
  - application/json
securityDefinitions:
  authentication_token:
    type: apiKey
    in: header
    name: Authorization
    description: The content should be "Token token=xxxx"
paths:
  /cards/{encrypted_stampay_id}:
    get:
      summary: Returns data associated with a scanned card.
      description: |
        Once a card is scanned, this query is used to get the consumer data.
      security:
        - authentication_token: []
      parameters:
        - $ref: '#/parameters/EncryptedStampayId'
      tags:
        - card
      responses:
        200:
          $ref: '#/responses/ConsumerDataResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ErrorResponse'
            
  /cards/{encrypted_stampay_id}/transaction:
    post:
      summary: Sends a transaction to get updated consumer data
      description: |
          Sends a transaction to get updated consumer data like new rewards etc. The ticket can be a raw string of the bon **or** a JSON object as described blow.
      security:
        - authentication_token: []
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/EncryptedStampayId'
        - $ref: '#/parameters/TransactionParam'
      tags:
        - transaction
        - card
      responses:
        201:
          $ref: '#/responses/ConsumerDataResponse'
        400:
          $ref: '#/responses/BadRequestResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ErrorResponse'
          
  /transaction:
    post:
      summary: Sends a transaction without card
      description: |
          Transaction without card.
      security:
        - authentication_token: []
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/TransactionWoCardParam'
      tags:
        - transaction
      responses:
        201:
          description: Created
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ErrorResponse'
          
  /articles:
    patch:
      summary: Updates article list
      description: |
        Updates the article list. After the sync has been completed, the partner
        owner gets an email notifing him about the changes. So he can visit our
        partner portal and assign white/black lists and redeemable articles.
      security:
        - authentication_token: []
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/ArticleListParams"
      tags:
        - articles
      responses:
        200:
          description: OK
        304:
          $ref: '#/responses/NotModifiedResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        422:
          $ref: '#/responses/ErrorResponse'
          
  /redeemable_articles:
    get:
      summary: Sends articles redeemable by offer
      description: Sends articles redeemable by offer
      security:
        - authentication_token: []
      tags:
        - terminal
        - articles
      responses:
        200:
          $ref: '#/responses/RedeemableArticlesResponse'
        304:
          $ref: '#/responses/NotModifiedResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        422:
          $ref: '#/responses/ErrorResponse'
          
  /terminal/login:
    post:
      summary: Request a new authorization token
      description: |
        This checks if there is terminal with the hardware_id and the salespoint_id. If this is not the case it assumes that there was some change and does not give back a token. This means the terminal must be reactivated.
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/RegisterDataParam'
      tags:
        - license
        - terminal
      responses:
        200:
          $ref: '#/responses/AuthentificationTokenResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ParamMissingResponse'

  /terminal/logout:
    delete:
      summary: Free license from linked terminal
      description: |
        Removes a license from a terminal to allow binding to another one or give back a license
      security:
        - authentication_token: []
      tags:
        - license
        - terminal
      responses:
        200:
          description: OK
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ErrorResponse'
          
  /terminal/data:
    get:
      summary: Returns terminal data
      description: |
        Returns terminal data:
          - terminal config as card config
          - Offer data
      security:
        - authentication_token: []
      tags:
        - terminal
      responses:
        200:
          $ref: '#/responses/TerminalDataResponse'
        304:
          $ref: '#/responses/NotModifiedResponse'
        401:
          $ref: '#/responses/UnauthorizedResponse'
        404:
          $ref: '#/responses/NotFoundResponse'
        422:
          $ref: '#/responses/ErrorResponse'
       
parameters:
  EncryptedStampayId:
    name: encrypted_stampay_id
    in: path
    description: Raw data of the scanned QR-Code
    required: true
    type: string
  
  TransactionParam:
    name: transaction
    in: body
    required: true
    schema:
      $ref: "#/definitions/Transaction"
      
  TransactionWoCardParam:
    name: inline_transaction
    in: body
    required: true
    schema:
      type: object
      required:
        - ticket
        - trx_id
      properties:
        created_at:
          type: string
          format: date-time
          description: |
            timescope of transaction creation. If not set, server time at
            processing is used. One should set this if transaction happened when
            server was not reachable.
        trx_id:
          type: string
          description: 'Transaction id. Has to be unique.'
        ticket:
          type: object
          required:
            - raw
          properties:
            raw:
              type: string
            line_items:
              type: array
              items:
                $ref: '#/definitions/LineItem'
      
  RegisterDataParam:
    name: register_data
    in: body
    required: true
    schema:
      type: object
      required:
        - license_key
        - salespoint_id
        - hardware_key
      properties:
        license_key:
          type: string
        salespoint_id:
          type: integer
          format: int32
        hardware_key:
          type: string
          
  ArticleListParams:
    name: article_params
    in: body
    required: true
    description: |
      Params for updating article list
    schema:
      type: object
      properties:
        articles:
          type: array
          items:
            type: object
            required:
              - article_number
              - name
            properties:
              article_number:
                description: Number of article in cash system
                type: integer
                format: int32
              name:
                description: Name of article
                type: string
              category:
                description: Article category
                type: string
    
definitions:
  AccountBalance:
    type: object
    description: A cards balance
    required:
      - amount
      - currency
    properties:
      amount: 
        type: number
        format: double
      currency:
        type: string
        
  Stampset:
    type: object
    required:
      - offer_ident
      - stampcount
    properties:
      offer_ident:
        type: string
      stampcount:
        type: integer
        format: int32

  Reward:
    type: object
    required:
      - id
      - offer_ident
    properties:
      id:
        type: integer
        format: int32
      offer_ident:
        type: string
        
  Offer: 
    type: object
    required:
      - ident
      - campaign_image
      - offer_image
      - name
      - threshold
      - active
      - type
    properties:
      ident:
        type: string
      campaign_image:
        type: object
        properties:
          url:
            type: string
      offer_image:
        type: object
        properties:
          url:
            type: string
      name: 
        type: string
      description:
        type: string
      threshold:
        type: integer
        format: int32
      active:
        type: boolean
      type:
        type: string
        description: Loyalty or Coupon
      redeemable_articles:
        type: array
        items:
          type: integer
          format: int32
          
  Transaction:
    type: object
    required:
      - trx_id
    properties:
      created_at:
        type: string
        format: date-time
        description: |
          timescope of transaction creation. If not set, server time at
          processing is used. One should set this if transaction happened when
          server was not reachable.
      trx_id:
        type: string
        description: 'Transaction id. Has to be unique.'
      storno:
        type: boolean
        description: 'Is this a storno transaction. Default is false'
      storno_trx_id:
        type: string
        description: 'Id of transaction this storno is referenced to.'
      topup:
        type: array
        items:
          type: object
          required:
            - amount
          properties:
            amount:
              type: number
              format: double
            currency:
              type: string
              description: default is EUR
      charge:
        type: array
        items:
          type: object
          required:
            - amount
          properties:
            amount:
              type: number
              format: double
            currency:
              type: string
              description: default is EUR
      clear:
        type: array
        items:
          type: object
          required:
            - reward_id
          properties:
            reward_id:
              type: string
      checkin:
        type: array
        items:
          type: object
          required:
            - amount
            - offer_ident
          properties:
            amount:
              type: number
              format: double
            offer_ident:
              type: string
      ticket:
        type: object
        required:
          - raw
        properties:
          raw:
            type: string
          line_items:
            type: array
            items:
              $ref: '#/definitions/LineItem'
          
  LineItem:
    type: object
    required:
      - amount
      - article_number
      - price
    properties:
      amount: 
        type: number
        format: double
      article_number:
        type: integer
        format: int32
      price:
        type: number
        format: double
        description: Single article price
      total:
        type: number
        format: double
        description: Summary after discounts. If not given, amount * price is used
      discounted_amount:
        type: number
        format: double
        description: Amount of discounted articles
        
responses:
  ErrorResponse:
    description: Unprocessable Entity
    schema:
      properties:
        code:
          type: integer
          format: int32
        errors:
          description: Error messages
          type: string
    examples:
      application/json:
        code: 10102
        errors: "Card not active or pending"
        
  ParamMissingResponse:
    description: Unprocessable Entity
    schema:
      properties:
        code:
          type: integer
          format: int32
        errors:
          description: Error messages
          type: string
    examples:
      application/json:
        code: 422
        errors: "License key missing"
          
  UnauthorizedResponse:
    description: Unauthorized
    schema:
      properties:
        code:
          type: integer
          format: int32
        errors:
          description: Error messages
          type: string
    examples:
      application/json:
        code: 401
        errors: "Validation failed. License key not valid or hardware key changed"
  
  NotFoundResponse:
    description: Record not found
  
  NotModifiedResponse:
    description: To use this you have to add the "If-Modified-Since" header
    
  AuthentificationTokenResponse:
    description: Response if the register was validated.
    schema:
      properties:
        authentication_token:
          type: string
          
  BadRequestResponse:
    description: Not all params are set
    schema:
      properties:
        code:
          type: integer
          format: int32
        errors:
          description: Error messages
          type: string
    examples:
      application/json:
        code: 400
        errors: "At leat one action has to be present"
          
  ConsumerDataResponse:
    description: Combined balance, stampsets and rewards for a user.
    schema:
      properties:
        active_stampsets:
          type: array
          items:
            $ref: '#/definitions/Stampset'
        open_rewards:
          type: array
          items:
            $ref: '#/definitions/Reward'
        account_balances:
          type: array
          items:
            $ref: '#/definitions/AccountBalance'
    examples:
      application/json:
        active_stampsets: 
          - offer_ident: "22bba168-e502-414f-9676-6f2ebf76da42"
            stampcount: 2
        open_rewards:
          - id: 502320
            offer_ident: "22bba168-e502-414f-9676-6f2ebf76da42"
        account_balances: []
      
  TerminalDataResponse:
    description: Terminal data
    schema:
      properties:
        card_config:
          type: object
          required:
            - 'prefix-allow'
            - 'prefix-deny'
            - 'prefix-payment-allow'
            - 'prefix-payment-deny'
          properties:
            prefix-allow:
              type: array
              description: Card prefixes allowed to checkin
              items:
                type: string
            prefix-payment-allow:
              type: array
              description: Card prefixes allowed to use payment
              items:
                type: string
            prefix-deny:
              type: array
              description: Card prefixes allowed to use payment
              items:
                type: string
            prefix-payment-deny:
              type: array
              description: Card prefixes allowed to use payment
              items:
                type: string
        offers:
          type: array
          items:
            $ref: '#/definitions/Offer'
    examples:
      application/json:
        card_config:
          prefix-allow:
           - 'c/'
          prefix-payment-allow: []
        offers: 
          ident: "22bba168-e502-414f-9676-6f2ebf76da42"
          campaign_image:
            url: "https://d1bjoav7ngkix4.cloudfront.net/campaign_images/84354d3a0d9333b8801db2453b7260cb.jpg"
            mobile:
              url: "https://d1bjoav7ngkix4.cloudfront.net/campaign_images/mobile_84354d3a0d9333b8801db2453b7260cb.jpg"
            mobile_retina:
              url: "https://d1bjoav7ngkix4.cloudfront.net/campaign_images/[email protected]"
            homepage:
              url: "https://d1bjoav7ngkix4.cloudfront.net/campaign_images/homepage_84354d3a0d9333b8801db2453b7260cb.jpg"
          offer_image:
            url: "https://d1bjoav7ngkix4.cloudfront.net/offer_images/41ecbd6c7875271a4556f16ccf441504.jpg"
            mobile:
              url: "https://d1bjoav7ngkix4.cloudfront.net/offer_images/mobile_41ecbd6c7875271a4556f16ccf441504.jpg"
              mobile_retina:
                url: "https://d1bjoav7ngkix4.cloudfront.net/offer_images/[email protected]"
            name: "Einkauf (pro 3,50€) 8+1"
            active: true
            type: "Loyalty"
            redeemable_articles: []
            threshold: 8

          
  RedeemableArticlesResponse:
    description: redeemable articles
    schema:
      type: array
      items:
        type: object
        properties:
          offer_ident:
            type: string
          redeemable_articles:
            type: array
            items:
              type: integer
              format: int32
              description: 'Article numbers for redeemable articles'
    examples:
      application/json:
        - offer_ident: "15ec2587-38b3-45c5-8e5d-27bcd9a0929a"
          redeemable_articles: []
        - offer_ident: "4ca495f0-e322-42b0-ba26-eb4c709a0f06"
          redeemable_articles:
            - 3