openapi: 3.2.0
info:
  description: '### Configuration API with a tree-like hierarchy.'
  title: CAFA Configuration API
  contact:
    email: david.zingerman@erply.com
  version: 4.19.2
tags:
- name: Configuration
paths:
  /configuration:
    get:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: 'All those parameters work like filters. You can search for all configs by type or by level. Or get all configs of Pos 1.

        With `Look-Deeper` header set to `true` you will get the following logic of the request:

        When you request a config at a User or Warehouse levels, if it is not there it will check Company level as well. When you request a config at a POS level, if it is not there it will check Warehouse (if request to ERPLY API was ok to get the Warehouse ID) and Company levels as well.'
      tags:
      - Configuration
      summary: Get all configurations or a sub-list
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: look for configuration on deeper levels. if CAFA does not find any configuration with the query parameters, CAFA will use the level_id(PointOfSaleID), to find which Warehouse the Pos belongs to and check for configuration with the same name(and type if present)
        name: Look-Deeper
        in: header
        schema:
          type: boolean
      - description: Application name that uses CAFA to store configs
        name: application
        in: query
        schema:
          type: string
      - description: Level is the operating level where the config is stored
        name: level
        in: query
        schema:
          type: string
          enum:
          - Company
          - Warehouse
          - Pos
          - User
          - Device
      - description: LevelID is a unique value, used to identify the instance of the level. for User level, user id, for Pos - Point of Sale ID. Warehouse can use any unique string to identify the instance of its level,  `Company level does not need level_id.`
        name: level_id
        in: query
        schema:
          type: string
      - description: Type is an optional grouping property, in this case its 'payment', indicating that this configuration belongs to payment integrations group used to query groups of related configurations
        name: type
        in: query
        schema:
          type: string
      - description: Name of the configuration
        name: name
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/configuration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: getConfiguration
      x-operation-id-source: derived
    put:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: '`level`, `level_id` and `type` are optional fields.'
      tags:
      - Configuration
      summary: Update `value` only
      deprecated: true
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/configurationRequest'
        description: ConfigurationDbRecord
        required: true
      operationId: putConfiguration
      x-operation-id-source: derived
    post:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: '`NB`: You cannot have 2 configurations with the same level,level_id, type, name and application

        level, level_id and type are optional fields.'
      tags:
      - Configuration
      summary: Save
      deprecated: true
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/configurationRequest'
        description: ConfigurationDbRecord
        required: true
      operationId: postConfiguration
      x-operation-id-source: derived
    delete:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: 'Delete will delete the configuration by strict match of the following fields: level, application, levelID, type and name.'
      tags:
      - Configuration
      summary: Delete
      deprecated: true
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: Application (s) name that uses CAFA to store configs
        name: application
        in: query
        required: true
        schema:
          type: string
      - description: Level is the operating level where the config is stored. Has to be one of Company, Warehouse, Pos, User
        name: level
        in: query
        schema:
          type: string
      - description: LevelID is an unique value, used to identify the instance of the level. for User level, user id, for Pos - Point of Sale ID. Warehouse can use any unique string to identify the instance of its level,  Company level does not need level_id.
        name: level_id
        in: query
        schema:
          type: string
      - description: Type is an optional grouping property, in this case its 'payment', indicating that this configuration belongs to payment integrations group used to query groups of related configurations
        name: type
        in: query
        schema:
          type: string
      - description: Name of the configuration
        name: name
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: deleteConfiguration
      x-operation-id-source: derived
  /configuration/apps:
    get:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: Get a list of all application names that the user has configurations for.
      tags:
      - Configuration
      summary: Get a list of all application names that the user has configurations for
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/appsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: getConfigurationApps
      x-operation-id-source: derived
  /configuration/{applicationName}:
    get:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: The endpoint allows you to get all the configurations in an application
      tags:
      - Configuration
      summary: Get all configurations for an application
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: Application name
        name: applicationName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/configuration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: getConfigurationByApplicationName
      x-operation-id-source: derived
  /configuration/{id}/move:
    put:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      tags:
      - Configuration
      summary: Moving means changing the level_id
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: ConfigurationDbRecord ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/moveRequest'
        description: desired levelID
        required: true
      operationId: putConfigurationByIdMove
      x-operation-id-source: derived
  /v3/configuration:
    put:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      description: '`NB`: You cannot have 2 configurations with the same level,level_id, type, name and application

        level, level_id and type are optional fields.'
      tags:
      - Configuration
      summary: Save or update a configuration
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/configurationRequest'
        description: ConfigurationDbRecord
        required: true
      operationId: putV3Configuration
      x-operation-id-source: derived
  /v3/configuration/{id}:
    get:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      tags:
      - Configuration
      summary: Get by ID
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: Configuration ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/configuration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: getV3ConfigurationById
      x-operation-id-source: derived
    put:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      tags:
      - Configuration
      summary: Update `value` by ID
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: Configuration ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/valueRequest'
        description: new configuration value
        required: true
      operationId: putV3ConfigurationById
      x-operation-id-source: derived
    delete:
      security:
      - sk: []
      - cc: []
      - hmac-auth: []
      - jwt: []
      tags:
      - Configuration
      summary: Delete By ID
      parameters:
      - description: UNIX timestamp used for the HMAC Auth method only
        name: timestamp
        in: header
        schema:
          type: string
      - description: configuration ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
      operationId: deleteV3ConfigurationById
      x-operation-id-source: derived
components:
  schemas:
    configuration:
      type: object
      properties:
        added:
          type: integer
        addedby_id:
          type: integer
        application:
          type: string
          example: erply-to-woo-sync
        changed:
          type: integer
        changedby_id:
          type: integer
        id:
          type: string
        level:
          description: Level is optional
          type: string
          example: Pos
        level_id:
          description: LevelID is optional
          type: string
          example: '1'
        name:
          type: string
          example: adyen
        type:
          description: Type is optional
          type: string
          example: payment
        value: {}
    response:
      type: object
      properties:
        id:
          type: integer
        message:
          type: string
        statusCode:
          type: string
    configurationRequest:
      type: object
      properties:
        application:
          description: Application (s) name that uses CAFA to store configs, application name has to be generated manually before it can be used in Identity Admin.
          type: string
          example: woo-comm
        level:
          description: Level is the operating level where the config will be stored. Has to be one of Company, Warehouse, Pos, User
          type: string
          example: Pos
        level_id:
          description: 'LevelID is a unique value, used to identify the instance of the level.

            for User level, user id

            for Pos - Point of Sale ID. Each Pos belongs to Warehouse. When we query CAFA for configuration on level: ''Pos'', and add ''Look-Deeper: true'' header, if CAFA dooes not find any configuration with the query parameters, CAFA will use the level_id(PointOfSaleID), to find which Warehouse the Pos belongs to and check for configuration with the same name(and type if present)

            Warehouse can use any unique string to identify the instance of its level, because the higher level for each Warehouse is Company level, which can only be one instance per account

            Company level does not need level_id because there can only be one company per account in Erply.'
          type: string
          example: '1'
        name:
          description: Name of the configuration
          type: string
          example: adyen
        type:
          description: 'Type is an optional grouping property, in this case its ''payment'',

            indicating that this configuration belongs to payment integrations group

            used to query groups of related configurations'
          type: string
          example: payment
        value:
          description: 'Value stored by the configuration. Supported types: JSON, JSON array, string'
    valueRequest:
      type: object
      properties:
        value:
          description: 'Value stored by the configuration. Supported types: JSON, JSON array, string'
    appsResponse:
      type: object
      properties:
        applications:
          type: array
          items:
            type: string
    moveRequest:
      type: object
      properties:
        level_id:
          description: LevelID is new level_id to set for the config
          type: string
  securitySchemes:
    cc:
      type: apiKey
      name: clientCode
      in: header
    hmac-auth:
      type: apiKey
      name: hmac-auth
      in: header
    jwt:
      type: apiKey
      name: jwt
      in: header
    sk:
      type: apiKey
      name: sessionKey
      in: header