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:

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "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",
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "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",
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "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",
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "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": []
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
    "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"}
    }]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
    "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"}
    }]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
    "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"}
        }
    ]
}