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. Para contribuir, leia CONTRIBUTING.md.

Funciona nativamente com Claude Code, Cursor, OpenAI Codex, Google Gemini CLI, GitHub Copilot, JetBrains AI Assistant e Windsurf.

• Credenciais de API Tray (Consumer Key e Consumer Secret) — obtidas em developers.tray.com.br

Adicione o plugin como dependência de desenvolvimento no seu repositório:

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.

# 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

Opção 1 (recomendada): instalar via pacote Node e apontar o rule file para o projeto.

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.

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

Opção 1 (recomendada): usar o pacote instalado e importar o AGENTS.md no contexto do seu projeto.

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.

git submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin

Opção 1 (recomendada): usar o pacote instalado e copiar o contexto GEMINI.md.

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.

git submodule add https://github.com/tray-tecnologia/tray-api-ai-plugin.git .tray-plugin
# Verificar contexto carregado:
/memory show

O arquivo .github/copilot-instructions.md deste repositório é reconhecido automaticamente pelo Copilot quando o projeto é aberto no VS Code.

O arquivo .aiassistant/rules/tray-api.md é detectado automaticamente como project rule pelo JetBrains AI Assistant.

O AGENTS.md na raiz é reconhecido automaticamente pelo Cascade como regra always-on.

visao-geral — regras invariantes da API Tray (OAuth, payload com chave do recurso, rate limit, dados BR)

autorizacao, webhooks, produtos, variacoes, imagens-produtos, categorias, pedidos, clientes, informacoes-loja

caracteristicas, marcas, kits, status-pedido, enderecos-cliente, perfis-cliente, frete, configuracao-frete, multicd, notas-fiscais, pagamentos

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

Ativados automaticamente pelo assistente-migracao. Consulte agents/AGENTES.md para guia completo de escolha de agente.

# 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

# 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

# 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

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.

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}}'

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

Aceita pipe sem flag adicional:

echo '{"Product":{"name":"X","price":1}}' | \
  node skills/produtos/scripts/validate.mjs --schema=produto.create

O validador é zero-deps em runtime e implementa um subset de JSON Schema Draft-07. Detalhes em 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.

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.

Copie .env.example para .env e preencha com credenciais de uma loja sandbox:

cp .env.example .env
# edite .env: TRAY_API_BASE, TRAY_ACCESS_TOKEN, ...
set -a; source .env; set +a

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

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.

# 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

O primeiro uso baixa a SPA pública (~625 KB) 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)

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:

export OPT_OUT_INSTRUMENTATION=true

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

{
  "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 }
}

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.

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:

tray-dev e visao-geral são puladas (são skills meta).

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.

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

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

# 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. O .mcp.json do root serve como template.

Contribuições são bem-vindas! Abra uma issue ou envie um pull request em GitHub.

• API Tray: https://developers.tray.com.br
• Plataforma Tray: https://tray.com.br
• Claude Code Plugins: https://code.claude.com/docs/pt/plugins

MIT License — veja LICENSE para detalhes.