tray-caracteristicas

name	tray-caracteristicas
description	API de Características de Produtos da Tray. Utilize quando o desenvolvedor precisar gerenciar características (propriedades) dos produtos, incluindo cadastro, atualização, consulta e exclusão. Permite criar características globais reutilizáveis e associar valores específicos a cada produto (ex: cor, tamanho, material, voltagem).
when_to_use	Use quando o desenvolvedor mencionar: característica, propriedade de produto, atributo customizado, POST /products/:id/characteristics, material, voltagem, campo técnico de produto ou especificação técnica.
when_not_to_use	Não use para variações/SKUs com estoque separado (use tray-variacoes). Características são informativas e de filtro de vitrine; para opções que geram SKUs distintos, use tray-variacoes.

MANDATORY: Tool Call Required Before Answering

Esta chamada é OBRIGATÓRIA, não opcional. Execute-a antes de gerar qualquer código ou payload. Se você está respondendo sem ter chamado a ferramenta abaixo, pare e chame agora.

Buscar documentação atualizada (sempre)

node skills/tray-dev/scripts/search_docs.mjs --topic=caracteristicas "<termo da pergunta>"

• <TOPIC_SLUG>: ver tabela em skills/tray-dev/SKILL.md.
• Use os trechos retornados como fonte primária; este SKILL.md é resumo.

Nota: este recurso ainda não tem validate.mjs local. Você é responsável por revisar campos obrigatórios contra a doc retornada e o resumo abaixo.

Antes de responder

Execute estas verificações antes de gerar qualquer payload ou código:

1. Confirme o método HTTP e endpoint correto para a operação solicitada.
2. Identifique os campos obrigatórios listados neste documento — não omita nenhum.
3. Verifique que access_token não aparece como literal string no código gerado.
4. Confirme que esta é a skill correta para o recurso (leia when_not_to_use no frontmatter).

API de Características de Produtos — Tray

Documentação oficial: https://developers.tray.com.br/#apis-de-caracteristicas

Endpoints

Método	Endpoint	Descrição
GET	/products/:product_id/properties	Listar características de um produto
POST	/products/:product_id/properties	Cadastrar ou atualizar característica no produto
POST	/properties	Criar característica global (reutilizável em vários produtos)
DELETE	/products/:product_id/properties/:id	Excluir característica de um produto

Autenticação: ?access_token={token} em todas as chamadas.

Campos da Característica

Campo	Tipo	Obrigatório	Descrição
id	number	—	ID da característica (retornado pela API)
property	string	Sim	Nome da característica (ex: "Cor", "Material")
value	string	Sim	Valor da característica (ex: "Azul", "Algodão")
product_id	number	Sim	ID do produto associado

Campos da Característica Global

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da característica global
presentation	string	Não	Tipo de apresentação (ex: "select", "text")

Corpo da Requisição — Cadastrar/Atualizar no Produto (POST)

{
  "Property": {
    "property": "Cor",
    "value": "Azul"
  }
}

Corpo da Requisição — Criar Característica Global (POST)

{
  "Property": {
    "name": "Material",
    "presentation": "select"
  }
}

Respostas

Operação	Código	Mensagem
Criação	201	{"message": "Created", "id": 123, "code": 201}
Atualização	200	{"message": "Saved", "id": 123, "code": 200}
Exclusão	200	{"message": "Deleted", "id": 123, "code": 200}

Exemplo de Resposta — Listar Características

{
  "Properties": [
    {
      "Property": {
        "id": "1",
        "property": "Cor",
        "value": "Azul",
        "product_id": "123"
      }
    },
    {
      "Property": {
        "id": "2",
        "property": "Material",
        "value": "Algodão",
        "product_id": "123"
      }
    }
  ]
}

Boas Práticas

1. Use características globais — crie características globais com POST /properties para padronizar nomes e evitar duplicidade
2. Padronize valores — mantenha consistência nos valores (ex: sempre "Azul" e nunca "azul" ou "AZUL")
3. Consulte antes de criar — verifique as características existentes do produto antes de adicionar novas
4. Características para filtros — as características são usadas como filtros na vitrine; escolha nomes claros para o consumidor final
5. Não confunda com variações — características são informativas; para opções que geram SKUs diferentes (estoque separado), use variações

Como Usar no Claude Code

Exemplos de Prompt

• "adiciona as características Cor, Material e Voltagem ao produto 123"
• "como padronizo características reutilizáveis entre vários produtos?"
• "cria características globais de Material e depois vincula ao produto"
• "lista todas as características do produto 456"

O que o Claude faz

1. Distingue características globais (reutilizáveis) de características por produto
2. Gera código de criação global via POST /properties quando a padronização é necessária
3. Gera código de vínculo com o produto via POST /products/:id/properties
4. Inclui o wrapper Property correto em cada chamada

O que você recebe

• Código do fluxo: criar global → vincular ao produto (quando aplicável)
• Código de adição direta de característica a um produto específico
• Exemplos com múltiplas características em sequência
• Consulta de características existentes via GET /products/:id/properties

Pré-requisitos

• Produto já cadastrado com product_id disponível
• access_token configurado