Criar característica

Cadastra uma nova característica de produto (como Cor, Tamanho ou Marca) e, se você quiser, já cria as opções dela.

Use esta operação para cadastrar um atributo novo: "Cor", "Voltagem", "Material", "Peso". Depois de criada, a característica ainda não aparece em nenhum produto: o valor é informado em cada produto, e as opções das características de lista (Vermelho, Azul) são criadas no próprio corpo desta chamada, em variants.

Antes de criar, confira se a loja já tem a característica. Ao cadastrar a loja, a plataforma pode ter criado um conjunto padrão de características, e o nome de uma característica é único por tipo.

POST/api/v1.0/featuresAdmin

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. Responde 201 com o registro completo, já com as opções criadas.

Corpo da requisição

descriptionstringobrigatório

Nome da característica (neste contrato o campo se chama description). Tags HTML são removidas. Não pode repetir o nome de outra característica do mesmo tipo, sem diferenciar maiúsculas de minúsculas.

feature_typestringobrigatório

CSMTNOGE

Tipo em letra: C caixa de marcação, S lista, M lista múltipla, T texto, N número, O data, G grupo, E marca. Maiúscula ou minúscula. O nome do tipo por extenso (select, brand...) também é aceito. Qualquer outro valor volta 400.

filter_stylestring

color

Com color junto de feature_type igual a S, a característica é criada como cor (cada opção pode ter uma cor em hexadecimal). Qualquer outro valor é ignorado.

positionintegerpadrão: 0

Posição de ordenação, do menor para o maior.

variantsarray

Opções a criar junto com a característica.

variantstringobrigatório

Texto da opção. Passa para minúsculas e perde espaços repetidos ao ser gravado. Uma opção sem texto ou repetida é ignorada em silêncio.

positioninteger

Posição da opção. Se omitida (ou 0), vale a posição na lista enviada, a partir de 0.

colorstring

Cor em hexadecimal (#FF0000), para característica de cor.

Os campos company_id e status são aceitos mas ignorados: a característica nasce sempre ativa (A) e pertence à loja.

POST/api/featuresAdmin

Criar característica (forma sem versão)

Igual a /api/v1.0/features, com o mesmo corpo. A resposta traz feature_id (e os variant_id das opções) como números decimais dentro de uma string.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/features" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Cor",
    "feature_type": "S",
    "filter_style": "color",
    "position": 5,
    "variants": [
      { "variant": "Vermelho", "color": "#FF0000" },
      { "variant": "Azul", "color": "#0000FF" }
    ]
  }'

Resposta

201Característica criada

json

{
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "description": "Cor",
  "feature_type": "S",
  "company_id": "0",
  "position": 5,
  "status": "A",
  "categories_path": "",
  "purpose": "",
  "filter_style": "color",
  "variants": [
    { "variant_id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d", "variant": "vermelho", "position": 0, "color": "#FF0000" },
    { "variant_id": "ddde805a-9ca2-41bf-83f7-f16640a0d16d", "variant": "azul", "position": 1, "color": "#0000FF" }
  ],
  "feature_style": "color",
  "comparison": "N",
  "display_on_catalog": "N",
  "display_on_product": "N",
  "display_on_header": "N",
  "full_description": "",
  "prefix": "",
  "sufix": "",
  "group_id": ""
}

Os campos da resposta são os descritos em Listar características e Consultar característica. Guarde o feature_id: é a chave para consultar, alterar e excluir a característica e para gravar valores em produtos.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
400	`feature_type` ou `description` ausentes	`{"message":"Field 'feature_type' is required","status":400}` ou `{"message":"Field 'description' is required","status":400}`
400	Tipo desconhecido, ou nome repetido	`{"message":"invalid feature type: Q","status":400}`, `{"message":"duplicate_feature_name: a feature named \"Cor\" already exists","status":400}`
401	Sem credenciais ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também

Criar característica

Cadastra uma nova característica de produto (como Cor, Tamanho ou Marca) e, se você quiser, já cria as opções dela.

POST/api/v1.0/featuresAdmin

Criar característica

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. Responde 201 com o registro completo, já com as opções criadas.

Corpo da requisição

descriptionstringobrigatório

feature_typestringobrigatório

CSMTNOGE

filter_stylestring

color

Com color junto de feature_type igual a S, a característica é criada como cor (cada opção pode ter uma cor em hexadecimal). Qualquer outro valor é ignorado.

positionintegerpadrão: 0

Posição de ordenação, do menor para o maior.

variantsarray

Opções a criar junto com a característica.

variantstringobrigatório

Texto da opção. Passa para minúsculas e perde espaços repetidos ao ser gravado. Uma opção sem texto ou repetida é ignorada em silêncio.

positioninteger

Posição da opção. Se omitida (ou 0), vale a posição na lista enviada, a partir de 0.

colorstring

Cor em hexadecimal (#FF0000), para característica de cor.

Os campos company_id e status são aceitos mas ignorados: a característica nasce sempre ativa (A) e pertence à loja.

POST/api/featuresAdmin

Criar característica (forma sem versão)

Igual a /api/v1.0/features, com o mesmo corpo. A resposta traz feature_id (e os variant_id das opções) como números decimais dentro de uma string.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/features" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Cor",
    "feature_type": "S",
    "filter_style": "color",
    "position": 5,
    "variants": [
      { "variant": "Vermelho", "color": "#FF0000" },
      { "variant": "Azul", "color": "#0000FF" }
    ]
  }'

Resposta

201Característica criada

json

{
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "description": "Cor",
  "feature_type": "S",
  "company_id": "0",
  "position": 5,
  "status": "A",
  "categories_path": "",
  "purpose": "",
  "filter_style": "color",
  "variants": [
    { "variant_id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d", "variant": "vermelho", "position": 0, "color": "#FF0000" },
    { "variant_id": "ddde805a-9ca2-41bf-83f7-f16640a0d16d", "variant": "azul", "position": 1, "color": "#0000FF" }
  ],
  "feature_style": "color",
  "comparison": "N",
  "display_on_catalog": "N",
  "display_on_product": "N",
  "display_on_header": "N",
  "full_description": "",
  "prefix": "",
  "sufix": "",
  "group_id": ""
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
400	`feature_type` ou `description` ausentes	`{"message":"Field 'feature_type' is required","status":400}` ou `{"message":"Field 'description' is required","status":400}`
400	Tipo desconhecido, ou nome repetido	`{"message":"invalid feature type: Q","status":400}`, `{"message":"duplicate_feature_name: a feature named \"Cor\" already exists","status":400}`
401	Sem credenciais ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Não é administrador	`{"message":"Forbidden: admin scope required","status":403}`