tray-kits

name	tray-kits
description	API de Kits de Produtos da Tray. Utilize quando o desenvolvedor precisar gerenciar kits (combos/bundles) de produtos, incluindo listagem, consulta individual, criação e atualização. Permite agrupar múltiplos produtos em um único kit com quantidades específicas, ideal para combos promocionais e pacotes de produtos.
when_to_use	Use quando o desenvolvedor mencionar: kit, combo, bundle, pacote de produtos, GET /kits, POST /kits, grupo de produtos, venda casada ou produto composto.
when_not_to_use	Não use para produtos simples (use tray-produtos) nem para variações/SKUs (use tray-variacoes). Use apenas para combos ou bundles de múltiplos produtos.

MANDATORY: Tool Call Required Before Answering

Esta chamada é OBRIGATÓRIA, não opcional. Execute-a antes de gerar qualquer código ou payload. Se você está respondendo sem ter chamado a ferramenta abaixo, pare e chame agora.

Buscar documentação atualizada (sempre)

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

Nota: este recurso ainda não tem validate.mjs local. Você é responsável por revisar campos obrigatórios contra a doc retornada e o resumo abaixo.

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 Kits de Produtos — Tray

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

Endpoints

Método	Endpoint	Descrição
GET	/products/kits	Listagem de kits com paginação
GET	/products/kits/:id	Consultar dados de um kit por ID
POST	/products/kits	Cadastrar novo kit
PUT	/products/kits/:id	Atualizar dados do kit

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

Nota: Para excluir um kit, use DELETE /kits/:id disponível na API de Produtos.

Campos do Kit

Campo	Tipo	Obrigatório	Descrição
id	number	—	ID do kit (retornado pela API)
product_id	number	Sim	ID do produto que compõe o kit
kit_product_id	number	Sim	ID do produto-kit (produto principal que representa o combo)
quantity	number	Sim	Quantidade do produto dentro do kit
product_parent_id	number	Sim	ID do produto pai (referência hierárquica do kit)

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

Corpo da Requisição (POST)

{
  "Kit": {
    "product_id": 456,
    "kit_product_id": 100,
    "quantity": 2,
    "product_parent_id": 100
  }
}

Corpo da Requisição (PUT)

{
  "Kit": {
    "quantity": 3
  }
}

Respostas

Operação	Código	Mensagem
Criação	201	{"message": "Created", "id": 50, "code": 201}
Atualização	200	{"message": "Saved", "id": 50, "code": 200}

Exemplo de Resposta — Listar Kits

{
  "paging": {
    "total": 5,
    "page": 1,
    "offset": 0,
    "limit": 30,
    "maxLimit": 50
  },
  "Kits": [
    {
      "Kit": {
        "id": "50",
        "product_id": "456",
        "kit_product_id": "100",
        "quantity": "2",
        "product_parent_id": "100"
      }
    }
  ]
}

Exemplo de Resposta — Consultar Kit por ID

{
  "Kit": {
    "id": "50",
    "product_id": "456",
    "kit_product_id": "100",
    "quantity": "2",
    "product_parent_id": "100"
  }
}

Fluxo de Criação de Kit

1. Crie o produto-kit — primeiro cadastre o produto principal que representará o combo via POST /products
2. Associe os produtos componentes — para cada produto que faz parte do kit, faça POST /products/kits informando o product_id do componente e o kit_product_id do produto principal
3. Defina quantidades — informe a quantidade de cada componente dentro do kit

Boas Práticas

1. Produto-kit deve existir — o kit_product_id deve referenciar um produto já cadastrado
2. Produtos componentes devem existir — o product_id também deve ser um produto válido
3. Estoque automático — o estoque do kit é calculado com base no menor estoque disponível dos componentes
4. Preço do kit — defina o preço do produto-kit diretamente no cadastro do produto principal
5. Evite loops — não inclua um kit como componente de outro kit
6. Para excluir — use DELETE /kits/:id da API de Produtos para remover o vínculo do kit

Como Usar no Claude Code

Exemplos de Prompt

• "cria um kit com 2 camisetas + 1 boné a partir dos produtos 101, 102 e 103"
• "como configuro um combo promocional de produtos?"
• "lista todos os kits cadastrados na loja"
• "atualiza a quantidade do produto 101 dentro do kit 50"

O que o Claude faz

1. Guia o fluxo de 3 etapas: criação do produto-kit → associação de componentes → definição de quantidades
2. Gera código sequencial com os IDs necessários em cada etapa
3. Explica o cálculo automático de estoque (menor estoque entre os componentes)
4. Inclui o wrapper Kit correto no body de cada chamada

O que você recebe

• Código do fluxo completo de criação de kit com múltiplos componentes
• Sequência correta de chamadas (produto pai → POST /products/kits para cada componente)
• Exemplo de atualização de quantidade com PUT /products/kits/:id
• Nota sobre como excluir via DELETE /kits/:id

Pré-requisitos

• Produto-kit (produto principal do combo) já cadastrado via tray-produtos
• Produtos componentes já cadastrados com IDs disponíveis
• access_token configurado