Package google.shopping.merchant.promotions.v1beta

Índice

PromotionsService

Serviço para gerenciar promoções de produtos.

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

Recupera a promoção da sua conta do Merchant Center.

Depois de inserir ou atualizar a entrada de uma promoção, pode levar vários minutos até que a promoção atualizada possa ser recuperada.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/content

Para mais informações, consulte a Visão geral do OAuth 2.0.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

Insere uma promoção na sua conta do Merchant Center. Se a promoção já existir, ela será atualizada.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/content

Para mais informações, consulte a Visão geral do OAuth 2.0.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

Lista as promoções na sua conta do Merchant Center. A resposta pode conter menos itens do que o especificado por pageSize. Use pageToken para determinar se há mais itens a serem solicitados.

Depois de inserir ou atualizar uma promoção, pode levar vários minutos até que a promoção processada atualizada possa ser recuperada.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/content

Para mais informações, consulte a Visão geral do OAuth 2.0.

Atributos

Atributos.

Campos
product_applicability

ProductApplicability

Obrigatório. Aplicabilidade da promoção a todos os produtos ou apenas a produtos específicos.
offer_type

OfferType

Obrigatório. Tipo de promoção. Use esse atributo para indicar se os clientes precisam ou não de um código do cupom para resgatar sua promoção.
generic_redemption_code

string

Opcional. Código de desconto genérico da promoção. Para ser usado com o campo offerType e precisa atender aos requisitos mínimos.
long_title

string

Obrigatório. Título longo da promoção.
coupon_value_type

CouponValueType

Obrigatório. O atributo tipo de valor do cupom para indicar o tipo de promoção que você está exibindo. Dependendo do tipo do valor do cupom selecionado, alguns atributos são obrigatórios.
promotion_destinations[]

DestinationEnum

Obrigatório. A lista de destinos a que a promoção se aplica. Se você não incluir um valor compatível na sua fonte de dados para especificar um destino, sua promoção será exibida nos anúncios do Shopping e nas listagens sem custo financeiro por padrão.

Talvez você já tenha enviado os seguintes valores como destinos para seus produtos: Shopping Actions, Google plataformas e Plataformas locais do Google. Para representar esses valores, use FREE_LISTINGS, FREE_LOCAL_LISTINGS e LOCAL_INVENTORY_ADS. Para mais detalhes, consulte Destino da promoção.
item_id_inclusion[]

string

Opcional. Filtre por ID do item para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
brand_inclusion[]

string

Opcional. Filtre por marca para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
item_group_id_inclusion[]

string

Opcional. Filtro de produtos por ID do grupo de itens para a promoção. Os atributos de filtro de produto só se aplicam quando os produtos qualificados para aplicabilidade do produto em promoção [product_applicability] estão definidos como produtos específicos specific_products.
product_type_inclusion[]

string

Opcional. Filtro de produto por tipo de produto para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
item_id_exclusion[]

string

Opcional. Filtre por exclusão de ID do item para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
brand_exclusion[]

string

Opcional. Filtro de produto por exclusão de marca para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
item_group_id_exclusion[]

string

Opcional. Filtre por ID do grupo de itens. Os atributos de filtro de produto só são válidos quando o atributo product_applicability da aplicabilidade do produto em promoção está definido como specific_products.
product_type_exclusion[]

string

Opcional. Filtre por exclusão de tipo de produto para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo product_applicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
minimum_purchase_amount

Price

Opcional. Montante mínimo da compra da promoção.
minimum_purchase_quantity

int64

Opcional. Quantidade mínima de compra da promoção.
limit_quantity

int64

Opcional. Quantidade de compra máxima da promoção.
limit_value

Price

Opcional. Preço máximo do produto na promoção.
percent_off

int64

Opcional. O desconto percentual oferecido na promoção.
money_off_amount

Price

Opcional. O valor do desconto oferecido na promoção.
get_this_quantity_discounted

int64

Opcional. Número de itens com desconto na promoção. O atributo é definido quando couponValueType é igual a buy_m_get_n_money_off ou buy_m_get_n_percent_off.
free_gift_value

Price

Opcional. Valor do brinde da promoção.
free_gift_description

string

Opcional. Descrição do brinde da promoção.
free_gift_item_id

string

Opcional. Código do item de brinde da promoção.
promotion_effective_time_period

Interval

Obrigatório. Representação de TimePeriod do início da vigência da promoção. Esse atributo especifica que a promoção pode ser testada na sua loja on-line durante esse período.
promotion_display_time_period

Interval

Opcional. Representação TimePeriod das datas de exibição da promoção. Esse atributo especifica a data e o período em que a promoção será publicada no Google.com.br e nos anúncios do Shopping. Se o atributo período de exibição da promoção promotion_display_time_period não for especificado, o período de vigência da promoção promotion_effective_time_period determinará a data e o período em que a promoção estará ativa no Google.com.br e nos anúncios do Shopping.
store_applicability

StoreApplicability

Opcional. Indica se a promoção se aplica a todas as lojas ou apenas lojas específicas. As promoções de anúncios de inventário local geram um erro se nenhuma aplicabilidade à loja estiver incluída. Um erro INVALID_ARGUMENT será gerado se store_applicability for definido como ALL_STORES e store_codes_inclusion ou score_code_exclusion estiver definido como um valor.
store_codes_inclusion[]

string

Opcional. Códigos de loja a serem incluídos na promoção. Os atributos de filtro da loja só se aplicam quando o atributo store_applicability está definido como specific_stores.

Código da loja física (o ID no seu Perfil da Empresa) da loja física em que o produto é vendido. Consulte a especificação dos dados do inventário de produtos disponíveis na loja física para mais informações.
store_codes_exclusion[]

string

Opcional. Códigos de loja a serem excluídos da promoção. Os atributos de filtro da loja só se aplicam quando o atributo store_applicability está definido como specific_stores.
promotion_url

string

Opcional. URL para a página do site do comerciante em que a promoção aparece. As promoções de anúncios de inventário local vão gerar um erro se nenhum promotion_url for incluído. é usado para confirmar que a promoção é válida e pode ser resgatada.

CouponValueType

Tipo de valor do cupom de uma promoção.

Tipos enumerados
COUPON_VALUE_TYPE_UNSPECIFIED Indica que o tipo de valor do cupom não foi especificado.
MONEY_OFF Tipo de valor do cupom de desconto.
PERCENT_OFF Tipo de valor do cupom de porcentagem de desconto.
BUY_M_GET_N_MONEY_OFF Compre uma quantidade M e ganhe N de desconto no tipo de valor do cupom. minimum_purchase_quantity e get_this_quantity_discounted precisam estar presentes. money_off_amount também precisa estar presente.
BUY_M_GET_N_PERCENT_OFF Compre a quantidade M e ganhe N com o tipo de valor do cupom. minimum_purchase_quantity e get_this_quantity_discounted precisam estar presentes. percent_off_percentage também precisa estar presente.
BUY_M_GET_MONEY_OFF Compre a quantidade M e ganhe um desconto de dinheiro. É necessário incluir minimum_purchase_quantity e money_off_amount.
BUY_M_GET_PERCENT_OFF Compre a quantidade M e ganhe um desconto de dinheiro. É necessário incluir minimum_purchase_quantity e percent_off_percentage.
FREE_GIFT Brinde apenas com descrição.
FREE_GIFT_WITH_VALUE Brinde com valor monetário.
FREE_GIFT_WITH_ITEM_ID Brinde com código do item.
FREE_SHIPPING_STANDARD Tipo de valor do cupom de frete grátis padrão.
FREE_SHIPPING_OVERNIGHT Tipo de valor do cupom de frete grátis de um dia para o outro.
FREE_SHIPPING_TWO_DAY Tipo de valor do cupom de frete grátis em dois dias.

GetPromotionRequest

Solicite mensagem para o método GetPromotion.

Campos
name

string

Obrigatório. Nome da promoção a ser recuperada. Formato: accounts/{account}/promotions/{promotions}

InsertPromotionRequest

Solicite mensagem para o método InsertPromotion.

Campos
parent

string

Obrigatório. A conta em que a promoção será inserida. Formato: accounts/{account}
promotion

Promotion

Obrigatório. Promoção a ser inserida.
data_source

string

Obrigatório. A fonte de dados no formato da promoção: accounts/{account}/dataSources/{datasource}.

ListPromotionsRequest

Solicite mensagem para o método ListPromotions.

Campos
parent

string

Obrigatório. A conta para listar as promoções processadas. Formato: accounts/{account}
page_size

int32

Apenas saída. O número máximo de promoções a serem retornadas. O serviço pode retornar menos que esse valor. O valor máximo é 1.000. Valores maiores serão convertidos para 1.000. Se não for especificado, o número máximo de promoções será retornado.
page_token

string

Apenas saída. Um token de página recebido de uma chamada ListPromotions anterior. Forneça isso para recuperar a página subsequente.

Ao paginar, todos os outros parâmetros fornecidos para ListPromotions precisam corresponder à chamada que forneceu o token da página.

ListPromotionsResponse

Mensagem de resposta para o método ListPromotions.

Campos
promotions[]

Promotion

As promoções processadas da conta especificada.
next_page_token

string

Um token, que pode ser enviado como page_token para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.

OfferType

Tipo de oferta de uma promoção.

Tipos enumerados
OFFER_TYPE_UNSPECIFIED Tipo de oferta desconhecido.
NO_CODE Tipo de oferta sem um código.
GENERIC_CODE Tipo de oferta com um código. É necessário um código de desconto genérico da promoção quando offerType = GENERIC_CODE.

ProductApplicability

A que produto ou lista de produtos a promoção se aplica.

Tipos enumerados
PRODUCT_APPLICABILITY_UNSPECIFIED Os produtos a que a promoção se aplica são desconhecidos.
ALL_PRODUCTS Aplicável a todos os produtos.
SPECIFIC_PRODUCTS Aplicável a apenas um produto ou uma lista de produtos.

Promoção

Representa uma promoção. Consulte os artigos a seguir para mais detalhes.

Os atributos de entrada obrigatórios da promoção que são necessários para passar nas verificações de validação de dados são definidos principalmente abaixo:

Depois de inserir e atualizar a entrada de uma promoção, pode levar vários minutos até que a promoção final seja recuperada.

Campos
name

string

Identificador. Nome da promoção. Formato: accounts/{account}/promotions/{promotion}
promotion_id

string

Obrigatório. O ID da promoção fornecido pelo usuário para identificar a promoção de maneira exclusiva. Siga os requisitos mínimos para evitar reprovações de promoções.
content_language

string

Obrigatório. O código de idioma ISO 639-1 de duas letras da promoção.

As promoções só estão disponíveis em idiomas selecionados.
target_country

string

Obrigatório. O país de destino usado como parte do identificador exclusivo. Representado como um código de território CLDR (em inglês).

As promoções só estão disponíveis em alguns países, anúncios de inventário local e listagens sem custo financeiro e anúncios do Shopping.
redemption_channel[]

RedemptionChannel

Obrigatório. Canal de resgate da promoção. É necessário ter pelo menos um canal.
data_source

string

Apenas saída. A fonte de dados principal da promoção.
attributes

Attributes

Opcional. Uma lista de atributos da promoção.
custom_attributes[]

CustomAttribute

Opcional. Uma lista de atributos personalizados (fornecidos pelo comerciante). Ele também pode ser usado para enviar qualquer atributo da especificação de dados na forma genérica (por exemplo, { "name": "size type", "value": "regular" }). Isso é útil para enviar atributos não expostos explicitamente pela API.
promotion_status

PromotionStatus

Apenas saída. O status de uma promoção e os problemas de validação de dados, ou seja, informações sobre uma promoção calculadas de forma assíncrona.
version_number

int64

Opcional. Representa a versão existente (atualização) da promoção, que pode ser usada para preservar a ordem correta quando várias atualizações são feitas ao mesmo tempo.

Se definido, a inserção será impedida quando o número da versão for menor que o número da versão atual da promoção existente. A reinserção (por exemplo, atualização de promoção após 30 dias) pode ser realizada com o version_number atual.

Se a operação for impedida, a exceção cancelada será lançada.

PromotionStatus

Status da promoção.

Campos
destination_statuses[]

DestinationStatus

Apenas saída. Os destinos pretendidos da promoção.
item_level_issues[]

ItemLevelIssue

Apenas saída. Uma lista de problemas associados à promoção.
creation_date

Timestamp

Apenas saída. Data em que a promoção foi criada no formato ISO 8601: data, hora e deslocamento (por exemplo, 2020-01-02T09:00:00+01:00 ou 2020-01-02T09:00:00Z)
last_update_date

Timestamp

Apenas saída. Data em que o status da promoção foi atualizado pela última vez no formato ISO 8601: data, hora e deslocamento (por exemplo, 2020-01-02T09:00:00+01:00 ou 2020-01-02T09:00:00Z)

DestinationStatus

O status do destino especificado.

Campos
reporting_context

ReportingContextEnum

Apenas saída. Nome do destino da promoção.
status

State

Apenas saída. O status do destino especificado.

Estado

O estado atual da promoção.

Tipos enumerados
STATE_UNSPECIFIED Status de promoção desconhecido.
IN_REVIEW A promoção está em análise.
REJECTED A promoção foi reprovada.
LIVE A promoção foi aprovada e está ativa.
STOPPED A promoção foi interrompida pelo comerciante.
EXPIRED A promoção não está mais ativa.
PENDING A promoção não foi interrompida, e todas as revisões foram aprovadas, mas a data de atividade está no futuro.

ItemLevelIssue

O problema associado à promoção.

Campos
code

string

Apenas saída. O código de erro do problema.
severity

Severity

Apenas saída. Como esse problema afeta a veiculação da promoção.
resolution

string

Apenas saída. Se o problema pode ser resolvido pelo comerciante.
attribute

string

Apenas saída. O nome do atributo, se o problema for causado por um único atributo.
reporting_context

ReportingContextEnum

Apenas saída. O destino a que o problema se aplica.
description

string

Apenas saída. Uma breve descrição do problema em inglês.
detail

string

Apenas saída. Uma descrição detalhada do problema em inglês.
documentation

string

Apenas saída. O URL de uma página da Web para ajudar a resolver o problema.
applicable_countries[]

string

Apenas saída. Lista de códigos de país (ISO 3166-1 alfa-2) onde o problema se aplica à oferta.

Gravidade

A gravidade do problema.

Tipos enumerados
SEVERITY_UNSPECIFIED Não especificado.
NOT_IMPACTED Esse problema representa um alerta e não tem efeito direto na promoção.
DEMOTED A promoção foi rebaixada e provavelmente tem performance limitada nos resultados da pesquisa
DISAPPROVED O problema reprova a promoção.

RedemptionChannel

Canal de uma promoção.

Tipos enumerados
REDEMPTION_CHANNEL_UNSPECIFIED Indica que o canal não foi especificado.
IN_STORE Indica que o canal está na loja. Isto é o mesmo que o canal local usado para products.
ONLINE Indica que o canal está on-line.

StoreApplicability

Códigos da loja ou lista de códigos da loja a que a promoção se aplica. Apenas para promoções de anúncios de inventário local.

Tipos enumerados
STORE_APPLICABILITY_UNSPECIFIED Os códigos da loja a que a promoção se aplica são desconhecidos.
ALL_STORES A promoção é válida para todas as lojas.
SPECIFIC_STORES A promoção é válida somente para as lojas especificadas.