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 para que a promoção processada atualizada seja 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. A aplicabilidade da promoção a todos os produtos ou apenas a produtos específicos.
offer_type

OfferType

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

string

Opcional. Código de resgate genérico da promoção. Para ser usado com o campo offerType, ele 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 de valor do cupom selecionado, alguns atributos são obrigatórios.
promotion_destinations[]

DestinationEnum

Obrigatório. A lista de destinos em que a promoção é válida. Se você não especificar um destino incluindo um valor compatível na sua fonte de dados, a promoção vai aparecer nos anúncios do Shopping e nas listagens sem custo financeiro por padrão.

Talvez você já tenha enviado os valores a seguir como destinos para seus produtos: Ações do Shopping, plataformas do Google 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 aplicabilidade do produto product_applicability dos produtos qualificados para a promoção está definido como specific_products.
brand_inclusion[]

string

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

string

Opcional. Filtro de produtos por ID do grupo de itens da promoção. Os atributos de filtro de produto só se aplicam quando os produtos qualificados para aplicabilidade do produto na 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 aplicabilidade do produto product_applicability dos produtos qualificados para a 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 de 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 aplicabilidade do produto product_applicability dos produtos qualificados para a promoção está definido como specific_products.
item_group_id_exclusion[]

string

Opcional. Filtre por ID do grupo de itens. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto product_applicability dos produtos qualificados para a 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 aplicabilidade do produto product_applicability dos produtos qualificados para a 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. O 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. TimePeriod representação das datas de início 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. TimePeriod representação 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 período de exibição do atributo promotion_display_time_period da promoção não for especificado, o período de vigência da promoção promotion_effective_time_period vai determinar a data e o período em que a promoção vai aparecer no Google.com e nos anúncios do Shopping.
store_applicability

StoreApplicability

Opcional. Se a promoção se aplica a todas as lojas ou apenas a lojas específicas. As promoções de anúncios de inventário local geram um erro se nenhuma aplicabilidade de loja for 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.

O código da loja (o ID da loja do 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 da página no 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. O URL é usado para confirmar se a promoção é válida e pode ser resgatada.

CouponValueType

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

Enums
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 Percentual de desconto do tipo de valor do cupom.
BUY_M_GET_N_MONEY_OFF Compre M unidades e ganhe N de desconto do tipo de valor do cupom. minimum_purchase_quantity e get_this_quantity_discounted precisam estar presentes. O campo money_off_amount também precisa estar presente.
BUY_M_GET_N_PERCENT_OFF Compre a quantidade M e ganhe N percentual de desconto no tipo de valor do cupom. minimum_purchase_quantity e get_this_quantity_discounted precisam estar presentes. O campo percent_off_percentage também precisa estar presente.
BUY_M_GET_MONEY_OFF Compre M unidades e ganhe um desconto. minimum_purchase_quantity e money_off_amount precisam estar presentes.
BUY_M_GET_PERCENT_OFF Compre M unidades e ganhe um desconto. minimum_purchase_quantity e percent_off_percentage precisam estar presentes.
FREE_GIFT Brinde com descrição apenas.
FREE_GIFT_WITH_VALUE Brinde com valor monetário.
FREE_GIFT_WITH_ITEM_ID Brinde com ID 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 noturno sem custo financeiro.
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. O 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 origem de dados da promoção Formato: 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 é 250. Valores acima disso serão convertidos para 250. 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.

Enums
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. O código de resgate genérico para a promoção é necessário quando offerType = GENERIC_CODE.

ProductApplicability

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

Enums
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 apenas a um único produto ou lista de produtos.

Promoção

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

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

Depois de inserir ou atualizar uma entrada de 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 usuário forneceu o ID da promoção para identificar exclusivamente a promoção. 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ão exibidas apenas em alguns idiomas.
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 estão disponíveis apenas em alguns países, listagens sem custo financeiro e anúncios do Shopping anúncios de inventário local
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 origem de dados principal da promoção.
attributes

Attributes

Opcional. Uma lista de atributos de 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, problemas de validação de dados, ou seja, informações sobre uma promoção computada de forma assíncrona.
version_number

int64

Opcional. Representa a versão atual (novidade) 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 é impedida quando o número da versão é menor que o número da versão atual da promoção. A reinserção (por exemplo, atualização da promoção após 30 dias) pode ser realizada com o version_number atual.

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

PromotionStatus

O status da promoção.

Campos
destination_statuses[]

DestinationStatus

Apenas saída. Os destinos pretendidos para a 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. O nome do destino da promoção.
status

State

Apenas saída. O status do destino especificado.

Estado

O estado atual da promoção.

Enums
STATE_UNSPECIFIED Estado 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 avaliações foram aprovadas, mas a data de ativação é futura.

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 esse problema.
applicable_countries[]

string

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

Gravidade

A gravidade do problema.

Enums
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 é rebaixada e provavelmente tem desempenho limitado nos resultados da pesquisa
DISAPPROVED O problema reprova a promoção.

RedemptionChannel

Canal de uma promoção.

Enums
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 de loja ou lista de códigos de loja aplicáveis à promoção. Somente para promoções de anúncios de inventário local.

Enums
STORE_APPLICABILITY_UNSPECIFIED Não é possível saber quais códigos de loja a promoção se aplica.
ALL_STORES A promoção é válida para todas as lojas.
SPECIFIC_STORES A promoção se aplica apenas às lojas especificadas.