Preços regionais

A configurar um catálogo de itens, você deve definir as políticas de preço para usuários em diferentes países (precificação regional) para itens virtuais e pacotes de chaves de jogo. Por padrão, o preço por cada item ou pacote de chaves de jogo é definido em USD. Você pode definir restrições regionais e preços regionais ao mesmo tempo.

Como funciona

Os preços no catálogo se baseiam no país do usuário.

Durante o pagamento via Pay Station, o preço de um item é convertido para a moeda do país do usuário e inclui impostos, se aplicável.

Determinação de país

• Ao solicitar um catálogo de itens, o país do usuário é passado no parâmetro country nos métodos da subseção Catálogo do grupo de métodos Itens virtuais & moeda ou Chaves do jogo.
  Se o país não for especificado, ele será determinado com base no endereço IP do usuário. Depois, os preços para o catálogo de itens são selecionados para o país do usuário.
• Ao comprar um item:
  • Se você usar as chamadas de cliente para obter um token de pagamento, é importante usá-las apenas do lado do cliente e não do lado do servidor. O país e a moeda nas chamadas de clientes são determinados pelo endereço IP do usuário. Usar esse método a partir do servidor pode levar a uma determinação incorreta da moeda e afetar os métodos de pagamento no Pay Station.
  • Se você usar a chamada de servidor Criar token de pagamento para compra, você deverá passar o objeto country no corpo da solicitação ou o endereço IP do usuário no cabeçalho X-User-Ip.

1. 1. Se o país no parâmetro country.value e o endereço IP no cabeçalho X-User-Ip forem passados, a preferência é dada ao valor do país no parâmetro country.value.

Princípios de exibição de preço no catálogo de itens

Para todos os itens do catálogo, você deve usar a mesma lista de moedas na qual os preços são especificados.

Isso deve ser feito para que todos os itens do catálogo sejam exibidos na mesma moeda. Se o preço não for especificado para um dos itens em um dos países, os preços de todo o catálogo nesse país serão exibidos na moeda padrão.

Se a moeda padrão for diferente nos itens, o preço será exibido na moeda padrão do primeiro item no catálogo. Se um dos itens não possuir um preço nessa moeda, será retornado um valor de null na resposta. Isso levará a uma exibição incorreta do preço do item e pode afetar a exibição do catálogo como um todo.

Exemplos:

• 1 item, 1 moeda, sem preços regionais
• 1 item, 2 moedas, sem preços regionais
• 1 item, existem preços regionais
• Múltiplos itens, existem preços regionais, uma moeda padrão
• Múltiplos itens, existem preços regionais, moedas padrões diferentes

A moeda padrão para o item é USD e o preço é 5 USD. Não há configurações para países. Nesse caso, todos os usuários de todos os países verão esse preço.

Duas opções de preço são definidas para o item: em USD e em EUR, mas preços especiais para países não são especificados. Nesse caso, os usuários dos países onde EUR é usado verão o preço como 7 EUR. Os usuários de todos os outros países verão o preço como 5 USD, pois esse é o preço na moeda padrão.

O projeto possui preços nas seguintes moedas:

• preço padrão — 7 USD
• preço em euro — 6 EUR
• preços regionais:
  • Alemanha — 8 EUR
  • Itália — 5 EUR
  • Malásia — 20 MYR
  • África do Sul — 90 ZAR

Dependendo do país do usuário, a exibição de preços no catálogo será como a seguir:

País do usuário	Preço do catálogo	Comentário
EUA	7 USD	Os EUA é um país onde se utiliza USD. Um preço especial para os EUA não é especificado.
Japão	7 USD	A moeda do Japão não é especificada, então o preço é exibido na moeda padrão.
França	6 EUR	A França é um país onde se utiliza EUR. Um preço especial para a França não é especificado.
Alemanha	8 EUR	Um preço regional é especificado para a Alemanha.
Itália	5 EUR	Um preço regional é especificado para a Itália.
Malásia	20 MYR	Um preço regional é especificado para a Malásia.
África do Sul	90 ZAR	Um preço regional é especificado para a África do Sul.

O projeto tem preços nas seguintes moedas:

• o preço padrão para todos os itens é exibido em dólares americanos (USD)
• na Malásia, os preços para todos os itens estão no Ringgit malaio (MYR)
• na África do Sul, os preços para todos os itens, com exceção de um, em Rand sul-africano (ZAR)

Nesse caso, o catálogo é exibido em MYR para os usuários da Malásia, mas em USD para a África do Sul. Para os usuários da África do Sul, o preço é exibido em USD, pois o preço em ZAR não foi especificado a um dos itens.

O projeto possui preços nas seguintes moedas:

• o preço padrão para o 1_test_item está em dólares americanos (USD)
• o preço padrão para o item 2_test_item está em euro (EUR)
• na África do Sul, o preço para 1_test_item é atribuído em rand sul-africano (ZAR), para 2_test_item ele não é especificado

Nesse caso, o preço deve ser exibido na moeda padrão do primeiro item do catálogo para os usuários da África do Sul — 1_test_item.

A moeda padrão para 1_test_item — USD. Não corresponde à moeda padrão de 2_test_item — EUR. Além disso, não há preço em USD na lista de preços para ele.

Portanto, o valor retornado para 2_test_item será null.

Quem pode usar

Parceiros que querem incrementar as vendas em países com baixo poder de compra ao definir a política de preços da loja para usuários de diferentes países.

Como obtê-lo

Você pode adicionar, editar e excluir preços regionais:

• através da Conta do Publicador ao criar/editar um item
• através da Conta do Publicador ao importar preços via arquivo
• usando métodos de API

Configurando via Conta do Publicador ao criar e editar itens:

1. Abra o projeto na Conta do Publicador.
2. Clique em Loja no menu lateral.
3. No painel Itens Virtuais , clique em Configurar.
4. Clique em + e selecione Criar item na lista suspensa.

5. Especifique:
   • imagem
   • SKU
   • um ou vários grupos ao qual o item deve pertencer
   • nome
   • descrição
   • propriedade do item — itens consumíveis, não consumíveis ou de tempo limitado
6. No bloco Configurações de preço, escolha Item pago.
7. Alterne o Preço na moeda real para Ativo e especifique o preço. Se você não definir preços regionais, o preço de um item será o mesmo para todos os países e em dólares americanos.

8. Configurar preços:
   • Se você quiser configurar o preço de um item em diferentes moedas, clique em + para especificar a moeda e o preço.
   • Se você quer definir preços especiais para países, clique em Adicionar preço e especifique o país, moeda e quantidade. Você pode definir a quantidade de preços regionais necessário.
9. Se você quer adicionar o preço na moeda virtual, alterne para Preço na moeda virtual para Ativo e especifique o preço.
10. Se quiser limitar a disponibilidade de itens para usuários específicos, alterne para Limitar número de vezes um usuário pode comprar este item para Ativo e especifique o número.
11. Se quiser exibir um item na loja, alterne para Exibir item na loja para Ativo.
12. Clique Criar item.

Importar do arquivo na Conta de Publicador

Você pode importar preços regionais de um arquivo para itens pré-criados.

Características

• Envie ou atualize preços regionais para vários itens de uma vez.
• Compatível para itens de todos os tipos:
  • itens virtuais
  • moeda virtual
  • pacotes de moeda virtual
  • pacotes de chaves de jogo
  • em uma plataforma específica

• Validação dos dados carregados. Se a estrutura do arquivo ou o formato de dados não atender aos requisitos, será exibida uma lista de erros durante a importação.

Estrutura de arquivos

• SKU — o SKU do item para a qual os preços regionais devem ser definidos.
• Country — o código do país no formato ISO 3166-1 alpha-2. Confira a lista de países suportados pela Xsolla antes de enviar o arquivo CSV. O preenchimento das células nessa coluna é opcional. Você pode ver exemplos de exibição de preço se o país não for especificado.
• Currency — o código da moeda está no formato ISO 4217.
• Amount — o preço do item. Use um ponto como separador decimal.

• IsDefault — se é o preço padrão. Especifique:

  • 1 — isso é para a linha com o preço padrão. É exibido em todos os países sem preços regionais.
  • 0 — para todas as outras linhas. Você também pode deixar a célula na coluna isDefault vazia.

Observação

O preço padrão não deve ser regional. Deixe a célula na coluna Country vazia.

EXEMPLO

Arquivo corretamente preenchido (diversos itens, 3 moedas, preços regionais disponíveis).

Arquivo preenchido incorretamente (diversos itens, 3 moedas, preços regionais disponíveis).
Erro: em virtual-item-1 e bundle-1, as células do grupo na coluna País não ficam vazias.

Ao adicionar cada novo item, você deve definir o preço na moeda padrão. Se não for especificado, um erro será exibido ao importar o arquivo.

EXEMPLO

Arquivo corretamente preenchido (diversos itens, 3 moedas, preços regionais disponíveis).

Arquivo preenchido incorretamente (diversos itens, 3 moedas, preços regionais disponíveis).
Erro: não há uma moeda padrão para os grupos virtual-item-1 e bundle-1.

• Plataforma — o SKU da plataforma. Utilizado ao definir preços regionais para chaves de jogo, mas não é usado para outros itens.

  Plataformas disponíveis.

  SKU da plataforma	Nome da plataforma
  steam	Steam
  playstation	PlayStation
  xbox	Xbox
  uplay	Uplay
  origin	Origin
  drmfree	Sem DRM
  gog	GOG
  epicgames	Epic Games Store
  nintendo_eshop	Nintendo Switch eShop
  discord_game_store	Discord Game Store
  oculus	Oculus
  viveport	Viveport
  stadia	Google Stadia

Observação

Chaves de jogo com o mesmo SKU, mas plataformas diferentes, são consideradas entidades diferentes. Cada entidade deve ter um preço especificado na moeda padrão.

EXEMPLO

Arquivo preenchido corretamente (diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 2 plataformas).

Arquivo preenchido incorretamente (diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 2 plataformas).
Erro 1: agrupamento incorreto de chaves de jogo por SKU e Plataforma, resultando em nove entidades encontradas, em vez de três.
Erro 2: grupos 3, 4, 5 e 6 não possuem um preço padrão devido ao agrupamento incorreto.
Erro 3: o grupo 9 sobrescreverá os dados do grupo 7 porque possui um conjunto inteiro de preços para o mesmo item. Como resultado, game-key-2 para a plataforma playstation terá um preço em MYR somente após a importação.

Exemplos de conclusão de arquivos e possíveis erros

• Diversos itens, 3 moedas, nenhum preço regional.
• Itens diversos, 1 moeda, nenhum preço regional.
• Diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 1 plataforma.
• Diversas chaves de jogo, 3 moedas, nenhum preço regional, 2 plataformas.

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault
virtual-item-1,EUR,9.09,,0
virtual-item-1,USD,10.1,,1
virtual-item-1,MYR,47,,0
virtual-currency-1-pack-100,EUR,2.09,,0
virtual-currency-1-pack-100,USD,2.3,,1
virtual-currency-1-pack-100,MYR,24,,0
bundle-1,EUR,15,,0
bundle-1,USD,17,,1
bundle-1,MYR,82,,0

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault
virtual-item-1,USD,10.1,,1
virtual-currency-1-pack-100,USD,2.3,,1
bundle-1,USD,17,,1

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault,Platform
game-key-1,EUR,9.09,,1,steam
game-key-1,EUR,9.2,DE,0,steam
game-key-1,EUR,8.09,IT,0,steam
game-key-1,USD,10.1,US,0,steam
game-key-1,MYR,47,MY,0,steam
game-key-2,EUR,2.09,,1,steam
game-key-2,EUR,2.2,DE,0,steam
game-key-2,EUR,1.79,IT,0,steam
game-key-2,USD,2.3,US,0,steam
game-key-2,MYR,24,MY,0,steam

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault,Platform
game-key-1,USD,10.1,,1,steam
game-key-1,EUR,9.09,,0,steam
game-key-1,MYR,47,,0,steam
game-key-1,USD,17,,1,playstation
game-key-1,EUR,15,,0,playstation
game-key-1,MYR,82,,0,playstation
game-key-2,USD,2.3,,1,steam
game-key-2,EUR,2.09,,0,steam
game-key-2,MYR,24,,0,steam

• Diversas chaves de jogo, 3 moedas, nenhum preço regional, 2 plataformas.
• Diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 2 plataformas.
• Diversos itens, 3 moedas, preços regionais disponíveis.
• Diversos itens, 3 moedas, preços regionais disponíveis.
• Diversos itens, 3 moedas, nenhum preço regional.

Erro: os grupos game-key-1 + steam e game-key-2 + steam não possuem preços padrões.

Erro: os grupos game-key-1 + steam e game-key-2 + steam possuem os EUA como o país de definição dos preços padrões.

Erro: os grupos virtual-item-1 e bundle-1 não possuem preços padrões.

Erro: os grupos virtual-item-1 e bundle-1 possuem os EUA como o país de definição dos preços padrões.

Erro 1: agrupamento incorreto de itens por SKU, resultando em cinco entidades encontradas em vez de três.
Erro 2: o grupo 3 não possui um preço padrão devido ao agrupamento incorreto.
Erro 3: o grupo 4 sobrescreverá os dados do grupo 2 porque possui um conjunto inteiro de preços para o mesmo item. Como resultado, o SKU do virtual-currency-1-pack-100 terá um preço em MYR somente após a importação.

Importação de arquivos

1. Abra seu projeto na Conta do Publicador.
2. Clique em Loja no menu lateral e vá para a seção com qualquer tipo de produto.
3. Clique em Importar preços.

4. Na janela Importar, baixe o modelo de arquivo e adicione os valores.
5. Carregue o arquivo para o campo correspondente na janela Importar.
6. Se ocorrer qualquer erro durante a importação, a janela Importar exibe uma lista dos erros e as recomendações para correção. Faça as alterações necessárias ao arquivo e carregue novamente.

Após um envio bem-sucedido, os preços regionais dos itens com os SKUs especificados será atualizado de acordo com os preços no arquivo. Os preços especificados anteriormente serão excluídos.

Exemplo:

Há diversos preços em moedas diferentes e diversos preços regionais para o item na Conta de Distribuidor. No arquivo importado, há apenas um preço em EUR. Depois de importar o arquivo, apenas um preço em EUR será especificado para esse item na Conta de Distribuidor.

Configuração usando métodos de API

• nos métodos para criar e atualizar itens virtuais
• nos métodos para criar e atualizar a moeda virtual
• nos métodos para criar e atualizar pacotes de moeda virtual
• nos métodos para criar e atualizar pacotes

• nos métodos para criar e atualizar pacotes de chaves de jogo

"prices": [
      {
        "amount": 100,
        "currency": "USD",
        "is_enabled": true,
        "is_default": true
      },
      {
        "amount": 200,
        "currency": "CZK",
        "country_iso": "CZ",
        "is_enabled": false,
        "is_default": false
      }
    ]