Sinônimos de valores

Dicionário que aponta palavras alternativas (como "Sem manga") para a opção oficial de uma característica, usado ao criar opções.

Quem cadastra produtos escreve o mesmo valor de jeitos diferentes: o fornecedor manda "Sem manga", o catálogo da loja tem a opção "Sem mangas". Sem ajuda, o cadastro criaria uma opção duplicada. O dicionário de sinônimos resolve isso: cada característica de lista tem uma tabela de palavras alternativas, e cada palavra aponta para uma das opções existentes. Quando uma nova opção é criada com um texto que está no dicionário (veja Opções de uma característica), a plataforma usa a opção oficial no lugar de criar outra.

O sinônimo é guardado em minúsculas e com espaços repetidos juntos: Verde Claro é registrado como verde claro. Por isso a busca não diferencia maiúsculas de minúsculas. Um sinônimo pertence a uma característica e aponta para uma opção dessa mesma característica.

Todas as quatro operações exigem o privilégio manage_features e usam o id da característica no caminho.

Ler o dicionário

GET/api/v1/admin/features/{id}/synonymsAdmin

Listar os sinônimos de uma característica

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sinônimos retornados

json

{
  "synonyms": [
    { "synonym": "verde claro", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" }
  ]
}

Campos da resposta

synonymsarray

Entradas do dicionário. Vazio quando não há nenhuma.

synonyms[].synonymstring

Palavra alternativa, em minúsculas.

synonyms[].variant_iduuid

Opção oficial para a qual a palavra aponta.

Acrescentar um sinônimo

POST/api/v1/admin/features/{id}/synonymsAdmin

Acrescentar um sinônimo

Registra uma entrada sem tocar nas outras. Se o sinônimo já existe, passa a apontar para a nova opção. Prefira esta rota quando for resolver valores um a um, por exemplo ao revisar uma importação.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymstringobrigatório

Palavra alternativa. Não pode ser vazia.

variant_iduuidobrigatório

Opção oficial. Precisa pertencer à característica do caminho.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonym": "Verde Claro", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" }'

Resposta

200Sinônimo registrado

json

{ "status": "ok" }

Substituir o dicionário inteiro

PUT/api/v1/admin/features/{id}/synonymsAdmin

Substituir todos os sinônimos de uma característica

Apaga todas as entradas atuais e grava a lista enviada, em uma única transação. Serve para uma tela de gerenciamento que mostra e edita a tabela inteira. Enviar "synonyms": [] esvazia o dicionário.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymsarrayobrigatório

Lista completa de entradas.

synonymstringobrigatório

Palavra alternativa.

variant_iduuidobrigatório

Opção oficial para a qual ela aponta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonyms": [ { "synonym": "Lima", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" } ] }'

Resposta

200Dicionário substituído

json

{ "status": "ok" }

Remover um sinônimo

POST/api/v1/admin/features/{id}/synonyms/removeAdmin

Remover um sinônimo

Apaga uma entrada pelo texto. É um POST (e não um DELETE) porque o texto livre, com espaços e acentos, não cabe bem no caminho. Se o sinônimo não existir, a resposta continua 200.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymstringobrigatório

Palavra a remover. Maiúsculas e espaços são normalizados como no cadastro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms/remove" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonym": "Verde Claro" }'

Resposta

200Sinônimo removido

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
400	Inclusão sem `synonym` ou sem `variant_id`, ou remoção sem `synonym`	`{"error":"invalid body","detail":"synonym e variant_id são obrigatórios"}` ou `{"error":"invalid body","detail":"synonym é obrigatório"}` (textos em português, como o servidor devolve)
400	`variant_id` de outra característica ou que não existe	`{"error":"failed","detail":"o valor escolhido não pertence a esta característica"}`
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
500	Falha ao gravar (por exemplo, `id` que não é UUID)	`{"error":"failed","detail":"..."}`

Veja também

API atual/Guia rápido/Características

Sinônimos de valores

Dicionário que aponta palavras alternativas (como "Sem manga") para a opção oficial de uma característica, usado ao criar opções.

Todas as quatro operações exigem o privilégio manage_features e usam o id da característica no caminho.

Ler o dicionário

GET/api/v1/admin/features/{id}/synonymsAdmin

Listar os sinônimos de uma característica

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sinônimos retornados

json

{
  "synonyms": [
    { "synonym": "verde claro", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" }
  ]
}

Campos da resposta

synonymsarray

Entradas do dicionário. Vazio quando não há nenhuma.

synonyms[].synonymstring

Palavra alternativa, em minúsculas.

synonyms[].variant_iduuid

Opção oficial para a qual a palavra aponta.

Acrescentar um sinônimo

POST/api/v1/admin/features/{id}/synonymsAdmin

Acrescentar um sinônimo

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymstringobrigatório

Palavra alternativa. Não pode ser vazia.

variant_iduuidobrigatório

Opção oficial. Precisa pertencer à característica do caminho.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonym": "Verde Claro", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" }'

Resposta

200Sinônimo registrado

json

{ "status": "ok" }

Substituir o dicionário inteiro

PUT/api/v1/admin/features/{id}/synonymsAdmin

Substituir todos os sinônimos de uma característica

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymsarrayobrigatório

Lista completa de entradas.

synonymstringobrigatório

Palavra alternativa.

variant_iduuidobrigatório

Opção oficial para a qual ela aponta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonyms": [ { "synonym": "Lima", "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01" } ] }'

Resposta

200Dicionário substituído

json

{ "status": "ok" }

Remover um sinônimo

POST/api/v1/admin/features/{id}/synonyms/removeAdmin

Remover um sinônimo

Apaga uma entrada pelo texto. É um POST (e não um DELETE) porque o texto livre, com espaços e acentos, não cabe bem no caminho. Se o sinônimo não existir, a resposta continua 200.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

synonymstringobrigatório

Palavra a remover. Maiúsculas e espaços são normalizados como no cadastro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/synonyms/remove" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "synonym": "Verde Claro" }'

Resposta

200Sinônimo removido

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
400	Inclusão sem `synonym` ou sem `variant_id`, ou remoção sem `synonym`	`{"error":"invalid body","detail":"synonym e variant_id são obrigatórios"}` ou `{"error":"invalid body","detail":"synonym é obrigatório"}` (textos em português, como o servidor devolve)
400	`variant_id` de outra característica ou que não existe	`{"error":"failed","detail":"o valor escolhido não pertence a esta característica"}`
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
500	Falha ao gravar (por exemplo, `id` que não é UUID)	`{"error":"failed","detail":"..."}`