tray-api
Complete plugin for integrating with the Tray E-commerce platform APIs. Provides 34 skills, 5 specialized agents, and 3 commands covering 15
Open source Repository Open in the app JSON README (API)
About
Complete plugin for integrating with the Tray E-commerce platform APIs. Provides 34 skills, 5 specialized agents, and 3 commands covering 150+ endpoints. Includes OAuth authentication flows, catalog and order management, shipping and payment configuration, webhooks, migration from other platforms (Shopify, WooCommerce, Magento, VTEX, Nuvemshop), and integration validation for app certification.
Details
- Kind
- Plugins
- Topic
- E-commerce & business
- Publisher
- tray-tecnologia
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 15
- Last push
- 2026-08-12T20:29:29Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
tray-tecnologia/tray-api-claude-plugin/tray-api
README
# Plugin Tray API para ferramentas de IA
[](https://opensource.org/licenses/MIT)
[](https://code.claude.com/docs/pt/plugins)
[](https://developers.tray.com.br)
Plugin completo para integração com as APIs da Tray. Acelera o desenvolvimento de aplicativos e-commerce por parceiros e comunidade na plataforma Tray, fornecendo documentação detalhada de **150+ endpoints**, fluxos de autenticação OAuth, webhooks e boas práticas de integração.
Plugin licenciado sob MIT. Antes de abrir issue de segurança, leia [`SECURITY.md`](SECURITY.md). Para contribuir, leia [`CONTRIBUTING.md`](CONTRIBUTING.md).
Funciona nativamente com **Claude Code**, **Cursor**, **OpenAI Codex**, **Google Gemini CLI**, **GitHub Copilot**, **JetBrains AI Assistant** e **Windsurf**.
## Pré-requisitos
- Credenciais de API Tray (Consumer Key e Consumer Secret) — obtidas em [developers.tray.com.br](https://developers.tray.com.br/#criando-seu-aplicativo)
## Instalação por ferramenta
### Instalação via pacote Node (recomendado para projetos locais)
Adicione o plugin como dependência de desenvolvimento no seu repositório:
```bash
npm install --save-dev github:tray-tecnologia/tray-api-ai-plugin
# ou
pnpm add -D github:tray-tecnologia/tray-api-ai-plugin
# ou
bun add -d github:tray-tecnologia/tray-api-ai-plugin
```
O pacote será instalado em `node_modules/@tray-tecnologia/tray-api-plugin/` e pode
ser referenciado pelas ferramentas que suportam contexto por arquivos locais.
### Claude Code (instalação nativa via plugin)
```bash
# Via marketplace
/plugin marketplace add tray-tecnologia/tray-api-ai-plugin
/plugin install tray-api@tray-plugins
# Desenvolvimento local
git clone https://github.com/tray-tecnologia/tray-api-ai-plugin.git
claude --plugin-dir ./tray-api-ai-plugin
```
### Cursor
Opção 1 (recomendada): instalar via pacote Node e apontar o rule file para o projeto.
```bash
cp node_modules/@tray-tecnologia/tray-api-plugin/.cursor/rules/tray-api.mdc .cursor/rules/tray-api.mdc
```
Opção 2: clone ou submódulo no projeto de integração. O arquivo `.cursor/rules/tray-api.mdc` é carregado automaticamente quando o Cursor abre o repositório.
```bash
git submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin
```
O Cursor passa a ter acesso a todos os skills via `@skills/` e aos agentes via `@agents/`.
### OpenAI Codex CLI
Opção 1 (recomendada): usar o pacote instalado e importar o `AGENTS.md` no contexto do seu projeto.
```bash
cp node_modules/@tray-tecnologia/tray-api-plugin/AGENTS.md ./
```
Opção 2: clone ou submódulo. O `AGENTS.md` na raiz é carregado automaticamente pelo Codex.
```bash
git submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin
```
### Google Gemini CLI
Opção 1 (recomendada): usar o pacote instalado e copiar o contexto `GEMINI.md`.
```bash
cp node_modules/@tray-tecnologia/tray-api-plugin/GEMINI.md ./
```
Opção 2: clone ou submódulo. O `GEMINI.md` na raiz é carregado automaticamente via sistema hierárquico de contexto.
```bash
git submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin
# Verificar contexto carregado:
/memory show
```
### GitHub Copilot (VS Code)
O arquivo `.github/copilot-instructions.md` deste repositório é reconhecido automaticamente pelo Copilot quando o projeto é aberto no VS Code.
### JetBrains AI Assistant
O arquivo `.aiassistant/rules/tray-api.md` é detectado automaticamente como project rule pelo JetBrains AI Assistant.
### Windsurf (Cascade)
O `AGENTS.md` na raiz é reconhecido automaticamente pelo Cascade como regra always-on.
## Componentes
| Componente | Quantidade | Descrição |
|:--|:--|:--|
| Skills | 35 | 1 skill de entrada (regras invariantes da API) + 34 skills com a documentação de cada recurso |
| Agentes | 10 | Fluxos especializados (setup, catálogo, pedidos, debug, migração + 5 especialistas por plataforma) |
| Comandos | 3 | Atalhos rápidos (setup, referência, validação) |
| Hooks | 2 | Validação automática de segurança |
## Skills Disponíveis
### Entrada (carregar primeiro)
`visao-geral` — regras invariantes da API Tray (OAuth, payload com chave do recurso, rate limit, dados BR)
### Base
`autorizacao`, `webhooks`, `produtos`, `variacoes`, `imagens-produtos`, `categorias`, `pedidos`, `clientes`, `informacoes-loja`
### Complementar
`caracteristicas`, `marcas`, `kits`, `status-pedido`, `enderecos-cliente`, `perfis-cliente`, `frete`, `configuracao-frete`, `multicd`, `notas-fiscais`, `pagamentos`
### Avançado
`cupons`, `carrinho-compras`, `listagem-carrinho`, `informacoes-adicionais`, `listas-preco-b2b`, `emissores-etiqueta`, `etiquetas-mercado-livre`, `etiquetas-hub`, `scripts-externos`, `newsletter`, `parceiros`, `palavras-chave`, `produtos-vendidos`, `usuarios`
## Agentes
### Principais
| Agente | Descrição |
|:--|:--|
| `/tray-api:configuracao-aplicativo` | Guia de setup inicial e configuração OAuth |
| `/tray-api:gestor-catalogo` | Gestão em massa de catálogo (produtos, categorias, variações) |
| `/tray-api:gestor-pedidos` | Ciclo completo de pedidos (criação, status, fulfillment) |
| `/tray-api:debug-integracao` | Diagnóstico de problemas e erros de API |
| `/tray-api:assistente-migracao` | Orquestra migração de outras plataformas; ativa o subagente da plataforma de origem |
### Subagentes de Migração
Ativados automaticamente pelo `assistente-migracao`. Consulte [agents/AGENTES.md](agents/AGENTES.md) para guia completo de escolha de agente.
| Subagente | Plataforma de Origem |
|:--|:--|
| `agents/migracao/shopify.md` | Shopify |
| `agents/migracao/woocommerce.md` | WooCommerce |
| `agents/migracao/magento.md` | Magento 2 |
| `agents/migracao/vtex.md` | VTEX |
| `agents/migracao/nuvemshop.md` | Nuvemshop |
## Comandos
| Comando | Descrição |
|:--|:--|
| `/tray-api:setup` | Configuração rápida de integração |
| `/tray-api:referencia-api` | Referência completa de endpoints |
| `/tray-api:validar-integracao` | Checklist de validação pré-publicação |
## Exemplo de Uso
```bash
# 1. Adicione o marketplace
❯ /plugin marketplace add tray-tecnologia/tray-api-ai-plugin
⎿ Successfully added marketplace: tray-plugins
# 2. Instale o plugin
❯ /plugin install tray-api@tray-plugins
⎿ ✓ Installed tray-api. Run /reload-plugins to activate.
# 3. Ative o plugin
❯ /reload-plugins
⎿ Reloaded: 1 plugins · 35 skills · 5 agents · 2 hooks · 1 plugin MCP server · 0 plugin LSP servers
```
```bash
# Veja todas as skills disponíveis
❯ Quais skills disponíveis?
⏺ Aqui estão as skills disponíveis:
Tray API - Início:
- /tray-api:visao-geral — Regras invariantes da API Tray (carregar primeiro)
Tray API - Setup & Auth:
- /tray-api:setup — Guia rápido de configuração inicial
- /tray-api:autorizacao — Fluxo OAuth 2.0, tokens, refresh
- /tray-api:validar-integracao — Valida código de integração
- /tray-api:referencia-api — Referência rápida de endpoints
- /tray-api:webhooks — Notificações em tempo real
Tray API - Catálogo:
- /tray-api:produtos — CRUD de produtos
- /tray-api:variacoes — Variações/SKUs
- /tray-api:categorias — Árvore de categorias
- /tray-api:marcas — Marcas/fabricantes
- /tray-api:imagens-produtos — Upload de imagens
- /tray-api:caracteristicas — Propriedades de produtos
- /tray-api:informacoes-adicionais — Campos customizados
- /tray-api:kits — Kits/combos de produtos
Tray API - Pedidos & Frete:
- /tray-api:pedidos — Ciclo completo de pedidos
- /tray-api:status-pedido — Status personalizados
- /tray-api:notas-fiscais — NF-e
- /tray-api:frete — Cálculo de frete
- /tray-api:configuracao-frete — Métodos de envio
- /tray-api:carrinho-compras — Carrinho de compras
- /tray-api:listagem-carrinho — Listagem de carrinhos
- /tray-api:etiquetas-hub — Etiquetas HUB
- /tray-api:etiquetas-mercado-livre — Etiquetas ML
- /tray-api:emissores-etiqueta — Emissores de etiqueta
Tray API - Clientes & Pagamentos:
- /tray-api:clientes — CRUD de clientes
- /tray-api:enderecos-cliente — Endereços
- /tray-api:perfis-cliente — Perfis/segmentos
- /tray-api:pagamentos — Meios de pagamento
- /tray-api:cupons — Cupons de desconto
- /tray-api:listas-preco-b2b — Preços B2B
Tray API - Loja & Outros:
- /tray-api:informacoes-loja — Dados da loja
- /tray-api:scripts-externos — Scripts JS na vitrine
- /tray-api:multicd — Centros de distribuição
- /tray-api:parceiros — Parceiros/revendedores
- /tray-api:usuarios — Usuários administrativos
- /tray-api:produtos-vendidos — Analytics de vendas
- /tray-api:palavras-chave — SEO
- /tray-api:newsletter — Assinaturas de newsletter
```
```bash
# Exemplos de uso
> /tray-api:setup
# Configura credenciais e testa conexão com a API Tray
> Como listar todos os produtos da minha loja?
# O plugin fornece automaticamente a documentação do endpoint GET /products
> /tray-api:validar-integracao
# Valida se sua integração está pronta para homologação
```
## Validação local com `validate.mjs`
8 das 35 skills do plugin (`autorizacao`, `produtos`, `pedidos`, `clientes`,
`webhooks`, `variacoes`, `categorias`, `marcas`) têm um script
`scripts/validate.mjs` para validar payloads contra o schema oficial **antes**
de chamar a API Tray.
### Uso básico
```
node skills/<skill>/scripts/validate.mjs --schema=<op> '<payload_json>'
```
Exemplo:
```
node skills/produtos/scripts/validate.mjs --schema=produto.create \
'{"Product":{"name":"Camiseta","price":49.90}}'
```
### Flags
- `--schema=<nome>` — obrigatório quando a skill tem múltiplos schemas; opcional se há só 1.
- `--json` — saída programática (formato Shopify-like) em vez de PT-BR humano.
- `--list-schemas` — lista os schemas disponíveis na skill e sai com 0.
- `--help` — imprime uso.
### Exit codes
| Code | Significado |
|---|---|
| 0 | Payload válido |
| 1 | Payload inválido (campos faltando, tipo errado, format BR errado, etc.) |
| 2 | Erro de uso (schema inexistente, JSON malformado, `--schema` faltando quando há múltiplos) |
### Stdin
Aceita pipe sem flag adicional:
```
echo '{"Product":{"name":"X","price":1}}' | \
node skills/produtos/scripts/validate.mjs --schema=produto.create
```
### Subset JSON Schema suportado
O validador é zero-deps em runtime e implementa um subset de JSON Schema
Draft-07. Detalhes em [`scripts/lib/SUBSET.md`](scripts/lib/SUBSET.md).
Formats brasileiros (CPF/CNPJ/CEP/EAN/NCM com algoritmos de DV; date e
datetime no formato Tray) são implementados em
[`scripts/lib/formats-br.mjs`](scripts/lib/formats-br.mjs).
## Como rodar exemplos localmente
Cada endpoint documentado tem (ou terá) exemplos runáveis em `skills/<skill>/examples/`,
em dois formatos: `curl` (`.curl.sh`) e Node 18+ (`.node.mjs`). Endpoints com corpo
(`POST`/`PUT`) trazem também `<endpoint>.fixture.json` — o mesmo payload serve de
input para o `validate.mjs`. O template e as convenções estão em
[`docs/example-template.md`](docs/example-template.md).
### 1. Configure as variáveis de ambiente
Copie `.env.example` para `.env` e preencha com credenciais de uma **loja sandbox**:
```bash
cp .env.example .env
# edite .env: TRAY_API_BASE, TRAY_ACCESS_TOKEN, ...
set -a; source .env; set +a
```
| Var | Uso |
|:--|:--|
| `TRAY_API_BASE` | Host da API da loja (`api_address` do callback OAuth) |
| `TRAY_ACCESS_TOKEN` | Token de acesso (expira em 3h) |
| `TRAY_STORE_URL` | URL da vitrine — só fluxo OAuth |
| `TRAY_CONSUMER_KEY` / `TRAY_CONSUMER_SECRET` | Credenciais do app — só `autorizacao` |
| `TRAY_PRODUCT_ID` | ID de recurso para exemplos `GET/:id`, `PUT`, `DELETE` |
### 2. Rode um exemplo
```bash
# curl
bash skills/produtos/examples/produto-listar.curl.sh
# Node (zero-install, fetch nativo)
node skills/produtos/examples/produto-listar.node.mjs
```
Os exemplos são **fail-fast** (saem com exit ≠ 0 em env var faltando ou HTTP non-2xx)
e **sandbox-first**. Exemplos destrutivos (`DELETE`) exigem confirmação explícita
(`CONFIRM_DELETE=yes`). Nenhum token fica hardcoded — o hook `PostToolUse` bloqueia literais.
Troubleshooting comum (`401`/`403`/`404`/`429`/`400`) na tabela final de
[`docs/example-template.md`](docs/example-template.md).
## Busca em docs com `search_docs.mjs`
A skill `tray-dev` indexa localmente `https://developers.tray.com.br` e oferece busca rápida (BM25) sobre todos os endpoints, parâmetros, exemplos e códigos de erro da API Tray.
### Uso
```bash
# Busca por termo
node skills/tray-dev/scripts/search_docs.mjs "como autenticar via OAuth"
# Restringir por recurso
node skills/tray-dev/scripts/search_docs.mjs --topic=pedidos "cancelamento"
# Output JSON estruturado
node skills/tray-dev/scripts/search_docs.mjs --json "webhook"
# Forçar refresh da doc
node skills/tray-dev/scripts/search_docs.mjs --refresh
# Listar tópicos disponíveis
node skills/tray-dev/scripts/search_docs.mjs --list-topics
```
### Cache
O primeiro uso baixa a página pública (~1,6 MB de HTML), converte para Markdown e indexa em `~/.cache/tray-plugin/dev-docs/`. Execuções subsequentes (24h) usam cache. Override via env vars:
- `TRAY_DOCS_CACHE_DIR` — diretório do cache
- `TRAY_DOCS_CACHE_TTL_MS` — TTL em milissegundos (default 86400000 = 24h)
### Privacidade (telemetria opt-out)
Por padrão, o `search_docs.mjs` envia o header `X-Tray-AI-Telemetry: on` para `developers.tray.com.br` indicando que a chamada veio do plugin. **Nenhuma query é enviada no header.**
Para desativar:
```bash
export OPT_OUT_INSTRUMENTATION=true
```
### Exit codes
- `0` query OK (mesmo se 0 resultados)
- `1` erro de execução (rede falha + sem cache)
- `2` erro de uso (flag desconhecida, query vazia, topic inexistente)
### Output JSON
```json
{
"query": "OAuth",
"expandedQuery": ["oauth","autentic","token","acess"],
"topic": null,
"results": [
{
"title": "Gerar Chaves de Acesso",
"url": "https://developers.tray.com.br/#gerar-chaves-de-acesso",
"snippet": "...",
"score": 0.92,
"topic": "autorizacao",
"h1": "Autorização",
"level": "h2",
"anchor": "gerar-chaves-de-acesso"
}
],
"totalResults": 12,
"took": 47,
"cache": { "hit": true, "ageMs": 3600000, "ttlMs": 86400000 }
}
```
### Sinônimos PT-BR
A busca expande termos PT-BR para equivalentes da API (`autenticar` ↔ `oauth`, `criar` ↔ `POST`, etc.). O dicionário fica em `skills/tray-dev/assets/synonyms-pt-br.json`. Para expandir, abra um PR.
## Mandatory Tool Calls em SKILL.md
Toda skill de recurso da API Tray começa com um bloco `## MANDATORY: Tool Call(s) Required Before Answering` listando as ferramentas que o agente DEVE invocar antes de responder:
- **Sempre** — `node skills/tray-dev/scripts/search_docs.mjs --topic=<slug> "<termo>"` para puxar a doc oficial mais recente.
- **Quando aplicável** (8 skills com schema local) — `node skills/<recurso>/scripts/validate.mjs --schema=<nome>` para validar o payload antes de retornar código.
As skills se dividem em três categorias:
| Categoria | Quantas | Conteúdo do MANDATORY |
|---|---|---|
| **A — search + validate** | 8 (autorizacao, produtos, pedidos, clientes, webhooks, variacoes, categorias, marcas) | search_docs **e** validate.mjs |
| **B — escrita sem validate** | 19 (cupons, multicd, pagamentos, etc.) | search_docs apenas |
| **C — só leitura** | 7 (usuarios, frete, palavras-chave, etc.) | search_docs apenas |
`tray-dev` e `visao-geral` são puladas (são skills meta).
### Validação automática
```bash
npm run lint:skills
```
Verifica em cada `skills/*/SKILL.md` (exceto `tray-dev` e `visao-geral`):
- presença do bloco MANDATORY;
- posição (antes do `## Antes de responder`);
- presença do comando de busca;
- presença do `validate.mjs` (categoria A);
- ausência de duplicata do step antigo no "Antes de responder";
- frase imperativa "OBRIGATÓRIA(S)".
Saída em `--json` para integração CI. Exit codes: `0` OK · `1` erro · `2` uso.
O CI roda `npm run lint:skills` antes do smoke; o smoke também invoca o linter na seção 14.
## Servidor MCP (`mcp/`)
O plugin Tray também expõe ferramentas via **Model Context Protocol (MCP)** para clientes que não suportam o formato de plugin nativo (Continue.dev, Zed, agents customizados, backends).
### Tools
- `tray.search_docs` — busca BM25 em `developers.tray.com.br` (mesma engine do P1.2).
- `tray.validate` — valida payload contra schemas das skills (mesma engine do P1.1).
### Uso rápido
```bash
# Local (já dentro do repo):
npm run mcp
# Via npx (após instalar o plugin):
npx --package=@tray-tecnologia/tray-api-plugin tray-mcp
```
Configuração para Claude Desktop, Cursor, Continue.dev e clientes genéricos está em [`mcp/README.md`](mcp/README.md). O [`.mcp.json`](.mcp.json) do root serve como template.
## Contribuindo
Contribuições são bem-vindas! Abra uma issue ou envie um pull request em [GitHub](https://github.com/tray-tecnologia/tray-api-ai-plugin).
## Referências
- **API Tray:** https://developers.tray.com.br
- **Plataforma Tray:** https://tray.com.br
- **Claude Code Plugins:** https://code.claude.com/docs/pt/plugins
## Licença
MIT License — veja [LICENSE](LICENSE) para detalhes.