MEF Product Offering Qualification API

openapi: 3.2.0
info:
  title: Mef Product Offering Qualification API
  version: 8.0.0
  description: 'Operations tagged productOfferingQualification across 2 of this provider''s published API definitions: mef-lso-cantata-product-offering-qualification-management-openapi.yml, mef-lso-sonata-product-offering-qualification-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/cantata/productOfferingQualification/v8/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
- 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.
paths:
  /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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/productOfferingQualification/v8/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
  /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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/productOfferingQualification/v8/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
components:
  schemas:
    RelatedPlaceRefOrQueryWithSubUnit:
      description: Allows pointing to a place by referring to a GeographicAddress, GeographicSite, or providing GeographicAddress by value. It also provides additional information like the `role` the place plays for given Product, `subUnit` to provide more detailed information about the precise location of the installation and `contact` needed access to this place.
      type: object
      properties:
        place:
          $ref: '#/components/schemas/PlaceRefOrQuery'
        role:
          description: Role of this place. The values that can be specified here are described by Product Specification (e.g. "INSTALL_LOCATION").
          type: string
        subUnit:
          description: A list of zero or more sub units included within the boundary of the `place` for this POQ Item. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        contact:
          description: The person to call to get access to this place in case such access is required to complete the evaluation of this POQ Item.
          type: array
          items:
            $ref: '#/components/schemas/ContactInformation'
      required:
      - place
      - role
    TimeUnit:
      description: 'Represents a unit of time.

        '
      type: string
      enum:
      - seconds
      - minutes
      - businessHours
      - calendarHours
      - businessDays
      - calendarDays
      - months
      - years
    QualificationItemRelationship:
      description: The relationship between product offering qualification items that can be used to validate business rules between POQ items.
      type: object
      properties:
        id:
          description: An identifier of the targeted POQ item within the same POQ request
          type: string
        relationshipType:
          description: 'Specifies the type (nature) of the relationship to the related Product. The nature of required relationships varies for Products of different types. For example, a UNI or ENNI Product may not have any relationships, but an Access E-Line may have two mandatory relationships (related to the UNI on one end and the ENNI on the other). More complex Products such as multipoint IP or Firewall Products may have more complex relationships. As a result, the allowed and mandatory `relationshipType` values are defined in the Product Specification.

            '
          type: string
      required:
      - id
      - relationshipType
    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 the Seller is able to deliver the 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 reaches 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
    MEFAlternateProduct:
      description: An alternative Product Offering that the Seller is proposing to the Buyer.
      type: object
      properties:
        productOffering:
          description: 'A reference to the alternate product offering.

            '
          $ref: '#/components/schemas/ProductOfferingRef'
        productConfiguration:
          description: MEFProductConfiguration is used to provide product-specific payload. The @type is used as a discriminator.
          $ref: '#/components/schemas/MEFProductConfiguration'
      required:
      - productConfiguration
      - productOffering
    ProductRelationship:
      description: A relationship to an existing Product. The requirements for usage for given Product are described in the Product Specification. When the Buyer provides multiple ProductRelationships of the same relationshipType the Seller determines if a list is supported as defined in the Product Specification.
      type: object
      properties:
        href:
          description: Hyperlink to the product in Seller's inventory that is referenced Hyperlink MAY be used when providing a response by the Seller Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request
          type: string
        id:
          description: unique identifier of the related Product
          type: string
        relationshipType:
          description: 'Specifies the type (nature) of the relationship to the related Product. The nature of required relationships varies for Products of different types. For example, a UNI or ENNI Product may not have any relationships, but an Access E-Line may have two mandatory relationships (related to the UNI on one end and the ENNI on the other). More complex Products such as multipoint IP or Firewall Products may have more complex relationships. As a result, the allowed and mandatory `relationshipType` values are defined in the Product Specification.

            '
          type: string
      required:
      - id
      - relationshipType
    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
    PlaceRefOrQuery:
      description: A place described by reference to a Geographic Address, Geographic Site or by Geographic Address Representations.
      type: object
      discriminator:
        propertyName: '@type'
        mapping:
          GeographicAddressRef: '#/components/schemas/GeographicAddressRef'
          GeographicSiteRef: '#/components/schemas/GeographicSiteRef'
          GeographicAddress_Query: '#/components/schemas/GeographicAddress_Query'
      oneOf:
      - $ref: '#/components/schemas/GeographicAddressRef'
      - $ref: '#/components/schemas/GeographicSiteRef'
      - $ref: '#/components/schemas/GeographicAddress_Query'
    GeographicAddressRef:
      description: 'A reference to a Geographic Address resource available through Address Validation API.

        '
      type: object
      properties:
        href:
          description: 'Hyperlink to the referenced Address. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request.

            '
          type: string
        id:
          description: Identifier of the referenced Geographic Address. This identifier is assigned during a successful address validation request (Geographic Address Management API)
          type: string
        '@type':
          description: Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
          - GeographicAddressRef
      required:
      - '@type'
      - id
    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
    TerminationError:
      description: This indicates an error that caused an Item to be terminated. The code and propertyPath should be used like in Error422.
      type: object
      properties:
        code:
          description: "One of the following error codes:\n  - missingProperty: The property the Seller has expected is not present in the payload\n  - invalidValue: The property has an incorrect value\n  - invalidFormat: The property value does not comply with the expected value format\n  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n  - unexpectedProperty: Additional property, not expected by the Seller has been provided\n  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n  - otherIssue: Other problem was identified (detailed information provided in a reason)\n"
          $ref: '#/components/schemas/Error422Code'
        propertyPath:
          description: 'A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used.

            Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901).

            '
          type: string
        value:
          description: Text to describe the reason of the termination.
          type: string
    ProductOfferingQualification:
      description: 'Represents a response to the Buyer''s POQ inquiry. This type defines a set of attributes that are assigned by the Seller while processing the request. A POQ response is a combination of attributes defined here with common attributes that are sent in the request. This type is used in response to an immediate request and POQ retrieval by an identifier.

        '
      allOf:
      - $ref: '#/components/schemas/ProductOfferingQualification_Common'
      - type: object
        properties:
          id:
            description: The identifier of the Product Offering Qualification that is unique within this Seller.
            type: string
          href:
            description: 'Hyperlink to this POQ. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request.

              '
            type: string
          state:
            description: The state of the qualification
            $ref: '#/components/schemas/MEFPOQTaskStateType'
          creationDate:
            description: Date when the POQ was created within the Seller's system
            type: string
            format: date-time
          expectedPOQCompletionDate:
            description: The date the Seller expects to provide qualification result. Set by the Seller in case of providing a deferred response when the POQ is in an acknowledged or inProgress state.
            type: string
            format: date-time
          productOfferingQualificationItem:
            description: One or more of Product Offering Qualification Items. It MUST contain exactly one entry for each item in the POQ request.
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/ProductOfferingQualificationItem'
          stateChange:
            description: 'A log of all state transitions for the POQ. It must be in sync with the most recent POQ Request state.

              '
            type: array
            items:
              $ref: '#/components/schemas/MEFPOQStateChange'
            minItems: 1
        required:
        - creationDate
        - id
        - productOfferingQualificationItem
        - state
        - stateChange
    ProductOfferingQualificationItem_Common:
      description: 'Common attributes shared between a POQ request and response. These attributes are provided by the Buyer and must not be modified by the Seller.

        '
      type: object
      properties:
        id:
          description: 'Id of this POQ item which is unique within the POQ. Assigned by the Buyer.

            '
          type: string
        action:
          description: The POQ Item Action associated with this POQ item. `add` means that this POQ Item being evaluated is a completely new deployment. `modify` means that this is a change to an exist-ing Product (e.g., to increase the bandwidth).
          $ref: '#/components/schemas/PoqProductActionType'
        product:
          description: 'Used by the Buyer to point to existing and/or describe the desired shape of the product. In case of `add` action - only `productConfiguration` MUST be specified. For `modify` action - both `id` and `productConfiguration` to point which product instance to update and to what state.

            '
          $ref: '#/components/schemas/MEFProductRefOrValue'
        qualificationItemRelationship:
          description: 'A list of references to related POQ items in this POQ

            '
          type: array
          items:
            $ref: '#/components/schemas/QualificationItemRelationship'
        endCustomerName:
          description: 'The name of the End Customer. The actual user of the Product that contracts for the Product with the Buyer or the Buyer''s representative.

            '
          type: string
      required:
      - action
      - id
      - product
    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
    ProductOfferingQualificationItem:
      description: An individual article included in a POQ that describes a Product of a particular type (Product Offering) being delivered to a specific geographical location. The objective is to determine if it is feasible for the Seller to deliver this item as described and for the Seller to inform the Buyer of the estimated time interval to complete this delivery.
      allOf:
      - $ref: '#/components/schemas/ProductOfferingQualificationItem_Common'
      - type: object
        properties:
          state:
            description: Current state of an item
            $ref: '#/components/schemas/MEFPOQItemTaskStateType'
          stateChange:
            description: 'A log of all state transitions for the POQ Item. It must be in sync with the most recent POQ Item''s state.

              '
            type: array
            items:
              $ref: '#/components/schemas/MEFPOQItemStateChange'
            minItems: 1
          serviceabilityConfidence:
            description: The level of confidence of the Seller to be able to service the request. When the item state is `done` the Seller **MUST** provide a value. It **MUST NOT** be populated for other states.
            $ref: '#/components/schemas/MEFServiceabilityColor'
          serviceabilityConfidenceReason:
            description: A free text description of the reason a particular Serviceability Confidence is being provided.
            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. When attribute `serviceabilityConfidence` is set to `green` or `yellow` the Seller **MUST** populate this attribute. **MUST NOT** be specified if ''state'' is ''terminatedWithError'' or `done.abandoned`.

              '
            $ref: '#/com

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-productofferingqualification-api-openapi.yml