tray-produtos

MANDATORY: Tool Call(s) Required Before Answering

• OBRIGATÓRIO: node skills/tray-dev/scripts/search_docs.mjs "<termo>" — confirme o comportamento da API antes de gerar código.
• OBRIGATÓRIO: node skills/produtos/scripts/validate.mjs '<payload_json>' — valide a estrutura do payload antes de retornar código ao usuário.

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)