> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace.md).

# 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)