openapi: 3.0.1 info: title: Product Offering Qualification Notification 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: - Send POQ Notifications 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/cantata/productOfferingQualificationNotification/v8/ variables: serverBase: description: The base of Buyer's URL. default: mplify.net tags: - name: Notification listeners description: | The Buyer's endpoint to send particular event types notifications to. paths: /listener/poqStateChangeEvent: post: tags: - Notification listeners summary: Product Offering Qualification Change Notification endpoint description: This endpoint is used to receive notifications on POQ state change operationId: poqStateChangeEvent 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: The event body content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/PoqStateChangeEvent' required: true 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' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' deprecated: false /listener/poqItemStateChangeEvent: post: tags: - Notification listeners summary: Poq Item State Change Notification endpoint description: | This endpoint is used to receive notifications on Poq Item state change operationId: listenToPoqItemStateChangeEvent 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: content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/PoqItemStateChangeEvent' required: true 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' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' deprecated: false components: schemas: 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 more 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: description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)' allOf: - $ref: '#/components/schemas/Error' - type: object 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 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. (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: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users type: string enum: - accessDenied - forbiddenRequester - tooManyUsers Error500: description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. type: string enum: - internalError required: - code Event: description: >- Event class is used to describe information structure used for notification. type: object properties: eventId: description: Id of the event type: string eventTime: description: Date-time when the event occurred type: string format: date-time eventType: description: The type of the notification. type: string event: description: The event linked to the involved resource object type: object required: - event - eventId - eventTime - eventType MEFPOQItemTaskStateType: description: | POQ item states - The specific states are managed by the Seller based on its processing and/or based on the Buyer's action. | MEFPOQItemTaskStateType | Mplify 79.1 | Description | | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | acknowledged | ACKNOWLEDGED | A request has been received by the Seller and has passed basic validation. For an Immediate response, the POQ moves directly to `done` state and does not pass through `acknowledged`. | | inProgress | IN_PROGRESS | The Seller is working on a POQ item response and the answer is not ready yet | | done.abandoned | ABANDONED | Applied to a POQ Item in case the final state is not reached and POQ is moved to the final state other than `done` | | done | READY | The POQ Item has been internally approved by the Seller. This state does not imply that Seller is able to deliver requested item. It only means that the response for this POQ Item is complete. | | rejected | REJECTED | A POQ Item has failed the business validation checks the Seller performs after it reached the `acknowledged` state. | | terminatedWithError | UNABLE_TO_MEET_TIME | The Seller is unable to provide a POQ Item response in the timeframe required by the Buyer (e.g., if an immediate response or a response date is set but cannot be met by the Seller). When a POQ Item goes to `terminatedWithError`, all POQ Items that are not `done` move to `done.abandoned`. | type: string enum: - acknowledged - inProgress - done.abandoned - done - rejected - terminatedWithError MEFPOQTaskStateType: description: | These values represent the valid states through which the product offering qualification can transition. The following mapping has been used between `MEFPOQTaskStateType` and Mplify 79.1: | MEFPOQTaskStateType | Mplify 79.1 | Description | | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | acknowledged | ACKNOWLEDGED | A request has been received by the Seller, has passed basic validation and the id was assigned. For an Immediate response, the POQ moves directly to the `done` state and does not pass through `acknowledged`. | | inProgress | IN_PROGRESS | The POQ is currently being worked by the Seller. | | done | READY | The POQ has been internally approved by the Seller. Reached when all items are in `done` state. It does not imply that the Seller can deliver all POQ Items in this POQ. It only means that the POQ has been completed. | | rejected | REJECTED | A POQ was submitted, and it has failed at least one of the business validation checks the Seller performs after it reached the `acknowledged` state. | | terminatedWithError | UNABLE_TO_MEET_TIME | The Seller is unable to provide a response in the timeframe required by the Buyer (e.g., if an immediate response or a response date is set but cannot be met by the Seller). | type: string enum: - acknowledged - inProgress - done - rejected - terminatedWithError PoqItemStateChangeEvent: allOf: - $ref: '#/components/schemas/Event' - description: PoqItemStateChangeEvent structure type: object properties: eventType: description: Indicates the type of product offering qualification event. type: string enum: - poqItemStateChangeEvent event: description: | A reference to the POQ that is source of the notification. $ref: '#/components/schemas/PoqItemStateChangeEventPayload' required: - event - eventType PoqItemStateChangeEventPayload: description: A reference to the POQ that is the source of the notification. type: object properties: id: description: The POQ unique identifier. type: string href: description: Link to the POQ type: string poqItemId: description: >- ID of the Poq Item (within the Poq) which state change triggered the event type: string state: description: The state reached at change date $ref: '#/components/schemas/MEFPOQItemTaskStateType' required: - id - poqItemId - state PoqStateChangeEvent: allOf: - $ref: '#/components/schemas/Event' - description: PoqStateChangeEvent structure type: object properties: eventType: description: Indicates the type of product offering qualification event. type: string enum: - poqStateChangeEvent event: description: | A reference to the POQ that is source of the notification. $ref: '#/components/schemas/PoqStateChangeEventPayload' required: - event - eventType PoqStateChangeEventPayload: description: A reference to the POQ that is the source of the notification. type: object properties: id: description: The POQ unique identifier. type: string href: description: Link to the POQ type: string state: description: The state reached at change date $ref: '#/components/schemas/MEFPOQTaskStateType' required: - id - state