tray-variacoes

name	tray-variacoes
description	API de Variações de Produtos da Tray. Utilize quando o desenvolvedor precisar gerenciar variantes de produtos (SKUs) como diferentes tamanhos, cores ou modelos. Inclui listagem, consulta, cadastro, atualização, exclusão e informações sobre limitações de variações por produto.
when_to_use	Use quando o desenvolvedor mencionar: variação, SKU, tamanho, cor, modelo, atributo de produto, POST /variants, PUT /variants, estoque por variação, preço de variação, código EAN de SKU ou limitação de variantes por produto.
when_not_to_use	Não use para o produto pai (use tray-produtos) nem para características informativas sem estoque separado (use tray-caracteristicas). Use para SKUs com atributos como cor e tamanho.

MANDATORY: Tool Calls Required Before Answering

Estas chamadas são OBRIGATÓRIAS, não opcionais. Execute-as antes de gerar qualquer código ou payload. Se você está respondendo sem ter chamado as duas ferramentas abaixo, pare e chame agora.

1. Buscar documentação atualizada (sempre)

node skills/tray-dev/scripts/search_docs.mjs --topic=variacoes "<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.

2. Validar payload localmente (antes de retornar código)

node skills/variacoes/scripts/validate.mjs --schema=<SCHEMA_NAME> '<payload_json>'

• Schemas disponíveis: variacao.create, variacao.update. Use --list-schemas para confirmar.
• Exit codes: 0 válido · 1 inválido · 2 erro de uso.
• Para output programático: --json.
• Corrija todos os erros antes de retornar o código (até 3 tentativas).

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 Variações de Produtos — Tray

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

Endpoints

Método	Endpoint	Descrição
GET	/variants	Listagem de variações com paginação
GET	/variants/:id	Consultar dados de uma variação
POST	/variants	Cadastrar nova variação
PUT	/variants/:id	Atualizar dados da variação
DELETE	/variants/:id	Excluir variação

Autenticação: ?access_token={token}

Campos da Variação

Campo	Tipo	Obrigatório (create)	Descrição
product_id	number	Sim	ID do produto pai
type_1	string	Sim	Nome do 1º atributo (ex: "Cor")
value_1	string	Sim	Valor do 1º atributo (ex: "Azul")
type_2	string	Condicional	Nome do 2º atributo; obrigatório se value_2 presente
value_2	string	Condicional	Valor do 2º atributo; obrigatório se type_2 presente
price	decimal	Não	Preço da variação (herda do produto se não informado)
cost_price	decimal	Não	Preço de custo
stock	number	Não	Estoque da variação
ean	string	Não	Código de barras da variação
reference	string	Não	Referência interna da variação
weight	number	Não	Peso em gramas
length	number	Não	Comprimento
width	number	Não	Largura
height	number	Não	Altura

⚠️ Atributos são campos planos type_N/value_N, NÃO um array. A API não aceita um campo values: [{name, value}] — esse formato resulta em erro de validação (campos type_1/value_1 ausentes). A plataforma suporta no máximo 2 eixos de atributo: type_1/value_1 e type_2/value_2.

Se type_1 for "Cor" ou "Color", a API resolve a cor (color_id) automaticamente a partir de value_1.

Herança de Dados

Quando um campo não é informado na variação, ele herda o valor do produto pai. Isso se aplica a: price, weight, length, width, height.

Limitação de Variações por Produto

A plataforma Tray impõe um limite de variações por produto. Consulte a seção "Limitação de variações por produto" na documentação oficial para os limites atuais.

Corpo da Requisição (POST/PUT)

Cada combinação de atributos é uma variação = uma chamada POST /variants:

{
  "Variant": {
    "product_id": 123,
    "type_1": "Cor",
    "value_1": "Azul",
    "type_2": "Tamanho",
    "value_2": "M",
    "price": "89.90",
    "stock": 50,
    "ean": "7891234567890"
  }
}

Criar múltiplas variações

Para um produto com várias combinações, faça uma chamada por combinação. Ex.: iPhone 15 nas cores Prata, Preto e Dourado, todos 256GB → 3 chamadas, variando apenas value_1:

// Variação 1
{ "Variant": { "product_id": 123, "type_1": "Cor", "value_1": "Prata",   "type_2": "Armazenamento", "value_2": "256GB" } }
// Variação 2
{ "Variant": { "product_id": 123, "type_1": "Cor", "value_1": "Preto",   "type_2": "Armazenamento", "value_2": "256GB" } }
// Variação 3
{ "Variant": { "product_id": 123, "type_1": "Cor", "value_1": "Dourado", "type_2": "Armazenamento", "value_2": "256GB" } }

Paginação

Mesmos parâmetros da API de Produtos: limit (máximo 50, padrão 30), page.

Imagens de Variação

As imagens de variação são gerenciadas pela API de Imagens separada (POST /variants/:id/images). Consulte o skill tray-imagens-produtos.

Como Usar no Claude Code

Exemplos de Prompt

• "adiciona variações de tamanho e cor ao produto 456"
• "atualiza o estoque da variação tamanho M cor azul"
• "lista todas as variações do produto 123"
• "como crio variações com preço e estoque individuais?"

O que o Claude faz

1. Gera o código com o wrapper Variant e o product_id do produto pai
2. Define os atributos em campos planos type_1/value_1 (e type_2/value_2 se houver 2 eixos)
3. Define campos individuais da variação (preço, estoque, EAN) quando necessário
4. Gera uma chamada por combinação de atributos quando há múltiplas variações
5. Explica a herança de dados do produto pai para campos não informados

O que você recebe

• Código de criação de variação com wrapper {"Variant": {...}} correto
• Atributos nos campos type_1/value_1 e type_2/value_2 (nunca array values)
• Lógica de herança explicada (quais campos herdam do produto pai)
• Exemplo de listagem por product_id

Pré-requisitos

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