tray-marcas

name	tray-marcas
description	API de Marcas da Tray. Utilize quando o desenvolvedor precisar gerenciar as marcas (fabricantes) dos produtos da loja, incluindo listagem, consulta individual, criação, atualização e exclusão. Inclui os campos da marca (brand, slug), paginação e filtros.
when_to_use	Use quando o desenvolvedor mencionar: marca, fabricante, brand, GET /brands, POST /brands, PUT /brands, brand_id, filtrar por marca ou cadastrar fabricante.
when_not_to_use	Não use para categorias da loja (use tray-categorias) nem para características de produto como cor ou material (use tray-caracteristicas).

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=marcas "<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/marcas/scripts/validate.mjs --schema=<SCHEMA_NAME> '<payload_json>'

• Schemas disponíveis: marca.create, marca.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 Marcas — Tray

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

Endpoints

Método	Endpoint	Descrição
GET	/products/brands	Listagem de marcas com paginação e filtros
GET	/products/brands/:id	Consultar dados de uma marca por ID
POST	/products/brands	Cadastrar nova marca
PUT	/products/brands/:id	Atualizar dados da marca
DELETE	/products/brands/:id	Excluir marca

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

Alias não oficial: a rota /brands (sem o prefixo /products/) também retorna HTTP 200 nesta API, mas não é documentada oficialmente pela Tray. Use sempre /products/brands para garantir compatibilidade e aderência à documentação oficial.

Campos da Marca

Campo	Tipo	Obrigatório	Descrição
id	number	—	ID da marca (retornado pela API)
brand	string	Sim	Nome da marca
slug	string	Não	Slug para URL amigável (gerado automaticamente se não informado)

⚠️ O campo do nome da marca é brand, NÃO name. Enviar name resulta em "Invalid data provided" (HTTP 400) — a API ignora o campo desconhecido e falha por brand ausente. Os campos aceitos no payload são apenas brand e slug. Os campos description e image não existem nesta API de marcas.

Atenção (causa #1 de HTTP 400 neste recurso): o campo do nome da marca é brand, não name. Enviar {"Brand": {"name": "Nike"}} resulta em HTTP 400. Confirmado contra a doc oficial: o body e a resposta usam brand (ex.: {"Brand": {"slug": "nike", "brand": "Nike"}}), e o filtro de listagem também é brand (não name).

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

Filtro	Tipo	Descrição
id	number	Filtrar por ID da marca
brand	string	Filtrar por nome da marca

Corpo da Requisição (POST/PUT)

{
  "Brand": {
    "brand": "Nike",
    "slug": "nike"
  }
}

Respostas

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

Exemplo de Resposta — Listar Marcas

{
  "paging": {
    "total": 25,
    "page": 1,
    "offset": 0,
    "limit": 30,
    "maxLimit": 50
  },
  "Brands": [
    {
      "Brand": {
        "id": "1",
        "brand": "Nike",
        "slug": "nike"
      }
    }
  ]
}

Exemplo de Resposta — Consultar Marca por ID

{
  "Brand": {
    "id": "1",
    "brand": "Nike",
    "slug": "nike"
  }
}

Boas Práticas

1. Crie marcas antes dos produtos — ao cadastrar produtos, o brand_id deve referenciar uma marca existente
2. Use slugs descritivos — o slug é usado na URL da página de marca na vitrine; mantenha-o limpo e legível
3. Evite duplicidade — consulte a listagem antes de criar para evitar marcas duplicadas
4. Campo correto — use sempre brand para o nome da marca; name é ignorado e causa erro
5. Exclusão segura — não exclua marcas que possuam produtos associados; reatribua os produtos antes

Como Usar no Claude Code

Exemplos de Prompt

• "cadastra as marcas Nike, Adidas e Puma"
• "lista todas as marcas disponíveis na loja"
• "verifica se a marca Samsung já existe antes de criar"
• "atualiza o slug da marca ID 10"

O que o Claude faz

1. Gera o código de criação com wrapper Brand, usando o campo brand (e slug automático)
2. Inclui verificação de duplicidade via GET /products/brands?brand=... antes de criar
3. Monta o payload apenas com os campos aceitos (brand, slug)
4. Explica que o brand_id retornado deve ser usado ao cadastrar produtos

O que você recebe

• Código de criação de marca com wrapper {"Brand": {...}} correto e campo brand
• Verificação de duplicidade antes de criar
• brand_id extraído da resposta para uso em produtos
• Código de listagem com paginação

Pré-requisitos

• access_token configurado