القائمة
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.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
API de Informações da Loja da Tray. Utilize quando o desenvolvedor precisar consultar dados de configuração da loja como nome, razão social, CNPJ, endereço, contatos, URLs (domínio) e status interno da loja.
API de Produtos da Tray. Utilize quando o desenvolvedor precisar listar, consultar, cadastrar, atualizar ou excluir produtos no catálogo de uma loja Tray. Inclui todos os campos do produto (nome, preço, estoque, EAN, NCM, dimensões, SEO), filtros de listagem, paginação, ordenação e exclusão de kits.
API de Clientes da Tray. Utilize quando o desenvolvedor precisar gerenciar dados de clientes da loja: listagem, consulta, cadastro, atualização e exclusão. Inclui campos de pessoa física (CPF) e jurídica (CNPJ), validações brasileiras e gestão de newsletter.
API completa de cupons de desconto da Tray (recurso `discount_coupons`). Cobre criar, editar, listar, consultar e excluir cupons (CRUD) e gerenciar os relacionamentos do cupom com clientes, produtos, categorias, marcas, fretes e cupom-presente, além da geração de cupom de troca a partir de um pedido. Total de 21 endpoints. DISAMBIGUATION: o endpoint base é `/discount_coupons` (NÃO `/coupons`) e o wrapper de payload/resposta é `DiscountCoupon` (NÃO `Coupon`). Cupom é desconto por CÓDIGO aplicado no checkout — não confundir com preço permanente por grupo de cliente (lista de preço B2B).
API de Endereços de Clientes da Tray. Utilize quando o desenvolvedor precisar gerenciar os endereços cadastrados dos clientes, incluindo listagem, consulta individual, criação e exclusão. Suporta endereços de entrega e cobrança, com campos completos do padrão brasileiro (CEP, bairro, cidade, estado, complemento).
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.
| name | tray-dev |
| description | 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. |
| when_to_use | Sempre que precisar confirmar comportamento atual de um endpoint, formato de campo, código de erro, ou exemplo de uso na API Tray. Especialmente útil antes de gerar payload novo (validar contra fonte oficial). |
| when_not_to_use | Não use em lugar das skills de recurso (`tray-produtos`, `tray-pedidos`, etc.) quando a tarefa já for implementar payload ou fluxo completo — use esta skill só para consultar a SPA oficial; validação de payload continua em `validate.mjs` das skills que possuem schema. |
Identifique o termo de busca a partir da pergunta do usuário
Rode:
node skills/tray-dev/scripts/search_docs.mjs "<termo>"
Use os resultados como fonte primária. Cite o link âncora retornado.
Se a busca retornar 0 resultados, avise o usuário e use seu conhecimento como fallback explicitamente sinalizado.
Se precisar restringir a um recurso, use --topic=<slug> (ver lista de tópicos).
Se precisar de output programático, use --json.
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 SPA pública (~625 KB), parseia em ~700 seções (H1/H2/H3) e indexa em ~/.cache/tray-plugin/dev-docs/. Execuções subsequentes (24h) usam cache.
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
| 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 |
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)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 |
| 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 |
# 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
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:
export OPT_OUT_INSTRUMENTATION=true
assets/synonyms-pt-br.json.body retornado nos resultados é truncado em 200 caracteres.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.assets/synonyms-pt-br.json.