# 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](https://desenvolvedores.skyhub.com.br/integracao-produtos#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**](https://desenvolvedores.skyhub.com.br/produtos/categorizacao/consultar-categorias). 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**](https://desenvolvedores.skyhub.com.br/produtos/consultar-marcas). ### 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**](https://desenvolvedores.skyhub.com.br/produtos/categorizacao/consultar-atributos-por-categoria), 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." } ```