Inventários de usuários

A API de Inventário permite acessar a maior parte das mesmas informações que a página Meu Inventário do Roblox. Você pode verificar se um usuário possui itens individuais e recuperar a lista completa de itens que um jogador possui.

As respostas da API de Inventário incluem itens das seguintes categorias:

• Roupas (acessórios, calças, roupas clássicas, sapatos, camisetas)
• Compras e recompensas (emblemas, passes, lugares comprados, servidores privados)
• Itens de avatar (animações de avatar, cabeças clássicas, emotes, rostos, cabelo, cabeças)

Antes de usar a API de Inventário, você deve gerar uma chave de API ou configurar OAuth 2 para seu app. Os exemplos nesta página usam chaves de API.

Verificar propriedade de item

Se você quiser verificar se um usuário possui um item específico (por exemplo, um item limitado, emblema, passe ou servidor privado), use o parâmetro filter para verificar uma lista separada por vírgulas de um ou mais IDs. Este exemplo de código verifica três IDs de ativos:

const https = require('node:https');

const userId = 11111111111;
const hostname = 'apis.roblox.com';
const path = `/cloud/v2/users/${userId}/inventory-items`;
const params = '?filter=assetIds=62724852,1028595,4773588762';

const url = 'https://' + hostname + path + params;

const apiKey = '123456789012345678901234567890123456789012345678';

const options = {
  headers: {
    'x-api-key': `${apiKey}`,
  },
};

https
  .get(url, options, (response) => {
    console.log('statusCode:', response.statusCode);
    let data = '';
    response.on('data', (d) => {
      data += d;
    });
    response.on('end', () => {
      if (response.statusCode === 200) {
        const jsonData = JSON.parse(data);
        console.log('Response Data:', JSON.stringify(jsonData, null, 2));
      } else {
        console.error('Error:', response.statusCode, response.statusMessage);
      }
    });
  })
  .on('error', (e) => {
    console.error(e);
  });

A seguinte resposta indica que o usuário possui um dos três itens:

{
  "inventoryItems": [
    {
      "path": "users/11111111111/inventory-items/VVNFUl9BU1NFVF9JRD0yMDAxMDUxMTkzODg",
      "assetDetails": {
        "assetId": "1028595",
        "inventoryItemAssetType": "CLASSIC_TSHIRT",
        "instanceId": "200105119388"
      }
    }
  ],
  "nextPageToken": ""
}

Filtrar itens

Se você quiser exibir, por exemplo, apenas as colecionáveis que um usuário possui, use o mesmo código que acima, apenas com um parâmetro filter diferente.

const params = '?filter=onlyCollectibles=true;inventoryItemAssetTypes=*';

Misture e combine filtros usando uma lista separada por ponto e vírgula. Aqui estão alguns exemplos:

filter=onlyCollectibles=true;inventoryItemAssetTypes=HAT,CLASSIC_PANTS

filter=badgeIds=111111,222222;gamePassIds=777777;privateServerIds=999999

filter=gamePasses=true;badges=true

A maioria das chamadas para a API não requer permissões específicas, mas vários filtros requerem permissões de leitura de Inventário. Para mais informações, consulte Filtragem.

Paginando resultados

Se uma resposta incluir um valor para nextPageToken, use esse valor no parâmetro pageToken da solicitação subsequente para recuperar a próxima página. Para mais informações, consulte Paginação.

Se o número de resultados for divisível por maxPageSize (por exemplo, você tem 50 resultados e um maxPageSize de 25), você pode encontrar uma situação em que sua resposta inclui um valor para nextPageToken, mas uma solicitação usando esse token não retorna resultados:

GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=cccDDD
{
    "inventoryItems": [],
    "nextPageToken": ""
}

Ao implementar a paginação em seu aplicativo, a melhor prática é verificar não apenas um nextPageToken não vazio, mas também um array inventoryItems não vazio.