Produto Simples
O produto simples é único, não possuindo variação de SKU. Nesta seção temos a estrutura para este tipo de produto, assim como orientações para a sua criação
O produto simples é aquele que possui uma estrutura única, sem SKUs agrupados (variações).
Atributos como cor, tamanho e voltagem podem ser definidos tanto a nível de produto quanto a nível de SKU (variações). Será necessário consultar a lista de atributos da categoria e identificar se a categoria aceita esses atributos, porém detalhamos mais abaixo.
Mesmo para produtos simples é necessário haver atributos e informações que fortaleçam a identidade do item, como um título claro e atributos de ficha técnica. Acompanhe o exemplo abaixo:
Quando tratamos um livro, por exemplo, é necessário fornecer o nome completo da obra, além de atributos de ficha técnica como tipo de capa, idioma, quantidade de páginas e outros para enriquecer o cadastro do produto 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 simples via API.
Estrutura do JSON
A estrutura básica para a criação de um produto simples 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 simples 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 do item.
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", // String
"name": "Título", // String
"brand": "CodigoMarca", // String
"categoryId": "IdCategoria", // String
"description": "Descrição", // String
"status": "enabled", // String
"qty": 0, // Integer
"crossdocking": "3", // 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
"ean": "EAN (European Article Number ou Numeração Europeia de Artigos, o código de barras do item)", // String
"nbm": "NCM (Nomenclatura Comum do Mercosul)", // String
"images": [ // Array
"URL da imagem" // String
],
"specifications": [ // Array
{ // Object
"id": "Valor", // String
"key”: "valor", // String
"idValue": “valor”, // String
"value”: "valor" // String
},
{ // Object
"key”: "valor", // String
"id": "valor", // String
"value": "valor" // 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 IDs disponíveis 'id', 'id1', 'id2' e 'id3'. Os IDs enumerados representam os níveis de categorias, enquanto o ID em verde representa toda a estrutura. Qualquer um desses IDs 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, há diferenças entre os tipos de atributos:
Atributos de Livre preenchimento: Em "specifications" a key “value” e “key” ainda são obrigatórias.
Atributos com valores já pré-determinados: Caso a categoria da especificação seja uma do tipo que receba “idValue”, ainda sera necessário enviar “value”, com o valor correspondente e “key” com o atributo em si. Exemplo:
Imagine que o "idValue" represente “Sim”, então o payload seria:
{ “key”: “is_kit”, "id": "1", "idValue": "2", "value": "Sim" }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 deverá 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.
POST - Cadastrando um produto simples
Para realizar o cadastro de um produto via API deverá ser utilizado o método POST para o seguinte endpoint:
https://api.skyhub.com.br/productsRequest headers:
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
Request body:
{
"product": {
"sku": "CodigoSKU",
"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)
"qty": 0, // Estoque
"crossdocking": "3" // Crossdocking
"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
"ean": "EAN",
"nbm": "NBM/NCM",
"images": [
"https:// URL da imagem"
],
"specifications": [ // Objeto responsável pela inclusão de atributos adicionais
{ // Atributo de categoria - preenchimento livre
"id": "id do atributo",
"key”: "atributo",
"value": "Texto livre"
},
{ // Atributo de categoria - valores pré-determinados
"id": "id do atributo",
"idValue": "id da opção selecionável"
"value": "Texto livre"
}
]
}
}Exemplo de request:
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": "2022001",
"name": "Camiseta Branca Tam. Único",
"brand": "1739052110001030",
"categoryId": "556",
"description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta regata feminina, disponível na cor branca e tamanho único.",
"status": "enabled",
"qty": 1,
"crossdocking": "3",
"price": 39.90,
"promotional_price": 35.90,
"cost": 19.89,
"weight": 0.1,
"height": 25,
"width": 1,
"length": 30,
"ean": "1234567890123",
"nbm": "11223344",
"images": [
"https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
],
"specifications": [
{
// Exemplo de atributo de categoria - valores pré-determinados
"id": "28966", // id referente a ser Kit ou não
"idValue": "49069", // id referente a Não
"key": "kit", // Atributo em si
"value": "Não" // Valor do atributo
},
{
// Exemplo de atributo de categoria - preenchimento livre
"id": "28968", // id referente a Fabricante
"value": "Fabricador próprio", // texto livre
"key": "factory" // Atributo em si
}
]
}
}'Resposta esperada:
201 [Success] - Created
Resultado esperado no GET após a criação:
{
"name": "Camiseta Branca Tam. Único",
"nbm": "11223344",
"ncm": null,
"sku": "2022001",
"brand": "1739052110001030",
"status": "enabled",
"ean": "1234567890123",
"description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta regata feminina, disponível na cor branca e tamanho único.",
"product_condition": null,
"qty": 1,
"crossdocking": 3,
"price": 39.9,
"promotional_price": 35.9,
"height": 25.0,
"width": 1.0,
"length": 30.0,
"weight": 0.1,
"cost": 19.89,
"images": [
"https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg",
"https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
],
"variation_attributes": [],
"variations": [
{
"ean": "1234567890123",
"sku": "2022001",
"name": "Camiseta Branca Tam. Único",
"description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta regata feminina, disponível na cor branca e tamanho único.",
"nbm": "11223344",
"ncm": null,
"status": "enabled",
"product_condition": null,
"crossdocking": 3,
"qty": 1,
"price": 39.9,
"cost": 19.89,
"promotional_price": 35.9,
"height": 25.0,
"width": 1.0,
"length": 30.0,
"weight": 0.1,
"images": [
"https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
],
"specifications": []
}
],
"specifications": [
{
"id": "28966",
"key": "kit",
"idValue": "49069",
"value": "Não"
},
{
"id": "28968",
"key": "factory",
"idValue": null,
"value": "Fabricador próprio"
}
],
"categories": [
{
"code": "556",
"name": "Maionese"
}
]
}Resultado esperado caso price ou promotional price não sejam válidos:
422 [Error] - Unprocessable Entity
{
"error": "O SKU [2022001] possue preço inválido. O preço não pode ser nulo ou igual a zero."
}Last updated