# Tray Marcas

> 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.

- Skill: `tray-tecnologia/tray-marcas` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add tray-tecnologia/tray-marcas`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tray-tecnologia/tray-marcas/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tray-tecnologia (https://skillmd.com/u/tray-tecnologia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tray-tecnologia/tray-marcas

---


## 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)

```bash
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)

```bash
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)

```json
{
  "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

```json
{
  "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

```json
{
  "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