openapi: 3.1.0
info:
  title: FairShare APIs
  description: >-
    The **FairShare APIs** provides documentation for FairShare tracking and
    analytics services
  contact:
    email: support@fluid.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
security: []
servers:
  - url: https://{company}.fluid.app
    description: Production server with company subdomain
    variables:
      company:
        default: myco
        description: Company subdomain
  - url: http://fluid.lvh.me:{port}
    description: Local development server
    variables:
      port:
        default: '3000'
        description: The port number for local development
components:
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
paths:
  /api/v1/fairshare/activities:
    post:
      summary: Creates a new fairshare_activity
      tags:
        - FairShare
      operationId: createActivity
      parameters: []
      responses:
        '202':
          description: Activity accepted for processing
        '422':
          description: Invalid parameters
        '429':
          description: Too Many Requests - Rate limit exceeded
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - visitor_token
                - activity_type
              properties:
                activity_type:
                  type: string
                  example: viewed_page
                visitor_token:
                  type: string
                  example: test_visitor_token
                trackable_type:
                  type: string
                  example: FairShare::PageVisit
                trackable_token:
                  type: string
                  example: test_token
                metadata:
                  type: object
                  properties:
                    url:
                      type: string
                      example: https://example.com
  /api/v1/fairshare/chat:
    post:
      summary: Submits a chat message
      tags:
        - FairShare
      operationId: chatSubmit
      parameters: []
      responses:
        '200':
          description: Chat submitted successfully
        '422':
          description: Invalid parameters
        '429':
          description: Too Many Requests - Rate limit exceeded
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - visitor_token
                - message
                - contact
              properties:
                visitor_token:
                  type: string
                  example: HzjitJgRQNgLq9LZvTDNHyoj
                message:
                  type: string
                  example: Hello, I need assistance.
                contact:
                  type: object
                  properties:
                    full_name:
                      type: string
                      example: John Doe
                    phone:
                      type: string
                      example: +1-1234567890
                    email:
                      type: string
                      example: test.dsl@gmail.com
                attribution:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    share_guid:
                      type: string
                      example: credit01
  /api/v1/fairshare/popup:
    post:
      summary: Submits a popup
      tags:
        - FairShare
      operationId: popupSubmit
      parameters: []
      responses:
        '200':
          description: Popup submitted successfully
        '404':
          description: Visitor or Popup not found
        '422':
          description: Invalid parameters
        '429':
          description: Too Many Requests - Rate limit exceeded
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - visitor_token
                - popup_id
                - contact
              properties:
                visitor_token:
                  type: string
                  example: HzjitJgRQNgLq9LZvTDNHyoj
                popup_id:
                  type: integer
                  example: 1
                contact:
                  type: object
                  properties:
                    full_name:
                      type: string
                      example: John Doe
                    phone:
                      type: string
                      example: +1-1234567890
                    email:
                      type: string
                      example: test@gmail.com
                attribution:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: null
                    share_guid:
                      type: string
                      example: share_guid_12345
  /api/v1/fairshare/view:
    post:
      summary: Creates a new page visit
      tags:
        - FairShare
      operationId: createPageVisit
      parameters: []
      responses:
        '201':
          description: PageVisit Created - Bot request
        '429':
          description: Too Many Requests - Rate limit exceeded
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - fluid_v
                - url
              properties:
                fluid_v:
                  type: string
                  example: visitor_token_12345
                fluid_c:
                  type: string
                  example: visitor_c_12345
                fingerprint:
                  type: string
                  example: fingerprint123
                url:
                  type: string
                  example: https://danphe.fluid.app/home/shop
                utm_params:
                  type: object
                  properties:
                    utm_source:
                      type: string
                      example: google
                    utm_medium:
                      type: string
                      example: cpc
                    utm_campaign:
                      type: string
                      example: spring_sale
                    utm_term:
                      type: string
                      example: shoes
                    utm_content:
                      type: string
                      example: banner_ad
  /api/v1/fairshare/orders/{order_id}/journey:
    get:
      summary: Retrieves visitor journey for an order
      tags:
        - FairShare Order Journey
      operationId: getOrderJourney
      security:
        - bearer_auth: []
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_journey:
                    type: object
                    properties:
                      id:
                        type: integer
                      visitor_token:
                        type: string
                      journey_started_at:
                        type: string
                        format: date-time
                      journey_duration:
                        type: integer
                      order_details:
                        type: object
                        properties:
                          order_date:
                            type: string
                            format: date-time
                          order_type:
                            type:
                              - string
                              - 'null'
                      product_details:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                          image_url:
                            type: string
                        required:
                          - id
                          - name
                          - image_url
                      share_details:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: integer
                          token:
                            type: string
                          name:
                            type: string
                          sent_at:
                            type: string
                            format: date-time
                      activities:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            activity_type:
                              type: string
                            company_id:
                              type: integer
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
                            occurred_at:
                              type: string
                              format: date-time
                            fairshare:
                              type: boolean
                            metadata:
                              type: object
                            source:
                              type: string
                            trackable_token:
                              type:
                                - string
                                - 'null'
                            trackable_type:
                              type: string
                            user_company_id:
                              type:
                                - 'null'
                                - integer
                            visitor_token:
                              type: string
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
        '404':
          description: not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error_message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
