Products

Product Types

Context

The base of the commercial offer available through apis of {{< masstack>}} and MasCatalogue is the product. Therefore, the first step is to be able to distinguish the different products offered through the {{< masstack>}} APIs. Two main types of products can be distinguished:

• Standalone products: products that are sold alone, out of the context of any bundle. In MasCatalogue API, they are referred as Commercial Products
• Bundled products: group of commercial products sold together as a bundle. In MasCatalogue API, they are referred as Bundled Products.

In addition to these two main product types, the MasCatalogue API also supports the sale of Value Added Services (VAS), whose life cycle is always bounded to the life cycle of the correspondent commercial product/bundled commercial product.

Following diagram shows MasCatalogue domain entities:

classDiagram
    MasCatalogue "1" *-- "1..*" CommercialProduct : GET /commercial_products
    MasCatalogue "1" *-- "1..*" BundledProduct : GET /bundled_products
    CommercialProduct "1" o-- "1" CommercialProductBasic : GET /commercial_products/${id}
    CommercialProduct "1" o-- "1..*" FreeUnitsPackage : GET /free_units_packages
    BundledProduct "1" o-- "1" BundledProductBasic : GET /bundled_products/${id}
    BundledProductBasic o-- CommercialProduct : compose
    BundledProductBasic .. BundleCategory : enumeration
    CommercialProductBasic "n" .. "n" BillingType : contains
    CommercialProductBasic "n" .. "1..*" Fee : contains
    FreeUnitsPackage "n" .. "1..*" Fee : contains
    FreeUnitsPackage "n" .. "1" FupTemplate : contains
    FreeUnitsPackage .. FupCategory : enumeration
    FupTemplate .. EventType : enumeration
    Fee .. FeeType : enumeration
    class CommercialProductBasic{
        +int id
        +String name
        +BillingType billingType
        +List~Fee~ fees
    }
    class BillingType{
        +int id
        +String name
        +String description
    }
    class CommercialProduct{
        +int id
        +String name
        +List~FreeUnitsPackage~ fups
    }
    class FreeUnitsPackage{
        +int id
        +String name
        +bool unlimited
        +FupCategory category
        +FupTemplate free_units_package_template
        +List~Fee~ fees
    }
    class FupCategory{
        FIXTOMOBILE
        FIXTOFIX
        ONNET
        INTERNATIONAL
        ROAMING
    }
    class FupTemplate{
        +int id
        +EventType eventType
    }
    class EventType{
        VOZ
        DATOS
        SMS
    }
    class Fee{
        +int id
        +FeeType type
    }
    class FeeType{
        RecurringCharge
        OneTimeFee
    }
    class BundledProductBasic{
        +int id
        +String name
        +BundleCategory category
        +BigDecimal downloadSpeed
        +BigDecimal uploadSpeed
        +String technology
        +List~CommercialProduct~ mainLines
        +List~CommercialProduct~ additionalLines
        +List~CommercialProduct~ extraLines
    }
    class BundleCategory{
        Fixed+Broadband
        Fixed+Broadband+Mobile
        Fixed+Mobile
        Fixed+Broadband+TV
        Fixed+Broadband+Mobile+TV
    }
    link CommercialProduct "commercialproducts.md" "CommercialProduct API Ref"
    link BundledProduct "bundledproducts.md" "BundledProduct API Ref"
    link MasCatalogue "/api/catalogue/2" "Catalogue API Ref"

Commercial Products

Main Attributes

In the context of MasCatalogue API, a commercial product is a product that can be sold alone or inside a bundle. Its model contains the main marketing and billing information, such as:

Once you have identified the main information about the product, the next step is to retrieve all the information about the free units associated to the product services that are included within the price. This information can be extracted from the so-called free units package. A commercial product is composed by a list of compatible free units packages. In some use cases, this list may be empty. This happens with the following:

• Internet products
• Tariff base products
• Products sold in bundles with no voice or data included (i.e fixed on mobile product)
• TV products

Free Units Packages (FUPs)

Free units packages are the pieces of the puzzle that make up the commercial product. The first important distinction that must be made concerns their obligatory nature:

• Structural (or mandatory) FUPs
• Optional FUPs

On the other hand, depending on the type of services included, we distinguish:

• Mobile Data FUPS
• Mobile Voice FUPs
• Mobile SMS FUPs
• Landline FUPs

Promotions

In order to show the actual price applicable for the correspondent commercial product, it is necessary to evaluate which automatic (mandatory) promotions are applicable to the correspondent selling context. These promotions may reduce the total amounf of fees applicable to the product.

Examples

Simplified real examples of commercial products can be found below. It is important to note that the data models and examples shown here are a simplification of the actual response of such a product. On the other hand, the objects represented in the diagram are concrete instances of a class.

Mobile commercial product

Simplified real example of a commercial mobile product with unlimited voice and 20gb of data included: TARIFA MAS 20GB CONV NC - id 313.

classDiagram
    MobileCommercialProduct *-- MandatoryFUP
    MobileCommercialProduct *-- OptionalFUP
    MandatoryFUP <|-- UnlimitedVoiceFUP
    UnlimitedVoiceFUP <|-- UnlimitedVoiceFUPTemplate
    MandatoryFUP <|-- 20gbDataFUP
    20gbDataFUP <|-- 20gbDataFUPTemplate
    OptionalFUP <|-- 15gbExtraExtraDataFUP
    15gbExtraExtraDataFUP <|-- 15gbExtraExtraDataFUPTemplate
    OptionalFUP <|-- 100minIntVoiceFUP
    100minIntVoiceFUP <|-- 100minIntVoiceFUPTemplate
    class MobileCommercialProduct{
        +List~MandatoryFUP~ mandatoryFUPs
        +List~OptionalFUP~ compatibleBonuses
    }
    class MandatoryFUP{
        +mandatory true
    }
    class OptionalFUP{
        +mandatory false
    }
    class 20gbDataFUP{
        +unlimited false
        +List~Fee~ fees
    }
    class 20gbDataFUPTemplate{
        +eventType DATOS
        +amount 21474836480
    }
    class UnlimitedVoiceFUP{
        +unlimited true
        +List~Fee~ fees
    }
    class UnlimitedVoiceFUPTemplate{
        +eventType VOZ
    }
    class 100minIntVoiceFUP{
        +unlimited false
        +List~Fee~ fees
    }
    class 100minIntVoiceFUPTemplate{
        +eventType VOZ
        +amount 6000
    }
    class 15gbExtraExtraDataFUP{
        +unlimited false
        +List~Fee~ fees
    }
    class 15gbExtraExtraDataFUPTemplate{
        +eventType DATOS
        +amount 16106127360
    }

{
  "id": "765",
  "marketing_name": "BONO VOZ ILIMITADA",
  "is_mandatory": true,
  "unlimited": true,
  "fees": [],
  "free_units_package_template": {
    "event_type": "VOZ",
    "id": "VOICE_RECURRING_NBTB_MM"
  }
}

{
  "id": "724",
  "marketing_name": "INTERNET 20GB",
  "is_mandatory": true,
  "unlimited": true,
  "unit_amount": 21474836480,
  "fees": [],
  "free_units_package_template": {
    "event_type": "DATOS",
    "id": "DATA_RECURRING_BTB"
  }
}

{
  "id": "466",
  "marketing_name": "INTERNET 15GB EXTRA 6 MESES",
  "is_mandatory": true,
  "unlimited": true,
  "unit_amount": 16106127360,
  "fees": [],
  "free_units_package_template": {
    "event_type": "DATOS",
    "id": "DATA_RECURRING_BTB"
  }
}

{
  "id": "350",
  "marketing_name": "BONO INTERNACIONAL 100MIN",
  "is_mandatory": true,
  "unlimited": true,
  "unit_amount": 16106127360,
  "fees": [],
  "free_units_package_template": {
    "event_type": "VOZ",
    "id": "VOICE_RECURRING_BTB"
  }
}

Bundled Products

Types

A bundled product is a group of commercial products that are sold together in a bundle. Depending on the number and type of mandatory commercial products that are included in the bundle, we can distinguish:

• Fixed+Broadband:
• Fixed+Broadband+Mobile:
• Fixed+Mobile:
• Fixed+Broadband+TV:
• Fixed+Broadband+Mobile+TV:

Main Attributes

Bundled product’s model contains the products main marketing, technology and commercial information, such as:

Composition

As previously explained, a bundle product is composed by a limited group of different kind of commercial products. Depending on the category of the bundled product, there are mandatory and optional commercial products in the composition. The list of bundled_product_subs_types is used to determinate the number and type of commercial products. Each sub type model of this list contains commercial product information such as:

As an example, in most 3P (Fixed+Broadband+Mobile) cases, a simplified interpretation of the bundled_product_sub_types list would be:

• One element of the list (a bundled_product_sub_type) represents the broadband commercial product type. In this case, the bundled_product_sub_type is mandatory, with an associated internet commercial product repeated only once (minimum_quantity = maximum_quantity = 1).
• Other bundled_product_sub_type represents the fixed line of the bundle. As in the broadband sub type, the commercial product is repeated only one time and it is mandatory.
• Another bundled_product_sub_type represents the mobile lines. In this case, the associated commercial products are mobile commercial products. In this case, the bundled_product_sub_type contains a list of commercial products, including the mandatory commercial product and a list of extra and additional optional commercial products. The minimum_quantity may be 1, but the maximum_quantity could be higher depending on the maximum number of additional and extra lines included in the bundle.

Bundled Commercial Products

So far, the referred bundled products were made up of commercial products. However, this requires a nuance. The bundled products are really made up of bundled commercial products. They are overridden instances of a certain commercial product.

That is, when a commercial product is sold in a bundled product, some of the characteristics of the commercial product (such as fees, promotions, commercial devices and vas) could be overridden in a bundled commercial product with the same id.

In addition to the commercial product information, it also includes information about the type of product that is inside the bundled product (if it is a main line, an extra line, etc).

Examples

The following are simplified real examples of a bundled products. It is important to note that the data models and examples shown here are a simplification of the actual response of such a product. On the other hand, the objects represented in the diagram are concrete instances of a class.

Fixed + Broadband + Mobile

Simplified real example of a 3P bundled product: FIBRA 600 + ILIMITADA 20GB NC 2019 - id 404.

classDiagram
    3pBundledProduct <|-- InternetSubType
    InternetSubType <|-- InternetBundledCommercialProduct
    InternetBundledCommercialProduct <|-- InternetCommercialProduct
    3pBundledProduct <|-- FixedSubType
    FixedSubType <|-- FixedBundledCommercialProduct
    FixedBundledCommercialProduct <|-- FixedCommercialProduct
    3pBundledProduct <|-- MobileSubType
    class 3pBundledProduct{
        +id 404
        +upload_speed 600
        +download_speed 600
        +technology FIBRA
        +List~BundledProductSubType~ subTypes
    }
    class InternetSubType{
        +id 628
        +is_mandatory true
        +min_quantity 1
        +max_quantity 1
        +subs_type INTERNET_FTTH
        +bundled_commercial_products [internetBCP]
    }
    class FixedSubType{
        +id 627
        +is_mandatory true
        +min_quantity 1
        +max_quantity 1
        +subs_type FIJO_DIGITAL
        +bundled_commercial_products [fixedBCP]
    }
    class InternetBundledCommercialProduct{
        +id 628
        +is_mandatory true
        +is_main_line true
        +commercial_product internetCommercialProduct
    }
    class InternetCommercialProduct{
        +id 589
        +marketing_name Fibra600MásMovil
    }
    class FixedBundledCommercialProduct{
        +id 627
        +is_mandatory true
        +is_main_line true
        +commercial_product internetCommercialProduct
    }
    class FixedCommercialProduct{
        +id 643
        +marketing_name Fibra600MásMovil
    }

classDiagram
    MobileSubType <|-- MobileMainLineBCP
    MobileSubType <|-- MobileAdditionalLineBCP
    MobileSubType <|-- MobileExtraLineBCP
    MobileMainLineBCP <|-- MobileMainLineCP
    MobileAdditionalLineBCP <|--MobileAdditionalLineCP
    MobileExtraLineBCP <|-- MobileExtraLineCP
    class MobileSubType{
        +id 626
        +is_mandatory true
        +min_quantity 1
        +max_quantity 6
        +subs_type POST_PAGO
        +bundled_commercial_products [mainLineBCP,adLineBCP,extraLineBCP]
    }
    class MobileMainLineBCP{
        +is_mandatory true
        +is_main_line true
        +commercial_product mobileMainLineCP
    }
    class MobileMainLineCP{
        +id 313
        +marketing_name TARIFA_MAS_20GB_CONV_NC
    }
    class MobileAdditionalLineBCP{
        +is_mandatory false
        +is_additional_line true
        +commercial_product mobileAdLineCP
    }
    class MobileAdditionalLineCP{
        +id 7065
        +marketing_name Tarifa_Más_20GB
    }
    class MobileExtraLineBCP{
        +is_mandatory false
        +is_extra_line true
        +commercial_product mobileExtraLineCP
    }
    class MobileExtraLineCP{
        +id 7058
        +marketing_name TARIFA_MAS_1GB_GRATIS_AD
    }

{
  "id": "404",
  "marketing_name": "FIBRA 600 + ILIMITADA 20GB NC 2019",
  "upload_speed": "600",
  "download_speed": "600",
  "category": "Fixed+Broadband+Mobile",
  "technology": {
    "name": "FIBRA",
    "id": "2"
  },
  "bundled_product_subs_types": []
}

{
  "id": "628",
  "is_mandatory": true,
  "min_quantity": 1,
  "max_quantity": 1,
  "subs_type": {
    "name": "INTERNET FTTH",
    "description": "INTERNET FTTH",
    "id": "6"
  },
  "bundled_commercial_products": [
    {
      "is_mandatory": true,
      "is_main_line": true,
      "commercial_product": { "id": "589", "marketing_name": "Fibra 600 MásMovil" }
    }
  ]
}

{
  "id": "627",
  "is_mandatory": true,
  "min_quantity": 1,
  "max_quantity": 1,
  "subs_type": {
    "name": "FIJO DIGITAL",
    "description": "DIGITAL",
    "id": "4"
  },
  "bundled_commercial_products": [
    {
      "is_mandatory": true,
      "is_main_line": true,
      "commercial_product": { "id": "643", "marketing_name": "Línea Fija" }
    }
  ]
}

{
  "id": "626",
  "is_mandatory": true,
  "min_quantity": 1,
  "max_quantity": 6,
  "subs_type": {
    "name": "POST-PAGO",
    "description": "POS-PAGO",
    "id": "2"
  },
  "bundled_commercial_products": [
    {
      "is_mandatory": true,
      "is_main_line": true,
      "is_additional": false,
      "is_extra": false,
      "commercial_product": { "id": "313", "marketing_name": "TARIFA MAS 20GB CONV NC" }
    },
    {
      "is_mandatory": false,
      "is_main_line": false,
      "is_additional": true,
      "is_extra": false,
      "commercial_product": { "id": "7065", "marketing_name": "Tarifa Más 20GB" }
    },
    {
      "is_mandatory": false,
      "is_main_line": false,
      "is_additional": false,
      "is_extra": true,
      "commercial_product": { "id": "7058", "marketing_name": "TARIFA MAS 1GB GRATIS AD" }
    }
  ]
}