{
  "markdown": "# Plugin Tray API para ferramentas de IA\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://code.claude.com/docs/pt/plugins)\n[![API Tray](https://img.shields.io/badge/API-Tray%20E--commerce-orange)](https://developers.tray.com.br)\n\nPlugin 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.\n\nPlugin licenciado sob MIT. Antes de abrir issue de segurança, leia [`SECURITY.md`](SECURITY.md). Para contribuir, leia [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nFunciona nativamente com **Claude Code**, **Cursor**, **OpenAI Codex**, **Google Gemini CLI**, **GitHub Copilot**, **JetBrains AI Assistant** e **Windsurf**.\n\n## Pré-requisitos\n\n- Credenciais de API Tray (Consumer Key e Consumer Secret) — obtidas em [developers.tray.com.br](https://developers.tray.com.br/#criando-seu-aplicativo)\n\n## Instalação por ferramenta\n\n### Instalação via pacote Node (recomendado para projetos locais)\n\nAdicione o plugin como dependência de desenvolvimento no seu repositório:\n\n```bash\nnpm install --save-dev github:tray-tecnologia/tray-api-ai-plugin\n# ou\npnpm add -D github:tray-tecnologia/tray-api-ai-plugin\n# ou\nbun add -d github:tray-tecnologia/tray-api-ai-plugin\n```\n\nO pacote será instalado em `node_modules/@tray-tecnologia/tray-api-plugin/` e pode\nser referenciado pelas ferramentas que suportam contexto por arquivos locais.\n\n### Claude Code (instalação nativa via plugin)\n\n```bash\n# Via marketplace\n/plugin marketplace add tray-tecnologia/tray-api-ai-plugin\n/plugin install tray-api@tray-plugins\n\n# Desenvolvimento local\ngit clone https://github.com/tray-tecnologia/tray-api-ai-plugin.git\nclaude --plugin-dir ./tray-api-ai-plugin\n```\n\n### Cursor\n\nOpção 1 (recomendada): instalar via pacote Node e apontar o rule file para o projeto.\n\n```bash\ncp node_modules/@tray-tecnologia/tray-api-plugin/.cursor/rules/tray-api.mdc .cursor/rules/tray-api.mdc\n```\n\nOpçã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.\n\n```bash\ngit submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin\n```\n\nO Cursor passa a ter acesso a todos os skills via `@skills/` e aos agentes via `@agents/`.\n\n### OpenAI Codex CLI\n\nOpção 1 (recomendada): usar o pacote instalado e importar o `AGENTS.md` no contexto do seu projeto.\n\n```bash\ncp node_modules/@tray-tecnologia/tray-api-plugin/AGENTS.md ./\n```\n\nOpção 2: clone ou submódulo. O `AGENTS.md` na raiz é carregado automaticamente pelo Codex.\n\n```bash\ngit submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin\n```\n\n### Google Gemini CLI\n\nOpção 1 (recomendada): usar o pacote instalado e copiar o contexto `GEMINI.md`.\n\n```bash\ncp node_modules/@tray-tecnologia/tray-api-plugin/GEMINI.md ./\n```\n\nOpção 2: clone ou submódulo. O `GEMINI.md` na raiz é carregado automaticamente via sistema hierárquico de contexto.\n\n```bash\ngit submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin\n# Verificar contexto carregado:\n/memory show\n```\n\n### GitHub Copilot (VS Code)\n\nO arquivo `.github/copilot-instructions.md` deste repositório é reconhecido automaticamente pelo Copilot quando o projeto é aberto no VS Code.\n\n### JetBrains AI Assistant\n\nO arquivo `.aiassistant/rules/tray-api.md` é detectado automaticamente como project rule pelo JetBrains AI Assistant.\n\n### Windsurf (Cascade)\n\nO `AGENTS.md` na raiz é reconhecido automaticamente pelo Cascade como regra always-on.\n\n## Componentes\n\n| Componente | Quantidade | Descrição |\n|:--|:--|:--|\n| Skills | 35 | 1 skill de entrada (regras invariantes da API) + 34 skills com a documentação de cada recurso |\n| Agentes | 10 | Fluxos especializados (setup, catálogo, pedidos, debug, migração + 5 especialistas por plataforma) |\n| Comandos | 3 | Atalhos rápidos (setup, referência, validação) |\n| Hooks | 2 | Validação automática de segurança |\n\n## Skills Disponíveis\n\n### Entrada (carregar primeiro)\n`visao-geral` — regras invariantes da API Tray (OAuth, payload com chave do recurso, rate limit, dados BR)\n\n### Base\n`autorizacao`, `webhooks`, `produtos`, `variacoes`, `imagens-produtos`, `categorias`, `pedidos`, `clientes`, `informacoes-loja`\n\n### Complementar\n`caracteristicas`, `marcas`, `kits`, `status-pedido`, `enderecos-cliente`, `perfis-cliente`, `frete`, `configuracao-frete`, `multicd`, `notas-fiscais`, `pagamentos`\n\n### Avançado\n`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`\n\n## Agentes\n\n### Principais\n\n| Agente | Descrição |\n|:--|:--|\n| `/tray-api:configuracao-aplicativo` | Guia de setup inicial e configuração OAuth |\n| `/tray-api:gestor-catalogo` | Gestão em massa de catálogo (produtos, categorias, variações) |\n| `/tray-api:gestor-pedidos` | Ciclo completo de pedidos (criação, status, fulfillment) |\n| `/tray-api:debug-integracao` | Diagnóstico de problemas e erros de API |\n| `/tray-api:assistente-migracao` | Orquestra migração de outras plataformas; ativa o subagente da plataforma de origem |\n\n### Subagentes de Migração\n\nAtivados automaticamente pelo `assistente-migracao`. Consulte [agents/AGENTES.md](agents/AGENTES.md) para guia completo de escolha de agente.\n\n| Subagente | Plataforma de Origem |\n|:--|:--|\n| `agents/migracao/shopify.md` | Shopify |\n| `agents/migracao/woocommerce.md` | WooCommerce |\n| `agents/migracao/magento.md` | Magento 2 |\n| `agents/migracao/vtex.md` | VTEX |\n| `agents/migracao/nuvemshop.md` | Nuvemshop |\n\n## Comandos\n\n| Comando | Descrição |\n|:--|:--|\n| `/tray-api:setup` | Configuração rápida de integração |\n| `/tray-api:referencia-api` | Referência completa de endpoints |\n| `/tray-api:validar-integracao` | Checklist de validação pré-publicação |\n\n## Exemplo de Uso\n\n```bash\n# 1. Adicione o marketplace\n❯ /plugin marketplace add tray-tecnologia/tray-api-ai-plugin\n  ⎿  Successfully added marketplace: tray-plugins\n\n# 2. Instale o plugin\n❯ /plugin install tray-api@tray-plugins\n  ⎿  ✓ Installed tray-api. Run /reload-plugins to activate.\n\n# 3. Ative o plugin\n❯ /reload-plugins\n  ⎿  Reloaded: 1 plugins · 35 skills · 5 agents · 2 hooks · 1 plugin MCP server · 0 plugin LSP servers\n```\n\n```bash\n# Veja todas as skills disponíveis\n❯ Quais skills disponíveis?\n\n⏺ Aqui estão as skills disponíveis:\n\n  Tray API - Início:\n  - /tray-api:visao-geral — Regras invariantes da API Tray (carregar primeiro)\n\n  Tray API - Setup & Auth:\n  - /tray-api:setup — Guia rápido de configuração inicial\n  - /tray-api:autorizacao — Fluxo OAuth 2.0, tokens, refresh\n  - /tray-api:validar-integracao — Valida código de integração\n  - /tray-api:referencia-api — Referência rápida de endpoints\n  - /tray-api:webhooks — Notificações em tempo real\n\n  Tray API - Catálogo:\n  - /tray-api:produtos — CRUD de produtos\n  - /tray-api:variacoes — Variações/SKUs\n  - /tray-api:categorias — Árvore de categorias\n  - /tray-api:marcas — Marcas/fabricantes\n  - /tray-api:imagens-produtos — Upload de imagens\n  - /tray-api:caracteristicas — Propriedades de produtos\n  - /tray-api:informacoes-adicionais — Campos customizados\n  - /tray-api:kits — Kits/combos de produtos\n\n  Tray API - Pedidos & Frete:\n  - /tray-api:pedidos — Ciclo completo de pedidos\n  - /tray-api:status-pedido — Status personalizados\n  - /tray-api:notas-fiscais — NF-e\n  - /tray-api:frete — Cálculo de frete\n  - /tray-api:configuracao-frete — Métodos de envio\n  - /tray-api:carrinho-compras — Carrinho de compras\n  - /tray-api:listagem-carrinho — Listagem de carrinhos\n  - /tray-api:etiquetas-hub — Etiquetas HUB\n  - /tray-api:etiquetas-mercado-livre — Etiquetas ML\n  - /tray-api:emissores-etiqueta — Emissores de etiqueta\n\n  Tray API - Clientes & Pagamentos:\n  - /tray-api:clientes — CRUD de clientes\n  - /tray-api:enderecos-cliente — Endereços\n  - /tray-api:perfis-cliente — Perfis/segmentos\n  - /tray-api:pagamentos — Meios de pagamento\n  - /tray-api:cupons — Cupons de desconto\n  - /tray-api:listas-preco-b2b — Preços B2B\n\n  Tray API - Loja & Outros:\n  - /tray-api:informacoes-loja — Dados da loja\n  - /tray-api:scripts-externos — Scripts JS na vitrine\n  - /tray-api:multicd — Centros de distribuição\n  - /tray-api:parceiros — Parceiros/revendedores\n  - /tray-api:usuarios — Usuários administrativos\n  - /tray-api:produtos-vendidos — Analytics de vendas\n  - /tray-api:palavras-chave — SEO\n  - /tray-api:newsletter — Assinaturas de newsletter\n```\n\n```bash\n# Exemplos de uso\n> /tray-api:setup\n# Configura credenciais e testa conexão com a API Tray\n\n> Como listar todos os produtos da minha loja?\n# O plugin fornece automaticamente a documentação do endpoint GET /products\n\n> /tray-api:validar-integracao\n# Valida se sua integração está pronta para homologação\n```\n\n## Validação local com `validate.mjs`\n\n8 das 35 skills do plugin (`autorizacao`, `produtos`, `pedidos`, `clientes`,\n`webhooks`, `variacoes`, `categorias`, `marcas`) têm um script\n`scripts/validate.mjs` para validar payloads contra o schema oficial **antes**\nde chamar a API Tray.\n\n### Uso básico\n\n```\nnode skills/<skill>/scripts/validate.mjs --schema=<op> '<payload_json>'\n```\n\nExemplo:\n\n```\nnode skills/produtos/scripts/validate.mjs --schema=produto.create \\\n  '{\"Product\":{\"name\":\"Camiseta\",\"price\":49.90}}'\n```\n\n### Flags\n\n- `--schema=<nome>` — obrigatório quando a skill tem múltiplos schemas; opcional se há só 1.\n- `--json` — saída programática (formato Shopify-like) em vez de PT-BR humano.\n- `--list-schemas` — lista os schemas disponíveis na skill e sai com 0.\n- `--help` — imprime uso.\n\n### Exit codes\n\n| Code | Significado |\n|---|---|\n| 0 | Payload válido |\n| 1 | Payload inválido (campos faltando, tipo errado, format BR errado, etc.) |\n| 2 | Erro de uso (schema inexistente, JSON malformado, `--schema` faltando quando há múltiplos) |\n\n### Stdin\n\nAceita pipe sem flag adicional:\n\n```\necho '{\"Product\":{\"name\":\"X\",\"price\":1}}' | \\\n  node skills/produtos/scripts/validate.mjs --schema=produto.create\n```\n\n### Subset JSON Schema suportado\n\nO validador é zero-deps em runtime e implementa um subset de JSON Schema\nDraft-07. Detalhes em [`scripts/lib/SUBSET.md`](scripts/lib/SUBSET.md).\n\nFormats brasileiros (CPF/CNPJ/CEP/EAN/NCM com algoritmos de DV; date e\ndatetime no formato Tray) são implementados em\n[`scripts/lib/formats-br.mjs`](scripts/lib/formats-br.mjs).\n\n## Como rodar exemplos localmente\n\nCada endpoint documentado tem (ou terá) exemplos runáveis em `skills/<skill>/examples/`,\nem dois formatos: `curl` (`.curl.sh`) e Node 18+ (`.node.mjs`). Endpoints com corpo\n(`POST`/`PUT`) trazem também `<endpoint>.fixture.json` — o mesmo payload serve de\ninput para o `validate.mjs`. O template e as convenções estão em\n[`docs/example-template.md`](docs/example-template.md).\n\n### 1. Configure as variáveis de ambiente\n\nCopie `.env.example` para `.env` e preencha com credenciais de uma **loja sandbox**:\n\n```bash\ncp .env.example .env\n# edite .env: TRAY_API_BASE, TRAY_ACCESS_TOKEN, ...\nset -a; source .env; set +a\n```\n\n| Var | Uso |\n|:--|:--|\n| `TRAY_API_BASE` | Host da API da loja (`api_address` do callback OAuth) |\n| `TRAY_ACCESS_TOKEN` | Token de acesso (expira em 3h) |\n| `TRAY_STORE_URL` | URL da vitrine — só fluxo OAuth |\n| `TRAY_CONSUMER_KEY` / `TRAY_CONSUMER_SECRET` | Credenciais do app — só `autorizacao` |\n| `TRAY_PRODUCT_ID` | ID de recurso para exemplos `GET/:id`, `PUT`, `DELETE` |\n\n### 2. Rode um exemplo\n\n```bash\n# curl\nbash skills/produtos/examples/produto-listar.curl.sh\n\n# Node (zero-install, fetch nativo)\nnode skills/produtos/examples/produto-listar.node.mjs\n```\n\nOs exemplos são **fail-fast** (saem com exit ≠ 0 em env var faltando ou HTTP non-2xx)\ne **sandbox-first**. Exemplos destrutivos (`DELETE`) exigem confirmação explícita\n(`CONFIRM_DELETE=yes`). Nenhum token fica hardcoded — o hook `PostToolUse` bloqueia literais.\n\nTroubleshooting comum (`401`/`403`/`404`/`429`/`400`) na tabela final de\n[`docs/example-template.md`](docs/example-template.md).\n\n## Busca em docs com `search_docs.mjs`\n\nA 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.\n\n### Uso\n\n```bash\n# Busca por termo\nnode skills/tray-dev/scripts/search_docs.mjs \"como autenticar via OAuth\"\n\n# Restringir por recurso\nnode skills/tray-dev/scripts/search_docs.mjs --topic=pedidos \"cancelamento\"\n\n# Output JSON estruturado\nnode skills/tray-dev/scripts/search_docs.mjs --json \"webhook\"\n\n# Forçar refresh da doc\nnode skills/tray-dev/scripts/search_docs.mjs --refresh\n\n# Listar tópicos disponíveis\nnode skills/tray-dev/scripts/search_docs.mjs --list-topics\n```\n\n### Cache\n\nO 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:\n\n- `TRAY_DOCS_CACHE_DIR` — diretório do cache\n- `TRAY_DOCS_CACHE_TTL_MS` — TTL em milissegundos (default 86400000 = 24h)\n\n### Privacidade (telemetria opt-out)\n\nPor 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.**\n\nPara desativar:\n\n```bash\nexport OPT_OUT_INSTRUMENTATION=true\n```\n\n### Exit codes\n\n- `0` query OK (mesmo se 0 resultados)\n- `1` erro de execução (rede falha + sem cache)\n- `2` erro de uso (flag desconhecida, query vazia, topic inexistente)\n\n### Output JSON\n\n```json\n{\n  \"query\": \"OAuth\",\n  \"expandedQuery\": [\"oauth\",\"autentic\",\"token\",\"acess\"],\n  \"topic\": null,\n  \"results\": [\n    {\n      \"title\": \"Gerar Chaves de Acesso\",\n      \"url\": \"https://developers.tray.com.br/#gerar-chaves-de-acesso\",\n      \"snippet\": \"...\",\n      \"score\": 0.92,\n      \"topic\": \"autorizacao\",\n      \"h1\": \"Autorização\",\n      \"level\": \"h2\",\n      \"anchor\": \"gerar-chaves-de-acesso\"\n    }\n  ],\n  \"totalResults\": 12,\n  \"took\": 47,\n  \"cache\": { \"hit\": true, \"ageMs\": 3600000, \"ttlMs\": 86400000 }\n}\n```\n\n### Sinônimos PT-BR\n\nA 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.\n\n## Mandatory Tool Calls em SKILL.md\n\nToda 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:\n\n- **Sempre** — `node skills/tray-dev/scripts/search_docs.mjs --topic=<slug> \"<termo>\"` para puxar a doc oficial mais recente.\n- **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.\n\nAs skills se dividem em três categorias:\n\n| Categoria | Quantas | Conteúdo do MANDATORY |\n|---|---|---|\n| **A — search + validate** | 8 (autorizacao, produtos, pedidos, clientes, webhooks, variacoes, categorias, marcas) | search_docs **e** validate.mjs |\n| **B — escrita sem validate** | 19 (cupons, multicd, pagamentos, etc.) | search_docs apenas |\n| **C — só leitura** | 7 (usuarios, frete, palavras-chave, etc.) | search_docs apenas |\n\n`tray-dev` e `visao-geral` são puladas (são skills meta).\n\n### Validação automática\n\n```bash\nnpm run lint:skills\n```\n\nVerifica em cada `skills/*/SKILL.md` (exceto `tray-dev` e `visao-geral`):\n\n- presença do bloco MANDATORY;\n- posição (antes do `## Antes de responder`);\n- presença do comando de busca;\n- presença do `validate.mjs` (categoria A);\n- ausência de duplicata do step antigo no \"Antes de responder\";\n- frase imperativa \"OBRIGATÓRIA(S)\".\n\nSaída em `--json` para integração CI. Exit codes: `0` OK · `1` erro · `2` uso.\n\nO CI roda `npm run lint:skills` antes do smoke; o smoke também invoca o linter na seção 14.\n\n## Servidor MCP (`mcp/`)\n\nO 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).\n\n### Tools\n\n- `tray.search_docs` — busca BM25 em `developers.tray.com.br` (mesma engine do P1.2).\n- `tray.validate` — valida payload contra schemas das skills (mesma engine do P1.1).\n\n### Uso rápido\n\n```bash\n# Local (já dentro do repo):\nnpm run mcp\n\n# Via npx (após instalar o plugin):\nnpx --package=@tray-tecnologia/tray-api-plugin tray-mcp\n```\n\nConfiguraçã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.\n\n## Contribuindo\n\nContribuições são bem-vindas! Abra uma issue ou envie um pull request em [GitHub](https://github.com/tray-tecnologia/tray-api-ai-plugin).\n\n## Referências\n\n- **API Tray:** https://developers.tray.com.br\n- **Plataforma Tray:** https://tray.com.br\n- **Claude Code Plugins:** https://code.claude.com/docs/pt/plugins\n\n## Licença\n\nMIT License — veja [LICENSE](LICENSE) para detalhes.\n",
  "bytes": 17286,
  "sha": "4016a20801e508272dc25080cad37ae24532028d5fc61016e321501cbe1a4d42",
  "repo_slug": "tray-tecnologia/tray-api-ai-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tray_tecnologia_tray_api_ai_plugin_83facef1/readme"
}