# Tray Variacoes

> 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.

- Skill: `tray-tecnologia/tray-variacoes` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add tray-tecnologia/tray-variacoes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tray-tecnologia/tray-variacoes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tray-tecnologia (https://skillmd.com/u/tray-tecnologia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tray-tecnologia/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)

```bash
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)

```bash
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`:

```json
{
  "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`:

```json
// 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