MEF LSO Cantata Product Offering Availability And Pricing Discovery Management

openapi: 3.0.1
info:
  title: Product Offering Availability And Pricing Discovery Management
  description: |
    **This file forms part of Mplify 160**
     
    **This API implements Business Requirements described in Mplify 110**

    Product Offering Availability Discovery is a way for the Buyer to specify a
    Product Specification to the Seller and to receive from the Seller a list
    of zero or more Product Configurations.

    Pricing Discovery allows the Buyer to receive from the Seller a list of
    one or more terms and pricing information for the Product Configuration
    specified by the Buyer.

    The following use cases are managed: 

    - Retrieve Product Offering Availability
    - Retrieve Pricing and Terms
  version: 4.0.0
servers:
  - url: >-
      https://{serverBase}/mefApi/cantata/productOfferingAvailabilityAndPricingDiscovery/v4/
    variables:
      serverBase:
        description: The base of Seller's URL.
        default: mef.net
tags:
  - name: Product Offering Availability
  - name: Pricing Discovery
paths:
  /productOfferingAvailability:
    post:
      tags:
        - Product Offering Availability
      summary: >-
        The Buyer requests a list of available Product Offering Configurations
        from the Seller for a specific Product Specification within the
        specified Delivery Context. The Seller responds to the Buyer with a list
        of Product Configurations meeting the Buyer's criteria and the
        Installation Interval for each of these. Each Product Configuration has
        a unique identifier that is passed to the Buyer by the Seller. This
        identifier is used to Retrieve Pricing and Terms.
      operationId: productOfferingAvailabilityRequest
      parameters:
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as a 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
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOfferingAvailability_Request'
        required: true
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOfferingAvailability'
        '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'
  /pricingDiscovery:
    post:
      tags:
        - Pricing Discovery
      summary: >-
        The Buyer requests a list of Pricing and Terms from the Seller for a
        specific Product Configuration Identifier within a specific Delivery
        Context. The Seller responds to the Buyer with a list of Pricing and
        Terms.
      operationId: pricingDiscoveryRequest
      parameters:
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as a 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
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/PricingDiscovery_Request'
        required: true
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/PricingDiscovery'
        '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'
components:
  schemas:
    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:
      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. 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:
                - 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
    Error422:
      description: >-
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: |
                One of the following error codes:
                  - missingProperty: The property the Seller has expected is not present in the payload
                  - invalidValue: The property has an incorrect value
                  - invalidFormat: The property value does not comply with the expected value format
                  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system
                  - unexpectedProperty: Additional property, not expected by the Seller has been provided
                  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.
                  - otherIssue: Other problem was identified (detailed information provided in a reason)
              $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
          required:
            - code
    Error422Code:
      description: |
        One of the following error codes:
          - missingProperty: The property the Seller has expected is not present in the payload
          - invalidValue: The property has an incorrect value
          - invalidFormat: The property value does not comply with the expected value format
          - referenceNotFound: The object referenced by the property cannot be identified in the Seller system
          - unexpectedProperty: Additional property, not expected by the Seller has been provided
          - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.
          - otherIssue: Other problem was identified (detailed information provided in a reason)
      type: string
      enum:
        - missingProperty
        - invalidValue
        - invalidFormat
        - referenceNotFound
        - unexpectedProperty
        - tooManyRecords
        - otherIssue
    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
    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
    GeographicSiteRef:
      description: >
        A reference to a Geographic Site resource available through Service Site
        API
      type: object
      properties:
        href:
          description: >
            Hyperlink to the referenced Site. 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 Site.
          type: string
        '@type':
          description:
            Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
            - GeographicSiteRef
      required:
        - '@type'
        - id
    MEFEndOfTermAction:
      description: |
        The action that needs to be taken by the Seller once the term expires.

        | Value          | Description                                                                                                            |
        | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
        | roll           | The Product's contract will continue on a rolling basis once the contract's current term expires                       |
        | autoDisconnect | The Product will automatically be disconnected (and contract terminated) by the Seller once the contract term expires  |
        | autoRenew      | The Product's contract will be renewed for another term equivalent to the original contract term.                      |
      type: string
      enum:
        - roll
        - autoDisconnect
        - autoRenew
    MEFItemTerm:
      description: Describes a term
      type: object
      properties:
        name:
          description: Name of the term
          type: string
        description:
          description: Description of the term
          type: string
        duration:
          description: Duration of the term
          $ref: '#/components/schemas/Duration'
        endOfTermAction:
          description: The action the Seller will take once the term expires.
          $ref: '#/components/schemas/MEFEndOfTermAction'
        rollInterval:
          description: >-
            The period that the Buyer is required to commit to pay in a
            recurring fashion at the end of the term to extend the term. If
            `endOfTermAction` is equal to `roll` then `rollInterval` MUST be
            specified. If `endOfTermAction` is equal to `autoRenew` or
            `autoDisconnect`, then `rollInterval` MUST NOT be specified.
          $ref: '#/components/schemas/Duration'
      required:
        - duration
        - endOfTermAction
        - name
    MEFPriceType:
      description:
        Indicates if the price is for recurring or non-recurring charges.
      type: string
      enum:
        - recurring
        - nonRecurring
        - usageBased
    MEFProductConfiguration:
      description: >-
        MEFProductConfiguration is used as an extension point for MEF specific
        product/service payload. The `@type` attribute is used as a
        discriminator
      type: object
      properties:
        '@type':
          description: >-
            The name of the type that uniquely identifies the type of the
            product that is the subject of the POQ Request. In the case of MEF
            product this is the URN provided in the Product Specification.
          type: string
      required:
        - '@type'
      discriminator:
        propertyName: '@type'
    Money:
      description: A base/value business entity used to represent money
      type: object
      properties:
        unit:
          description:
            Currency (ISO4217 norm uses 3 letters to define the currency)
          type: string
        value:
          description: A positive floating point number
          type: number
          format: float
      required:
        - unit
        - value
    PlaceRef:
      description: >-
        A place described by reference to Geographic Address or Geographic Site.
      type: object
      discriminator:
        propertyName: '@type'
        mapping:
          GeographicAddressRef: '#/components/schemas/GeographicAddressRef'
          GeographicSiteRef: '#/components/schemas/GeographicSiteRef'
      oneOf:
        - $ref: '#/components/schemas/GeographicAddressRef'
        - $ref: '#/components/schemas/GeographicSiteRef'
    Price:
      description: >-
        Provides all amounts (tax included, duty-free, tax rate), used currency
        and percentage to apply for Price Alteration.
      type: object
      properties:
        taxRate:
          description:
            'Price Tax Rate. Unit: [%]. E.g. value 16 stand for 16% tax.'
          type: number
          format: float
        taxIncludedAmount:
          description:
            All taxes included amount (expressed in the given currency)
          $ref: '#/components/schemas/Money'
        dutyFreeAmount:
          description:
            All taxes excluded amount (expressed in the given currency)
          $ref: '#/components/schemas/Money'
      required:
        - dutyFreeAmount
    PricingAndTerm:
      description: >-
        An option for price and term available to a Buyer for a Product
        Configuration with a specific Delivery Context
      properties:
        identifier:
          description: The identifier of the Pricing and Term.
          type: string
        installationInterval:
          description: >
            The indicative duration >=0 for the delivery of the configuration in
            the specified Delivery Context when manual work is required. The
            shortest interval is specified by the Seller. It is not considered a
            commitment by the Seller. A value of 0 indicates immediate
            installation.
          $ref: '#/components/schemas/Duration'
        term:
          description: >-
            The minimum length of the commitment for this PricingAndTerm for the
            given `productOfferingConfigurationIdentifier` within the requested
            Delivery Context.
          $ref: '#/components/schemas/MEFItemTerm'
        price:
          description: >-
            The prices that apply to this PricingAndTerm for the given Product
            Offering Configuration within the requested Delivery Context.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/QuotePrice'
        subjectToAdditionalNonrecurringCharges:
          description: >-
            An indicator to inform the Buyer that additional non-recurring
            charges may be added during fulfillment.
          type: boolean
      required:
        - identifier
        - installationInterval
        - price
        - subjectToAdditionalNonrecurringCharges
        - term
    PricingDiscovery:
      allOf:
        - $ref: '#/components/schemas/PricingDiscovery_Request'
        - description: >-
            PricingDiscovery allows the Seller to provide the list of Pricing
            and Terms matching action, delivery context, and Product
            Configuration Identifier provided by the Buyer
          type: object
          properties:
            pricingAndTerm:
              description: >-
                A set of contract terms and corresponding prices available for a
                given Product Configuration considering the Delivery Context.
              type: array
              items:
                $ref: '#/components/schemas/PricingAndTerm'
          required:
            - pricingAndTerm
    PricingDiscovery_Request:
      description: >-
        A set of attributes common to PricingDiscovery_Request and
        PricingDiscovery
      type: object
      properties:
        action:
          description: >-
            The action to be performed by the Seller to fulfill any Order that
            results from this interaction.
          $ref: '#/components/schemas/ProductActionAddModifyType'
        productOfferingConfigurationIdentifier:
          description: >
            The identifier for the Product Offering Configuration that the
            Pricing Discovery is being requested for.
          type: string
        productRef:
          description: >-
            A reference to a Product in the Product Inventory. It MUST NOT be
            provided when the `action` = `add`. It MUST be provided when the
            `action` = `modify`.
          $ref: '#/components/schemas/ProductRef'
        productRelationship:
          description: >-
            A list of Product Relationships as defined by the Product
            Specification. It MUST be provided when the `action` = `add`. It
            MUST NOT be provided when the `action` = `modify`
          type: array
          items:
            $ref: '#/components/schemas/ProductRelationship'
        place:
          description: >-
            A list of Geographic Addresses or Sites and their roles with
            relation to the Product. It MUST be provided when the `action` =
            `add`. It MUST NOT be provided when the `action` = `modify`
          type: array
          items:
            $ref: '#/components/schemas/RelatedPlaceRefWithSubUnit'
      required:
        - action
        - productOfferingConfigurationIdentifier
    ProductActionAddModifyType:
      description: |
        Action to be performed on the Product.

        The following mapping has been used between `ProductActionType` and Mplify
        110:

        | ProductActionType | Mplify 110    |
        |------------------ | ---------- |
        | add               | INSTALL    |
        | modify            | CHANGE     |
      type: string
      enum:
        - add
        - modify
    ProductOfferingAvailability:
      description: >-
        Product Offering Availability allows the Seller to provide a list of
        Product Offering Configurations matching action, delivery context and
        Product Specification provided by the Buyer
      allOf:
        - $ref: '#/components/schemas/ProductOfferingAvailability_Request'
        - type: object
          properties:
            availableProductOfferingConfiguration:
              description: The list of available Product Offering Configurations
              type: array
              minItems: 0
              items:
                $ref: '#/components/schemas/ProductOfferingConfiguration'
          required:
            - availableProductOfferingConfiguration
    ProductOfferingAvailability_Request:
      description: >
        Product Offering Availability Request allows the Buyer to provide the
        action, delivery context, and Product Specification to ask the Seller to
        provide a list of available Product Offering Configurations.
      type: object
      properties:
        action:
          description: >-
            The action to be performed by the Seller to fulfill any Product
            Order that results from this interaction.
          $ref: '#/components/schemas/ProductActionAddModifyType'
        productSpecification:
          description: >-
            A reference to a Product Specification used to describe the Product.
            This MUST be provided when the `action` is `add`. It MUST NOT be
            provided when the `action` = `modify`
          $ref: '#/components/schemas/ProductSpecificationRef'
        productRef:
          description: >
            A reference to a Product in the Product Inventory. It MUST NOT be
            provided when the `action` = `add`. It MUST be provided when the
            `action` = `modify`.
          $ref: '#/components/schemas/ProductRef'
        productRelationship:
          description: >-
            A list of Product Relationships as defined by the Product
            Specification. It MUST be provided when the `action` = `add`. It
            MUST NOT be provided when the `action` = `modify`
          type: array
          items:
            $ref: '#/components/schemas/ProductRelationship'
        place:
          description: >-
            A list of Geographic Addresses or Sites and their roles in relation
            to the Product. It MUST be provided when the `action` = `add`. It
            MUST NOT be provided when the `action` = `modify`
          type: array
          items:
            $ref: '#/components/schemas/RelatedPlaceRefWithSubUnit'
      required:
        - action
    ProductOfferingConfiguration:
      description: >-
        Allows the Seller to provide detailed information of the Product
        Configuration matching Buyer's Product Offering Availability Request.
      type: object
      properties:
        productOffering:
          description: >
            The identifier of the Product Offering for which this Product
            Configurationn is valid.
          $ref: '#/components/schemas/ProductOfferingRef'
        productConfiguration:
          description: >-
            The set of technical attributes for the Product Offering that make
            this configuration unique. This essentially specifies the values for
            attributes defined in the Product Offering.
          $ref: '#/components/schemas/MEFProductConfiguration'
        productOfferingConfigurationIdentifier:
          description: >
            An identifier of the returned `productConfiguration` that can be
            used in the next step for Pricing Discovery
          type: string
        installationInterval:
          description: >
            The indicative duration (>=0) for the delivery of the configuration
            in the specified Delivery Context. The shortest possible interval is
            specified by the Seller. It is not considered a commitment by the
            Seller.
          $ref: '#/components/schemas/Duration'
      required:
        - installationInterval
        - productConfiguration
        - productOffering
        - productOfferingConfigurationIdentifier
    ProductOfferingRef:
      description:
        A reference to a Product Offering offered by the Seller to the Buyer.
      type: object
      properties:
        href:
          description: >
            Hyperlink to a Product Offering in the Seller catalog. In case the
            Seller is not providing a catalog API this field is not used. The
            catalog is provided by the Seller to the Buyer during onboarding.
            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: >-
            id of a Product Offering. It is assigned by the Seller. The Buyer
            and the Seller exchange information about offerings' ids during the
            onboarding process.
          type: string
      required:
        - id
    ProductRef:
      description: A reference to a Product in the Product Inventory
      type: object
      properties:
        id:
          description: Unique identifier of a Product
          type: string
        href:
          description: >-
            Hyperlink to a Product instance in Sellers Product Inventory.
            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
      required:
        - id
    ProductRelationship:
      description: >-
        A relationship to an existing Product. The requirements for usage for
        given Product are described 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
    ProductSpecificationRef:
      description: >-
        A reference to a structured set of well-defined technical attributes
        and/or behaviors that are used to construct a Product Offering for sale
        to a market.
      type: object
      properties:
        href:
          description: >
            Hyperlink to a Product Specification in the seller's catalog. In
            case Sell

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-product-offering-availability-and-pricing-discovery-openapi.yml