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
Atualização do pai em produtos com variação
Devido ao novo sistema de herança, atualizar apenas o pai em um produto com variações, não resultara em modificações nos filhos, sendo necessário informar uma variação para tal. Veja mais na seção Como será agora?
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:
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:
Response esperado:
422 [Error] - Unprocessable Entity
Exemplo de erro para apenas um sku com preço invalido:
Response esperado:
422 [Error] - Unprocessable Entity
Note que os SKUs informados são apenas das variações, pois em um produto variável os valores são herdados do pai para criar as variações, e o pai funciona como um elemento agrupador. O mesmo é verdade para a validação dos erros, onde ambas as variações não possuem weight, que é um atributo obrigatório, mas ainda assim um erro de validação não é retornado para o mesmo, pois o valor é herdado do payload do pai.
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.
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.
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.
Response esperado:
201 [Sucess] - Created
Exemplo de produto criado com sucesso da requisição:
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:
Como será agora?
O crossdocking deverá ser enviado na raiz da variação. Dessa forma:
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:
Como será agora?
O preço e o preço promocional deverão ser enviados no body da variação. Dessa forma:
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 '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ê. "
}
}'
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ê. "
}
}'
{
"error": "O SKU [P2022] possue preço inválido. O preço não pode ser nulo ou igual a zero."
}
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"
}
]
}
}'
{
"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."
}
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"
}
]
}
}'
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"
}
}'
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"
}
]
}
}'
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
}
}'
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'
