Tray Visao Geral

Antes de responder

Execute estas verificações antes de gerar qualquer payload ou código:

1. Confirme que o pedido envolve a API Tray (não confunda com outras APIs de e-commerce). Se não for Tray, redirecione.
2. Identifique o recurso (produto, pedido, cliente, frete, etc.) e carregue a skill específica antes de responder com detalhes.
3. Verifique que access_token, consumer_key, consumer_secret e refresh_token não aparecem como literais no código gerado.
4. Confirme que o payload, se houver, está envolvido na chave do recurso ({"Product": {...}}, {"Order": {...}}, {"Customer": {...}}).
5. 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

• 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

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

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:

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