Este guia descreve como usar o serviço de Segmentação por Lista de Clientes de Fidelidade na API Merchant. Esse serviço permite que comerciantes e provedores de fidelidade terceirizados que atuam em nome de comerciantes gerenciem dados de fidelidade do cliente, como identificadores de usuário e informações de nível, para personalização orgânica na Pesquisa Google, sem precisar de uma conta ativa do Google Ads.
Visão geral
Use o serviço de Segmentação por Lista de Clientes com Fidelidade para fazer upload de dados de fidelidade, que são usados para oferecer recursos de personalização de fidelidade orgânica na Pesquisa Google, como mostrar preços específicos para membros. Use o método personalizado ManageLoyaltyCustomerMatch
para associar seus clientes aos níveis do programa de fidelidade, permitindo
inserir, atualizar ou remover o status de fidelidade deles com base em identificadores
de usuário.
Principais conceitos
- Interface unificada: um endpoint exclusivo para adicionar, atualizar ou remover detalhes do nível de fidelidade do cliente.
- Design com foco em privacidade: para proteger a privacidade do usuário e evitar sondagens não autorizadas de contas, a API não oferece suporte às operações GET ou LIST, garantindo que os dados sejam gerenciados sem recuperação ou auditoria.
- Identificação flexível: faça a correspondência de usuários usando pelo menos um identificador válido, como endereço de e-mail, endereço físico ou número de telefone.
- Processamento com base em consentimento: o serviço armazena e usa os dados do cliente somente quando o usuário final concede ao Google a permissão necessária. Para proteger e evitar a sondagem da existência da conta ou do status de consentimento, o serviço retorna um sucesso silencioso se não houver correspondência ou se o consentimento não for concedido.
- Atualização do saldo de pontos: o Google usa o
pointBalancede um cliente apenas por 60 dias após a atualização mais recente desse cliente. Para mais detalhes, consulte Manter os saldos de pontos atualizados.
Pré-requisitos
Siga estes requisitos para usar o serviço de Segmentação por Lista de Clientes com Fidelidade:
- Configuração da conta: verifique se você tem uma conta ativa do Merchant Center (ou acesso autorizado à conta do comerciante, se você for um provedor de fidelidade terceirizado). Não é necessário criar uma conta do Google Ads para usar o serviço de Segmentação por Lista de Clientes de Fidelidade.
- Configuração do programa de fidelidade: ative o programa de fidelidade na sua conta do Merchant Center e defina os níveis de fidelidade.
- Ordem dos níveis: preste atenção à ordem em que os níveis de fidelidade são definidos na interface do Merchant Center. A API usa essa sequência exata para o mapeamento de tipo enumerado.
Método: ManageLoyaltyCustomerMatch
O método ManageLoyaltyCustomerMatch serve como a interface central para
gerenciar associações de fidelidade do cliente. Com base na entrada fornecida, o serviço
determina automaticamente se o status do nível de fidelidade de um cliente
precisa ser inserido, atualizado ou removido. A operação é
idempotente: solicitações idênticas
repetidas têm o mesmo efeito que uma única solicitação.
A solicitação a seguir demonstra como gerenciar associações de fidelidade do cliente pela API:
POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage
Essa solicitação define os seguintes parâmetros de caminho obrigatórios:
API_VERSION: a versão da API, como v1.ACCOUNT_ID: o ID da conta do Merchant Center.
Inclua um objeto loyaltyCustomer no corpo da solicitação.
{
"userIdentifier": {
"emailAddress": "string",
"address": {
"addressLines": ["string"],
"locality": "string",
"administrativeArea": "string",
"postalCode": "string",
"regionCode": "string"
},
"phoneNumber": "string"
},
"loyaltyTier": "LoyaltyTier",
"pointBalance": "integer"
}
Campos loyaltyCustomer
- userIdentifier: o conjunto de identificadores usados para corresponder ao cliente. Pelo menos um campo em userIdentifier precisa ser fornecido e válido.
- loyaltyTier: o nível de fidelidade a ser associado ao
cliente. É associado à ordem da faixa na configuração do Merchant Center.
Para mais detalhes, consulte
Noções básicas sobre o mapeamento do
loyaltyTier. Use NON_MEMBER para remover uma associação. - pointBalance: o saldo de pontos atual do cliente. O Google usa esse valor por 60 dias após a atualização. Para mais detalhes, consulte Manter os saldos de pontos atualizados.
Campos userIdentifier
Informe pelo menos um dos seguintes campos:
- emailAddress: o endereço de e-mail do cliente.
- address: o endereço físico do cliente. O CEP é obrigatório.
- phoneNumber: o número de telefone do cliente. O formato E.164 é recomendado.
Entender o mapeamento do loyaltyTier
A API não usa os nomes personalizados. Os valores de tipo enumerado loyaltyTier (TIER1
a TIER7) são rótulos semânticos. Eles não usam os nomes personalizados (por exemplo,
"Gold Rewards") ou rótulos personalizados (por exemplo, "gold_tier") que você atribuiu na
interface do Merchant Center. Em vez disso, eles são mapeados estritamente para a ordem em que
você definiu os níveis nas configurações do programa de fidelidade no
Merchant Center:
TIER1: corresponde ao primeiro nível listado na configuração do programa de fidelidade do Merchant Center.TIER2: corresponde ao segundo nível listado na configuração do programa de fidelidade do Merchant Center.TIER3aTIER7: correspondem do terceiro ao sétimo nível listados na configuração do programa de fidelidade do Merchant Center.
Exemplo:
Se o programa de fidelidade do Merchant Center tiver níveis definidos nesta ordem:
- Nome do nível: "Status Prata", rótulo do nível: "prata"
- Nome do nível: "Membro Ouro", rótulo do nível: "ouro"
- Nome do nível: "Platinum Elite", rótulo do nível: "platinum"
Em seguida, nas chamadas de API
accounts.loyaltyCustomers.manage:
- Para atribuir um cliente ao "Status Prata", use
loyaltyTier: TIER1. - Para atribuir um cliente a "Membro Gold", use
loyaltyTier: TIER2. - Para atribuir um cliente à categoria "Platinum Elite", use
loyaltyTier: TIER3.
Valores de tipo enumerado LoyaltyTier
TIER1TIER2TIER3TIER4TIER5TIER6TIER7NON_MEMBER(usado para sinalizar a remoção da associação de fidelidade do cliente)
Entender o corpo da resposta de ManageLoyaltyCustomerMatch
O método ManageLoyaltyCustomerMatch retorna um objeto ManageLoyaltyCustomerMatchResponse:
{
"loyaltyCustomer": {
// loyaltyCustomer object from the request
}
}
Considerações importantes para respostas
Upsert bem-sucedido (repositório de dados): para armazenar ou atualizar a associação de nível de fidelidade de um cliente, atenda às seguintes condições:
- você faz a correspondência de um usuário do Google com o
userIdentifierfornecido; - você definir o
loyaltyTierna solicitação como um valor válido diferente deNON_MEMBER; - o usuário correspondente tiver consentido com o uso de dados de fidelidade.
- você faz a correspondência de um usuário do Google com o
A resposta contém o objeto loyaltyCustomer da sua solicitação, indicando
que o serviço processou e armazenou os dados:
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"loyaltyTier": "TIER2",
"pointBalance": 1500
}
}
- Exclusão bem-sucedida: para remover qualquer associação de fidelidade
existente do cliente com esse comerciante, as seguintes condições
precisam ser atendidas:
- você faz a correspondência de um usuário do Google com o
userIdentifierfornecido; - você define o
loyaltyTierna solicitação comoNON_MEMBER;
- você faz a correspondência de um usuário do Google com o
A resposta é um objeto JSON vazio:
{}
- Sem correspondência / sem consentimento (sucesso silencioso): se o
userIdentifierfornecido não corresponder a uma Conta do Google ou se o usuário correspondente não tiver consentido com o uso de dados de fidelidade, a API vai retornar um status HTTP 200 OK com um objeto JSON vazio:{}. Isso acontece tanto para tentativas de upsert quanto de remoção.
Manter os saldos de pontos atualizados
O Google só vai usar o pointBalance de um cliente se você tiver atualizado os dados de fidelidade dele nos últimos 60 dias. Essa regra se aplica a cada cliente
separadamente.
O que redefine o período de 60 dias: cada upsert bem-sucedido redefine o período para esse cliente, mesmo que os valores de
loyaltyTierepointBalancenão tenham mudado.O que não redefine o período: uma resposta de sucesso silenciosa (
{}) significa que o sistema não armazenou dados, então o período não é redefinido.O que acontece após 60 dias: se você não atualizar os dados de fidelidade de um cliente por mais de 60 dias, o Google vai parar de usar o
pointBalancedesse cliente. As experiências baseadas em pontos, como o resgate de pontos, não aparecem mais para esse cliente. O Google ainda reconhece o nível de fidelidade do cliente, então os benefícios do nível, como preço e frete para membros, continuam aparecendo.
Para manter as experiências baseadas em pontos disponíveis, envie uma atualização quando o saldo de pontos de um cliente mudar. Além disso, envie os dados de fidelidade atuais de cada cliente pelo menos uma vez a cada 60 dias, mesmo que não tenham mudado.
Exemplos
TIER1 corresponde ao primeiro nível definido (por exemplo, 'Basic'), e TIER2 corresponde ao segundo nível (por exemplo, 'Premium').
Para adicionar um cliente ao TIER2 ou atualizar o status dele usando um endereço de e-mail, envie a seguinte solicitação:
POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
-d '{
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"loyaltyTier": "TIER2",
"pointBalance": 1500
}'
Quando um usuário é correspondido e dá o consentimento, a API retorna a seguinte resposta:
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"loyaltyTier": "TIER2",
"pointBalance": 1500
}
}
Quando não há correspondência ou o usuário não deu consentimento, a API retorna a seguinte resposta:
{}
Para remover a associação de fidelidade de um cliente usando um número de telefone, envie a seguinte solicitação:
POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
-d '{
"userIdentifier": {
"phoneNumber": "+18005550132"
},
"loyaltyTier": "NON_MEMBER"
}'
Independentemente de um registro existir ou não, a API retorna a seguinte resposta de sucesso:
{}
Para adicionar ou atualizar um cliente usando vários identificadores, envie a seguinte solicitação:
POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
-d '{
"userIdentifier": {
"emailAddress": "user@example.com",
"address": {
"postalCode": "94043",
"regionCode": "US"
}
},
"loyaltyTier": "TIER1"
}'
A resposta é semelhante à do primeiro exemplo, dependendo da correspondência e do consentimento.
Tratamento de erros
A API usa códigos HTTP padrão. As strings de erro comuns incluem:
| Código HTTP | String de erro | Descrição |
| 400 | INVALID_ARGUMENT | O user_identifier ou o loyalty_tier está ausente ou o identificador está vazio. |
| 401 | UNAUTHENTICATED | Credenciais inválidas ou ausentes. |
| 403 | PERMISSION_DENIED | O usuário autenticado não tem acesso à conta do Merchant Center especificada. |
| 404 | NOT_FOUND | O rótulo do nível de fidelidade especificado não existe na sua configuração. |
| 412 | FAILED_PRECONDITION | Você não configurou um programa de fidelidade na sua conta. |
| 429 | RESOURCE_EXHAUSTED | Limite de cota atingido. |
Exemplos de erro
Exemplo de 404 NOT_FOUND:
Qualquer solicitação válida para um ID de conta que não tenha um programa de fidelidade configurado.
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 404,
"message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
"status": "NOT_FOUND",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "notFound",
"domain": "merchantapi.googleapis.com",
"metadata": {
"ACCOUNT_ID": "{ACCOUNT_ID}",
"REASON": "NOT_FOUND_LOYALTY_PROGRAM"
}
}
]
}
}
Motivo: a conta do comerciante no caminho não tem um programa de fidelidade ativo.
Exemplos de 400 INVALID_ARGUMENT:
Um erro vai ocorrer se a solicitação tiver um valor inválido para o campo
loyaltyTier:
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"loyaltyTier": "TIER11",
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "loyalty_customer.loyalty_tier",
"description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
}
]
}
]
}
}
Motivo: TIER11 não é um valor de tipo enumerado válido para loyaltyTier. O mesmo
erro pode acontecer quando você tenta especificar TIER2 quando há apenas um nível
disponível.
Um erro vai ocorrer se o campo obrigatório loyaltyTier estiver ausente no corpo da solicitação:
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "required",
"domain": "merchantapi.googleapis.com",
"metadata": {
"FIELD_LOCATION": "loyalty_customer.loyalty_tier",
"REASON": "MISSING_REQUIRED_FIELD"
}
}
]
}
}
Motivo: o campo loyaltyTier é obrigatório.
Um erro vai ocorrer se um identificador de endereço estiver incompleto, como quando o campo postalCode estiver ausente:
{
"loyaltyCustomer": {
"userIdentifier": {
"address": {
"locality": "Sunnyvale",
"administrativeArea": "CA",
"regionCode": "US"
}
},
"loyaltyTier": "TIER1",
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "invalid",
"domain": "merchantapi.googleapis.com",
"metadata": {
"FIELD_NAME": "loyalty_customer.user_identifier",
"REASON": "INVALID_VALUE"
}
}
]
}
}
Motivo: um endereço foi informado, mas o campo obrigatório postalCode
está faltando. Por isso, ele não é considerado um identificador válido.
Um erro vai ocorrer se você solicitar um índice de nível que esteja fora dos limites do programa configurado:
Cenário: o comerciante tem apenas um nível configurado no Merchant Center.
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@example.com"
},
"loyaltyTier": "TIER2",
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "invalid",
"domain": "merchantapi.googleapis.com",
"metadata": {
"FIELD_NAME": "loyalty_customer.loyalty_tier",
"PATTERN": "valid LoyaltyTier",
"FIELD_VALUE": "TIER2",
"REASON": "INVALID_VALUE"
}
}
]
}
}
Motivo: TIER2 é solicitado, mas o programa de fidelidade vinculado à conta não tem um segundo nível definido.
Um erro vai ocorrer se a solicitação tiver um emailAddress inválido:
{
"loyaltyCustomer": {
"userIdentifier": {
"emailAddress": "customer@google"
},
"loyaltyTier": "TIER1",
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "invalid",
"domain": "merchantapi.googleapis.com",
"metadata": {
"FIELD_NAME": "loyalty_customer.user_identifier",
"REASON": "INVALID_VALUE"
}
}
]
}
}
Motivo: o formato do endereço de e-mail é inválido.
Um erro vai ocorrer se o objeto userIdentifier estiver vazio:
{
"loyaltyCustomer": {
"userIdentifier": {},
"loyaltyTier": "TIER1",
"pointBalance": 100
}
}
A API retorna a seguinte resposta de erro:
{
"error": {
"code": 400,
"message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "required",
"domain": "merchantapi.googleapis.com",
"metadata": {
"FIELD_LOCATION": "loyalty_customer.user_identifier",
"REASON": "MISSING_REQUIRED_FIELD"
}
}
]
}
}
Motivo: o objeto userIdentifier está presente, mas não contém campos de identificador reais.
Observação: validação do identificador.
- A API realiza verificações básicas de formato nos identificadores (por exemplo,
estrutura de e-mail, presença de
postalCodenos endereços). - No entanto, alguns identificadores que passam nas verificações iniciais podem não corresponder a nenhuma
conta de usuário do Google ou não estar em um formato reconhecido pelo sistema de correspondência
de back-end. Nesses casos, você vai receber a resposta vazia de sucesso silencioso
{}com o status HTTP200 OK.
Práticas recomendadas
Siga estas práticas recomendadas para otimizar sua integração.
Para integração em grande escala: como a API opera por solicitação, o paralelismo do lado do cliente é necessário para alcançar a capacidade de processamento necessária para grandes conjuntos de dados. Projete sua integração para gerenciar várias solicitações simultâneas. Para orientações sobre como estruturar sua implementação para lidar com volumes maiores por meio do carregamento em paralelo, consulte nosso guia sobre como enviar várias solicitações.
Gerenciamento de cotas: a cota padrão é de 1.000.000 de solicitações/dia e 10.000 solicitações/minuto. Para saber como monitorar e verificar suas cotas, consulte Cotas e limites.
Atualize os saldos de pontos pelo menos a cada 60 dias: envie uma atualização para cada cliente cujo saldo de pontos mudar. Além disso, reenvie os dados de fidelidade atuais de cada cliente pelo menos uma vez a cada 60 dias. Inclua essas atualizações ao planejar sua cota diária. Para mais detalhes, consulte Manter os saldos de pontos atualizados.
Priorize o endereço de e-mail: sempre que possível, inclua o
emailAddressdo cliente nouserIdentifier. Os endereços de e-mail geralmente são o identificador mais preciso e confiável para associar usuários às Contas do Google.Processar respostas vazias: projete seu aplicativo para interpretar corretamente as respostas
{}vazias como um sucesso, entendendo que isso significa que os dados não foram armazenados por motivos de privacidade (sem correspondência ou sem consentimento). Não tente fazer a solicitação novamente.Verifique a ordem dos níveis: sempre confirme a ordem dos níveis de fidelidade na interface do Merchant Center para garantir que você esteja usando os valores de tipo enumerado corretos de
TIER1aTIER7nas chamadas de API. Esse mapeamento é baseado na ordem definida na interface, não nos nomes.Monitorar erros: registre e monitore as respostas da API, prestando atenção a qualquer erro
4xxpara detectar problemas de integração, especialmente erros404, que podem indicar uma incompatibilidade na compreensão do nível.