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
Não estão ainda em produção alterações a respeito de Categorização, Marcas e atributos de categorias.
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 seção Integração: Produto desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace
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.
Novo atributo no corpo do produto.
A partir de Março/2025, a raiz do produto poderá receber o atributo crossdocking.
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.
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.
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:
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.
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 porém importantes para enriquecimento de cadastro.
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/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
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
}
]
}
}'
