Guia de Migração

Migrando da v1 para v2

Este guia cobre as mudanças que você precisa fazer ao atualizar da API v1 para v2 do SteamApis. A v2 adiciona novas categorias (Conta, Market Data), reorganiza os endpoints de usuários Steam e de apps, e introduz um envelope de resposta padronizado.

Autenticação

v1 passava a API key como query parameter, normalmente api_key ou key:

GET /steam/profile/76561198038526790?api_key=YOUR_KEY

v2 passa a API key pelo header x-api-key (recomendado) ou como query parameter ?key= (ainda suportado):

fetch('https://api.steamapis.com/v2/steam/users/76561198038526790', {
  headers: { 'x-api-key': 'YOUR_KEY' }
})

Usar o header é recomendado porque a key não aparece em logs de servidor, histórico do browser nem em headers de referer.

Envelope de resposta

v1 retornava os dados diretamente no nível superior:

{
  "steamid": "76561198038526790",
  "personaname": "PEPZ"
}

v2 envolve cada resposta em um envelope padrão. A forma exata depende se o endpoint retorna um único recurso ou uma lista paginada:

{
  "success": true,
  "result": { "steamID": "76561198038526790", "nickname": "PEPZ" }
}

{
  "success": true,
  "results": [ { /* ... */ } ],
  "cursor": "6789abcdef012345",
  "hasMore": true
}

Os erros usam o mesmo envelope com success: false:

{
  "success": false,
  "error": { "name": "NOT_FOUND", "message": "User not found", "meta": {} }
}

Para acessar os dados, use data.result (recurso único) ou data.results (lista) em vez de ler o nível superior diretamente.

Renomeação de campos do usuário Steam

O endpoint de usuário v2 retorna os mesmos dados subjacentes da Steam, mas com nomes de campos em camelCase e um objeto avatar aninhado. Se você parseia respostas de usuário, atualize seus tipos:

Parâmetro Steam ID

Na v1, os endpoints de usuário exigiam um SteamID64 (ID numérico de 17 dígitos). Na v2, o parâmetro steamid aceita múltiplos formatos de Steam ID — SteamID64, SteamID, SteamID3 — e a API resolve automaticamente.

Mapeamento de endpoints

As tabelas a seguir mapeiam cada endpoint v1 para seu equivalente v2, agrupadas por categoria. Entradas marcadas "Novo na v2" não têm predecessor em v1.

Conta

Usuários Steam

Apps Steam

Itens Steam

Imagens

Market Data (marketplaces de terceiros)

Market Data é uma nova categoria na v2. Agrega dados de preço, ofertas, vendas e order book de 26 marketplaces de terceiros — funcionalidade que não existia na v1.

Além dos endpoints REST abaixo, a v2 também expõe um stream de ofertas via WebSocket em tempo real:

Resumo das breaking changes

1. Autenticação — mova a API key do query parameter api_key para o header x-api-key (ou deixe como ?key= se o acesso ao header não for prático).
2. Envelope de resposta — desempacote data.result (recurso único) ou data.results (lista) em vez de ler o nível superior. Respostas de lista paginadas incluem também cursor e hasMore.
3. Campos do usuário Steam — renomeie steamid → steamID, personaname → nickname, profileurl → url e outros (veja a tabela completa acima). Campos planos de avatar movidos para um objeto avatar aninhado.
4. Caminhos de endpoints — endpoints de usuário Steam agora vivem em /v2/steam/users/, endpoints de app em /v2/steam/apps/, endpoints de item em /v2/steam/items/.
5. Entrada de Steam ID — v2 aceita múltiplos formatos de Steam ID, não apenas SteamID64.
6. Novos endpoints — Conta, bans, recently-played, achievements, stats, friends, groups, player-counts, global-achievements, news, schema, store rankings, lista de itens e a categoria Market Data inteira.
7. Formato de erro — erros retornam { "success": false, "error": { "name": "...", "message": "...", "meta": ... } } em vez de variar por endpoint.