# Tray Autorizacao

> Autenticação e autorização na API da Tray. Utilize quando o desenvolvedor precisar implementar o fluxo OAuth 2.0, gerar chaves de acesso (access_token), renovar tokens expirados via refresh_token, ou tratar erros de autenticação na plataforma Tray. Inclui o fluxo completo de 3 etapas, campos de resposta, tempos de expiração e códigos de erro.

- Skill: `tray-tecnologia/tray-autorizacao` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add tray-tecnologia/tray-autorizacao`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tray-tecnologia/tray-autorizacao/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tray-tecnologia (https://skillmd.com/u/tray-tecnologia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tray-tecnologia/tray-autorizacao

---


## MANDATORY: Tool Calls Required Before Answering

> **Estas chamadas são OBRIGATÓRIAS, não opcionais.** Execute-as antes de gerar
> qualquer código ou payload. Se você está respondendo sem ter chamado as duas
> ferramentas abaixo, **pare e chame agora**.

### 1. Buscar documentação atualizada (sempre)

```bash
node skills/tray-dev/scripts/search_docs.mjs --topic=autorizacao "<termo da pergunta>"
```

- `<TOPIC_SLUG>`: ver tabela em `skills/tray-dev/SKILL.md`.
- Use os trechos retornados como fonte primária; este SKILL.md é resumo.

### 2. Validar payload localmente (antes de retornar código)

```bash
node skills/autorizacao/scripts/validate.mjs --schema=<SCHEMA_NAME> '<payload_json>'
```

- Schemas disponíveis: `auth-request`, `auth-refresh`. Use `--list-schemas` para confirmar.
- Exit codes: `0` válido · `1` inválido · `2` erro de uso.
- Para output programático: `--json`.
- Corrija todos os erros antes de retornar o código (até 3 tentativas).

## 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).

# 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 — **já inclui o sufixo `/web_api`** (ex.: `urldaloja.com.br/web_api`). |

> **`api_address` contém `/web_api`.** Conforme a doc oficial, `api_address` é o
> domínio da loja **+ `/web_api`** (ex.: `urldaloja.com.br/web_api`). A URL final
> fica `https://{api_address}/<recurso>` = `https://urldaloja.com.br/web_api/<recurso>`.
> Armazene o `api_address` exatamente como veio do callback; remover o `/web_api`
> (guardar só `urldaloja.com.br`) causa `HTTP 404` em todas as chamadas.

### 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):**

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "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