MEF LSO Sonata Product Offering Qualification Management

openapi: 3.0.1
info:
  title: Product Offering Qualification Management
  description: >
    **This file forms part of Mplify 87.1**
     
    This API implements Business Requirements described in Mplify 79.1

    The Product Offering Qualification (POQ) Management API allows a Buyer to

    check whether the Seller can deliver a product or set of products from

    among their product offerings at the geographic address or a service site

    specified by the Buyer; or modify a previously purchased product.


    The following use cases are managed:

    - Create Product Offering Qualification

    - Retrieve POQ List

    - Retrieve POQ by Identifier

    - Register for POQ Notifications (note: Send POQ Notification is supported
    by productOfferingQualificationNotification.api.yaml)


    Copyright 2025 Mplify Alliance and its contributors


    This file includes content based on the TM Forum Product Offering

    Qualification API (TMF679 v4.0.0) available at

    https://github.com/tmforum-apis/TMF679_ProductOfferingQualification, which

    is licensed by the TM Forum under the Apache License version 2.0. Such

    content has been modified by the Mplify Alliance and its contributors.
  version: 8.0.0
servers:
  - url: 'https://{serverBase}/mefApi/sonata/productOfferingQualification/v8/'
    variables:
      serverBase:
        description: The base of Seller's URL.
        default: mplify.net
tags:
  - name: productOfferingQualification
    description:
      Operations for managing the Product Offering Qualification request.
  - name: events subscription
    description:
      Operations for managing the subscription for events notification.
paths:
  /hub:
    post:
      tags:
        - events subscription
      summary:
        Allows a Buyer to register to receive POQ state change notifications
      description: >-
        A request initiated by the Buyer to instruct the Seller to send
        notifications of POQ create, POQ and/or POQ Item state changes if the
        Buyer has registered for these notifications. The state change
        notifications are sent only in the Deferred response scenario as in the
        Immediate response scenario once the response to the POQ Request is
        provided (create notification), there will be no further state changes.
      operationId: registerListener
      parameters:
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Buyer. MUST be specified in the request when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request when the responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      requestBody:
        description: >-
          Data containing the callback endpoint to which to deliver the
          information.
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/EventSubscriptionInput'
        required: true
      responses:
        '201':
          description:
            'Created. (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: >-
            Method not implemented. Used in case Seller is not supporting
            Notification mechanism
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
  '/hub/{id}':
    get:
      tags:
        - events subscription
      summary: Retrieves a Hub by ID
      description: This operation retrieves a hub entity.
      operationId: retrieveHub
      parameters:
        - name: id
          in: path
          description: Identifier of the Hub
          required: true
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Method not implemented.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
    delete:
      tags:
        - events subscription
      summary: Unregister a listener
      description: |
        This operation is used to delete an event subscription.
      operationId: unregisterListener
      parameters:
        - name: id
          in: path
          description: Identifier of the EventSubscription
          required: true
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Buyer. MUST be specified in the request when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request when the responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      responses:
        '204':
          description:
            'No Content. (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: >-
            Method not implemented. Used in case Seller is not supporting
            Notification mechanism
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
  /productOfferingQualification:
    get:
      tags:
        - productOfferingQualification
      summary: >-
        Retrieve a list of ProductOfferingQualifications based on a set of
        criteria
      description: >-
        The Buyer requests a list of POQs from the Seller based on a set of POQ
        filter criteria. For each POQ returned, the Seller also provides a POQ
        Identifier that uniquely identifies this POQ within the Seller's system.
        The order of the elements returned to the Buyer is defined by the Seller
        (e.g. natural order) and does not change between the pages. If criteria
        for attribute X are provided, all returned items must match it.
      operationId: listProductOfferingQualification
      parameters:
        - name: state
          in: query
          description: >-
            State of the POQ to be retrieved. See `MEFPOQTaskStateType`
            definition for details
          required: false
          schema:
            type: string
            enum:
              - acknowledged
              - inProgress
              - done
              - rejected
              - terminatedWithError
        - name: creationDate.gt
          in: query
          description: Creation Date is on or after this date
          required: false
          schema:
            type: string
            format: date-time
        - name: creationDate.lt
          in: query
          description: Creation Date is on or before this date
          required: false
          schema:
            type: string
            format: date-time
        - name: requestedPOQCompletionDate.gt
          in: query
          description: POQ requested response date is on or after this date
          required: false
          schema:
            type: string
            format: date-time
        - name: requestedPOQCompletionDate.lt
          in: query
          description: POQ requested response date is on or before this date
          required: false
          schema:
            type: string
            format: date-time
        - name: externalId
          in: query
          description: >-
            ID given by the consumer and only understandable by him (to
            facilitate his searches afterward)
          required: false
          schema:
            type: string
        - name: projectId
          in: query
          description: Identifier of Buyer project associated with POQ
          required: false
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Buyer
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller
          required: false
          schema:
            type: string
        - name: offset
          in: query
          description: >-
            Requested index for the start of POQ to be provided in response
            requested by the client. Note that the index starts with "0".
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: >-
            Requested number of POQ to be provided in response requested by
            client
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          headers:
            X-Pagination-Throttled:
              description: >
                Used to indicate that the result page was throttled to maximum
                possible size  and there are additional results that can be
                fetched
              schema:
                type: boolean
            X-Total-Count:
              description: >
                The total number of matching POQ. E.g. if there are 50 matching
                items in total, but the request has offset=10 and limit=10, then
                the X-Total-Count is 50.
              schema:
                type: integer
            X-Result-Count:
              description: The number of POQ included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductOfferingQualification_Find'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: >-
            Method not implemented. Used in case Seller is not supporting
            Notification mechanism
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
    post:
      tags:
        - productOfferingQualification
      summary: Send a request to perform product offering qualification
      description: >-
        A request initiated by the Buyer to determine whether the Seller is able
        to deliver a product or set of products from among their product
        offerings, at the Buyer's location(s); or modify a previously purchased
        product. The Seller also provides estimated time intervals to complete
        these deliveries.
      operationId: createProductOfferingQualification
      parameters:
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Buyer. MUST be specified in the request when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request when the responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      requestBody:
        description: >-
          POQ content provided by the Buyer. See the definition's description
          for details.
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOfferingQualification_Create'
        required: true
      responses:
        '201':
          description:
            'Created. (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOfferingQualification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  '/productOfferingQualification/{id}':
    get:
      tags:
        - productOfferingQualification
      summary: Retrieves a ProductOfferingQualification by ID
      description: >-
        The Buyer requests the full details of a single Product Offering
        Qualification based on a POQ identifier returned from  the POQ create
        (`createProductOfferingQualification`) or POQ find
        (`listProductOfferingQualification`)
      operationId: retrieveProductOfferingQualification
      parameters:
        - name: id
          in: path
          description:
            POQ identifier (matches `ProductOfferingQualification.id`)
          required: true
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request when the responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOfferingQualification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: >-
            Method not implemented. Used in case Seller is not supporting
            Notification mechanism
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
components:
  schemas:
    AlternateProductOfferingProposal:
      description: >
        If in request the Buyer has requested to have alternate product
        proposals, then this class represents a single proposal. All properties
        are assigned by the Seller.
      type: object
      properties:
        id:
          description: >
            A unique identifier for this Alternate Product Offering Proposal
            assigned by the Seller.
          type: string
        serviceabilityConfidence:
          description: >-
            The level of confidence of the Seller to be able to service the
            request with the Alternate Product Offering. Note that this response
            is only an evaluation of the technical feasibility of delivery
            independent of when the Product Offering can be delivered. When the
            item state is `done` the Seller **MUST** provide a value. It **MUST
            NOT** be populated for other states.
          $ref: '#/components/schemas/AlternateServiceabilityColor'
        serviceabilityConfidenceReason:
          description:
            The reason for the Serviceability Confidence Reason value.
          type: string
        installationInterval:
          description: >
            The estimated minimum interval that the Seller requires in their
            standard process to complete the delivery of this product from the
            time the order is placed and any precedents have been completed.
          $ref: '#/components/schemas/Duration'
        alternateProduct:
          description: Alternate product proposal
          $ref: '#/components/schemas/MEFAlternateProduct'
        guaranteedUntilDate:
          description: |
            Date until the Seller guarantees the qualification result.
          type: string
          format: date-time
        deliveryType:
          description: >
            The mechanism used to deliver the Product to the place of its
            installation.
          $ref: '#/components/schemas/DeliveryType'
        3rdPartyProvider:
          description: >
            If the Delivery Type is `offNet*` it specifies what 3rd party
            provider is used to connect to that place of installation.
          type: string
        3rdPartyProviderProductOffering:
          description: >
            If the Delivery Type is `offNet*`, it specifies the 3rd party
            provider's offering is used to connect to that place of
            installation.
          type: string
      required:
        - alternateProduct
        - deliveryType
        - id
        - installationInterval
        - serviceabilityConfidence
    AlternateServiceabilityColor:
      description: |
        A color that indicates confidence to service the request. 

        | ServiceabilityColor      | Description                                                            |
        |------------------------- | ----------------------------------------------------------------------------- |
        | green                    |  The Seller is highly confident that they can deliver the Product Offering. It is not expected that the Seller will change this after an order is placed.           |
        | yellow                   |  The Seller is confident that they can deliver the Product Offering subject to a feasibility check. The delivery of the Product Offering is subject to checks that the Seller may not carry out until later in the pre-sales/fulfillment process. The Seller cannot be highly confident that they can deliver the Product Offering until those checks are performed. There is a possibility that the Seller may determine that they will not be able to deliver the Product Offering. |
      type: string
      enum:
        - green
        - yellow
    ContactInformation:
      description: >-
        Contact data for a person or organization that is involved in the
        product offering qualification. In a given context it is always
        specified by the Seller (e.g. Seller Contact Information) or by the
        Buyer.
      type: object
      properties:
        number:
          description: Phone number
          type: string
        emailAddress:
          description: Email address
          type: string
        postalAddress:
          description: >-
            Identifies the postal address of the person or office to be
            contacted.
          $ref: '#/components/schemas/FieldedAddressRepresentation'
        organization:
          description: The organization or company that the contact belongs to
          type: string
        name:
          description: Name of the contact
          type: string
        numberExtension:
          description: Phone number extension
          type: string
      required:
        - emailAddress
        - name
        - number
    DeliveryType:
      description: |
        The mechanism used to deliver the Product to the place of its installation.

        | Delivery Type      | Description                                                                                                                                                                                                                                                    |
        | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | offNetWithBuild    | A place does not have an existing connection to the Seller's network, but the Seller can connect via a partner who is willing to build out their network to connect to the place (refer to definition of Build). Some providers may refer to this as Near-Net. |
        | offNetWithoutBuild | A place that does not have an existing connection to the Seller's network, but the Seller can connect via a 3rd party's existing connection. This may require augmentation of additional equipment, but no Build is needed for the connection.                 |
        | onNetWithBuild     | A place that does not have an existing connection to the Seller's network, but to which the Seller is willing to build out their network to connect to the place (refer to definition of Build). Some providers may refer to this as Near-Net.                 |
        | onNetWithoutBuild  | A place that has an existing connection to the Seller's network. This may require the augmentation of additional equipment.                                                                                                                                        |
      type: string
      enum:
        - offNetWithBuild
        - offNetWithoutBuild
        - onNetWithBuild
        - onNetWithoutBuild
    Duration:
      description: 'A Duration in a given unit of time e.g. 3 hours, or 5 days.'
      type: object
      properties:
        amount:
          description: 'Duration (number of seconds, minutes, hours, etc.)'
          type: integer
          minimum: 0
        units:
          description: Time unit enumerated
          $ref: '#/components/schemas/TimeUnit'
      required:
        - amount
        - units
    Error:
      description: >
        Standard Class used to describe API response error Not intended to be
        used directly. The `code` in the HTTP header is used as a discriminator
        for the type of error returned in runtime.
      type: object
      properties:
        reason:
          description: >-
            Text that explains the reason for the error. This can be shown to a
            client user.
          type: string
          maxLength: 255
        message:
          description: >-
            Text that provides mode details and corrective actions related to
            the error. This can be shown to a client user.
          type: string
        referenceError:
          description: URL pointing to documentation describing the error
          type: string
          format: uri
      required:
        - reason
    Error400:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              description: >-
                One of the following error codes:

                - missingQueryParameter: The URI is missing a required
                query-string parameter

                - missingQueryValue: The URI is missing a required query-string
                parameter value

                - invalidQuery: The query section of the URI is invalid.

                - invalidBody: The request has an invalid body
              $ref: '#/components/schemas/Error400Code'
          required:
            - code
          type: object
      description:
        'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
    Error400Code:
      description: >-
        One of the following error codes:

        - missingQueryParameter: The URI is missing a required query-string
        parameter

        - missingQueryValue: The URI is missing a required query-string
        parameter value

        - invalidQuery: The query section of the URI is invalid.

        - invalidBody: The request has an invalid body
      type: string
      enum:
        - missingQueryParameter
        - missingQueryValue
        - invalidQuery
        - invalidBody
    Error401:
      description:
        'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)'
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: >-
                One of the following error codes:

                - missingCredentials: No credentials provided.

                - invalidCredentials: Provided credentials are invalid or
                expired
              $ref: '#/components/schemas/Error401Code'
          required:
            - code
    Error401Code:
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      type: string
      enum:
        - missingCredentials
        - invalidCredentials
    Error403:
      description: >-
        Forbidden. This code indicates that the server understood the request
        but refuses to authorize it.
        (https://tools.ietf.org/html/rfc7231#section-6.5.3)
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: |-
                This code indicates that the server understood
                the request but refuses to authorize it because
                of one of the following error codes:
                -

# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-sonata-product-offering-qualification-management-openapi.yml