Criação e atualização de produtos e variações no Marketplace
A partir do dia 31 de Março de 2025, será necessário incluir algumas informações essenciais no JSON do produto ao enviá-lo para a SkyHub. Saiba mais neste comunicado.
Visando a eficiência, precisão e agilidade, nossa API vai passar por uma reestruturação no que diz respeito à conexão de produtos
Toda solução integrada à nossa API, seja própria ou um ERP/Plataforma, deverá se adequar a essas novas alterações.
Produtos
Quais são essas alterações?
A estrutura mercadológica deverá ser enviada no JSON do produto;
As categorias terão agora seus atributos, que deverão ser enviados também no JSON do produto;
A loja deverá enviar a marca, antes consultando uma lista de marcas disponíveis;
Os preços de produto e variação não poderão ser 0 ou nulo;
Os valores ausentes nas variações na criação e atualização de produtos variáveis serão herdados do pai;
O atributo crossdocking agora deverá ser enviado na raiz do produto;
As imagens do produto pai agora serão utilizadas como consolidador das imagens das variações;
O mapeamento de atributos deixará de existir.
Validação de preço e preço promocional Ao criar e atualizar um produto os campos promotional_price e price, não podem ser 0 ou nulos.
Mapeamento de atributos O mapeamento de atributos deixa-rá de existir, o que significa que os valores antes mapeados agora deverão ser enviados na raiz do produto ou da variação. Veja os campos disponíveis para substituir seus mapeamentos na seção Herança de atributos
Herança de atributos Os valores ausentes nas variações durante a atualização de produto serão herdados do produto no momento da execução da requisição. Veja na seção Herança de atributos
Como era antes?
Categorias:
Eram definidas automaticamente por sistemas internos levando em consideração informações do produto.
Atributos de categoria:
Não existiam, apenas atributos de produto (que deixam de existir).
Os atributos de produtos antes eram enviados dentro de 'specifications' com 'key' e 'value', este formato agora será alterado.
Atualização do produto pai reflete nos filhos ao conectar um produto:
Ao atualizar apenas o produto pai em produtos com variação, os valores presentes no pai poderiam ser utilizados nos filhos no momento da atualização.
Marca:
Era enviada como texto livre no JSON de produtos, no atributo "brand".
Como será agora?
Categorias:
Deverá ser enviado à SkyHub, no JSON do produto, o ID da categoria na qual o lojista deseja que seu produto seja catalogado. Esse ID deverá ser previamente consultado em uma lista de categorias disponíveis.
Atributos de categoria:
Existirão atributos de categoria, obrigatórios ou não, que devem ser enviados no JSON do produto. Quanto mais atributos o lojista preencher, mais informações estarão presentes na oferta no Marketplace. Os atributos estarão disponíveis para consulta previamente.
Atualização do produto pai reflete nos filhos ao conectar um produto:
Devido ao novo sistema de herança, as atualizações do pai apenas serão aplicadas nos filhos no momento da interação pela API de criação/atualização de produto se os campos em questão estiverem ausentes nos filhos. Não mais no momento da conexão do produto.
Dito isso, atualizar um produto com variação pelo endpoint de atualização/criação de produtos, sem informar uma variação, não surtirá efeito.
Marca:
Assim como a categoria, deverá ser enviado à SkyHub, no JSON do produto, o ID da marca. Esse ID deverá ser previamente consultado em uma lista de marcas disponíveis.
Atualização e criação com preço inválido:
São considerados preços invalidos quando price ou promotional_price é nulo ou zero.
Como era antes?
Anteriormente era possível criar um produto ou variação com preço inválido. Segue exemplo:
curl --location '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 '{
"product": {
"sku": "P2022",
"promotional_price": 0.0,
"price": 0.0,
"name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
"width": 9.0,
"weight": 0.056,
"length": 17.0,
"height": 4.0,
"description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. "
}
}'
Response esperado:
201 [Sucess] - Created
Como será agora?
Preço inválidos retornarão um erro de validação durante a criação/atualização.
Exemplo de erro para mais de um sku com preço invalido:
curl --location '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 '{
"product": {
"sku": "P2022",
"promotional_price": 0.0,
"price": 0.0,
"name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
"width": 9.0,
"weight": 0.056,
"length": 17.0,
"height": 4.0,
"description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. "
}
}'Response esperado:
422 [Error] - Unprocessable Entity
{
"error": "O SKU [P2022] possue preço inválido. O preço não pode ser nulo ou igual a zero."
}Exemplo de erro para apenas um sku com preço invalido:
curl --location '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 '{
"product": {
"sku": "P2022",
"promotional_price": 0.0,
"price": 0.0,
"name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
"width": 9.0,
"weight": 0.056,
"length": 17.0,
"height": 4.0,
"description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. ",
"variations": [
{
"sku": "P2022-var"
},
{
"sku": "P2022-var2"
}
]
}
}'Response esperado:
422 [Error] - Unprocessable Entity
{
"error": "Os seguintes SKUs possuem preços inválidos: P2022-var, P2022-var2. O preço não pode ser nulo ou igual a zero."
}Atualização de produto, apenas de estoque:
Para atualizar apenas o estoque sem sofrer com a validação de preço invalido, é possível enviar apenas o payload mínimo, com "sku" e "qty" para produtos simples e "sku", "variations[].sku" e "variations[].qty" para produtos com variação no payload de produtos.
curl --location --request PUT 'https://api.skyhub.com.br/products/{SKU DO PRODUTO}\
--header 'X-User-Email: EMAIL' \
--header 'X-Api-Key: CHAVE API' \
--header 'X-Accountmanager-Key: Api' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"product": {
"sku": "SKU",
"qty": 122,
"variations": [ // Necesário apenas para produtos com variação
{
"sku": "SKU_VARIATIONS",
"qty": 130
}
]
}
}'
Atualização de imagens:
Ao adicionar ou atualizar imagens nas variações de um produto, essas imagens serão automaticamente incluídas no produto pai.
{
"images": [
"https://example.com/img0l.png",
"https://example.con/img02.png",
"https://example.com/img03.png",
"https://example.con/img04.png",
"https://example.com/img05.png",
"https://example.com/img06.png",
"https://example.com/img07.png",
"https://example.com/img08.png",
],
"variations": [
{
"sku": "var-01",
"images": [
"https://example.com/img0l.png",
"https://example.con/img02.png",
"https://example.com/img03.png"
]
},
{
"sku": "var-02",
"images": [
"https://example.con/img04.png",
"https://example.com/img05.png",
"https://example.com/img06.png",
"https://example.com/img07.png"
]
},
{
"sku": "var-03",
"images": [
"https://example.com/img08.png"
]
}
]
}Herança dos valores dos atributos pai nas variações:
Agora os valores ausentes nas variações serão herdados automaticamente do payload do produto pai no momento da criação/atualização caso não sejam repassadas. Lembre-se que SKU, quantidade, especificações e imagens precisam ser definidas individualmente para cada variação.
{
"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": [
{
"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",
"key": "atributo",
"value": "Texto livre",
"idValue": "49105"
}
]
},
{
"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"
}
]
},
{
"sku": "F2025",
"qty": 10
}
]
}
}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": null,
"sku": "F2025",
"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": 0,
"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": [],
"specifications": []
},
{
"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"
}
]
}Note que na variação de sku F2025 houve uma herança de todos os atributos herdáveis do pai e a mesma recebeu o payload mínimo para a criação.
Valores herdados para o filho:
ean
name
description
status
crossdocking
price
cost
promotional_price
height
width
length
weight
nbm
nbc
Valores não herdados para o filho:
qty
img
specifications
sku
Crossdocking
Como era antes?
O crossdocking era enviado dentro do 'specifications' com 'key' e 'value'. Dessa forma:
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
"variation": {
"specifications": [
{
"value": "crossdocking",
"key": "3"
}
]
}
}'Como será agora?
O crossdocking deverá ser enviado na raiz da variação. Dessa forma:
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
"variation": {
"crossdocking": "3"
}
}'Preço na variação
Como era antes?
O preço e o preço promocional eram enviados dentro do 'specifications' com 'key' e 'value'. Dessa forma:
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
"variation": {
"specifications": [
{
"key": "price",
"value": "185.90"
},
{
"key": "promotional_price",
"value": "180.90"
}
]
}
}'Como será agora?
O preço e o preço promocional deverão ser enviados no body da variação. Dessa forma:
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
"variation": {
"price": 158,
"promotional_price": 126.4
}
}'Objeto 'associations' descontinuado no GET individual de produto
Como era antes?
No GET em /products/SKU_PRODUTO, tinha a presença do array associations:
curl --location -g --request GET 'https://api.skyhub.com.br/products/{SKU}' \
--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'Response antes da migração:
{
"sku": "SKU do produto",
"name": "Título",
"description": "Descrição detalhada",
"status": "disabled",
"removed": false,
"qty": 5,
"price": 100.0,
"promotional_price": 80.0,
"cost": 49.0,
"weight": 3.0,
"height": 1.0,
"width": 1.0,
"length": 1.0,
"condition_type": null,
"brand": "Marca",
"ean": "1234567890123",
"nbm": "11223344",
"categories": [
{
"code": "01",
"name": "SKYHUB"
}
],
"images": [
"https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
],
"specifications": [
{
"key": "Tamanho",
"value": "Único"
},
{
"key": "Crossdocking",
"value": "3"
}
],
"associations": [
{
"platform": "B2W",
"status": "linked"
}
]
}Como será agora?
Este objeto não estará mais presente no retorno:
Response após a migração:
{
"name": "Produto Genérico",
"nbm": null,
"ncm": null,
"sku": "000000",
"brand": "Marca Genérica",
"status": "enabled",
"ean": "0000000000000",
"description": "Descrição genérica do produto. Informações detalhadas sobre tamanho, uso recomendado e materiais podem ser incluídas aqui. Ideal para demonstrar o uso de campos em uma estrutura de produto.",
"product_condition": null,
"qty": 0,
"crossdocking": 0,
"price": 50.00,
"promotional_price": 40.00,
"height": 10.0,
"width": 10.0,
"length": 10.0,
"weight": 1.0,
"cost": 20.0,
"images": [
"https://example.com/image1.png",
"https://example.com/image2.png"
],
"variation_attributes": [],
"variations": [],
"specifications": [
{
"id": "20",
"key": "Produto Internacional",
"idValue": "59",
"value": "Não"
},
{
"id": "18",
"key": "Condição do Item",
"idValue": "56",
"value": "Novo"
}
],
"categories": []
}
Confira nossa documentação atualizada:
Criação de ProdutoConfira nossas seções sobre categorização e marcas:
CategorizaçãoConsultar MarcasEm caso de dúvidas, estamos à disposição através do nosso canal de atendimento
Last updated