tray-pedidos

MANDATORY: Tool Call(s) Required Before Answering

• OBRIGATÓRIO: node skills/tray-dev/scripts/search_docs.mjs "<termo>" — confirme o comportamento da API antes de gerar código.
• OBRIGATÓRIO: node skills/pedidos/scripts/validate.mjs '<payload_json>' — valide a estrutura do payload antes de retornar código ao usuário.

Antes de responder

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

1. Confirme o método HTTP e endpoint correto para a operação solicitada.
2. Identifique os campos obrigatórios listados neste documento — não omita nenhum.
3. Verifique que access_token não aparece como literal string no código gerado.
4. Confirme que esta é a skill correta para o recurso (leia when_not_to_use no frontmatter).
5. Execute node skills/pedidos/scripts/validate.mjs '<payload_json>' para confirmar a estrutura do payload que vai gerar. O validador checa apenas estrutura (campos obrigatórios, tipos e campos desconhecidos), nunca valores reais — então monte um payload sintético com placeholders sempre que os valores vierem de variáveis de ambiente, da entrada do usuário ou de outras chamadas. Exemplo: node skills/pedidos/scripts/validate.mjs '{"Order":{"client_id":"<id>"}}'. Corrija todos os erros antes de retornar o código ao usuário. Até 3 tentativas — se persistir, explique o problema ao usuário.

API de Pedidos — Tray

Documentação oficial: https://developers.tray.com.br/#apis-de-pedidos

Endpoints

Método	Endpoint	Descrição
GET	/orders	Listagem de pedidos com paginação e filtros
GET	/orders/:id	Dados do pedido por ID
GET	/orders/:id/full	Dados completos (produtos, cliente, pagamento, frete)
POST	/orders	Cadastrar novo pedido
PUT	/orders/:id	Atualizar dados do pedido
PUT	/orders/:id/cancel	Cancelar pedido
POST	/orders/:id/products	Incluir produtos no pedido
DELETE	/orders/:id/products/:product_id	Excluir produto do pedido

Autenticação: ?access_token={token}

Campos do Pedido

Campo	Tipo	Descrição
id	number	ID do pedido
store_id	number	ID da loja
status_id	number	ID do status atual
client_id	number	ID do cliente
adm_user	string	Usuário administrativo
total_amount	decimal	Valor total do pedido
shipping_cost	decimal	Custo do frete
shipping_method	string	Método de envio
tracking_number	string	Código de rastreamento
payment_method	string	Método de pagamento
coupon_code	string	Código do cupom aplicado
discount	decimal	Valor do desconto
taxes	decimal	Impostos
created_at	datetime	Data de criação
updated_at	datetime	Data de atualização

Consulta Completa

O endpoint GET /orders/:id/full retorna dados completos incluindo:

• Produtos — lista de itens com quantidade, preço e variação
• Cliente — dados completos do comprador
• Endereço — endereço de entrega
• Pagamento — dados do método e status de pagamento
• Frete — dados de envio e rastreamento

Filtros de Listagem

Filtro	Descrição
status	Filtrar por status do pedido
created_at	Filtrar por data de criação
updated_at	Filtrar por data de atualização
customer_id	Filtrar por cliente
payment_method	Filtrar por método de pagamento

Cancelamento

Para cancelar um pedido, use PUT /orders/:id/cancel. O cancelamento atualiza o status e pode disparar webhooks.

Incluir/Excluir Produtos

• POST /orders/:id/products — adiciona produtos ao pedido existente
• DELETE /orders/:id/products/:product_id — remove produto do pedido

Paginação

limit (máximo 50, padrão 30), page.

Ciclo de Vida do Pedido

Criação → Aguardando Pagamento → Pago → Em Separação → Enviado → Entregue
                                    ↘ Cancelado

Boas Práticas

1. Use /orders/:id/full — para obter todos os dados em uma única chamada
2. Webhook de pedido — configure o webhook order para receber notificações em tempo real
3. Código de rastreamento — atualize o tracking_number quando o pedido for enviado
4. Não exclua pedidos — use cancelamento ao invés de exclusão

Como Usar no Claude Code

Exemplos de Prompt

• "lista os pedidos em aberto dos últimos 7 dias"
• "busca os dados completos do pedido ID 1001 incluindo produtos e pagamento"
• "cancela o pedido ID 2050"
• "atualiza o código de rastreamento do pedido 1500"

O que o Claude faz

1. Identifica a operação desejada (listar, consultar, atualizar ou cancelar)
2. Usa /orders/:id/full para consultas completas e /orders/:id para dados básicos
3. Gera o código com os filtros adequados na listagem (status, data, cliente)
4. Inclui o tratamento da resposta e extração dos campos relevantes

O que você recebe

• Código de consulta com os filtros aplicados e paginação configurada
• Chamada para /orders/:id/full com os dados completos do pedido
• Código de atualização com os campos necessários
• Código de cancelamento via PUT /orders/:id/cancel

Pré-requisitos

• access_token configurado
• order_id disponível para operações em pedidos específicos