tray-produtos

name	tray-produtos
description	API de Produtos da Tray. Utilize quando o desenvolvedor precisar listar, consultar, cadastrar, atualizar ou excluir produtos no catálogo de uma loja Tray. Inclui todos os campos do produto (nome, preço, estoque, EAN, NCM, dimensões, SEO), filtros de listagem, paginação, ordenação e exclusão de kits.
when_to_use	Use quando o desenvolvedor mencionar: cadastrar produto, atualizar produto, sincronizar catálogo, preço, estoque, EAN, SKU, imagem de produto, POST /products, PUT /products, variação de produto ou importar produtos.
when_not_to_use	Não use para variações/SKUs (use tray-variacoes), imagens (use tray-imagens-produtos), kits/combos (use tray-kits) nem para características informativas (use tray-caracteristicas).

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).
5. Execute node skills/produtos/scripts/validate.mjs '<payload_json>' para confirmar a estrutura do payload que vai gerar. O validador checa apenas estrutura (campos obrigatórios, tipos e campos desconhecidos), nunca valores reais — então monte um payload sintético com placeholders sempre que os valores vierem de variáveis de ambiente, da entrada do usuário ou de outras chamadas. Exemplo: node skills/produtos/scripts/validate.mjs '{"Product":{"name":"<nome>","price":"<preço>"}}'. Corrija todos os erros antes de retornar o código ao usuário. Até 3 tentativas — se persistir, explique o problema ao usuário.

API de Produtos — Tray

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

Endpoints

Método	Endpoint	Descrição
GET	/products	Listagem de produtos com paginação, filtros e ordenação
GET	/products/:id	Consultar dados detalhados de um produto
POST	/products	Cadastrar novo produto
PUT	/products/:id	Atualizar dados do produto
DELETE	/products/:id	Excluir produto
DELETE	/kits/:id	Excluir kit de produto

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

Campos do Produto

Dados Básicos

Campo	Tipo	Limite	Descrição
name	string	200 chars	Nome do produto
ean	string	120 chars	Código de barras (EAN)
ncm	string	8 chars	Classificação fiscal (NCM)
description	string	4800 chars	Descrição completa
description_small	string	500 chars	Descrição curta
reference	string	120 chars	Referência interna

Preços

Campo	Tipo	Descrição
price	decimal	Preço de venda
cost_price	decimal	Preço de custo
promotional_price	decimal	Preço promocional
start_promotion	date (YYYY-MM-DD)	Início da promoção
end_promotion	date (YYYY-MM-DD)	Fim da promoção
ipi_value	decimal	Valor do IPI

Dimensões e Peso

Campo	Tipo	Descrição
weight	number	Peso em gramas
length	number	Comprimento
width	number	Largura
height	number	Altura
cubic_weight	number	Peso cúbico

Estoque e Disponibilidade

Campo	Tipo	Descrição
stock	number	Quantidade em estoque
available	number	0=indisponível, 1=disponível
available_in_store	number	0=oculto da vitrine, 1=visível
availability	string	Texto de disponibilidade (ex: "Disponível em 3 dias")
availability_days	number	Dias até disponível

Classificação

Campo	Tipo	Descrição
category_id	number	ID da categoria principal
brand	string (120)	Nome da marca
brand_id	number	ID da marca
model	string (150)	Modelo
related_categories	array	IDs de categorias adicionais

Exibição e Marketing

Campo	Tipo	Descrição
hot	number	0=normal, 1=destaque
release	number	0=lançado, 1=lançamento
release_date	date	Data de lançamento
virtual_product	string	0=físico, 1=digital/virtual
free_shipping	number	0=frete normal, 1=frete grátis
warranty	string	Descrição da garantia
upon_request	number	Produto sob consulta

SEO

Campo	Tipo	Descrição
metatag	object	{type: "keywords", content: "..."}
shortcut	string	Slug da URL

Paginação

Parâmetro	Descrição
limit	Itens por página (máximo 50, padrão 30)
page	Número da página

Resposta inclui: total, page, offset, limit, maxLimit

Filtros de Listagem

id, name, reference, ean, category_id, brand, available, available_in_store, stock, price, price_range, promotion, free_shipping, release, hot, quantity_sold, created, modified

Ordenação: parâmetro sort com nome do campo. rand para aleatório.

Corpo da Requisição (POST/PUT)

O body JSON deve envolver os dados na chave "Product":

{
  "Product": {
    "name": "Camiseta Exemplo",
    "price": "99.90",
    "stock": 100,
    "category_id": 1,
    "available": 1
  }
}

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}

Resposta de Consulta Individual

O endpoint GET /products/:id retorna o objeto Product com dados adicionais:

• Properties — características do produto
• payment_option_details — opções de parcelamento
• related_categories — categorias associadas
• all_categories — todas as categorias
• ProductImage — array de imagens com thumbnails (30px, 90px, 180px em HTTP e HTTPS)
• Variant — array de variações do produto

Como Usar no Claude Code

Exemplos de Prompt

• "cadastra um novo produto na loja com preço, estoque e categoria"
• "atualiza o estoque e o preço promocional do produto ID 123"
• "lista todos os produtos sem estoque disponível"
• "como filtro produtos por categoria e faixa de preço?"

O que o Claude faz

1. Identifica a operação desejada (criar, atualizar, listar ou consultar)
2. Gera o código com o wrapper Product obrigatório no body
3. Inclui os campos relevantes para o caso de uso (preço, estoque, dimensões, SEO)
4. Adiciona paginação e filtros se for listagem

O que você recebe

• Código funcional da chamada à API com todos os campos necessários
• Wrapper {"Product": {...}} correto no body
• Parâmetros de paginação (limit, page) e filtros aplicados
• Tratamento da resposta com os IDs gerados

Pré-requisitos

• access_token configurado
• category_id válido se for criar produto (use tray-categorias antes)
• brand_id válido se quiser associar marca (use tray-marcas antes)