# Criação e atualização de produtos e variações no Marketplace

Visando a eficiência, precisão e agilidade, nossa API vai passar por uma reestruturação no que diz respeito à conexão de produtos

Toda solução integrada à nossa API, seja própria ou um ERP/Plataforma, deverá se adequar a essas novas alterações. 

## Produtos

#### Quais são essas alterações?

* A estrutura mercadológica deverá ser enviada no JSON do produto;
* As categorias terão agora seus atributos, que deverão ser enviados também no JSON do produto;
* A loja deverá enviar a marca, antes consultando uma lista de marcas disponíveis;
* Os preços de produto e variação **não poderão ser 0 ou nulo;**
* Os valores ausentes nas variações na criação e atualização de produtos variáveis serão herdados do pai;
* O atributo **crossdocking** agora deverá ser enviado na raiz do produto;
* As imagens do produto pai agora serão utilizadas como consolidador das imagens das variações;
* O mapeamento de atributos deixará de existir.

{% hint style="danger" %}
**Validação de preço e preço promocional**\
\
Ao criar e atualizar um produto os campos ***promotional\_price*** e ***price***, **não podem ser 0 ou nulos**.
{% endhint %}

{% hint style="warning" %}
**Mapeamento de atributos**\
\
O mapeamento de atributos deixa-rá de existir, o que significa que os valores antes mapeados agora deverão ser enviados na raiz do produto ou da variação.  Veja os campos disponíveis para substituir seus mapeamentos na seção [Herança de atributos](#heranca-dos-valores-dos-atributos-pai-nas-variacoes)
{% endhint %}

{% hint style="warning" %}
**Herança de atributos**\
\
Os valores ausentes nas variações durante a atualização de produto serão herdados do produto no momento da execução da requisição. Veja na seção [Herança de atributos](#heranca-dos-valores-dos-atributos-pai-nas-variacoes)
{% endhint %}

{% hint style="info" %}
**Atualização do pai em produtos com variação**\
\
Devido ao novo sistema de herança, atualizar apenas o pai em um produto com variações, não resultara em modificações nos filhos, sendo necessário informar uma variação para tal. Veja mais na seção [Como será agora?](#atualizacao-do-produto-pai-reflete-nos-filhos-ao-conectar-um-produto)
{% endhint %}

### <mark style="color:red;">Como era antes?</mark>

#### Categorias:

Eram definidas automaticamente por sistemas internos levando em consideração informações do produto.

#### Atributos de categoria:

Não existiam, apenas atributos de produto (que deixam de existir).&#x20;

Os atributos de produtos antes eram enviados dentro de 'specifications' com 'key' e 'value', este formato agora será alterado.

#### **Atualização do produto pai reflete nos filhos ao conectar um produto:**

Ao atualizar apenas o produto pai em produtos com variação, os valores presentes no pai poderiam ser utilizados nos filhos no momento da atualização.

#### Marca:

Era enviada como texto livre no JSON de produtos, no atributo "brand".

### <mark style="color:green;">Como será agora?</mark>

#### Categorias:

Deverá ser enviado à SkyHub, no JSON do produto, o ID da categoria na qual o lojista deseja que seu produto seja catalogado. Esse ID deverá ser previamente consultado em uma lista de categorias disponíveis.

#### Atributos de categoria:

Existirão atributos de categoria, obrigatórios ou não, que devem ser enviados no JSON do produto. Quanto mais atributos o lojista preencher, mais informações estarão presentes na oferta no Marketplace. Os atributos estarão disponíveis para consulta previamente.

#### **Atualização do produto pai reflete nos filhos ao conectar um produto:**

Devido ao novo sistema de herança, as atualizações do pai **apenas serão aplicadas** nos filhos **no momento da interação pela API de criação/atualização de produto** se os campos em questão estiverem ausentes nos filhos. <mark style="color:red;">**Não mais no momento da conexão do produto.**</mark>

Dito isso, atualizar um produto com variação pelo [endpoint de atualização/criação](/produtos/criacao-de-produto/produto-variavel.md) de produtos, sem informar uma variação, não surtirá efeito.

#### Marca:

Assim como a categoria, deverá ser enviado à SkyHub, no JSON do produto, o ID da marca. Esse ID deverá ser previamente consultado em uma lista de marcas disponíveis.

## Atualização e criação com preço inválido:

São considerados preços invalidos quando ***price*** ou ***promotional\_price*** é **nulo** ou **zero**.

### <mark style="color:red;">Como era antes?</mark>

Anteriormente era possível criar um produto ou variação com preço inválido. Segue exemplo:

```json
curl --location '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 '{
    "product": {
        "sku": "P2022",
        "promotional_price": 0.0,
        "price": 0.0,
        "name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
        "width": 9.0,
        "weight": 0.056,
        "length": 17.0,
        "height": 4.0,
        "description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. "
    }
}'

```

**Response esperado:**

{% hint style="success" %}
201 \[Sucess] - Created
{% endhint %}

### <mark style="color:green;">Como será agora?</mark>

Preço inválidos retornarão um erro de validação durante a criação/atualização.

Exemplo de erro para mais de um **sku** com preço invalido:

```json
curl --location '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 '{
    "product": {
        "sku": "P2022",
        "promotional_price": 0.0,
        "price": 0.0,
        "name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
        "width": 9.0,
        "weight": 0.056,
        "length": 17.0,
        "height": 4.0,
        "description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. "
    }
}'
```

**Response esperado:**

{% hint style="danger" %}
422 \[Error] - Unprocessable Entity
{% endhint %}

```json
{
    "error": "O SKU [P2022] possue preço inválido. O preço não pode ser nulo ou igual a zero."
}
```

&#x20;Exemplo de erro para apenas um **sku** com preço invalido:

```json
curl --location '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 '{
  "product": {
      "sku": "P2022",
      "promotional_price": 0.0,
      "price": 0.0,
      "name": "Aspirador Nasal Com Sucção Para Bebês Com Estojo 11859 Buba",
      "width": 9.0,
      "weight": 0.056,
      "length": 17.0,
      "height": 4.0,
      "description": "O Aspirador Nasal com Estojo da Buba é ideal para limpar com segurança a congestão nasal do seu bebê. ",
      "variations": [
          {
              "sku": "P2022-var"
          },
          {
              "sku": "P2022-var2"
          }
      ]
  }
}'
```

**Response esperado:**

{% hint style="danger" %}
422 \[Error] - Unprocessable Entity
{% endhint %}

```json
{
    "error": "Os seguintes SKUs possuem preços inválidos: P2022-var, P2022-var2. O preço não pode ser nulo ou igual a zero."
}
```

{% hint style="info" %}
Note que os SKUs informados são apenas das variações, pois em um produto variável os valores são herdados do pai para criar as variações, e o pai funciona como um elemento agrupador. O mesmo é verdade para a validação dos erros, onde ambas as variações não possuem **weight,** que é um atributo obrigatório, mas ainda assim um erro de validação não é retornado para o mesmo, pois o valor é herdado do **payload** do pai.
{% endhint %}

#### Atualização de produto, apenas de estoque:

Para atualizar apenas o estoque sem sofrer com a validação de preço invalido, é possível enviar apenas o payload mínimo, com "sku" e "qty" para produtos simples e "sku", "variations\[].sku" e "variations\[].qty" para produtos com variação no payload de produtos.

```json
curl --location --request PUT 'https://api.skyhub.com.br/products/{SKU DO PRODUTO}\
--header 'X-User-Email: EMAIL' \
--header 'X-Api-Key: CHAVE API' \
--header 'X-Accountmanager-Key: Api' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "product": {
        "sku": "SKU",
        "qty": 122,
        "variations": [ // Necesário apenas para produtos com variação
            {
                "sku": "SKU_VARIATIONS",
                "qty": 130
            }
        ]
    }
}'

```

#### Atualização de imagens:

Ao adicionar ou atualizar imagens nas variações de um produto, essas imagens serão automaticamente incluídas no produto pai.

```json
{
  "images": [
    "https://example.com/img0l.png",
    "https://example.con/img02.png",
    "https://example.com/img03.png",
    "https://example.con/img04.png",
    "https://example.com/img05.png",
    "https://example.com/img06.png",
    "https://example.com/img07.png",
    "https://example.com/img08.png",

  ],
  "variations": [
    {
      "sku": "var-01",
      "images": [
        "https://example.com/img0l.png",
        "https://example.con/img02.png",
        "https://example.com/img03.png"
      ]
    },
    {
      "sku": "var-02",
      "images": [
        "https://example.con/img04.png",
        "https://example.com/img05.png",
        "https://example.com/img06.png",
        "https://example.com/img07.png"
      ]
    },
    {
      "sku": "var-03",
      "images": [
        "https://example.com/img08.png"
      ]
    }
  ]
}
```

#### Herança dos valores dos atributos pai nas variações:

Agora os valores ausentes nas variações serão **herdados automaticamente** do payload do produto pai no momento da criação/atualização caso não sejam repassadas. Lembre-se que SKU, quantidade, especificações e imagens precisam ser definidas individualmente para cada variação.

```json
{
    "product": {
        "sku": "P2022",
        "name": "Identificador de cédula falsa",
        "brand": "Skyhub",
        "categoryId": "24",
        "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
        "status": "enabled",
        "price": 100.00,
        "promotional_price": 99.00,
        "cost": 0.0,
        "weight": 0.100,
        "height": 20,
        "width": 30,
        "length": 20,
        "nbm": "98769898",
        "images": [
            "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
        ],
        "specifications": [
            {
                "id": "id_do_atributo",
                "value": "Texto livre",
                "key": "atributo"
            },
            {
                "id": "id_do_atributo",
                "key": "atributo",
                "value": "Texto livre",
                "idValue": "id_da_opcao_selecionavel"
            }
        ],
        "variations": [
            {
                "sku": "F2023",
                "status": "enabled",
                "qty": 10,
                "ean": "9876543210987",
                "weight": 0.100,
                "height": 20,
                "width": 30,
                "length": 20,
                "crossdocking": "3",
                "images": [
                    "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
                ],
                "specifications": [
                    {
                        "id": "29229",
                        "key": "atributo",
                        "value": "Texto livre",
                        "idValue": "49105"
                    }
                ]
            },
            {
                "sku": "F2024",
                "promotional_price": 89.99,
                "status": "enabled",
                "qty": 10,
                "ean": "9876543210985",
                "weight": 0.100,
                "height": 20,
                "width": 30,
                "length": 20,
                "crossdocking": "3",
                "images": [
                    "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
                ],
                "specifications": [
                    {
                        "id": "29229", // ID referente a voltagem
                        "key": "voltagem",
                        "value": "220v",
                        "idValue": "49106"
                    }
                ]
            },
            {
                "sku": "F2025",
                "qty": 10
            }
        ]
    }
}
```

**Response esperado:**

{% hint style="success" %}
201 \[Sucess] - Created
{% endhint %}

Exemplo de produto criado com sucesso da requisição:

```json
{
    "name": "Identificador de cédula falsa",
    "nbm": null,
    "ncm": null,
    "sku": "P2022",
    "brand": "Skyhub",
    "status": "enabled",
    "ean": null,
    "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
    "product_condition": null,
    "qty": 0,
    "crossdocking": 0,
    "price": 0.0,
    "promotional_price": 0.0,
    "height": 20.0,
    "width": 30.0,
    "length": 20.0,
    "weight": 0.1,
    "cost": 0.0,
    "images": [
        "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg",
        "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
    ],
    "variation_attributes": [],
    "variations": [
        {
            "ean": "9876543210987",
            "sku": "F2023",
            "name": "Identificador de cédula falsa",
            "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
            "nbm": "98769898",
            "ncm": null,
            "status": "enabled",
            "product_condition": null,
            "crossdocking": 3,
            "qty": 10,
            "price": 100.0,
            "cost": 0.0,
            "promotional_price": 99.0,
            "height": 20.0,
            "width": 30.0,
            "length": 20.0,
            "weight": 0.1,
            "images": [
                "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
            ],
            "specifications": [
                {
                    "id": "29229",
                    "key": "atributo",
                    "idValue": "49105",
                    "value": "Texto livre"
                }
            ]
        },
        {
            "ean": null,
            "sku": "F2025",
            "name": "Identificador de cédula falsa",
            "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
            "nbm": "98769898",
            "ncm": null,
            "status": "enabled",
            "product_condition": null,
            "crossdocking": 0,
            "qty": 10,
            "price": 100.0,
            "cost": 0.0,
            "promotional_price": 99.0,
            "height": 20.0,
            "width": 30.0,
            "length": 20.0,
            "weight": 0.1,
            "images": [],
            "specifications": []
        },
        {
            "ean": "9876543210985",
            "sku": "F2024",
            "name": "Identificador de cédula falsa",
            "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.",
            "nbm": "98769898",
            "ncm": null,
            "status": "enabled",
            "product_condition": null,
            "crossdocking": 3,
            "qty": 10,
            "price": 100.0,
            "cost": 0.0,
            "promotional_price": 89.99,
            "height": 20.0,
            "width": 30.0,
            "length": 20.0,
            "weight": 0.1,
            "images": [
                "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg"
            ],
            "specifications": [
                {
                    "id": "29229",
                    "key": "voltagem",
                    "idValue": "49106",
                    "value": "220v"
                }
            ]
        }
    ],
    "specifications": [
        {
            "id": "id_do_atributo",
            "key": "atributo",
            "idValue": "id_da_opcao_selecionavel",
            "value": "Texto livre"
        }
    ],
    "categories": [
        {
            "code": "24",
            "name": "Automação comercial"
        }
    ]
}
```

Note que na variação de sku <mark style="color:blue;">F2025</mark> houve uma herança de todos os atributos herdáveis do pai e a mesma recebeu o payload mínimo para a criação.

**Valores herdados para o filho:**&#x20;

* ean
* name
* description
* status
* crossdocking
* price
* cost
* promotional\_price
* height
* width
* length
* weight
* nbm
* nbc

**Valores&#x20;**<mark style="color:red;">**não**</mark>**&#x20;herdados para o filho:**

* qty
* img
* specifications
* sku

## Crossdocking

### <mark style="color:red;">Como era antes?</mark>

O crossdocking era enviado dentro do '**specifications**' com '*key*' e '*value*'. Dessa forma:

```json
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
  "variation": {
    "specifications": [
      {
        "value": "crossdocking",
        "key": "3"
      }
    ]
  }
}'
```

### <mark style="color:green;">Como será agora?</mark>

O crossdocking deverá ser enviado na raiz da variação. Dessa forma:

```json
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
  "variation": {
    "crossdocking": "3"
  }
}'
```

## Preço na variação

### <mark style="color:red;">Como era antes?</mark>

O preço e o preço promocional eram enviados dentro do '**specifications**' com '*key*' e '*value*'. Dessa forma:

```json
curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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 '{
  "variation": {
  	"specifications": [
  		{
  			"key": "price",
  			"value": "185.90"
  		},
  		{
  			"key": "promotional_price",
  			"value": "180.90"
  		}
  	]
  }
}'
```

### <mark style="color:green;">Como será agora?</mark>

O preço e o preço promocional deverão ser enviados no body da variação. Dessa forma:

<pre class="language-json"><code class="lang-json">curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \
--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' \
<strong>--header 'Content-Type: application/json' \
</strong>--data-raw '{
  "variation": {    
    "price": 158,
    "promotional_price": 126.4
    }
  }'
</code></pre>

## Objeto 'associations' descontinuado no GET individual de produto

### <mark style="color:red;">Como era antes?</mark>

No GET em /products/SKU\_PRODUTO, tinha a presença do array **associations**:

```
curl --location -g --request GET 'https://api.skyhub.com.br/products/{SKU}' \
--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'
```

#### Response antes da migração:

```
{
    "sku": "SKU do produto",
    "name": "Título",
    "description": "Descrição detalhada",
    "status": "disabled",
    "removed": false, 
    "qty": 5,
    "price": 100.0,
    "promotional_price": 80.0,
    "cost": 49.0,
    "weight": 3.0,
    "height": 1.0,
    "width": 1.0,
    "length": 1.0,
    "condition_type": null,
    "brand": "Marca",
    "ean": "1234567890123",
    "nbm": "11223344",
    "categories": [
        {
            "code": "01",
            "name": "SKYHUB"
        }
    ],
    "images": [
        "https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
    ],
    "specifications": [
    { 
                "key": "Tamanho",
                "value": "Único"
            },
            { 
                "key": "Crossdocking",
                "value": "3"
            }
    ],
    "associations": [
        {
            "platform": "B2W",
            "status": "linked"
        }
    ]
}
```

### <mark style="color:green;">Como será agora?</mark>

Este objeto não estará mais presente no retorno:

#### Response após a migração:

```
{
  "name": "Produto Genérico",
  "nbm": null,
  "ncm": null,
  "sku": "000000",
  "brand": "Marca Genérica",
  "status": "enabled",
  "ean": "0000000000000",
  "description": "Descrição genérica do produto. Informações detalhadas sobre tamanho, uso recomendado e materiais podem ser incluídas aqui. Ideal para demonstrar o uso de campos em uma estrutura de produto.",
  "product_condition": null,
  "qty": 0,
  "crossdocking": 0,
  "price": 50.00,
  "promotional_price": 40.00,
  "height": 10.0,
  "width": 10.0,
  "length": 10.0,
  "weight": 1.0,
  "cost": 20.0,
  "images": [
    "https://example.com/image1.png",
    "https://example.com/image2.png"
  ],
  "variation_attributes": [],
  "variations": [],
  "specifications": [
    {
      "id": "20",
      "key": "Produto Internacional",
      "idValue": "59",
      "value": "Não"
    },
    {
      "id": "18",
      "key": "Condição do Item",
      "idValue": "56",
      "value": "Novo"
    }
  ],
  "categories": []
}

```

## Confira nossa documentação atualizada:

{% content-ref url="/pages/-MG4Gis5UfYeVHsMwz1j" %}
[Criação de Produto](/produtos/criacao-de-produto.md)
{% endcontent-ref %}

## Confira nossas seções sobre categorização e marcas:

{% content-ref url="/pages/898KJnFAWyWmBWFg9E8R" %}
[Categorização](/produtos/categorizacao.md)
{% endcontent-ref %}

{% content-ref url="/pages/tBFjsMyZAgV9oaM1N5qo" %}
[Consultar Marcas](/produtos/consultar-marcas.md)
{% endcontent-ref %}

Em caso de dúvidas, estamos à disposição através do nosso [canal de atendimento](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2024/novo-canal-de-atendimento)


---

# 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/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace.md?ask=<question>
```

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.