Copy of Produto Variável

O produto variável é aquele onde há um agrupamento de dois ou mais SKUs tendo um atributo diferenciador para distingui-los. Nesta seção temos a estrutura para a criação desse tipo de produto

Não estão ainda em produção alterações a respeito de Categorização, Marcas e atributos de categorias.

Produto variável é aquele em que um ou mais SKUs são agrupados; estes SKUs serão diferenciados através de atributos específicos, como tamanho ou cor, por exemplo.

Atributos como cor, tamanho e voltagem podem ser definidos tanto a nível de produto quanto a nível de SKU (variações). Será necessário consultar a lista de atributos da categoria e identificar se a categoria aceita esses atributos, porém detalhamos mais abaixo.

Mesmo para produtos variáveis é necessário haver atributos e informações que fortaleçam a identidade do item, como um título claro e características bem definidas em sua ficha técnica. Acompanhe o exemplo abaixo:

Quando tratamos uma camiseta é necessário fornecer uma breve descrição de suas características dentro do título, a fim de chamar a atenção de um potencial cliente (por exemplo, Título: Camiseta Branca Lisa). Além disso, também faz-se necessário incluir atributos de ficha técnica, como material, fabricante, marca, dentre outros para enriquecer o cadastro do item quando anunciado.

Esses atributos de ficha técnica favorecem a localização do produto na realização de filtros nos sites de e-commerce e o título destaca a escolha do cliente final ao realizar as buscas.

Mas não é só isso, existem vários outros requisitos necessários para a integração com o marketplace, como o correto preenchimento do peso, dimensões, status, indexação de imagens, além da inclusão em sua correta estrutura mercadológica.

A seção Integração: Produto desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace

A seguir confira a estrutura esperada para a criação de um produto variável via API.

Estrutura do JSON

A estrutura básica para a criação de um produto variável contém campos que devem ser preenchidos com os formatos de dados determinados pela API.

A seguir são apresentados os campos que constituem a estrutura de um produto variável e o formato a ser utilizado para inclusão dos dados. A não utilização dos formatos corretos para preenchimento dos dados pode acarretar em reprova proveniente do marketplace, impossibilitando a publicação da oferta.

Dentro de "specifications", somente atributos de categoria.

A partir de Março/2025, no array specifications deverá constar somente atributos de categoria. Mais abaixo explicamos o funcionamento destes atributos.

{
    "product": { // Object
        "sku": "CodigoSKU_agrupador", // String 
        "name": "Título", // String
        "brand": "CodigoMarca", // String
        "categoryId": "IdCategoria", // String
        "description": "Descrição", // String
        "status": "enabled", // String
        "price": 0.0, // Double
        "promotional_price": 0.0, // Double
        "cost": 0, // Double
        "weight": 0, // Double
        "height": 0, // Double
        "width": 0, // Double
        "length": 0, // Double
        "brand": "Marca", // String        
        "nbm": "NCM (Nomenclatura Comum do Mercosul)", // String
        "images": [ // Array
            "URL da imagem" // String
        ],
        "specifications": [ // Array
            { // Object
                "key": "Atributo", // String
                "value": "Valor do atributo" // String
            },
            { // Object
                "id": "Valor", // String
                "idValue" // String
            },
            { // Object
                "id": "valor", // String
                "value": "valor" // String
            }
        ],
        "variations": [ // Array
             { // Object }          
        ],
        "variation_attributes":[ // Array
          "atributo1",
          "atributo2",
          "atributo3"
          ]
    }
}

Como declarar a categoria

Será necessário realizar a consulta na lista de categorias para obter o categoryId e preencher no body do JSON.

Para isso, seguir a documentação Consultar lista de categorias.

Haverá os IDs disponíveis 'id', 'id1', 'id2' e 'id3'. Os IDs enumerados representam os níveis de categorias, enquanto o ID em verde representa toda a estrutura. Qualquer um desses IDs disponíveis deve constar em categoryId, vai depender do nível em que o lojista deseja catalogar seu produto.

Como declarar a marca

Será necessário realizar a consulta das marcas para obter o brand e preencher no body do JSON. Para isso, seguir a documentação Consultar Marcas.

Como declarar atributos de categoria

Os atributos de categoria devem ser declarados dentro de 'specifications', porém com distinção em relação aos demais atributos. Como visto em Consultar atributos por categoria, há diferenças entre os tipos de atributos:

• Se for um atributo de livre preenchimento: Em 'specifications' deve ser declarado id (id do atributo) e value (texto livre e não tem um dado estruturado, ou seja, não há idValue para ser enviado).

• Se for um atributo com valores já pré-determinados: Em 'specifications' deve ser declarado id (id do atributo) e idValue (id do valor de uma das opções presente no array valueData).

Atenção ao campo "toSKU"

A consulta de atributos por categoria retornará um campo chamado "toSKU", onde este define se o atributo deve ser enviado no produto PAI ou na sua variação. Caso o "toSKU" seja false, o atributo deve ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho.

Porém, se por acaso o "toSKU" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "specifications" do produto normalmente.

Atributos com o 'required' igual a True ao consultar os atributos da categoria, deverão obrigatoriamente constar no JSON do produto. Os demais, são opcionais o envio.

Atributos de categoria são diferentes de atributos de produtos. Atributos de categoria possuem o padrão "id" e "idValue"/"value", já os atributos de produto possuem o padrão "key" e "value".

POST - Cadastrando um produto variável

Para realizar o cadastro de um produto variável via API deverá ser utilizado o método POST para o seguinte endpoint:

https://api.skyhub.com.br/products

Request headers:

Key	Value
X-User-Email	email_de_usuario
X-Api-Key	token_de_integracao de sua conta SkyHub
X-Accountmanager-key	token_account único de cada Plataforma/ERP
Accept	application/json
Content-Type	application/json

A diferença para o JSON do produto simples é que no cadastro da variação é informado o array variations com as informações dos SKUs agrupados, seus atributos diferenciadores e outras especificações.

Dentro de 'specifications' deverá ser declarado o atributo de variação preenchido, de acordo com consulta prévia no endpoint de atributos de categoria.

Todo produto variável deve contar com o array variation_attributes, onde deverão ser informados os atributos responsáveis pela diferenciação das variações.

Por exemplo, ao cadastrar uma camiseta e preencher para os SKUs filhos - aqueles vinculados a um SKU agrupador/pai - o atributo "Tamanho" para diferenciar uma variação da outra, é esperado que o mesmo atributo ("Tamanho") seja informado no array variation_attributes.

Request body:

{
    "product": {
        "sku": "CodigoSKU_agrupador",
        "name": "Título",
        "brand": "Código da Marca", // Obtido realizando o GET em Marcas
        "categoryId": "Id da Categoria", // Obtido realizando o GET na lista de Categorias
        "description": "Descrição detalhada do produto criado",
        "status": "enabled", // Status (ativo/enabled ou inativo/disabled)
        "price": 0.0, // Preço
        "promotional_price": 0.0, // Preço promocional
        "cost": 0, // Custo do produto para o seller
        "weight": 0, // Peso
        "height": 0, // Altura
        "width": 0, // Largura
        "length": 0, // Comprimento
        "brand": "Marca",
        "nbm": "NBM/NCM",
        "images": [
            ""
        ],
        "specifications": [ // Objeto responsável pela inclusão de atributos
            {
                "key": "Atributo",
                "value": "Valor do atributo"
            },
            { // Atributo de categoria - preenchimento livre
                "id": "id do atributo",
                "value": "Texto livre"
            },
            { // Atributo de categoria - valores pré-determinados
                "id": "id do atributo",
                "idValue": "id da opção selecionável"
            }
        ],
        "variations": [
            {
                "sku": "CodigoSKU_variacao",
                "qty": 0, // Estoque
                "ean": "EAN (European Article Number ou Numeração Europeia de Artigos, o código de barras do item)",
                "images": [
                    "https:// URL da imagem" // Imagem da variação
                ],
                "specifications": [ // Objeto responsável pela inclusão de atributos
                    {
                        "key": "Atributo",
                        "value": "Valor do atributo"
                    },
                    {
                        "key": "Atributo",
                        "value": "Valor do atributo"
                    },
                    {
                        "key": "price", 
                        "value": "0.0" // Preço da variação
                    },
                    {
                        "key": "promotional_price",
                        "value": "0.0" // Preço promocional da variação
                    }
                ]
            }
        ],
        "variation_attributes": [ // Objeto responsável pela inclusão do atributo diferenciador
            "Atributo_diferenciador_1",
            "Atributo_diferenciador_2"
        ]
    }
}

Há um limite de 100 variações que podem ser inclusas na estrutura de um produto, sendo necessário respeitar tal limitação para não haverem reprovas ao encaminhar o SKU variável para a API.

Example request:

Veja abaixo o JSON de criação de um produto com variações, sendo o SKU P2022 o ID do produto "pai" e os SKUs F2023 e F2024 os IDs das variações:

curl --location --request POST 'https: //api.skyhub.com.br/products' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "product": {
        "sku": "P2022",
        "name": "Identificador de cédula falsa",
        "brand": "1739052110001030", // id de uma marca
        "categoryId": "24" // id referente a categoria de Identificador de cédula falsa
        "description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
        "status": "enabled",
        "price": 00.00,
        "promotional_price": 00.00,
        "cost": 0.0,
        "weight": 0.100,
        "height": 20,
        "width": 30,
        "length": 20,
        "brand": "Skyhub",
        "nbm": "98769898",
        "images": [
            ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
        ],
        "specifications": [
            {
                "key": "Especicações do Produto PAI",
                "value": "Especificações do Produto PAI"
            },
            { // Atributo de categoria - preenchimento livre
                "id": "id do atributo",
                "value": "Texto livre"
            },
            { // Atributo de categoria - valores pré-determinados
                "id": "id do atributo",
                "idValue": "id da opção selecionável"
            }
        ],
        "variations": [
            {
                "sku": "F2023",
                "price": 00.00, // Alteração ainda não está em vigor
                "promotional_price": 00.00, // Alteração ainda não está em vigor
                "qty": 10,
                "ean": "9876543210987",
                "images": [
                    ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
                ],
                "specifications": [
                    {
                        "key": "Cor",
                        "value": "Branca"
                    },
                    {
                        "key": "Tamanho",
                        "value": "P"
                    },
                    {
                        "key": "price",
                        "value": "50.00"
                    },
                    {
                        "key": "promotional_price",
                        "value": "40.00"
                    },
                 {
                        "id": "29229", // id referente a voltagem
                        "idValue": "49105" // id referente ao valor 220 V
                    }
                ]
            },
            {
                "sku": "F2024",
                "price": 00.00, // Alteração ainda não está em vigor
                "promotional_price": 00.00, // Alteração ainda não está em vigor
                "qty": 10,
                "ean": "9876543210985",
                "images": [
                    ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
                ],
                "specifications": [
                    {
                        "key": "Cor",
                        "value": "Branca"
                    },
                    {
                        "key": "Tamanho",
                        "value": "M"
                    },
                    {
                        "key": "price",
                        "value": "50.00"
                    },
                    {
                        "key": "promotional_price",
                        "value": "40.00"
                    },
                    {
                        "id": "29229", // id referente a voltagem
                        "idValue": "49106" // id referente ao valor 220 V
                    }
                ]
            }
        ],
        "variation_attributes": [
            "Cor",
            "Tamanho"
        ]
    }
}'