DealHub Asynchronous Operations API

openapi: 3.2.0
info:
  title: Version Asynchronous Operations API
  description: 'This API provides a comprehensive set of services for managing versions and the associated product catalog within the DealHub CPQ system. It allows for system-to-system integration to get, create, duplicate, activate, and manage the content of versions.


    Several operations, such as duplicating, activating, and uploading a product catalog, are asynchronous. These endpoints return a `request_id` for tracking.


    All requests require a secret Bearer Token in the `Authorization` header, which is generated by a CPQ administrator.'
  version: 1.0.0
servers:
- url: https://api.dealhub.io
  description: The base URL for your DealHub instance.
  variables:
    your-dealhub-instance:
      default: app
      description: Your specific DealHub instance name (e.g., 'app', 'service-eu1').
security:
- bearerAuth: []
tags:
- name: Asynchronous Operations
  description: Endpoints for tracking the status of asynchronous requests.
paths:
  /api/v1/request/{request_id}/status:
    get:
      tags:
      - Asynchronous Operations
      summary: Get Asynchronous Request Status
      description: Polls and retrieves the current status of a specific asynchronous request (e.g., duplicate version, activate version).
      operationId: getAsyncRequestStatus
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The ID of the asynchronous request.
      responses:
        '200':
          description: Success. Returns the current status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatus'
              examples:
                requestStatusExample:
                  summary: Example of a completed request status
                  value:
                    request_id: 4D114DAD97
                    status: done
                    error_description: ''
                    error_code: null
  /api/v1/request/{request_id}/summary:
    get:
      tags:
      - Asynchronous Operations
      summary: Get Asynchronous Request Execution Summary
      description: Retrieves a summary of a completed asynchronous process, including success, error, and warning counts. This is particularly useful for operations like product catalog uploads.
      operationId: getAsyncRequestSummary
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The ID of the asynchronous request.
      responses:
        '200':
          description: Success. Returns the execution summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestSummaryResponse'
              examples:
                requestSummaryExample:
                  summary: Example of a request summary with warnings
                  value:
                    status: Completed
                    summary:
                      success_count: 1
                      errors_count: 0
                      warnings:
                      - 'Missing currency in price item for SKU KY014X, using default currency: USD'
                      errors: []
components:
  schemas:
    RequestSummaryResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - In Progress
          - Completed
          - Error
          description: The status of the asynchronous request.
        summary:
          $ref: '#/components/schemas/RequestSummary'
    RequestSummary:
      type: object
      properties:
        success_count:
          type: integer
          description: The number of successfully processed records.
        errors_count:
          type: integer
          description: The number of records that could not be processed.
        warnings:
          type: array
          items:
            type: string
            description: List of warnings that occurred during execution.
        errors:
          type: array
          items:
            type: string
          description: List of errors that occurred during execution.
    RequestStatus:
      type: object
      properties:
        request_id:
          type: string
          description: ID of the asynchronous request.
        status:
          type: string
          enum:
          - in-progress
          - done
          - failed
          - queued
          description: Status of the asynchronous request.
        error_description:
          type: string
          description: Description of the error if the status is 'failed'.
        error_code:
          type: string
          description: Code of the error if the status is 'failed'.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A secret token generated by a CPQ administrator.