Receber notificações push sobre mudanças no status do produto

Você pode se inscrever nas notificações do PRODUCT_STATUS_CHANGE para receber alertas em tempo real sempre que o status de aprovação do produto mudar nas suas contas do Merchant Center. Por exemplo, é possível detectar quando um produto é reprovado para corrigir possíveis problemas de qualidade de dados.

Antes de começar, verifique se o URI de callback está configurado de acordo com os requisitos descritos na Visão geral da sub-API Notifications.

Inscrever-se para receber notificações sobre mudanças no status do produto

Para se inscrever nas mudanças de status do produto, envie uma solicitação POST ao recurso notificationsubscriptions com registeredEvent definido como PRODUCT_STATUS_CHANGE.

Inscrever-se em uma conta de destino específica

O exemplo de solicitação a seguir se inscreve nas mudanças de status do produto para uma conta do comerciante específica:

POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/{TARGETACCOUNT_ID}",
  "callBackUri": "https://example.com/callback"
}

Substitua:

• ACCOUNT_ID: o identificador da conta que é proprietária da assinatura e recebe notificações.
• TARGETACCOUNT_ID: o identificador da conta sobre a qual você quer receber notificações.

Se a sua conta do Merchant Center for independente e não tiver contas vinculadas, use o ID da sua própria conta para as duas variáveis.

Assinar para todas as contas gerenciadas

Se você gerencia várias contas (como uma conta avançada com subcontas), pode se inscrever para receber mudanças no status do produto em todas as contas gerenciadas definindo allManagedAccounts: true:

POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com/callback"
}

As chamadas bem-sucedidas retornam um identificador name para sua assinatura, incluindo um ID exclusivo:

{
  "name":"accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com/callback"
}

Decodificar payloads de mudança de status do produto

Quando ocorre uma mudança no status do produto, o URI de callback recebe uma mensagem codificada em Base64. Quando decodificado, o payload segue o formato ProductStatusChangeMessage:

{
  "account": "accounts/{TARGETACCOUNT_ID}",
  "managingAccount": "accounts/{ACCOUNT_ID}",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/{TARGETACCOUNT_ID}/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

Campos e regras de payload

• oldValue e newValue: representam o status anterior e o atualizado. Os valores possíveis são approved, pending, disapproved ou uma string vazia ('').
  • Se oldValue for omitido, o produto será criado.
  • Se newValue for omitido, o produto foi excluído.
• expirationTime: indica quando a oferta do produto expira. Esse campo é omitido quando um produto é excluído.
• reportingContext: a plataforma de publicidade ou listagem sem custo financeiro em que o status mudou. Os valores compatíveis incluem SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE e FREE_LISTINGS_UCP_CHECKOUT do ReportingContextEnum.
• eventTime: o carimbo de data/hora em que o evento foi gerado. Use esse carimbo de data/hora para garantir a ordem correta dos eventos.

Testar notificações de mudança no status do produto

Use o exemplo de solicitação a seguir para testar se o endpoint de callback recebe, confirma e decodifica corretamente as mensagens de mudança de status do produto:

curl --request POST \
'https://{YOUR_CALLBACK_URI}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"message":{"data": "ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}'

Em resposta a essa chamada, o URI de callback precisa retornar um código de status HTTP aceitável (como 200 OK). A mensagem decodificada tem o seguinte conteúdo:

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}