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 seção 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.
Será necessário realizar a consulta na lista de categorias para obter o categoryId e preencher no body do JSON.
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
Como declarar atributos de categoria
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
}
]
}
}'
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."
}
Para isso, seguir a documentação .
Será necessário realizar a consulta das marcas para obter o brand e preencher no body do JSON.
Para isso, seguir a documentação .
Os atributos de categoria devem ser declarados dentro de "specifications", mas com distinções dependendo do tipo de atributo.
Conforme explicado em , há diferenças entre os tipos de atributos:
