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/sonata/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 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: Unique identifier of the Product Specification type: string required: - id QuotePrice: description: Description of price and discount awarded type: object properties: unitOfMeasure: description: >- Unit of Measure if price depending on it (Gb, SMS volume, etc..) Mplify: if Quote Item Price Type equals usageBased type: string price: description: The associated price $ref: '#/components/schemas/Price' name: description: Name of the quote/quote item price type: string priceType: description: >- Indicates if the price is for recurring, non-recurring, or usage based charges $ref: '#/components/schemas/MEFPriceType' description: description: Description of the quote/quote item price type: string recurringChargePeriod: description: Used for a recurring charge to indicate a period $ref: '#/components/schemas/Duration' required: - name - price - priceType RelatedPlaceRefWithSubUnit: description: >- Allows pointing to a place by referring to a GeographicAddress, GeographicSite. type: object properties: place: description: A place described by reference to Geographic Address or Geographic Site. $ref: '#/components/schemas/PlaceRef' 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. It MUST only be used together with GeographicAddressRef type: array items: $ref: '#/components/schemas/SubUnit' required: - place - role SubUnit: description: Allows for sub unit identification type: object properties: subUnitNumber: description: >- The discriminator used for the subunit, often just a simple number but may also be a range. type: string subUnitType: description: >- The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF. type: string required: - subUnitNumber - subUnitType TimeUnit: description: | Represents a unit of time. type: string enum: - seconds - minutes - businessHours - calendarHours - businessDays - calendarDays - months - years