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 os status de aprovação dos produtos mudarem 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 de notificações.

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

A solicitação de exemplo a seguir se inscreve nas mudanças de status do produto para uma conta de 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 proprietária da assinatura e que 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 uma conta independente e não tiver contas vinculadas, use seu próprio ID de conta para as duas variáveis.

Assinar todas as contas gerenciadas

Se você gerencia várias contas (como uma conta avançada com subcontas), pode se inscrever para receber notificações sobre mudanças no status dos produtos 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 no status do produto

Quando ocorre uma mudança no status de um produto, o URI de callback recebe uma mensagem codificada em base64. Quando decodificado, o payload está de acordo com 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 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 de 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 aceitos incluem SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE e FREE_LISTINGS_UCP_CHECKOUT de 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, reconhece 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"
}