| name | tray-visao-geral |
| description | Skill de entrada para qualquer trabalho de integração com a API da Tray. Estabelece as regras invariantes da plataforma (OAuth como query param, payloads envolvidos na chave do recurso, expiração de tokens, rate limit, validação de dados brasileiros) e orienta para a skill específica do recurso. Sempre carregue esta skill antes de gerar código contra a API Tray.
|
| when_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.
|
| when_not_to_use | Não use quando a pergunta não envolver a API ou plataforma Tray. Para detalhes específicos de um recurso (produtos, pedidos, clientes, frete, etc.) carregue esta skill em conjunto com a skill do recurso, não isolada.
|
Antes de responder
Execute estas verificações antes de gerar qualquer payload ou código:
- Confirme que o pedido envolve a API Tray (não confunda com outras APIs
de e-commerce). Se não for Tray, redirecione.
- Identifique o recurso (produto, pedido, cliente, frete, etc.) e
carregue a skill específica antes de responder com detalhes.
- Verifique que
access_token, consumer_key, consumer_secret e
refresh_token não aparecem como literais no código gerado.
- Confirme que o payload, se houver, está envolvido na chave do recurso
(
{"Product": {...}}, {"Order": {...}}, {"Customer": {...}}).
- Confirme que o
access_token é passado como query parameter
(?access_token={token}), nunca como header.
Visão Geral — API Tray
Documentação oficial: https://developers.tray.com.br
Regras invariantes da plataforma
Estas regras valem para toda chamada à API Tray e devem ser aplicadas
mesmo que a skill do recurso específico não as repita.
1. Autenticação OAuth 2.0
| Token | Vida útil | Como renovar |
|---|
access_token | 3 horas | GET /auth?consumer_key=...&refresh_token=... |
refresh_token | 30 dias | Refazer fluxo OAuth completo |
- Sempre passado como query parameter:
?access_token={token}.
- Nunca como header (
Authorization: Bearer ... não funciona na API Tray).
- Nunca hardcoded no código — sempre via variável de ambiente.
Detalhes do fluxo de 3 etapas em skills/autorizacao/SKILL.md.
2. URL base por loja
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.
Atenção — api_address já contém /web_api. O valor retornado no
callback é o domínio da loja + /web_api (ex.: urldaloja.com.br/web_api),
conforme a doc oficial (api_address = {URL da loja}/web_api). Logo a URL
final de qualquer recurso é https://urldaloja.com.br/web_api/<recurso> — o
{api_address} dos exemplos das skills já embute o /web_api, por isso os
exemplos não o repetem. Armazene o api_address exatamente como veio do
callback (com o /web_api); guardar só urldaloja.com.br e montar
https://urldaloja.com.br/<recurso> resulta em HTTP 404.
3. Formato de payload
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.
4. Paginação e datas
- Máximo 50 itens por página em listagens. Use
pager.total da
resposta para paginar.
- Datas:
YYYY-MM-DD.
- Timestamps:
YYYY-MM-DD HH:MM:SS (sem timezone — assume horário de Brasília).
5. Rate limit
| Limite | Valor padrão | Corporate |
|---|
| Curto prazo | 180 req/min | 180 req/min |
| Diário | 10.000 req/dia | 50.000 req/dia |
- Em operações em lote: 150 itens por batch com pausa de 60 s.
HTTP 429 exige backoff exponencial (1s, 2s, 4s, 8s...).
6. Dados brasileiros
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 |
Fluxo recomendado para o agente
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
Skills por área
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).
Erros mais comuns e como evitar
| 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 |
