openapi: 3.2.0
info:
  title: FirstPromoter Admin Products API
  version: 1.0.0
  description: Admin API endpoints for managing products in FirstPromoter
servers:
- url: https://api.firstpromoter.com/api/v2/company
  description: Staging server
security:
- BearerAuth: []
tags:
- name: Products
paths:
  /products:
    get:
      summary: Get available products
      tags:
      - Products
      description: "Get available products \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/products`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: q
        schema:
          type: string
        description: Search params. Searches by name and prices
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create product
      tags:
      - Products
      description: "Create product \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/products`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - prices
              properties:
                name:
                  type: string
                  description: Name of the product
                ext_id:
                  type: string
                  description: External ID of the product
                prices:
                  type: array
                  description: List of prices for the product
                  items:
                    type: object
                    required:
                    - ext_id
                    properties:
                      ext_id:
                        type: string
                        description: External ID of the price (must be unique within the product)
                      desc:
                        type:
                        - string
                        - 'null'
                        description: Description of the price
      responses:
        '201':
          description: Product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{id}:
    get:
      summary: Get product
      tags:
      - Products
      description: "Get product based on id \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/products/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: ID of the product
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update product
      tags:
      - Products
      description: "Update product based on id \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/products/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: ID of the product to be updated
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prices
              properties:
                name:
                  type: string
                  description: Name of the product
                ext_id:
                  type: string
                  description: External ID of the product
                prices:
                  type: array
                  description: List of prices for the product
                  items:
                    type: object
                    properties:
                      ext_id:
                        type: string
                        description: External ID of the price
                      desc:
                        type:
                        - string
                        - 'null'
                        description: Description of the price
      responses:
        '200':
          description: Product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete product
      tags:
      - Products
      description: "Delete product based on id \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/products/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: ID of the product to be deleted
      responses:
        '200':
          description: Product deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account ID. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          description: ID of the product
        name:
          type: string
          description: Name of the product
        ext_id:
          type:
          - string
          - 'null'
          description: External ID of the product
        prices:
          type: array
          description: List of prices for the product
          items:
            type: object
            properties:
              ext_id:
                type: string
                description: External ID of the price
              desc:
                type: string
                description: Description of the price
        created_at:
          type: string
          format: date-time
          description: Date and time when the product was created
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    ValidationError:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          description: Validation errors
          additionalProperties:
            type: array
            items:
              type: string
        code:
          type: string
          description: Error code
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header. You can find your API Key on Your FirstPromoter Dashboard. Navigate to Settings → Integrations section → Manage API Keys
    accountId:
      type: apiKey
      in: header
      name: Account-ID
      description: Account ID required with bearer token