Transações aprimoradas

Visão geral

Use este guia para saber como associar um local a um comerciante específico e exibir informações detalhadas sobre ele.

Quando você emite comprovantes de transações abreviados, como "ACMEHCORP", seus clientes podem ter dificuldade para entender. Isso pode levar a cobranças contestadas e custos extras de suporte para você. Em vez disso, é melhor fornecer o nome completo do comerciante, como Acme Housewares.

Com as Transações Enriquecidas, é mais fácil fornecer informações intuitivas sobre as transações, incluindo o nome completo do comerciante, a categoria de negócios, a imagem da vitrine e os detalhes de contato e localização. Isso aumenta a transparência, melhora os Net Promoter Scores (NPS) e faz com que as pessoas passem mais tempo no app.

Exemplos de telas de dispositivos móveis comparando extratos de transações brutos com detalhes aprimorados do comerciante
Telas de amostra das transações aprimoradas (clique para ampliar)

Ativar APIs

Para implementar as transações aprimoradas, você precisa ativar as APIs abaixo no console do Google Cloud. Os links a seguir abrem o console do Google Cloud para que você possa ativar cada API no projeto selecionado:

Para mais detalhes sobre a configuração, consulte Começar a usar a Plataforma Google Maps.

Seções do guia de implementação

As seguintes implementações e personalizações são abordadas neste guia:

Associar comerciantes à Plataforma Google Maps Associe um comerciante no histórico de transações a um lugar na Plataforma Google Maps.
Exibir detalhes do comerciante Mostre transações com muitos dados e informações úteis sobre o comerciante para que os clientes possam reconhecer rapidamente a operação.
Adicionar um mapa do local do comerciante Adicione um mapa do local do comerciante com um marcador avançado.

Associar comerciantes à Plataforma Google Maps

Este exemplo usa:API Places (nova) Também disponível: JavaScript

Veja no fluxograma a seguir como seu aplicativo associa as transações do comerciante para retornar um resultado usando o Place Details de um banco de dados de comerciantes ou uma solicitação do Text Search:

Fluxograma para associar registros de transações de comerciantes a IDs de lugar e Place Details
Matriz de fluxo de correspondência do comerciante (clique para ampliar)

Conseguir IDs de lugar da Plataforma Google Maps

Você pode ter um banco de dados de comerciantes com informações básicas, como o nome e endereço da empresa. Para buscar as informações que a Plataforma Google Maps tem sobre esse lugar, incluindo detalhes de contato e avaliações enviadas pelos clientes, encontre o ID de lugar que corresponde a cada comerciante do seu banco de dados.

Para saber o ID de lugar de uma empresa, faça uma chamada para o endpoint do Text Search (novo) na API Places (nova) e solicite apenas o campo places.id na máscara de campo, o que aciona a SKU Text Search Essentials (somente IDs). Se o comerciante tiver vários locais, inclua a cidade ou a rua com o nome dele na consulta. Valide os resultados retornados para confirmar que eles correspondem ao comerciante.

O exemplo a seguir solicita o ID de lugar do escritório do Google em Taipei usando o nome do comerciante e a cidade:

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Armazenar IDs de lugar

Se quiser armazenar informações da Plataforma Google Maps sobre o comerciante para solicitações futuras, armazene o ID de lugar indefinidamente no seu banco de dados como um atributo do registro da empresa. Você só precisa executar a solicitação do Text Search (novo) uma vez para cada comerciante ou pode pesquisar o ID de lugar sempre que um cliente solicitar detalhes da transação.

Para manter a precisão dos IDs de lugar armazenados, atualize-os a cada 12 meses fazendo uma solicitação de Place Details (novo) que especifique apenas o campo id na máscara de campo.

Se os detalhes do lugar que aparecem não são relacionados ao comerciante em que o cliente concluiu a transação, o Google recomenda permitir que os clientes enviem feedback sobre a qualidade da correspondência.

Exibir detalhes do comerciante

Este exemplo usa:API Places (nova) Também disponível: SDK do Places para Android | SDK do Places para iOS | Biblioteca Places, API Maps JavaScript

Você pode compartilhar os detalhes de que os clientes precisam depois de visitar um local do comerciante. Depois de chamar o endpoint do Place Details (novo) na API Places (nova), você pode filtrar e renderizar a resposta em uma janela de informações, uma barra lateral na Web ou uma visualização de detalhes para dispositivos móveis dentro dos limites dos Termos de Serviço da Plataforma Google Maps.

Visualização detalhada da transação em dispositivos móveis mostrando o nome, o endereço, o mapa e os detalhes de contato do comerciante
Exemplo de tela de detalhes do comerciante (clique para ampliar)

Para emitir uma solicitação ao endpoint do Place Details, você precisa do ID de lugar para cada local. Consulte Acessar IDs de lugar da Plataforma Google Maps para recuperar o ID de lugar de um estabelecimento.

A seguinte solicitação do Place Details (New) retorna o nome de exibição, o endereço formatado, as coordenadas, o site, o número de telefone, o ícone, o horário de funcionamento e a classificação em formato JSON com o ID de lugar do escritório do Google no edifício Taipei 101:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

Se você estiver criando um aplicativo da Web com a API Maps JavaScript, também poderá usar a classe Place para buscar os mesmos campos no cliente:

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

Adicionar um mapa do local do comerciante

Este exemplo usa: API Maps JavaScript | API Geocoding | API Maps Static Também disponível: Android | iOS

Determinar o local do comerciante

É possível colocar um marcador em um mapa usando coordenadas geográficas de detalhes do lugar. Se o banco de dados de comerciantes tiver endereços sem coordenadas geográficas e você não estiver solicitando detalhes de lugares, use a API Geocoding para converter endereços em coordenadas de latitude e longitude no servidor, armazenar essas coordenadas no banco de dados e atualizá-las pelo menos uma vez a cada 30 dias.

O exemplo a seguir usa a API Geocoding para ver a latitude e longitude do ID de lugar do escritório do Google em Taipei:

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

Adicionar um marcador avançado em um mapa da Web

Como os clientes consultam o mapa para confirmar transações, em vez de pesquisar essas informações, configure seu mapa com interatividade limitada e coloque um marcador avançado no local do comerciante. Os Marcadores Avançados exigem um ID de mapa e a biblioteca marker (libraries=marker).

Primeiro, carregue a API Maps JavaScript com libraries=marker e adicione um contêiner div para o mapa:

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

Em seguida, inicialize o mapa com gestureHandling: "none" e zoomControl: false para limitar a interatividade, forneça seu mapId e crie um google.maps.marker.AdvancedMarkerElement nas coordenadas do comerciante:

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

Também é possível personalizar seus marcadores avançados mudando o plano de fundo, a borda ou a cor do glifo do alfinete ou fornecendo uma imagem gráfica personalizada para a categoria do comerciante.

Adicionar uma imagem de mapa estática

Se você preferir uma imagem de mapa não interativa para computadores ou Web para dispositivos móveis, crie um URL da API Maps Static com um único marcador nas coordenadas de latitude e longitude ou no endereço do comerciante. A API Maps Static retorna uma versão de imagem de um mapa usando os parâmetros que você especificar.

A solicitação a seguir retorna um mapa de 640 x 480 pixels, centralizado em um marcador vermelho no escritório do Google em Taipei com um estilo de mapa baseado na nuvem:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

A tabela a seguir descreve cada seção da solicitação:

URL da API https://maps.googleapis.com/maps/api/staticmap?
Tamanho da imagem size=640x480
Marcadores de local do comerciante (usando codificação de URL) markers=color:red%7C25.033976%2C121.5645389
Estilização de mapas baseada na nuvem map_id=b224095f76859890
Chave de API key=YOUR_API_KEY
Assinatura digital (saiba como assinar digitalmente sua solicitação) signature=BASE64_SIGNATURE

A solicitação produz a seguinte imagem de mapa estático:

Mapa centralizado no escritório do Google em Taipei com um marcador de local vermelho

Também é possível usar um endereço como a localização do marcador:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

Para mais opções de parâmetro, consulte a documentação da API Maps Static.

Adicionar um mapa ao seu app para dispositivos móveis

Se você usa o SDK do Maps para Android ou o SDK do Maps para iOS, é possível inserir um marcador avançado usando as coordenadas de Place Details.

Como os clientes visualizam o mapa para confirmar transações, em vez de pesquisar essas informações, configure um mapa com interatividade limitada: