# Produto Variável 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. 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. {% hint style="info" %} A seção [Integração: Produto](/produtos/integracao-produtos.md#pre-requisitos) desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace {% endhint %} A seguir confira a estrutura esperada para a criação de um produto variável via API. ## Estrutura do JSON {% hint style="danger" %} **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. {% endhint %} {% hint style="info" %} **Novos atributos no corpo das variações.**\ A partir de Março/2025, a raiz das variações ganha os atributos *price, promotional\_price, height, width, length, weight e crossdocking*. {% endhint %} {% hint style="warning" %} **Variações herdam atributos do produto pai.** Portanto, se algum atributo constar somente na raiz do produto, as variações também o assumirão. Exemplo: Caso as dimensões estejam somente no produto pai, as variações assumirão as mesmas dimensões. {% endhint %} {% hint style="danger" %} **Validação de preço e preço promocional com valores válidos** A partir de Março/2025 existirá uma validação na criação e atualização de produto, produto com variação e variação com valores válidos de preço e preço promocional. Esses valores serão considerados válidos quando forem **diferentes** de **nulo** ou **zero**. {% endhint %} {% hint style="info" %} **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. {% endhint %} ```json { "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 "id": "Valor", // String "idValue": "valor", // String "value": "valor", // String "key": "valor" // String }, { // Object "id": "valor", // String "value": "valor", // String "key": "valor" // String } ], "variations": [ // Array { "sku": "CodigoSKU", // String "name": "Título", // String "qty": 10 // String } ] } } ``` ### 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**](/produtos/categorizacao/consultar-categorias.md). Haverá os ID's disponíveis **'id'**, 'id1', 'id2' e 'id3'. Os ID's enumerados representam os níveis de categorias, enquanto o ID em verde representa toda a estrutura. Qualquer um desses ID's 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**](/produtos/consultar-marcas.md). ### Como declarar atributos de categoria Os atributos de categoria devem ser declarados dentro de "specifications", mas com distinções dependendo do tipo de atributo.\ \ Conforme explicado em [**Consultar atributos por categoria**](/produtos/categorizacao/consultar-atributos-por-categoria.md), os atributos podem ser de dois tipos:
* Atributos de Livre Preenchimento:\ \ Em '**specifications**' deve ser declarado ***id*** (identificador do atributo), ***value*** (texto livre e não tem um dado estruturado, ou seja, não há idValue para ser enviado), **key** (atributo) e **value** (valor em texto livre do atributo).
* Atributos com valores já pré-determinados:\ \ Em '**specifications**' deve ser declarado ***id*** (identificador do atributo), ***idValue*** (identificador do valor escolhido dentro do array *valueData*), **key** (atributo) e **value** (valor em texto livre do atributo). #### 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. {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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". {% endhint %} ## **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(s) atributo(s) de variação(ões) preenchido(s), de acordo com consulta prévia no endpoint de atributos de categoria. \ \ Como informado mais acima, atributos que possuírem o campo "**toSKU**" como true, tratam-se de atributos de variação e devem ser enviados dentro das especificações das variações. #### Request body: ```json { "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 "crossdocking": "3", // Crossdocking "nbm": "NBM/NCM", "images": [ "" ], "specifications": [ // Objeto responsável pela inclusão de atributos { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre", "key": "atributo" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável", "key": "atributo", "value": "valor do atributo" } ], "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)", "price": 0.00, // Preço "status": "enabled", "promotional_price": 0.00, // Preço promocional "weight": 0, // Peso "height": 0, // Altura "width": 0, // Largura "length": 0, // Comprimento "crossdocking": "3", // Crossdocking "images": [ "https:// URL da imagem" // Imagem da variação ], "specifications": [ // Objeto responsável pela inclusão de atributos // Somente atributos com "toSKU" igual a True { // Atributo de categoria - preenchimento livre "id": "id do atributo", "key": "atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "key": "atributo", "value": "valor do atributo", "idValue": "id da opção selecionável" } ] } ] } } ``` {% hint style="warning" %} 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. {% endhint %} #### **Exemplo de 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: ```json 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": "Skyhub", "categoryId": "24", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "status": "enabled", "price": 100.00, "promotional_price": 99.00, "cost": 0.0, "weight": 0.100, "height": 20, "width": 30, "length": 20, "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": [ { "id": "id_do_atributo", "value": "Texto livre", "key": "atributo" }, { "id": "id_do_atributo", "key": "atributo", "value": "Texto livre", "idValue": "id_da_opcao_selecionavel" } ], "variations": [ { //Price e promotional price herdados do pai "sku": "F2023", "status": "enabled", "qty": 10, "ean": "9876543210987", "weight": 0.100, "height": 20, "width": 30, "length": 20, "crossdocking": "3", "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", // ID referente a voltagem "key": "atributo", "value": "Texto livre", "idValue": "49105" } ] }, { //Price herdado do pai "sku": "F2024", "promotional_price": 89.99, "status": "enabled", "qty": 10, "ean": "9876543210985", "weight": 0.100, "height": 20, "width": 30, "length": 20, "crossdocking": "3", "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", // ID referente a voltagem "key": "voltagem", "value": "220v", "idValue": "49106" } ] } ] } }' ``` **Response esperado:** {% hint style="success" %} 201 \[Sucess] - Created {% endhint %} Exemplo de produto criado com sucesso da requisição: ```json { "name": "Identificador de cédula falsa", "nbm": null, "ncm": null, "sku": "P2022", "brand": "Skyhub", "status": "enabled", "ean": null, "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "product_condition": null, "qty": 0, "crossdocking": 0, "price": 0.0, "promotional_price": 0.0, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "cost": 0.0, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg", "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "variation_attributes": [], "variations": [ { "ean": "9876543210987", "sku": "F2023", "name": "Identificador de cédula falsa", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "nbm": "98769898", "ncm": null, "status": "enabled", "product_condition": null, "crossdocking": 3, "qty": 10, "price": 100.0, "cost": 0.0, "promotional_price": 99.0, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", "key": "atributo", "idValue": "49105", "value": "Texto livre" } ] }, { "ean": "9876543210985", "sku": "F2024", "name": "Identificador de cédula falsa", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "nbm": "98769898", "ncm": null, "status": "enabled", "product_condition": null, "crossdocking": 3, "qty": 10, "price": 100.0, "cost": 0.0, "promotional_price": 89.99, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", "key": "voltagem", "idValue": "49106", "value": "220v" } ] } ], "specifications": [ { "id": "id_do_atributo", "key": "atributo", "idValue": "id_da_opcao_selecionavel", "value": "Texto livre" } ], "categories": [ { "code": "24", "name": "Automação comercial" } ] } ``` **Exemplo de resposta caso o preço do pai e o preço promocional do pai sejam enviados com 0 ou nulo.** {% hint style="danger" %} 422 \[Error] - Unprocessable Entity {% endhint %} **Response body:** ```json { "error": "Os seguintes SKUs possuem preços inválidos: F2023, F2024. O preço não pode ser nulo ou igual a zero." } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://desenvolvedores.skyhub.com.br/produtos/criacao-de-produto/produto-variavel.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.