VeePee Taxonomy

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The taxonomy must be stored in classes, which should be available for exports from the UI in Export Taxonomy table. The taxonomy is used for internal validation and we will need to map the values and push the codes to VeePee.

Every time we send products for creation we have to do internal check if all required attributes are part of the the product as Item Specifics or Variation Specifics according to their taxonomy which we download and store on the instance.

The VeePee taxonomy have different languages for the different channel and we need to make sure we are validating the correct values against the selected channel. For example if we have selected in Account VeePee > Shop channel ID - France we need to make sure we are validating against "fr" values.

To download the taxonomy, we should follow the steps:

List categories

Using this call, we are able to get all available categories. There are a total of 1632 categories available for download.

API Call:GET {{BaseUrl}}/v4/taxonomy

API Docs: https://www.pink-connect.com/swagger#operation/listCategories

Sample Response:

categories.json

[
    {
        "code": "11351",
        "name": {
            "en": "BEAUTY AND WELL-BEING",
            "es": "BELLEZA Y BIENESTAR",
            "it": "BELLEZZA E BENESSERE",
            "fr": "Beauté et bien-être",
            "be_fr": "Beauté et bien-être"
        },
        "path": {
            "en": "BEAUTY AND WELL-BEING",
            "es": "BELLEZA Y BIENESTAR",
            "it": "BELLEZZA E BENESSERE",
            "fr": "Beauté et bien-être",
            "be_fr": "Beauté et bien-être"
        },
        "level": 1
    },
    {
        "code": "11352",
        "name": {
            "en": "HYGIENE AND CARE",
            "es": "HIGIENE Y CUIDADO",
            "it": "IGIENE E CURA",
            "fr": "Hygiène et soin",
            "be_fr": "Hygiène et soin"
        },
        "path": {
            "en": "BEAUTY AND WELL-BEING > HYGIENE AND CARE",
            "es": "BELLEZA Y BIENESTAR > HIGIENE Y CUIDADO",
            "it": "BELLEZZA E BENESSERE > IGIENE E CURA",
            "fr": "Beauté et bien-être > Hygiène et soin",
            "be_fr": "Beauté et bien-être > Hygiène et soin"
        },
        "parent_code": 11351,
        "level": 2
    },
    {
        "code": "11353",
        "name": {
            "en": "BEAUTY AND HYGIENE ACCESSORY",
            "es": "ACCESORIO DE BELLEZA E HIGIENE",
            "it": "BELLEZZA E IGIENE ACCESSORIE",
            "fr": "Accessoire beauté et hygiène",
            "be_fr": "Accessoire beauté et hygiène"
        },
        "path": {
            "en": "BEAUTY AND WELL-BEING > HYGIENE AND CARE > BEAUTY AND HYGIENE ACCESSORY",
            "es": "BELLEZA Y BIENESTAR > HIGIENE Y CUIDADO > ACCESORIO DE BELLEZA E HIGIENE",
            "it": "BELLEZZA E BENESSERE > IGIENE E CURA > BELLEZZA E IGIENE ACCESSORIE",
            "fr": "Beauté et bien-être > Hygiène et soin > Accessoire beauté et hygiène",
            "be_fr": "Beauté et bien-être > Hygiène et soin > Accessoire beauté et hygiène"
        },
        "parent_code": 11352,
        "level": 3
    },
    {
        "code": "11399",
        "name": {
            "en": "COMB - HAIRBRUSH",
            "es": "PEINE - CEPILLO",
            "it": "PETTINE - SPAZZOLA",
            "fr": "PEIGNE - BROSSE",
            "be_fr": "PEIGNE - BROSSE"
        },
        "path": {
            "en": "BEAUTY AND WELL-BEING > HYGIENE AND CARE > BEAUTY AND HYGIENE ACCESSORY > COMB - HAIRBRUSH",
            "es": "BELLEZA Y BIENESTAR > HIGIENE Y CUIDADO > ACCESORIO DE BELLEZA E HIGIENE > PEINE - CEPILLO",
            "it": "BELLEZZA E BENESSERE > IGIENE E CURA > BELLEZZA E IGIENE ACCESSORIE > PETTINE - SPAZZOLA",
            "fr": "Beauté et bien-être > Hygiène et soin > Accessoire beauté et hygiène > PEIGNE - BROSSE",
            "be_fr": "Beauté et bien-être > Hygiène et soin > Accessoire beauté et hygiène > PEIGNE - BROSSE"
        },
        "parent_code": 11353,
        "level": 4
    }
]

We want to use the path for Product Account > Primary Category ID in the relevant language and map it against the correct language and push the code to VeePee. We are allowed to list products only in "level": 4 categories so we need to make sure we are validating the category level. The final level is 4 and we treat it as leaf category in Hemi. The parent_coderefers to the previous level of the category which we use to navigate to the final level 4.

Get Category Attributes

Use this call to get the specific category attributes. For this request we have a limit of 1000 request so should be OK to use it this way. We want to the the attributes for all leaf categories (level:4)

API Call:GET {{BaseUrl}}/v4/taxonomy/11351/attributesAPI Call Structure: {base_url}/v4/taxonomy/{category_code}/attributes

API Docs: https://www.pink-connect.com/swagger#operation/listAttributesByCategory

Sample Response:

attributes.json

{
        "code": "skin_type",
        "description": {
            "en": "Skin type",
            "es": "Tipo de piel",
            "it": "Tipo di pelle\r\n",
            "fr": "Type de peau",
            "be_fr": "Type de peau"
        },
        "category_code": 11774,
        "label": {
            "en": "Skin type",
            "es": "Tipo de piel",
            "it": "Tipo di pelle",
            "fr": "Type de peau",
            "be_fr": "Type de peau"
        },
        "required": false,
        "data_type": "str",
        "type": "generic",
        "recommended": true,
        "min_value": null,
        "max_value": null,
        "sort_order": 100,
        "entity_type": "productoffer",
        "variant": false,
        "values_list": "choices_skin_type"
    }

We will be using the label for optimization and we need to map the relevant language and push the code to VeePee in the payload. We need to call each category and get its attributes however we would like to define some root attributes which are not treated as item specifics and we do not want to include them in the export file:

Skipped Attributes

model

category

stock

tax_rate_percentage

manufacturer_recommended_price

code

sku

image_url_1

image_url_2

image_url_3

image_url_4

image_url_5

image_url_6

image_url_7

image_url_8

gtin

is_variation

description

variation_type

dimension

name

retail_price_justification

selling_price

Get Attribute Values

All attribute which have the attribute "values_list" means there are values which we can download For example: "values_list": "choices_skin_type". We need to the match the choices_skin_type to the code from the response

API Call:GET https://api-pinkstaging.pink-connect.com/v4/taxonomy/value-listAPI Call Structure: {base_url}/v4/taxonomy/value-list

API Docs: https://www.pink-connect.com/swagger#operation/listValuesLists

Sample Response:

values.json

 {
        "code": "choices_gloves_product_type",
        "label": {
            "en": "Product Type (Gloves Mitts)",
            "es": "Tipo de producto (guantes mitones)",
            "fr": "Type de produit (gants mitaines)",
            "be_fr": null,
            "it": "Tipo di prodotto (guanti mezzoguanti)"
        },
        "values": {
            "c_mitts": {
                "id": "c_mitts",
                "value_en": "Mitts",
                "value_es": "Manoplas",
                "value_fr": "Moufles",
                "value_it": "Mezzoguanti"
            },
            "c_other": {
                "id": "c_other",
                "value_en": "Other",
                "value_es": "Otro",
                "value_fr": "Autre",
                "value_it": "Altro"
            },
            "c_gloves": {
                "id": "c_gloves",
                "value_en": "Gloves",
                "value_es": "Guantes",
                "value_fr": "Gants",
                "value_it": "Guanti"
            },
            "c_mittens": {
                "id": "c_mittens",
                "value_en": "Mittens",
                "value_es": "Mitones",
                "value_fr": "Mitaines",
                "value_it": "Muffole"
            },
            "c_glove-liners": {
                "id": "c_glove-liners",
                "value_en": "Glove Liners",
                "value_es": "Sotoguantes",
                "value_fr": "Sous-gants",
                "value_it": "Sottoguanti"
            }
        }
    }

From the values response we want to use the values as Product Account > Item Specific Value ("Sous-gants") and push the same value to the marketplace. Please note we need to send the VALUE in such enumeration type fields, not the code. Again as for the other attributes in general we want to validate against the language of the chosen Channel for the Account in Hemi

The links between the category and the attributes is the code once we get all categories we need to call category per category to get all the attributes. Then once we have the attributes if the attribute values_list is populated we need to map it with the code from the values. This way we can connect each category with its attributes and values.

There are some values like:

{
        "code": "choices_morphogender",
        "label": {
            "en": "Gender and Lifestage",
            "es": "Género y edad",
            "fr": "Genre et groupe d´âge",
            "be_fr": null,
            "it": "Genere e età"
        },
        "values": {
            "c_boy": {
                "id": "c_boy",
                "value_en": "Boy",
                "value_es": "Niño",
                "value_fr": "Garçon",
                "value_it": "Bambino"
            },
            "c_man": {
                "id": "c_man",
                "value_en": "Man",
                "value_es": "Hombre",
                "value_fr": "Homme",
                "value_it": "Uomo"
            },
            "c_girl": {
                "id": "c_girl",
                "value_en": "Girl",
                "value_es": "Niña",
                "value_fr": "Fille",
                "value_it": "Bambina"
            },
            "c_other": {
                "id": "c_other",
                "value_en": "Other",
                "value_es": "Otro",
                "value_fr": "Autre",
                "value_it": "Altro"
            },
            "c_woman": {
                "id": "c_woman",
                "value_en": "Woman",
                "value_es": "Mujer",
                "value_fr": "Femme",
                "value_it": "Donna"
            },
            "c_baby-boy": {
                "id": "c_baby-boy",
                "value_en": "Baby Boy",
                "value_es": "Bebé Niño",
                "value_fr": "Bébé Garçon",
                "value_it": "Bebè maschio"
            },
            "c_baby-girl": {
                "id": "c_baby-girl",
                "value_en": "Baby Girl",
                "value_es": "Bebé Niña",
                "value_fr": "Bébé Fille",
                "value_it": "Bebè femmina"
            },
            "c_maternity": {
                "id": "c_maternity",
                "value_en": "Maternity",
                "value_es": "Lactancia",
                "value_fr": "Maternité",
                "value_it": "Maternità"
            },
            "c_no_gender": {
                "id": "c_no_gender",
                "value_en": "No gender",
                "value_es": "Sin género",
                "value_fr": "Sans Sexe",
                "value_it": "Senza Genere"
            },
            "c_baby-unisex": {
                "id": "c_baby-unisex",
                "value_en": "Baby Unisex",
                "value_es": "Bebé Unisex",
                "value_fr": "Bébé mixte",
                "value_it": "Bebè unisex"
            },
            "c_teenage-boy": {
                "id": "c_teenage-boy",
                "value_en": "Teenage Boy",
                "value_es": "Joven Él",
                "value_fr": "Ado Garçon",
                "value_it": "Adolescente maschio"
            },
            "c_adult-unisex": {
                "id": "c_adult-unisex",
                "value_en": "Adult Unisex",
                "value_es": "Adulto Unisex",
                "value_fr": "Adulte Mixte",
                "value_it": "Adulto unisex"
            },
            "c_child-unisex": {
                "id": "c_child-unisex",
                "value_en": "Child Unisex",
                "value_es": "Infantil Unisex",
                "value_fr": "Enfant mixte",
                "value_it": "Bambino unisex"
            },
            "c_teenage-girl": {
                "id": "c_teenage-girl",
                "value_en": "Teenage Girl",
                "value_es": "Joven Ella",
                "value_fr": "Ado Fille",
                "value_it": "Adolescente femmina"
            },
            "c_pre-maternity": {
                "id": "c_pre-maternity",
                "value_en": "Pre-maternity",
                "value_es": "Premamá",
                "value_fr": "Pré-maternité",
                "value_it": "Premaman"
            },
            "c_post-maternity": {
                "id": "c_post-maternity",
                "value_en": "Post-maternity",
                "value_es": "Postparto",
                "value_fr": "Post-maternité",
                "value_it": "Post-maternità"
            },
            "c_teenage-unisex": {
                "id": "c_teenage-unisex",
                "value_en": "Teenage Unisex",
                "value_es": "Joven Unisex",
                "value_fr": "Ado Unisexe",
                "value_it": "Adolescente unisex"
            }
        }
    }

The actual values list is choices_morphogender however the values we want to use are from the c_boy > value_fr - Garçon this is what VeePee will expect and also this is what we want to export and store in Product Account > Item Specific Value For example:

Taxonomy export file

In order to generate the taxonomy file we will need to create a new record in Taxonomy export with: Marketplace = VeePee Status = pending Category for Export = all (or we can specify which exact categories using the category name) Email = email to which the file will be send

Please find more details on the file structure how it should look like after exported here - Taxonomy General requirements .

Sample export file for France

Please note we want to export taxonomies based on the language values (if the account is set for France we need to export only the France values). The possible language values are “Es”, “En”, “It”, “Fr”, “all”

When we create a new record in table Export Taxonomy there we select just the distinct marketplace (veepee) which is not split by channel. So, to achieve export split by language we have to introduce a new field “Language” which will hold available languages for the “distinct marketplace” selected. This way when we are creating a new integration we can specify available languages if there are multiple such and controll what values we want to export. Best handle of this field is to be shown only for relevant marketplaces (meaning it will also not be mandatory). Last but not least we need to store or send an error if we are unsuccessfull in exporting the taxonomy. I don’t have a preferred method we just need to ensure that it is known the taxonomy export was unsuccessful and the relevant error.

As we introduce the Language field everything else should be handled the same way. Language + “all” = exports all categories with their attributes with the specified language values. Language + “{{specific_category}}“ exports this specific category with the values in the language provided. If Language value does not match to the value provided for the Category it should be treated as error