Ricevere notifiche push per le modifiche allo stato del prodotto

Puoi abbonarti alle notifiche PRODUCT_STATUS_CHANGE per ricevere avvisi in tempo reale ogni volta che lo stato di approvazione dei prodotti cambia nei tuoi account Merchant Center. Ad esempio, puoi rilevare quando un prodotto viene disapprovato per poter risolvere potenziali problemi di qualità dei dati.

Prima di iniziare, assicurati che l'URI di callback sia configurato in base ai requisiti descritti nella Panoramica della sub-API Notifications.

Iscriviti alle modifiche dello stato del prodotto

Per abbonarti alle modifiche dello stato del prodotto, invia una richiesta POST alla risorsa notificationsubscriptions con registeredEvent impostato su PRODUCT_STATUS_CHANGE.

Iscrizione a un account di destinazione specifico

La seguente richiesta di esempio esegue la registrazione alle modifiche dello stato del prodotto per un account commerciante specifico:

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

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

Sostituisci quanto segue:

• ACCOUNT_ID: l'identificatore dell'account proprietario dell'abbonamento e che riceve le notifiche.
• TARGETACCOUNT_ID: L'identificatore dell'account su cui vuoi ricevere notifiche.

Se il tuo account Merchant Center è un account autonomo senza account collegati, utilizza il tuo ID account per entrambe le variabili.

Iscriviti per tutti gli account gestiti

Se gestisci più account (ad esempio un account avanzato con subaccount), puoi iscriverti alle modifiche dello stato dei prodotti in tutti gli account gestiti impostando allManagedAccounts: true:

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

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

Le chiamate riuscite restituiscono un name identificatore per l'abbonamento, incluso un ID abbonamento univoco:

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

Decodificare i payload di modifica dello stato del prodotto

Quando si verifica una modifica dello stato del prodotto, l'URI di callback riceve un messaggio codificato in base64. Una volta decodificato, il payload è conforme al 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"
}

Campi e regole del payload

• oldValue e newValue: rappresentano lo stato precedente e quello aggiornato. I valori possibili sono approved, pending, disapproved o una stringa vuota ('').
  • Se oldValue viene omesso, il prodotto viene creato di recente.
  • Se newValue viene omesso, il prodotto è stato eliminato.
• expirationTime: indica la data di scadenza dell'offerta del prodotto. Questo campo viene omesso quando un prodotto viene eliminato.
• reportingContext: La piattaforma pubblicitaria o di schede senza costi in cui è cambiato lo stato. I valori supportati includono SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE e FREE_LISTINGS_UCP_CHECKOUT da ReportingContextEnum.
• eventTime: il timestamp di generazione dell'evento. Utilizza questo timestamp per garantire il corretto ordine degli eventi.

Testare le notifiche di modifica dello stato del prodotto

Utilizza la seguente richiesta di esempio per verificare se l'endpoint di callback riceve, riconosce e decodifica correttamente i messaggi di modifica dello stato del prodotto:

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=="}}'

In risposta a questa chiamata, l'URI di callback deve restituire un codice di stato HTTP accettabile (ad esempio 200 OK). Il messaggio decodificato ha i seguenti contenuti:

{
  "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"
}