Tezro Tollar ad system API

openapi: '3.0.3'
info:
  title: Tollar AdSystem API
  version: '1.0.0'
  description: |
    Tollar AdSystem is Tezro bonus and promotion system for merchants.
    ---
    This API is available for merchants of Tezro after registering in Tollar AdSystem using app.

    <b>Summary</b>
    - The system is for merchants, who plans to improve customer conversions and sails using givebacks (bonus) to customers based on their activity (e.g. X funds for product view or share)
    - The API is used as bridge between merchants' system and Tezro AdSystem.
    - Currently API provides two endpoints:
      - `POST /activities` - for sending tracked customer activity to Tezro for future givebacks to customer. Available to use right from client-side (browser or mobile app)
      - `GET /customers/:customer_id` - for retrieving customers current state in Tezro bonus system
    - Detailed description of DTOs and data types are described right in schemas, please expand them to get more info

    <b>Developer notes</b>
    - Currently API Security is under construction and accepts any valid string value (error causes if `PublicApiKey` header is missing`)
    - All endpoints require `PublicApiKey`
    - Private (server-to-server) endpoints will also require `SignedAuthKey` auth header (currently is /customers/ and it's under construction)
    - `POST /activities` endpoint in the production mode will also use extra mechanisms like origin domains and ip adresses whitelisting, browser fingerprinting and rate-limits to reduce system abuse from public and fraudulent access
    - Timestamp header is used to validate actuality of requests and reply MITM attacks

servers:
  - url: https://dev-openapi.tezro.com/adsystem/mock
    description: Dev mock server
  - url: http://localhost:8080
    description: For local development

tags:
  - name: Activities
    description: Endpoints realted to creating customer activities
  - name: Customers
    description: Endpoints realted to tracking customers' info

paths:
  /activities:
    post:
      operationId: addActivity
      summary: Add new activity info
      description: Based on `customer_id` will register new or update existing customer info.
      tags:
        - Activities
      security:
        - PublicApiKey: []
      parameters:
        - $ref: '#/components/parameters/Timestamp'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddActivityPayloadDto'
      responses:
        '400':
          $ref: '#/components/responses/400_bad_request'
        '401':
          $ref: '#/components/responses/401_missing_auth'
        '403':
          $ref: '#/components/responses/403_forbidden'
        '201':
          $ref: '#/components/responses/201_empty_ok'

  /customers/{customer_id}:
    get:
      operationId: getCustomer
      summary: Get customer info
      tags:
        - Customers
      security:
        - PublicApiKey: []
        - SignedAuthKey: []
      parameters:
        - $ref: '#/components/parameters/Timestamp'
        - in: path
          required: true
          name: customer_id
          examples:
            Customer not linked to Tezro:
              value: customer-not-linked-to-tezro
            Customer linked to Tezro:
              value: customer-linked-to-tezro
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '401':
          $ref: '#/components/responses/401_missing_auth'
        '403':
          $ref: '#/components/responses/403_forbidden'
        '404':
          $ref: '#/components/responses/404_not_found'
        '200':
          description: Customer info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDto'
              examples:
                Customer not linked to Tezro:
                  description: Example state of DTO for customer, who not authorized and linked account in Tezro yet
                  value:
                    customer_id: customer-not-linked-to-tezro
                    created_at: 2024-05-14T05:02:34.234Z
                    code: 'refer-code-customer-not-linked-to-tezro'
                    link_to_app: 'https://tezro.app.link/customer-not-linked-to-tezro'
                    balance:
                      total_earned_tollars: '10'
                      total_earned_in_usd: '0.01'
                      today_earned_tollars: '10'
                      today_earned_in_usd: '0.01'
                Customer linked to Tezro:
                  description: Example state of DTO for customer, who linked account in Tezro
                  value:
                    customer_id: customer-linked-to-tezro
                    created_at: 2024-05-14T05:02:34.234Z
                    code: 'refer-code-customer-linked-to-tezro'
                    link_to_app: 'https://tezro.app.link/customer-linked-to-tezro'
                    balance:
                      total_earned_tollars: '100'
                      total_earned_in_usd: '0.1'
                      today_earned_tollars: '10'
                      today_earned_in_usd: '0.01'
                    linked_user_id: tezro-user-id
                    linked_user_at: 2024-05-14T15:02:34.234Z

components:
  # Security schemas for current API
  # TODO WIP
  securitySchemes:
    PublicApiKey:
      type: apiKey
      name: KeyId
      in: header
    SignedAuthKey:
      type: apiKey
      name: x-tezro-signature
      in: header
      description: WIP. Calculated for every request. For mock or dev servers may pass `API_INTEGRATE`.

  parameters:
    Timestamp:
      name: timestamp
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/DateTime'

  # DTOs and other data types
  schemas:
    DateTime:
      description: System wide date-time format. Prefer to use UTC time.
      externalDocs:
        url: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
      type: string
      format: date-time
      example: 2024-05-14T05:02:34.234Z
    CustomerId:
      type: string
      description: "Customer's id"
      example: 'ea077b53-012d-4efe-99b6-2de5a17630dd'

    # Add new activity request payload
    AddActivityPayloadDto:
      type: object
      required:
        - tag
        - customer_id
        - entity_id
      properties:
        tag:
          $ref: '#/components/schemas/ActivityTagEnum'
        customer_id:
          $ref: '#/components/schemas/CustomerId'
        entity_id:
          description: Entity is universal name for this endpoint. Pass here system-wide unique value for entity like product, order, product review and etc.
          type: string
          example: 'some-product-or-order-or-other-entity-id'
        meta:
          description: |
            Any valid JSON object. Tezro stores it and provides you ability to do analytics based on this data
            You are able to pass here extra info about event (e.g. customers' session duration or current page info or product review notes)
          type: object
          example: { key: value }

    # Activity types (enum)
    ActivityTagEnum:
      type: string
      description: Activity tag unique code. List below is to be extended in the future.
      example: 'view_product'
      enum:
        - view_product
        - buy_product
        - share_product
        - favorite_product
        - view_shared_product
        - buy_shared_product
        - leave_review

    # Merchant's
    CustomerDto:
      type: object
      description: Customer info
      required:
        - id
        - created_at
        - code
        - link_to_app
      properties:
        customer_id:
          $ref: '#/components/schemas/CustomerId'
        created_at:
          $ref: '#/components/schemas/DateTime'
        code:
          type: string
          example: sOmEUnIqUeReFeRaLcOdE
        link_to_app:
          type: string
          description: Deeplink. Generate QR code based on this value, so customers are available to navigate to Tezro and get givebacks to their wallet.
          example: https://tezro.app.link/customer-referal-link
        balance:
          $ref: '#/components/schemas/CustomerBalanceDto'
        linked_user_id:
          type: string
          description: Available after authorizing in Tezro app and linking customer account.
          example: 'some-tezro-user-id'
        linked_user_at:
          $ref: '#/components/schemas/DateTime'

    CustomerBalanceDto:
      description: |
        Customer's balance info.<br />
        P.s. Tollar - abstract currency in context of current system.<br />
        P.p.s $ equivalents are recalculated by actual rate on time of request.
      type: object
      properties:
        total_earned_tollars:
          description: All time earned funds.
          type: string
          default: '0'
          example: '1000.00'
        total_earned_in_usd:
          description: $ equivalent of all time earned funds.
          type: string
          default: '0'
          example: '10.00'
        today_earned_tollars:
          description: Earned funds since 00:00:00 (UTC) until current time.
          type: string
          default: '0'
          example: '1000.00'
        today_earned_in_usd:
          description: $ equivalent of earned funds since 00:00:00 (UTC) until current time.
          type: string
          default: '0'
          example: '10.00'

    # Common error response structure
    ErrorResponseDto:
      description: Common error response payload
      type: object
      required:
        - code
        - message
        - description
      properties:
        code:
          description: HTTP status code
          type: number
          example: 400
        message:
          description: ERROR_CODE
          type: string
          example: FORBIDDEN
        description:
          description: More detailed info
          type: string
          example: Entity not found

  # Common responses
  responses:
    201_empty_ok:
      description: Ok, entity created

    400_bad_request:
      description: Bad request payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'

    401_missing_auth:
      description: Required to provide auth credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'

    403_forbidden:
      description: You are not allowed to perform this request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'

    404_not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'