Endpoint Atributos

Os atributos são elementos que ajudam a diferenciar ou descrever características de especificação técnica do produto criado

Esse endpoint foi descontinuado em Março/2025.

Por que algo simples é tão importante para o produto?

Os atributos são informações importantes para os filtros de categorias e para diferenciar os SKUs de um produto; quanto mais atributos/composição o produto tiver, mais chances terá de aparecer no filtro de categorias.

Abaixo temos alguns exemplos de atributos que são obrigatórios no marketplace (mktp) por categoria:

Atributos	Categoria
Cor	Moda
Sabor	Nutrição/Suplementos
Tamanho	Moda
Voltagem	Eletrodomésticos
Volumetria	Perfumes

Os produtos não devem se limitar apenas aos atributos mencionados acima, por exemplo, no seguimento de moda temos outros atributos/composição do produto, tais como marca, fabricante, dentre outros.

Para melhor compreensão de atributos obrigatórios, imagine uma loja do seguimento de moda vendendo no marketplace, o mktp precisa ter a informação de cor e tamanho de uma camiseta, pois estes são atributos de diferenciação para cada SKU do produto; através destes atributos será possível que o marketplace disponibilize as opções disponíveis para venda.

Agora que mencionamos a importância dessas informações, vamos à prática!

A API disponibiliza um endpoint para a criação de atributos que poderão ser utilizados para a caracterização dos produtos, assim como através do mesmo também é possível realizar a consulta dos atributos existentes na conta.

POST - Criando um atributo

A criação de atributos se dá a partir de um POST no endpoint a seguir:

https://api.skyhub.com.br/attributes

Request headers:

Key	Value
X-User-Email	email_de_usuario
X-Api-Key	token_de_integracao de sua conta SkyHub
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Accept	application/json
Content-Type	application/json

Request body:

{
  "attribute": {
    "name": "att_name", // [String] Identificador interno do atributo
    "label": "Atributo Exemplo", // [String] Label que será visualizada no front da API
    "options": [ // [Array] Campo opcional. Lista as opções do atributo caso ele seja do tipo 'select' (por exemplo, cor: azul, branca, vermelha)
      "foo",
      "foo",
      "foo"
    ]
  }
}

Example request:

curl --location --request POST 'https://api.skyhub.com.br/attributes' \
--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 '{
  "attribute": {
    "name": "Cor_Exemplo",
    "label": "Cor - Exemplo", 
    "options": [ 
      "Azul",
      "Branco",
      "Vermelho"
    ]
  }
}'

Response esperado:

201 - Created

Para visualizar o atributo diretamente no front da API, deve ser acessado o menu SkyHub > Atributos. A seguir temos a visualização retirada do front atual da API:

Na tela acima, o Código traz o campo name definido via API. Já o Título traz o valor preenchido para o campo label.

Caso esteja utilizando o antigo front da API, a sequência vista será Label e Código, que representam, respectivamente os campos label e name.

Dentre as melhores práticas, recomendamos fortemente que o atributo seja criado à parte, para posterior envio (vínculo) junto ao produto que deseja criar na API.

Não seguir a prática acima eleva a taxa de processamento da API, podendo ocasionar retornos menos eficientes: Os atributos também são criados ao serem incluídos na estrutura do produto; cada vez que um SKU é enviado para a API, nossa ferramenta verifica se seus atributos já existem para que seja realizada ou não a criação dos mesmos.

Com o atributo previamente criado, é possível seguir com a sua inclusão na estrutura do produto, ação que é exemplificada a seguir utilizando a base de um produto variável:

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": "2022002",
    "name": "Camiseta Tam. Único",
    "description": "Camiseta regata feminina, disponível na cor branca e tamanho único.",
    "status": "enabled",
    "price": 30.00,
    "promotional_price": 29.00,
    "cost": 19.90,
    "weight": 0.100,
    "height": 20,
    "width": 30,
    "length": 20,
    "brand": "SkyHub",
    "nbm": "11223344",
    "categories": [],
    "images": [
      "https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg"
    ],
    "specifications": [
      {
        "key": "Tamanho",
        "value": "Único"
      }
    ],
    "variations": [
      {
        "sku": "2022002A",
        "qty": 10,
        "ean": "1234567890123",
        "images": [],
        "specifications": [
          {
            "key": "Cor_Exemplo", // Código (name) do atributo
            "value": "Branco"
          }
        ]
      }
    ],
    "variation_attributes": [
      "Cor_Exemplo" // Em caso de produtos variáveis, o Código (name) também deverá ser adicionado ao array variation_attributes ao se tratar de um atributo diferenciador 
    ]
  }
}'

O campo a ser inserido no array specifications é o valor da coluna Código (aquele que demonstramos na tela de atributos do painel SkyHub), ou seja, será incluído o campo que via API foi identificado como name.

GET - Consultando os atributos existentes

A consulta visa listar todos os atributos criados em uma conta. A partir dos headers padronizados e sinalizados acima basta executar um GET no endpoint:

https://api.skyhub.com.br/attributes

Example request:

curl --location --request GET 'https://api.skyhub.com.br/attributes' \
--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 esperado:

200 - Success [OK]: O retorno da requisição trará uma lista com os atributos existentes na conta, sendo eles os padrões (como sku, status, description, entre outros) ou aqueles criados via API:

{
    "attributes": [
        {
            "name": "Altura",
            "label": "Altura",
            "type": "text"
        },
        {
            "name": "Anatel",
            "label": "Anatel",
            "type": "text"
        },
        {
            "name": "Cor",
            "label": "Cor",
            "type": "select"
        },
        {
            "name": "Garantia",
            "label": "Garantia",
            "type": "text"
        },
        {
            "name": "brand",
            "label": "brand",
            "type": "text"
        },
        {
            "name": "cost",
            "label": "cost",
            "type": "text"
        },
        {
            "name": "crossdocking",
            "label": "crossdocking",
            "type": "text"
        }
        (...)
    ]
}

Como informado em nosso guia de melhores práticas, nossa estrutura de criação de atributos não possibilita que trabalhe com a mesma string de um atributo com case sensitive tentando diferenciar essa criação.

Devido a esta regra é necessário que sempre utilize em seus produtos o atributo que foi usado pela primeira vez, o que torna a consulta de atributos um recurso extremamente importante para a sua integração com a API.

PUT - Atualizando um atributo

Para atualizar um determinado atributo que foi criado na API deverá ser realizada uma requisição com o método PUT, onde serão utilizados os headers padronizados e sinalizados acima no endpoint:

https://api.skyhub.com.br/attributes/{name}

É possível atualizar apenas a label (título do atributo na API) e as opções do atributo, o name (código) é mantido.

Request body:

{
  "attribute": {
    "label": "Atributo Atualizado",
    "options": [
      "foo",
      "foo",
      "foo"
    ]
  }
}

Example request:

curl --location --request PUT 'https://api.skyhub.com.br/attributes/Cor_Exemplo' \
--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 '{
  "attribute": {
    "label": "Cor - Exemplo Atualizado",
    "options": [
      "Azul",
      "Branco",
      "Vermelho",
      "Preto"
    ]
  }
}'

Response esperado:

204 [Success] - No content

Atributo de produtos em pré-venda

É possível tratar através da API a criação de produtos em pré-venda, para isso teremos o atributo com a label "dataLancamento" no qual o value deve conter a informação da data seguindo o padrão "DD/MM/AAAA", conforme cURL de exemplo disponibilizado a seguir:

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": "2022003",
    "name": "Produto Simples Para Pré-Venda",
    "description": "Criação de produto simples para a inclusão do atributo pré-venda",
    "status": "enabled",
    "qty": 0,
    "price": 100,
    "promotional_price": 89.99,
    "cost": 49.00,
    "weight": 3,
    "height": 1,
    "width": 1,
    "length": 1,
    "brand": "SkyHub",
    "ean": "1111333355557",
    "nbm": "22446688",
    "categories": [],
    "images": [
      "https://foo"
    ],
    "specifications": [
      {
        "key": "dataLancamento",
        "value": "31/12/2025"
      }
    ]
  }
}'