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
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.
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.
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.
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.
{
"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.
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.
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, 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.
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/productsRequest 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:
{
"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"
}
]
}
]
}
}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.
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:
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:
201 [Sucess] - Created
Exemplo de produto criado com sucesso da requisição:
{
"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.
422 [Error] - Unprocessable Entity
Response body:
{
"error": "Os seguintes SKUs possuem preços inválidos: F2023, F2024. O preço não pode ser nulo ou igual a zero."
}Last updated