tray-autorizacao

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/autorizacao/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/autorizacao/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, do callback OAuth ou de outras chamadas. Exemplo: node skills/autorizacao/scripts/validate.mjs '{"consumer_key":"<env>","consumer_secret":"<env>","code":"<callback>"}'. Corrija todos os erros antes de retornar o código ao usuário. Até 3 tentativas — se persistir, explique o problema ao usuário.

Autorização — API Tray

Documentação oficial: https://developers.tray.com.br/#autorizacao

Fluxo OAuth 2.0 (3 etapas)

Etapa 1 — Redirecionamento

Redirecione o lojista para a tela de autorização da Tray:

https://{dominio_loja}/auth.php?response_type=code&consumer_key={consumer_key}&callback={callback_url}

Parâmetros:

• response_type — sempre code
• consumer_key — chave do aplicativo (obtida ao criar o app na Tray)
• callback — URL de retorno do seu aplicativo

Etapa 2 — Callback

Após o lojista autorizar, a Tray redireciona para sua callback com os parâmetros:

Parâmetro	Descrição
code	Código de autorização (uso único)
adm_user	Identificador do usuário administrativo
store	URL da loja
api_address	Endereço base da API para esta loja

Etapa 3 — Gerar Chaves de Acesso

Endpoint: POST https://{api_address}/auth

Parâmetros do body (JSON):

Campo	Tipo	Obrigatório	Descrição
consumer_key	string	Sim	Chave do aplicativo
consumer_secret	string	Sim	Segredo do aplicativo
code	string	Sim	Código recebido no callback

Resposta de sucesso (201):

{
  "code": 201,
  "message": "Created tokens",
  "access_token": "xxxxxxxxxxxxx",
  "refresh_token": "xxxxxxxxxxxxx",
  "date_expiration_access_token": "2026-03-21 15:00:00",
  "date_expiration_refresh_token": "2026-04-20 12:00:00",
  "date_activated": "2026-03-21 12:00:00",
  "api_host": "https://{api_address}/",
  "store_id": "123456"
}

Renovar Chave de Acesso

Endpoint: GET https://{api_address}/auth?refresh_token={refresh_token}

Resposta de sucesso (200):

{
  "code": 200,
  "message": "Refreshed tokens",
  "access_token": "novo_access_token",
  "refresh_token": "novo_refresh_token",
  "date_expiration_access_token": "2026-03-21 18:00:00",
  "date_expiration_refresh_token": "2026-04-20 15:00:00",
  "store_id": "123456"
}

Expiração de Tokens

Token	Expiração	Ação necessária
access_token	3 horas	Renovar via refresh_token antes de expirar
refresh_token	30 dias	Requer nova autorização completa se expirar

Autenticação nas Requisições

Todas as chamadas à API (exceto rotas públicas) exigem o access_token como query parameter:

GET https://{api_address}/products?access_token={access_token}
POST https://{api_address}/products?access_token={access_token}

Códigos de Erro de Autenticação

Código	Situação	Ação recomendada
1000	Token expirado, loja ativa	Renovar via refresh_token
1001	Token expirado, loja bloqueada	Verificar status com o lojista
1002	Token expirado, loja inativa	Verificar ativação da loja
1003	Token expirado, loja cancelada	Loja não está mais disponível
1099	Token inválido ou expirado (motivo desconhecido)	Verificar token e refazer autenticação

Nota: o campo retornado pela API é error_code (não code). Validado em teste real: token inválido retorna error_code: 1099 com HTTP 401.

Resposta de erro (401):

{
  "code": 401,
  "message": "Unauthorized",
  "causes": ["Token expired or invalid"]
}

Limites de Requisições

Tipo	Limite
Curto prazo	180 requisições por minuto
Diário (padrão)	10.000 requisições por dia
Diário (corporate)	50.000 requisições por dia

Resposta de limite excedido (429): A API retorna HTTP 429 quando o limite é atingido. Implemente backoff exponencial.

Boas Práticas

1. Nunca hardcode tokens — use variáveis de ambiente (TRAY_ACCESS_TOKEN, TRAY_CONSUMER_KEY, TRAY_CONSUMER_SECRET)
2. Renove antes de expirar — agende renovação antes das 3 horas (ex: a cada 2h30)
3. Trate todos os códigos — implemente tratamento para códigos 1000, 1001, 1002, 1003 e 1099
4. Backoff exponencial — para erros 429, aguarde progressivamente (1s, 2s, 4s, 8s...)
5. Armazene o api_address — ele é específico por loja e retornado no callback

Como Usar no Claude Code

Exemplos de Prompt

• "implementa o fluxo OAuth completo com a API da Tray"
• "como conecto minha aplicação à Tray pela primeira vez?"
• "adiciona renovação automática do access_token antes de expirar"
• "como trato o erro 1099 da Tray na autenticação?"

O que o Claude faz

1. Explica o fluxo OAuth 2.0 de 3 etapas (redirecionamento → callback → geração de tokens)
2. Gera o código de autenticação na linguagem e framework do projeto
3. Implementa a lógica de renovação automática via refresh_token antes das 3 horas
4. Adiciona tratamento específico para cada código de erro (1000–1003, 1099)
5. Documenta as variáveis de ambiente necessárias

O que você recebe

• Código funcional do fluxo OAuth pronto para integrar
• Helper ou middleware de renovação automática de tokens
• Handler com os 5 códigos de erro de autenticação mapeados
• Exemplo de .env com todas as variáveis necessárias

Pré-requisitos

• consumer_key e consumer_secret do seu app na Tray (obtidos no painel de parceiros)
• URL de callback configurada e acessível publicamente