# 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](https://desenvolvedores.skyhub.com.br/integracao-produtos#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**](https://desenvolvedores.skyhub.com.br/produtos/categorizacao/consultar-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**](https://desenvolvedores.skyhub.com.br/produtos/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**](https://desenvolvedores.skyhub.com.br/produtos/categorizacao/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: ```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." } ```