openapi: 3.0.1
info:
  title: 'Product catalog REST Service: API Specification'
  description: The product catalog REST Service is that provides REST api endpoints
    for product catalog data.
  version: 1.1.1
servers:
- description: ''
  url: https://api.cve.btx.eu.banqup.com/product/catalog
paths:
  /v1/spaces/{spaceId}/productCatalogs:
    get:
      tags:
      - Product catalogs
      summary: Get product catalogs
      description: 'Get a list of all product catalogs <br/> Scope: space_read'
      operationId: getAllProductCatalogs
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProductCatalogResponse'
              example: |-
                {
                    "productCatalogs": [
                        {
                            "id": "00000011-0000-0000-0000-000000000001",
                            "spaceId": "00000011-0000-0000-0001-000000000001",
                            "name": "Corporate Tax Catalog",
                            "description": "A catalog containing tax-related products for corporate entities"
                        },
                        {
                            "id": "0000001-0000-0000-0000-000000000000",
                            "spaceId": "00000011-0000-0000-0001-000000000000",
                            "name": "VAT & Indirect tax catalog",  // Match exact case from API response
                            "description": "A catalog containing VAT and indirect tax-related products"
                        }
                    ]
                }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
    post:
      tags:
      - Product catalogs
      summary: Create product catalog
      description: 'Create a new product catalog <br/> Scope: space_write'
      operationId: createProductCatalog
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Product catalog to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCatalogRequest'
            example:
              name: Corporate Tax Catalog
              description: A catalog containing tax-related products for corporate
                entities
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalog'
              example:
                id: 00000011-0000-0000-0000-000000000001
                spaceId: 00000011-0000-0000-0001-000000000001
                name: Corporate Tax Catalog
                description: A catalog containing tax-related products for corporate
                  entities
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/productCatalogs/{catalogId}:
    get:
      tags:
      - Product catalogs
      summary: Get product catalog by id
      description: 'Get product catalog by uuid <br/> Scope: space_read'
      operationId: getProductCatalog
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalog'
              example:
                id: 00000011-0000-0000-0000-000000000001
                spaceId: 00000011-0000-0000-0001-000000000001
                name: Corporate Tax Catalog
                description: A catalog containing tax-related products for corporate
                  entities
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
    delete:
      tags:
      - Product catalogs
      summary: Delete product catalog
      description: 'Delete product catalog by uuid <br/> Scope: space_write'
      operationId: deleteProductCatalog
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content - The product catalog was successfully deleted.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
    patch:
      tags:
      - Product catalogs
      summary: Update product catalog
      description: 'Update an existing product catalog <br/> Scope: space_write'
      operationId: updateProductCatalog
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Product catalog data to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCatalogRequest'
            example:
              name: Corporate Tax Catalog
              description: A catalog containing tax-related products for corporate
                entities
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalog'
              example:
                id: 00000011-0000-0000-0000-000000000001
                spaceId: 00000011-0000-0000-0001-000000000001
                name: Corporate Tax Catalog
                description: A catalog containing tax-related products for corporate
                  entities
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/products:export:
    get:
      tags:
      - Products
      summary: Export all products to Excel
      description: 'Export all products from all catalogs in a space to an Excel file
        <br/> Scope: space_read'
      operationId: exportAllProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language for Excel headers (en, fr, nl, de)
        schema:
          type: string
          default: en
      - name: active
        in: query
        description: Filter by active status
        schema:
          type: boolean
      responses:
        '200':
          description: Excel file with all products
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - oauth2:
        - space_read
  /v1/spaces/{spaceId}/productCatalogs/{catalogId}/products:export:
    get:
      tags:
      - Products
      summary: Export products to Excel
      description: 'Export all products from a catalog to an Excel file with headers
        in the specified language <br/> Scope: space_read'
      operationId: exportProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language for Excel headers (en, fr, nl, de)
        schema:
          type: string
          default: en
      - name: active
        in: query
        description: Filter by active status
        schema:
          type: boolean
      responses:
        '200':
          description: Excel file with products
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product Catalog not found
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
  /v1/spaces/{spaceId}/products:generateTemplate:
    get:
      tags:
      - Products
      summary: Generate product import template
      description: "Generate an Excel template for importing products. Set multiCatalog=true
        to include 'Catalog Name' column for multi-catalog imports. <br/> Scope: space_read"
      operationId: generateProductTemplate
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language for Excel headers (en, fr, nl, de)
        schema:
          type: string
          default: en
      - name: multiCatalog
        in: query
        description: Include 'Catalog Name' column for multi-catalog import
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Excel template file
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
      security:
      - oauth2:
        - space_read
  /v1/spaces/{spaceId}/productCatalogs/{catalogId}/products:import:
    post:
      tags:
      - Products
      summary: Import products from Excel
      description: 'Import products into a catalog from an Excel file. Supports UPDATE
        (update existing only), APPEND (add new only), or UPSERT (update or create)
        modes. <br/> Scope: space_write'
      operationId: importProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: mode
        in: query
        description: 'Import mode: UPDATE, APPEND, or UPSERT (default)'
        schema:
          type: string
          default: UPSERT
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The Excel file to import
                  format: binary
      responses:
        '200':
          description: Import completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductImportResponse'
              example:
                totalRows: 100
                successfulImports: 98
                failedImports: 2
                updatedProducts: 30
                createdProducts: 68
                errorFileUrl: 
                  https://storage.googleapis.com/bucket/errors_import_20240204_143022.xlsx?X-Goog-Signature=...
                errors:
                - rowNumber: 12
                  itemName: Product X
                  errorMessage: 'Invalid category. Valid values: GOODS, SERVICE'
                - rowNumber: 47
                  itemName: Product Y
                  errorMessage: VAT percentage must be between 0 and 100
        '400':
          description: Bad Request - Invalid file or data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '422':
          description: Unprocessable Entity - File validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/products:import:
    post:
      tags:
      - Products
      summary: Import products across multiple catalogs from Excel
      description: "Import products into multiple catalogs from a single Excel file.
        Excel must include 'Catalog Name' column. <br/> Scope: space_write"
      operationId: importProductsMultiCatalog
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: mode
        in: query
        description: 'Import mode: UPDATE, APPEND, or UPSERT (default)'
        schema:
          type: string
          default: UPSERT
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The Excel file to import
                  format: binary
      responses:
        '200':
          description: Import completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductImportResponse'
              example:
                totalRows: 100
                successfulImports: 98
                failedImports: 2
                updatedProducts: 30
                createdProducts: 68
                errorFileUrl: 
                  https://storage.googleapis.com/bucket/errors_import_20240204_143022.xlsx?X-Goog-Signature=...
                errors:
                - rowNumber: 12
                  itemName: Product X
                  errorMessage: 'Invalid category. Valid values: GOODS, SERVICE'
                - rowNumber: 47
                  itemName: Product Y
                  errorMessage: VAT percentage must be between 0 and 100
        '400':
          description: Bad Request - Invalid file or data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '422':
          description: Unprocessable Entity - File validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/productCatalogs/{catalogId}/products:
    get:
      tags:
      - Products
      summary: Get products in a catalog
      description: 'Get a list of all products in a catalog <br/> Scope: space_read'
      operationId: getAllProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: search
        in: query
        description: Search term to filter out territories
        schema:
          type: string
      - name: active
        in: query
        description: Filter by active status
        schema:
          type: boolean
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          type: integer
          format: int32
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          type: integer
          format: int32
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      - name: sortBy
        in: query
        description: Sort by criteria
        schema:
          type: string
          enum:
          - name
          - name.asc
          - name.desc
          - netPrice
          - netPrice.asc
          - netPrice.desc
          - unit
          - unit.asc
          - unit.desc
          - category
          - category.asc
          - category.desc
          - vatPercentage
          - vatPercentage.asc
          - vatPercentage.desc
          - active
          - active.asc
          - active.desc
        example: name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProductResponse'
              example:
                products:
                - id: 08443048-4771-4ad4-91d4-7308cd3b6723
                  catalogId: 9e20d8ca-d4ed-4836-83df-5c62cd0245dd
                  productDetails:
                    itemName: Product 1
                    itemDescription: Product 1 description
                    itemCategory: GOODS
                  vatDetails:
                    vatPercentage: 21
                  pricingDetails:
                    itemPrice: 120.5
                    priceIndicator: GROSS
                  unit: H87
                  active: true
                  notes: Product 1 notes
                  addedDate: 2025-08-21T06:53:03.234606Z
                - id: f227a6b4-0644-411e-a340-5ef2b3f08250
                  catalogId: e7d1d7a0-938b-44b0-9247-398981a62fb0
                  productDetails:
                    itemName: Product 2
                    itemDescription: Product 2 description
                    itemCategory: SERVICE
                  vatDetails:
                    vatPercentage: 0
                  pricingDetails:
                    itemPrice: 47
                    priceIndicator: NET
                  unit: XPK
                  active: false
                  notes: Product 2 notes
                  addedDate: 2025-10-17T06:30:41.170850Z
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
    post:
      tags:
      - Products
      summary: Create product
      description: 'Create a new product in a catalog <br/> Scope: space_write'
      operationId: createProduct
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Product to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductRequest'
            example:
              productDetails:
                itemName: Product 1
                itemDescription: Product 1 description
                itemCategory: GOODS
              vatDetails:
                vatPercentage: 21
              pricingDetails:
                itemPrice: 120.5
                priceIndicator: GROSS
              unit: H87
              active: true
              notes: Product 1 notes
              catalogId: fafff479-96ee-4a3c-aa5e-399b85ad89cb
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                id: 08443048-4771-4ad4-91d4-7308cd3b6723
                catalogId: 01f6c71a-e5ed-4b6f-bd65-8c92894fa384
                productDetails:
                  itemName: Product 1
                  itemDescription: Product 1 description
                  itemCategory: GOODS
                vatDetails:
                  vatPercentage: 21
                pricingDetails:
                  itemPrice: 120.5
                  priceIndicator: GROSS
                unit: H87
                active: true
                notes: Product 1 notes
                addedDate: 2025-08-21T06:53:03.234606Z
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
    delete:
      tags:
      - Products
      summary: Delete products
      description: 'Delete multiple products by UUIDs <br/> Scope: space_write'
      operationId: deleteProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: List of product UUIDs to delete
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
        required: true
      responses:
        '204':
          description: No Content - The products were successfully deleted.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/productCatalogs/{catalogId}/products/{productId}:
    get:
      tags:
      - Products
      summary: Get product by uuid
      description: 'Get product by uuid <br/> Scope: space_read'
      operationId: getProduct
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: productId
        in: path
        description: The product identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                id: 08443048-4771-4ad4-91d4-7308cd3b6723
                catalogId: 01f6c71a-e5ed-4b6f-bd65-8c92894fa384
                productDetails:
                  itemName: Product 1
                  itemDescription: Product 1 description
                  itemCategory: GOODS
                vatDetails:
                  vatPercentage: 21
                pricingDetails:
                  itemPrice: 120.5
                  priceIndicator: GROSS
                unit: H87
                active: true
                notes: Product 1 notes
                addedDate: 2025-08-21T06:53:03.234606Z
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product or Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
    delete:
      tags:
      - Products
      summary: Delete product
      description: 'Delete product by uuid <br/> Scope: space_write'
      operationId: deleteProduct
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: productId
        in: path
        description: The product identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content - The product was successfully deleted.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product or Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
    patch:
      tags:
      - Products
      summary: Update product
      description: 'Update an existing product <br/> Scope: space_write'
      operationId: updateProduct
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: catalogId
        in: path
        description: The product catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: productId
        in: path
        description: The product identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Product data to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductRequest'
            example:
              productDetails:
                itemName: Product 1
                itemDescription: Product 1 description
                itemCategory: GOODS
              vatDetails:
                vatPercentage: 21
              pricingDetails:
                itemPrice: 120.5
                priceIndicator: GROSS
              unit: H87
              active: true
              notes: Product 1 notes
              catalogId: fafff479-96ee-4a3c-aa5e-399b85ad89cb
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                id: 08443048-4771-4ad4-91d4-7308cd3b6723
                catalogId: 01f6c71a-e5ed-4b6f-bd65-8c92894fa384
                productDetails:
                  itemName: Product 1
                  itemDescription: Product 1 description
                  itemCategory: GOODS
                vatDetails:
                  vatPercentage: 21
                pricingDetails:
                  itemPrice: 120.5
                  priceIndicator: GROSS
                unit: H87
                active: true
                notes: Product 1 notes
                addedDate: 2025-08-21T06:53:03.234606Z
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Product or Catalog not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
  /v1/spaces/{spaceId}/products:
    get:
      tags:
      - Products
      summary: Get products across all catalogs
      description: 'Get a list of all products across all catalogs in a space <br/>
        Scope: space_read'
      operationId: getFullProductList
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: search
        in: query
        description: Search term to filter products
        schema:
          type: string
      - name: active
        in: query
        description: Filter by active status
        schema:
          type: boolean
      - name: page
        in: query
        description: Zero-based page index, cannot be negative, default 0
        schema:
          type: integer
          format: int32
        example: 20
      - name: pageSize
        in: query
        description: 'Page size. Minimum 1, maximum: 200, default 20'
        schema:
          type: integer
          format: int32
        example: 20
      - name: includeTotalElements
        in: query
        description: Return the totalElements number of entries in the response
        schema:
          type: boolean
        example: true
      - name: sortBy
        in: query
        description: Sort by criteria
        schema:
          type: string
          enum:
          - name
          - name.asc
          - name.desc
          - netPrice
          - netPrice.asc
          - netPrice.desc
          - unit
          - unit.asc
          - unit.desc
          - category
          - category.asc
          - category.desc
          - vatPercentage
          - vatPercentage.asc
          - vatPercentage.desc
          - active
          - active.asc
          - active.desc
        example: name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProductResponse'
              example:
                products:
                - id: 08443048-4771-4ad4-91d4-7308cd3b6723
                  catalogId: 9e20d8ca-d4ed-4836-83df-5c62cd0245dd
                  productDetails:
                    itemName: Product 1
                    itemDescription: Product 1 description
                    itemCategory: GOODS
                  vatDetails:
                    vatPercentage: 21
                  pricingDetails:
                    itemPrice: 120.5
                    priceIndicator: GROSS
                  unit: H87
                  active: true
                  notes: Product 1 notes
                  addedDate: 2025-08-21T06:53:03.234606Z
                - id: f227a6b4-0644-411e-a340-5ef2b3f08250
                  catalogId: e7d1d7a0-938b-44b0-9247-398981a62fb0
                  productDetails:
                    itemName: Product 2
                    itemDescription: Product 2 description
                    itemCategory: SERVICE
                  vatDetails:
                    vatPercentage: 0
                  pricingDetails:
                    itemPrice: 47
                    priceIndicator: NET
                  unit: XPK
                  active: false
                  notes: Product 2 notes
                  addedDate: 2025-10-17T06:30:41.170850Z
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Space not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
  /v1/spaces/{spaceId}/productCatalogs/{sourceCatalogId}/products:move:
    post:
      tags:
      - Products
      summary: Move products between catalogs
      description: 'Move products from one catalog to another <br/> Scope: space_write'
      operationId: moveProducts
      parameters:
      - name: spaceId
        in: path
        description: The space unique identifier. (A UUID specified by RFC4122).
        required: true
        schema:
          type: string
          format: uuid
      - name: sourceCatalogId
        in: path
        description: Source catalog identifier
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Move products request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveProductsRequest'
            example:
              targetCatalogId: 00000000-0000-0000-0000-000000000002
              productIds:
              - 10000000-0000-0000-0000-000000000001
              - 10000000-0000-0000-0000-000000000002
        required: true
      responses:
        '200':
          description: OK - Products were successfully moved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoveProductsResponse'
              example:
                productsMoved: 2
                movedProductIds:
                - 10000000-0000-0000-0000-000000000001
                - 10000000-0000-0000-0000-000000000002
                sourceCatalogId: 00000000-0000-0000-0000-000000000001
                targetCatalogId: 00000000-0000-0000-0000-000000000002
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Catalog or Products not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
components:
  schemas:
    ProductCatalog:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the product catalog
          format: uuid
        spaceId:
          type: string
          description: Space identifier associated with the product catalog
          format: uuid
        name:
          type: string
          description: Name of the product catalog
          example: Electronics Catalog
        description:
          type: string
          description: Description of the product catalog
          example: A catalog containing all electronic products
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    ProductCatalogRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the product catalog
          example: Electronics Catalog
        description:
          type: string
          description: Description of the product catalog
          example: A catalog containing all electronic products
    ListProductCatalogResponse:
      type: object
      properties:
        productCatalogs:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalog'
    ImportError:
      type: object
      properties:
        rowNumber:
          type: integer
          description: Row number in Excel file
          format: int32
        itemName:
          type: string
          description: Product name
        errorMessage:
          type: string
          description: Error message
      description: List of import errors
    ProductImportResponse:
      type: object
      properties:
        totalRows:
          type: integer
          description: Total number of rows in the Excel file
          format: int32
        successfulImports:
          type: integer
          description: Number of successfully imported products
          format: int32
        failedImports:
          type: integer
          description: Number of failed imports
          format: int32
        updatedProducts:
          type: integer
          description: Number of products updated
          format: int32
        createdProducts:
          type: integer
          description: Number of products created
          format: int32
        errors:
          type: array
          description: List of import errors
          items:
            $ref: '#/components/schemas/ImportError'
        errorFileUrl:
          type: string
          description: Signed URL to download Excel file with failed rows (expires
            in 60 minutes)
    PricingDetails:
      type: object
      properties:
        itemPrice:
          type: number
          description: Price of the item
          format: double
        priceIndicator:
          type: string
          description: Price indicator (NET or GROSS)
      description: Product pricing details
    Product:
      type: object
      properties:
        id:
          type: string
          description: Product unique identifier
          format: uuid
        catalogId:
          type: string
          description: Catalog unique identifier
          format: uuid
        productDetails:
          $ref: '#/components/schemas/ProductDetails'
        vatDetails:
          $ref: '#/components/schemas/VatDetails'
        pricingDetails:
          $ref: '#/components/schemas/PricingDetails'
        unit:
          type: string
          description: Unit of measurement
        notes:
          type: string
          description: Additional notes
        active:
          type: boolean
          description: Product active status
        addedDate:
          type: string
          description: Date when the product was added
          format: date-time
    ProductDetails:
      type: object
      properties:
        itemName:
          type: string
          description: Name of the item
        itemDescription:
          type: string
          description: Description of the item
        itemCategory:
          type: string
          description: Category of the item
      description: Product details
    VatDetails:
      type: object
      properties:
        vatPercentage:
          type: number
          description: VAT percentage
          format: double
      description: Product VAT details
    PriceIndicator:
      type: string
      description: Specifies whether the product price is net or gross.
      example: NET
      enum:
      - NET
      - GROSS
    PricingDetailsRequest:
      type: object
      properties:
        itemPrice:
          type: number
          description: Price of the item
          format: double
        priceIndicator:
          $ref: '#/components/schemas/PriceIndicator'
      description: Product pricing details
    ProductCategory:
      type: string
      description: Specifies the product category type.
      example: GOODS
      enum:
      - GOODS
      - SERVICE
    ProductDetailsRequest:
      type: object
      properties:
        itemName:
          type: string
          description: Name of the item
        itemDescription:
          type: string
          description: Description of the item
        itemCategory:
          $ref: '#/components/schemas/ProductCategory'
      description: Product details
    ProductRequest:
      type: object
      properties:
        productDetails:
          $ref: '#/components/schemas/ProductDetailsRequest'
        vatDetails:
          $ref: '#/components/schemas/VatDetailsRequest'
        pricingDetails:
          $ref: '#/components/schemas/PricingDetailsRequest'
        unit:
          type: string
          description: Unit of measurement
        active:
          type: boolean
          description: Product active status
        notes:
          type: string
          description: Additional notes
        catalogId:
          type: string
          description: Optional target catalog ID if moving the product to another
            catalog
    VatDetailsRequest:
      type: object
      properties:
        vatPercentage:
          type: number
          description: VAT percentage
          format: double
      description: Product VAT details
    ListProductResponse:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        totalElements:
          type: integer
          description: Total number of items in the database that correspond to this
            search criteria
          format: int64
        currentPage:
          type: integer
          description: Current page
          format: int32
        pageSize:
          type: integer
          description: Response page size
          format: int32
    MoveProductsResponse:
      type: object
      properties:
        productsMoved:
          type: integer
          description: Number of products successfully moved
          format: int32
        movedProductIds:
          type: array
          description: List of moved product IDs
          items:
            type: string
            description: List of moved product IDs
        sourceCatalogId:
          type: string
          description: Source catalog ID
        targetCatalogId:
          type: string
          description: Target catalog ID
    MoveProductsRequest:
      type: object
      properties:
        targetCatalogId:
          type: string
          description: Target catalog identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        productIds:
          type: array
          description: List of product IDs to move
          items:
            type: string
            description: List of product IDs to move
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.cve.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
