From tray-api
Establishes invariant rules for Tray API integration: OAuth as query param, payload wrapping, token expiry, rate limits, and Brazilian data validation. Load before resource-specific skills.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tray-api:visao-geralWhen to use
Use no início de qualquer conversa sobre API Tray, integração com Tray, cadastro de produtos/pedidos/clientes na Tray, OAuth da Tray, webhooks da Tray, ou quando o desenvolvedor mencionar consumer_key, consumer_secret, access_token, refresh_token, api_address ou developers.tray.com.br. Carregue antes da skill específica do recurso.
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
- **OBRIGATÓRIO:** `node skills/tray-dev/scripts/search_docs.mjs "<termo>"` — confirme o comportamento da API antes de gerar código.
node skills/tray-dev/scripts/search_docs.mjs "<termo>" — confirme o comportamento da API antes de gerar código.Execute estas verificações antes de gerar qualquer payload ou código:
access_token, consumer_key, consumer_secret e
refresh_token não aparecem como literais no código gerado.{"Product": {...}}, {"Order": {...}}, {"Customer": {...}}).access_token é passado como query parameter
(?access_token={token}), nunca como header.Documentação oficial: https://developers.tray.com.br
Estas regras valem para toda chamada à API Tray e devem ser aplicadas mesmo que a skill do recurso específico não as repita.
| Token | Vida útil | Como renovar |
|---|---|---|
access_token | 3 horas | GET /auth?consumer_key=...&refresh_token=... |
refresh_token | 30 dias | Refazer fluxo OAuth completo |
?access_token={token}.Authorization: Bearer ... não funciona na API Tray).Detalhes do fluxo de 3 etapas em skills/autorizacao/SKILL.md.
https://{api_address}/<recurso>?access_token={token}
api_address varia por loja e é retornado no callback OAuth da
Etapa 2. Armazene junto com os tokens.
Payloads JSON em POST e PUT são sempre envolvidos na chave do
recurso, em PascalCase singular:
POST /products
{ "Product": { "name": "Camiseta", "price": "99.90" } }
POST /orders
{ "Order": { "client_id": 1, "products": [...] } }
POST /customers
{ "Customer": { "name": "João Silva", "cpf": "12345678901" } }
Esquecer essa chave é a causa #1 de erro HTTP 400 na API Tray.
pager.total da
resposta para paginar.YYYY-MM-DD.YYYY-MM-DD HH:MM:SS (sem timezone — assume horário de Brasília).| Limite | Valor padrão | Corporate |
|---|---|---|
| Curto prazo | 180 req/min | 180 req/min |
| Diário | 10.000 req/dia | 50.000 req/dia |
HTTP 429 exige backoff exponencial (1s, 2s, 4s, 8s...).Antes de enviar à API, valide:
| Campo | Formato | Observação |
|---|---|---|
| CPF | 11 dígitos | Validar dígitos verificadores |
| CNPJ | 14 dígitos | Validar dígitos verificadores |
| CEP | 8 dígitos numéricos | Sem traço |
| EAN | Código de barras válido | GTIN-8/12/13/14 |
| NCM | 8 dígitos | Classificação fiscal |
pedido do dev sobre API Tray
↓
identifique o recurso (produtos, pedidos, clientes, frete...)
↓
carregue a skill específica do recurso (skills/<recurso>/SKILL.md)
↓
aplique as 6 regras desta skill em conjunto com a do recurso
↓
se houver scripts/validate.mjs no recurso, valide o payload antes de retornar
↓
gere o código com tokens via env, payload com chave do recurso,
access_token como query param
Carregue a skill do recurso correspondente:
| Área | Skills |
|---|---|
| Autenticação | tray-autorizacao, tray-webhooks |
| Catálogo | tray-produtos, tray-variacoes, tray-imagens-produtos, tray-categorias, tray-marcas, tray-kits, tray-caracteristicas, tray-informacoes-adicionais |
| Pedidos e logística | tray-pedidos, tray-status-pedido, tray-notas-fiscais, tray-frete, tray-configuracao-frete, tray-multicd, tray-carrinho-compras, tray-listagem-carrinho, tray-etiquetas-hub, tray-etiquetas-mercado-livre, tray-emissores-etiqueta |
| Clientes e pagamentos | tray-clientes, tray-enderecos-cliente, tray-perfis-cliente, tray-pagamentos, tray-cupons, tray-listas-preco-b2b, tray-newsletter |
| Loja e analytics | tray-informacoes-loja, tray-usuarios, tray-scripts-externos, tray-produtos-vendidos, tray-palavras-chave, tray-parceiros |
Para tarefas complexas que cruzam múltiplos recursos, use os agentes
especializados em agents/ (configuração, gestão de catálogo, gestão
de pedidos, debug, migração).
| Sintoma | Causa provável | Correção |
|---|---|---|
HTTP 400 campo obrigatório ausente | Faltou a chave do recurso ({"Product": {...}}) ou campo obrigatório | Reler skill do recurso; rodar validate.mjs |
HTTP 401 Unauthorized | access_token expirado (3h) ou em header em vez de query param | Renovar via refresh_token; mover para query param |
HTTP 404 em endpoint válido | URL base errada (api_address é por loja) | Usar api_address retornado no callback OAuth |
HTTP 429 Too Many Requests | Rate limit (180 req/min ou 10k/dia) | Backoff exponencial; reduzir batch size para 150 |
| Resposta inesperada em listagem | Esperando todos os itens em uma chamada | Paginação máxima é 50 — ler pager.total |
npx claudepluginhub tray-tecnologia/tray-api-ai-plugin --plugin tray-apiProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.