# Produto Simples 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. {% hint style="info" %} A seção [Integração: Produto](/produtos/integracao-produtos.md#pre-requisitos) desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace {% endhint %} A seguir confira a estrutura esperada para a criação de um produto simples via API. ## Estrutura do JSON {% hint style="danger" %} **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. {% endhint %} {% hint style="info" %} **Novo atributo no corpo do produto.** A partir de Março/2025, a raiz do produto poderá receber o atributo *crossdocking*. {% endhint %} {% hint style="info" %} **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. {% endhint %} {% hint style="danger" %} **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**. {% endhint %} ```json { "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**](/produtos/categorizacao/consultar-categorias.md). 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**](/produtos/consultar-marcas.md).
### 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**](/produtos/categorizacao/consultar-atributos-por-categoria.md), 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: ```json { “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. {% hint style="info" %} 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. {% endhint %} ## 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:
KeyValue
X-User-Emailemail_de_usuario
X-Api-Keytoken_de_integracao de sua conta SkyHub
X-Accountmanager-keytoken_account único de cada Plataforma/ERP
Acceptapplication/json
Content-Typeapplication/json
#### Request body: ```json { "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: ```json 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: {% hint style="success" %} 201 \[Success] - Created {% endhint %} **Resultado esperado no GET após a criação:** ```json { "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: {% hint style="danger" %} 422 \[Error] - Unprocessable Entity {% endhint %} ```json { "error": "O SKU [2022001] possue preço inválido. O preço não pode ser nulo ou igual a zero." } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://desenvolvedores.skyhub.com.br/produtos/criacao-de-produto/produto-simples.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.