tray-marcas

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/marcas/scripts/validate.mjs '<payload_json>' — valide a estrutura do payload de marca 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/marcas/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/marcas/scripts/validate.mjs '{"Brand":{"brand":"<nome>"}}'. 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 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.

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