> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido

> Início rápido do PlayFab Economy v2 para configurar um Catalog v2, definir permissões, adicionar itens e habilitar a validação de recibos no Game Manager.

# Início rápido do Catalog v2

<Info>
  O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o [Fórum do PlayFab](https://community.playfab.com).
</Info>

Depois de se familiarizar com o Game Manager, você pode:

1. Configurar as permissões, as configurações e os itens de um Catalog v2.
2. Configurar a validação de recibos
3. Percorrer a compra de um item

Consulte o [tutorial específico do Unity](/pt-BR/services/playfab/economy-monetization/economy-v2/tutorials/getting-started-with-unity-and-android) para obter um passo a passo detalhado no Unity.

## Parte 1: Visão geral do catálogo

### Etapa 1 – Obter permissões

A primeira etapa é habilitar o catálogo na página de configurações da interface do Game Manager em ⚙️ **Title Settings** > **Economy (V2)**. Você pode usar a API `UpdateCatalogConfig` e definir o sinalizador `IsCatalogEnabled` como true.

Para interagir com o catálogo, você precisa entrar no Game Manager e usar as ferramentas do site ou obter um token de entidade para usar as APIs. A maneira mais fácil de obter um token de entidade é com a API [GetEntityToken](https://learn.microsoft.com/en-us/rest/api/playfab/authentication/authentication/get-entity-token).

<Note>
  Para chamar a API como administrador ou serviço autoritativo, o que você precisará fazer antes de criar seu primeiro item de catálogo, você precisará incluir um cabeçalho X-SecretKey com uma chave secreta do título. Você pode criar chaves secretas do título na interface do Game Manager em ⚙️ **Title Settings** > **Secret Keys**.
</Note>

#### API

```bash theme={null}
curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{titleId}}.playfabapi.com/Authentication/GetEntityToken \
  -d "{\"CustomTags\": {\"user\": \"{{email}}\"}}"
```

#### C# SDK

```csharp theme={null}
// ENABLE_PLAYFABSERVER_API symbol denotes this is an admin-level game server and not a game client.
private static async Task PlayFabEconomyv2QuickStart()
{
#if ENABLE_PLAYFABSERVER_API
    string systemGUID = Environment.GetEnvironmentVariable("SYSTEM_GUID", EnvironmentVariableTarget.Process);
    PlayFabSettings.staticSettings.DeveloperSecretKey =
        Environment.GetEnvironmentVariable("PLAYFAB_SECRET_KEY", EnvironmentVariableTarget.Process);

#endif
    PlayFabSettings.staticSettings.TitleId =
        Environment.GetEnvironmentVariable("PLAYFAB_TITLE_ID", EnvironmentVariableTarget.Process);
    PlayFab.EconomyModels.EntityKey gameEntityKey = new()
    {
        Type = "title",
        Id = PlayFabSettings.staticSettings.TitleId
    };

    PlayFabResult<GetEntityTokenResponse> gameTokenRequest = null;
    try
    {
        gameTokenRequest = await PlayFabAuthenticationAPI.GetEntityTokenAsync(new GetEntityTokenRequest()
        {
            CustomTags = new Dictionary<string, string>
            {
#if ENABLE_PLAYFABSERVER_API
                { "server", systemGUID }
#endif
            }
        });
        if (gameTokenRequest.Error != null)
        {
            throw new Exception(gameTokenRequest.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab Auth Error: {0}", e));
        return;
    }

    PlayFabAuthenticationContext gameAuthContext = new()
    {
        EntityToken = gameTokenRequest.Result.EntityToken,
    };
}
```

***

<Tip>
  Ao fazer chamadas como administrador de um título, ou seja, sem um [SessionTicket](https://learn.microsoft.com/en-us/rest/api/playfab/server/authentication/authenticate-session-ticket) de login de um usuário, a prática recomendada é incluir uma entrada *CustomTags* registrando quem está fazendo a chamada, seja você, um servidor ou um script automatizado. Isso facilita o rastreamento de alterações e a identificação de problemas ao consultar seus logs do PlayFab.
</Tip>

### Etapa 2 - Definir as configurações do catálogo

As [configurações do catálogo](/pt-BR/services/playfab/economy-monetization/economy-v2/settings) incluem muitas configurações diferentes, de tipos de conteúdo a conteúdo gerado pelo usuário. Você pode atualizar e recuperar todas elas por meio da API e visualizar facilmente muitas delas no Game Manager.

#### Game Manager

1. No [Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager), navegue até ⚙️ **Title Settings** > **Economy**.
2. Na guia **Catalog (V2)**, acesse **Catalog Settings**
3. Crie um *Content Type* padrão (criar um tipo "Game Item" é um bom ponto de partida).

#### API

Chame o método [Catalog/GetCatalogConfig](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/get-catalog-config) e, em seguida, use [UpdateCatalogConfig](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/update-catalog-config) para atualizar a matriz ContentTypes do catálogo com um tipo de catálogo.

```bash theme={null}
curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetCatalogConfig \
  -d "{\"CustomTags\": {\"user\": \"{{Email}}\"}}"

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateCatalogConfig \
  -d "{\"Config\": {{{CatalogConfig}}}, \"CustomTags\": {\"user\": \"{{Email}}\"}}"
```

Exemplo de payload retornado para um título com alguns tipos de conteúdo para Catalog e UGC:

```json theme={null}
{
    "code": 200,
    "status": "OK",
    "data": {
        "Config": {
            "IsCatalogEnabled": true,
            "AdminEntities": [...],
            "Catalog": {
                "ContentTypes": [
                    "gameitem",
                    "enemy",
                    "weapon",
                    "armor",
                    "levelupstats"
                ],
                "Tags": [...]
            },
            "DeepLinkFormats": [],
            "DisplayPropertyIndexInfos": [
                {
                    "Name": "TestSearchable",
                    "Type": "SearchString"
                }
            ],
            "ReviewerEntities": [],
            "UserGeneratedContent": {
                "ContentTypes": [
                    "weapon",
                    "armor"
                ],
                "Tags": [...]
            },
            ...
        }
    }
}
```

***

### Etapa 3 - Publicar um item no catálogo

#### GameManager

Navegue até **Economy** > **Catalog (V2)**.

Na guia **Items**, selecione **New Item**.

Preencha os metadados obrigatórios – há apenas quatro propriedades obrigatórias (*Creator Type*, *Title*, *Start date* e *Content type*). Selecione **Publish**.

<Tip>
  O Creator Type assume como padrão "title", embora possa haver casos em que jogadores criam itens para o seu jogo. Nesse caso, você selecionaria "title\_player\_account". Os campos com a opção *Edit JSON* são indexados por metadados, como o idioma de localização, que assume como padrão "neutral". Todas as datas estão em UTC.
</Tip>

```json theme={null}
{
  "NEUTRAL": "My Game Item",
  "en-US": "My Game Item"
}
```

#### API

Crie um item de catálogo em "rascunho" chamando o ponto de extremidade [CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item):

* O EntityToken (de GetEntityToken ou de outra chamada `login` do PlayFab) no cabeçalho X-EntityToken
* A ID do título do PlayFab em CreatorEntity.Id do item

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"
```

Dados:

```json theme={null}
{
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

#### C# SDK

```csharp theme={null}
private static async Task PlayFabEconomyv2QuickStart()
{
    // Continued from above example...
    CreateDraftItemRequest gameFireItem = new()
    {
        AuthenticationContext = gameAuthContext,
        Item = new CatalogItem()
        {
            CreatorEntity = gameEntityKey,
            Type = "catalogItem",
            ContentType = "gameitem",
            Title = new Dictionary<string, string>
            {
                { "NEUTRAL", "My Amazing Fire Sword" },
                { "en-US", "My Lit Lit Sword" }
            },
            StartDate = DateTime.Now,
            Tags = new List<string>
            {
              "weapon"
            }
        },
        Publish = true,
        CustomTags = new Dictionary<string, string>
        {
            { "server", systemGUID }
        }
    };
    PlayFabResult<CreateDraftItemResponse> gameDraftItemResponse = null;
    try
    {
        gameDraftItemResponse = await PlayFabEconomyAPI.CreateDraftItemAsync(gameFireItem);
        if (gameDraftItemResponse.Error != null)
        {
            throw new Exception(gameDraftItemResponse.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab CreateDraftItem Error: {0}", e));
        return;
    }
    Console.WriteLine(string.Format("PlayFab CreateDraftItem Success: {0}",
        JsonConvert.SerializeObject(gameDraftItemResponse.Result, Formatting.Indented)));
}
```

***

<Note>
  Colocar o item em estado de rascunho não é obrigatório – o rascunho se destina aos casos em que você espera iterar nos metadados por algum tempo. Damos suporte ao parâmetro "publish", que, quando definido como "true", publica o item imediatamente. Isso pode economizar algum volume de chamadas, dependendo do seu padrão.
</Note>

Quando um item estiver em rascunho, você poderá enviá-lo para o estado 'Published' usando o ponto de extremidade [PublishDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/publish-draft-item) (essa etapa é tratada de forma invisível no Game Manager). Depois que um item é publicado, ele pode ser pesquisado e fica disponível publicamente. Você precisa usar o ItemId retornado na resposta de CreateDraftItem para publicar.

### Etapa 4 - Fazer uma pesquisa

Depois que a chamada de publicação for bem-sucedida, o item poderá ser pesquisado usando o ItemId publicado anteriormente e o ponto de extremidade [SearchItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/search-items). A API Catalog/Search executa uma pesquisa no catálogo publicado usando um conjunto de parâmetros fornecidos à API e retorna um conjunto de resultados paginados.

#### Game Manager

A pesquisa do Game Manager é autoexplicativa e existe em cada página do Catalog v2. Os filtros *Published* e *Draft* ficam na parte superior. Selecione o ícone *Filters (Funnel)* ao lado do botão *Search* para ver a lista de filtros. Selecione `Enter ODATA filter` para adicionar um filtro OData.

#### API

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/SearchItems \
  -d "{{Data}}"
```

```json theme={null}
{
  "Search": "Fire",
  "Filter": "tags/any(t:t eq 'desert') and contentType eq 'gameitem'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2
}
```

Salve a ID retornada para usar mais adiante neste início rápido.

***

<Note>
  Os campos filter, orderBy e select de Catalog/search usam o [OData](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview) como padrão de consulta.
</Note>

## Parte 2: Visão geral de inventário e moedas virtuais

Itens de inventário e moedas virtuais são os dois 'compartimentos' de bens virtuais do jogo aos quais o PlayFab dá suporte para entidades de jogador. O processo é:

1. Configurar uma moeda virtual inicial
2. Criar um item com um custo em moeda virtual
3. Adicionar o item ao inventário de um jogador

### Etapa 1: Criar uma moeda

As moedas virtuais são a base das economias dos jogos. Jogadores e personagens podem receber essas moedas, que podem então ser usadas para comprar ou trocar itens.

Os itens podem ter um custo em moeda virtual ou em dinheiro real. Cada título pode dar suporte a várias moedas virtuais arbitrárias. As moedas oferecem flexibilidade para que seu jogo implemente qualquer meio de troca que você desejar (por exemplo, ouro, gemas, corações ou créditos interestelares).

#### Game Manager

1. Abra o Game Manager e acesse **Economy** > **Catalog (V2)**.
2. Selecione a guia **Currency**.
3. Escolha **New Currency**, definindo a *Start date*, um *Title* legível por humanos para a chave "neutral" e, no campo *Friendly ID*, insira um código de moeda exclusivo para essa moeda.
4. Selecione **Save as draft**. A Item ID é usada como código de moeda de rascunho.
5. Veja sua nova moeda selecionando o filtro **Draft** na lista de moedas.
6. Edite a moeda novamente e selecione **Save and publish**. A Friendly ID é usada como código de moeda publicado.

#### API

Crie um item de catálogo de moeda em rascunho chamando o ponto de extremidade [CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item) com o tipo definido como "currency", usando:

* Um EntityToken com permissões de catálogo
* O Entity.Id como 'Creator' do item
* A ID do título do PlayFab
* O item deve ser um Bundle do tipo 'Currency' e conter um Title e uma Description

Chame PublishItem com o ItemId retornado por CreateDraftItem.

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"
```

Dados:

```json theme={null}
{ 
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "currency",
    "ContentType": "gameitem",
    "AlternateIds": [
      { 
        "Type": "FriendlyId",
        "Value": "TC"
      } 
    ],
    "Title": {
      "NEUTRAL": "My Amazing Test Currency",
      "en-US": "My Test Coin"
    },
    "StartDate": "2023-07-27T00:00:00.000Z"
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

***

<Tip>
  Uma Catalog/Search pelo tipo 'currency' retornará todas as moedas que você definiu.
</Tip>

### Etapa 2 - Conceder moedas

#### Game Manager

Sua entidade de jogador precisa de moeda virtual para fazer uma compra.

1. Abra o Game Manager, navegue até Players e selecione **Search** para recuperar a lista de jogadores.
2. Selecione a Player ID à qual você deseja conceder moeda.
3. Selecione a guia **Inventory (V2)**.
4. Filtre pelo **Type** "Currency" e selecione **Pick multiple items** para ver a lista completa de moedas.
5. Escolha a *Currency* que você criou e insira uma nova quantidade para a entidade *Player*.
6. Selecione **Save**.

<Warning>
  As páginas que expõem as concessões de moeda aos jogadores não estão no Game Manager atualmente.
</Warning>

#### API

Você pode chamar [AddInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items) para adicionar moeda à carteira de uma entidade. Por padrão, você precisa usar a autenticação de entidade no nível do título para adicionar moedas virtuais arbitrariamente ao inventário de um jogador.

***

<Note>
  *AddInventoryItems* é considerada uma chamada de administrador do título e normalmente não é chamada diretamente pelo cliente do jogo.
</Note>

### Etapa 3 - Atualizar um item de catálogo

Um item deve ter um valor em moeda para poder ser comprado com moeda virtual.

#### GameManager

1. Abra o Game Manager e navegue até **Economy**.
2. Selecione a guia **Catalog (V2)** e verifique se o filtro está definido para itens **Published**.
3. Selecione o título do item que você criou anteriormente.
4. Selecione **Edit draft item**.
5. Selecione **➕ Add new price** e defina um *Amount* selecionando o item de moeda que você criou. Selecione **Add** para concluir.
6. Selecione **Save and Publish**.

#### API

Obtenha o rascunho do seu item de catálogo chamando o ponto de extremidade [GetDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/get-draft-item). Em seguida, atualize o rascunho com o ponto de extremidade [UpdateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/update-draft-item) usando:

* O EntityToken (de GetEntityToken ou de outra chamada `login` do PlayFab) no cabeçalho X-EntityToken
* O Entity.Id da chamada anterior em EntityKey.Id do item

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetDraftItem \
  -d "{{Data}}"
```

Dados:

```json theme={null}
{
  "Id": "{{EntityID}}",
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateDraftItem \
  -d "{{Data}}"
```

```json theme={null}
{
  "Item": {
    "Id": "{{EntityID}}",
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
    "PriceOptions": {
      "Prices": [
        {
          "Amounts": [
            {
              "ItemId": "{{CurrencyID}}",
              "Amount": 15
            }
          ]
        }
      ]
    }
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

Se você não definir `Publish` como `true`, deverá enviá-lo para o estado publicado usando [PublishDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/publish-draft-item). Depois que um item é publicado, ele pode ser pesquisado e fica disponível publicamente. Você precisa usar o "itemId" retornado na resposta de GetDraftItem para publicar.

## Confira também

* [Visão geral do Economy v2](/pt-BR/services/playfab/economy-monetization/economy-v2/overview)
* [Configurações](/pt-BR/services/playfab/economy-monetization/economy-v2/settings)
* [Lojas](/pt-BR/services/playfab/economy-monetization/economy-v2/catalog/stores)


## Related topics

- [Início rápido Linux](/pt-BR/services/playfab/sdks/c/quickstart-linux.md)
- [Início rápido Android](/pt-BR/services/playfab/sdks/c/quickstart-android.md)
- [Início rápido GDK](/pt-BR/services/playfab/sdks/c/quickstart-gdk.md)
- [Início rápido iOS](/pt-BR/services/playfab/sdks/c/quickstart-ios.md)
- [Início rápido Win32](/pt-BR/services/playfab/sdks/c/quickstart-win32.md)