Tray Variacoes

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

Autenticação: ?access_token={token}

Campos da Variação

⚠️ 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