openapi: 3.1.0
info:
  title: UPowr Quote API
  version: 1.0.0
servers:
  - url: /api/v1/quotes
security:
  - session: []
paths:
  /{quoteId}/accept:
    post:
      summary: Accept a Quote
      description: >-
        Accept a Quote on behalf of a customer - this will trigger the
        order/installation process for the project as long as the contract has
        been accepted. A quote must have been approved before it can be
        accepted. If approval is required use the /{quoteId}/approve endpoint
        instead and set the accept flag to true. Do *not* use this to accept
        quotes that are Awaiting External Approval.
      operationId: acceptQuote
      security:
        - session:
            - quote:accept
      parameters:
        - $ref: '#/components/parameters/quoteId'
      responses:
        '200':
          description: Successfully accepted quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        '500':
          description: Error accepting quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
  /{quoteId}/approve:
    post:
      summary: Approve a Quote
      description: >-
        Approve a Quote for publishing to a customer and optionally Accept on
        behalf of the customer. Use of the optional Acceptance will also accept
        the contract and void all other quotes, and then trigger the
        Order/Installation process. When using this flag the API will return
        before Acceptance happens so you will need to listen for Quote.Accepted
        and the other events to know when the Order is ready. Use this for
        quotes that are Awaiting External Approval.
      operationId: approveQuote
      security:
        - session:
            - quote:approve
      parameters:
        - $ref: '#/components/parameters/quoteId'
        - name: accept
          in: query
          description: >-
            Whether to accept the quote as well (this will mean all other quotes
            for the project are rejected regardless of state)
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Successfully approved quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        '500':
          description: Error approving quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
  /{quoteId}/reject:
    post:
      summary: Reject a Quote
      description: Reject a Quote
      operationId: rejectQuote
      security:
        - session:
            - quote:reject
      parameters:
        - $ref: '#/components/parameters/quoteId'
      responses:
        '200':
          description: Successfully rejected quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        '500':
          description: Error rejecting quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
  /{quoteId}/void:
    post:
      summary: Void a Quote
      description: Void a Quote
      operationId: voidQuote
      security:
        - session:
            - quote:void
      parameters:
        - $ref: '#/components/parameters/quoteId'
        - name: customerId
          in: query
          description: The unique identifier for an existing customer.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully void quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        '500':
          description: Error voiding quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
  /{quoteId}/request-external-approval:
    post:
      summary: Request external approval
      description: Request external approval
      operationId: requestExternalApproval
      security:
        - session:
            - quote:request-external-approval
      parameters:
        - $ref: '#/components/parameters/quoteId'
      responses:
        '200':
          description: Successfully requested approval
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        '500':
          description: Error rejecting quote
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
  /{quoteId}/files/{fileCode}:
    put:
      summary: Replace a quote file
      description: Replace a quote file
      operationId: replaceQuoteFile
      security:
        - session:
            - quote:file:update
      parameters:
        - $ref: '#/components/parameters/quoteId'
        - name: fileCode
          in: path
          description: The name of the file to replace
          required: true
          schema:
            type: string
            enum:
              - single_line_diagram
              - system_design
              - design_markup
              - customer_design_markup
              - quote
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successfully replaced quote file
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Error replacing quote file
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
components:
  parameters:
    quoteId:
      name: quoteId
      in: path
      description: The quote ID
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    session:
      type: oauth2
      description: Machine-to-Machine Authorization
      flows:
        clientCredentials:
          tokenUrl: https://id.core.upowr.cloud/oauth/token
          scopes:
            quote:accept: Accept a Quote
            quote:reject: Reject a Quote
            quote:void: Void a Quote
            quote:request-external-approval: Request external approval
            quote:file:update: Replace a quote file
