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

A partir do dia 31 de Março de 2025, será necessário incluir algumas informações essenciais no JSON do produto ao enviá-lo para a SkyHub. Saiba mais neste comunicado.

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.

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?

Como era antes?

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

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".

Como será agora?

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. Não mais no momento da conexão do produto.

Dito isso, atualizar um produto com variação pelo endpoint de atualização/criação 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.

Como era antes?

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

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:

Como será agora?

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:

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:

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

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

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:

{
    "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."
}

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.

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.

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.

{
  "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.

{
    "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:

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

{
    "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 F2025 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:

  • ean

  • name

  • description

  • status

  • crossdocking

  • price

  • cost

  • promotional_price

  • height

  • width

  • length

  • weight

  • nbm

  • nbc

Valores não herdados para o filho:

  • qty

  • img

  • specifications

  • sku

Crossdocking

Como era antes?

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

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"
      }
    ]
  }
}'

Como será agora?

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

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

Como era antes?

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

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"
  		}
  	]
  }
}'

Como será agora?

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

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": {    
    "price": 158,
    "promotional_price": 126.4
    }
  }'

Objeto 'associations' descontinuado no GET individual de produto

Como era antes?

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"
        }
    ]
}

Como será agora?

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:

Criação de Produto

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

CategorizaçãoConsultar Marcas

Em caso de dúvidas, estamos à disposição através do nosso canal de atendimento

Last updated