# Tray Dev

> Skill de busca em developers.tray.com.br. Utilize quando o desenvolvedor precisar de informações atualizadas sobre endpoints, parâmetros, formatos ou exemplos da API Tray oficial. Substitui referências estáticas envelhecidas por busca local sobre snapshot fresco da SPA.

- Skill: `tray-tecnologia/tray-dev` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tray-tecnologia/tray-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tray-tecnologia/tray-dev/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-dev

---


## Antes de responder

1. Identifique o termo de busca a partir da pergunta do usuário
2. Rode:

   ```
   node skills/tray-dev/scripts/search_docs.mjs "<termo>"
   ```

3. Use os resultados como **fonte primária**. Cite o link âncora retornado.
4. Se a busca retornar 0 resultados, avise o usuário e use seu conhecimento como fallback **explicitamente sinalizado**.
5. Se precisar restringir a um recurso, use `--topic=<slug>` (ver lista de tópicos).
6. Se precisar de output programático, use `--json`.

## Visão geral

`tray-dev` indexa localmente `https://developers.tray.com.br` (fetch + cache 24h) e oferece busca lexical (BM25) sobre todos os endpoints, campos, exemplos e códigos de erro da API Tray, em < 100 ms p95 com cache quente. Substitui a documentação estática que envelhece entre releases.

A primeira execução faz fetch da página pública (~1,6 MB de HTML), converte para Markdown (~660 KB), parseia em ~820 seções (H1/H2/H3) e indexa em `~/.cache/tray-plugin/dev-docs/`. Execuções subsequentes (24h) usam cache.

## CLI

### Sintaxe

```bash
node skills/tray-dev/scripts/search_docs.mjs "<query>"
node skills/tray-dev/scripts/search_docs.mjs --topic=<slug> "<query>"
node skills/tray-dev/scripts/search_docs.mjs --json "<query>"
node skills/tray-dev/scripts/search_docs.mjs --limit=<n> "<query>"
node skills/tray-dev/scripts/search_docs.mjs --no-cache "<query>"
node skills/tray-dev/scripts/search_docs.mjs --refresh
node skills/tray-dev/scripts/search_docs.mjs --list-topics
node skills/tray-dev/scripts/search_docs.mjs --help
```

### Flags

| Flag | Default | Descrição |
|---|---|---|
| `--topic=<slug>` | (todos) | Filtra por recurso (ex.: `produtos`, `pedidos`) |
| `--json` | false | Output JSON estruturado |
| `--limit=<n>` | 5 | Máximo de resultados |
| `--no-cache` | false | Força refetch da SPA |
| `--refresh` | false | Re-indexa sem fazer query |
| `--list-topics` | false | Lista tópicos disponíveis |
| `--help` | false | Ajuda |

### Exit codes

- `0` query OK (mesmo se 0 resultados)
- `1` erro de execução (rede falha + sem cache; falha de parse)
- `2` erro de uso (flag desconhecida, query vazia, topic inexistente)

## Tópicos disponíveis

Use `--list-topics` para a lista atualizada. Mapeamento canônico:

| Slug | Recurso |
|---|---|
| `autorizacao` | OAuth, tokens |
| `produtos` | Catálogo de produtos |
| `pedidos` | Pedidos e ciclo |
| `clientes` | Clientes (PF/PJ) |
| `webhooks` | Notificações |
| `variacoes` | SKUs / variações |
| `categorias` | Árvore de categorias |
| `marcas` | Marcas |
| `cupons` | Cupons de desconto |
| `multicd` | Multi-CD |
| `frete` | Cálculo de frete |
| `pagamentos` | Pagamentos (PIX, boleto, cartão) |
| `notas-fiscais` | NF-e |
| `status-pedido` | Status customizados |
| `kits` | Kits / combos |
| `caracteristicas` | Atributos de produto |
| `informacoes-loja` | Dados da loja |
| `carrinho-compras` | Carrinho |
| `listagem-carrinho` | Listagem de carrinhos |
| `listas-preco-b2b` | Preços B2B |
| `usuarios` | Usuários administrativos |
| `parceiros` | Parceiros |
| `palavras-chave` | SEO |
| `newsletter` | Newsletter |
| `produtos-vendidos` | Histórico de vendas |
| `imagens-produtos` | Imagens de produtos |
| `informacoes-adicionais` | Campos extras |
| `etiquetas-hub` | Etiquetas HUB |
| `etiquetas-mercado-livre` | Etiquetas ML |
| `emissores-etiqueta` | Emissores |
| `configuracao-frete` | Config de frete |
| `scripts-externos` | JS na vitrine |

## Variáveis de ambiente

| Var | Default | Efeito |
|---|---|---|
| `TRAY_DOCS_CACHE_DIR` | `~/.cache/tray-plugin/dev-docs/` | Override do cache |
| `TRAY_DOCS_CACHE_TTL_MS` | `86400000` (24h) | Override do TTL |
| `TRAY_DOCS_BASE_URL` | `https://developers.tray.com.br` | Override da URL fonte |
| `OPT_OUT_INSTRUMENTATION` | unset | `true` desativa header de telemetria |

## Exemplos

```bash
# Conceitual
node skills/tray-dev/scripts/search_docs.mjs "como autenticar via OAuth"

# Endpoint específico
node skills/tray-dev/scripts/search_docs.mjs "POST /products"

# Restrito por recurso
node skills/tray-dev/scripts/search_docs.mjs --topic=pedidos "cancelamento"

# Output JSON para integração
node skills/tray-dev/scripts/search_docs.mjs --json "webhook"

# Forçar atualização da doc
node skills/tray-dev/scripts/search_docs.mjs --refresh
```

## Privacidade

Por padrão, o `search_docs.mjs` envia o header `X-Tray-AI-Telemetry: on` para `developers.tray.com.br` indicando origem (não envia conteúdo da query). Para desativar:

```bash
export OPT_OUT_INSTRUMENTATION=true
```

## Limitações

- Sinônimos PT-BR cobrem ~23 grupos no MVP. Expansão via PR em `assets/synonyms-pt-br.json`.
- Stemmer simples (sufixos comuns). Não é Snowball/RSLP completo.
- Sem busca semântica/embeddings (out of scope; lexical é suficiente para o volume da doc).
- O `body` retornado nos resultados é truncado em 200 caracteres.

## Erros comuns

- **`OFFLINE_NO_CACHE`** — sem rede e sem cache. Rode com rede uma vez para popular cache inicial.
- **`INVALID_TOPIC`** — slug não está no mapa. Use `--list-topics`.
- **Resultados zero para query óbvia** — provavelmente sinônimo PT-BR faltando. Abra PR em `assets/synonyms-pt-br.json`.