Puoi utilizzare l'API Merchant Notifications per ricevere notifiche push relative alle modifiche ai dati di prodotto. Ad esempio, se ti abboni alle notifiche di modifica dello stato del prodotto, puoi ricevere una notifica in tempo reale quando un prodotto viene disapprovato. Puoi abbonarti alle notifiche per uno qualsiasi dei tuoi sottoaccount o altri account collegati.
Questa guida fornisce esempi di come gestire le notifiche per le modifiche dello stato del prodotto. Puoi utilizzare questi esempi per gestire le notifiche per altri eventi modificando il valore del campo registeredEvent nelle tue richieste. Per un elenco completo
dei tipi di eventi, consulta i riferimenti dell'API Merchant Notifications.
Iscriviti
Per ricevere le notifiche, devi avere un callBackUri. L'URI di callback deve soddisfare i seguenti requisiti:
- Deve essere un indirizzo HTTPS accessibile pubblicamente con un certificato SSL valido, firmato da un'autorità di certificazione.
- Deve accettare le richieste HTTP
POSTcon l'intestazioneContent-Typee il valoreapplication/json. - Deve restituire uno dei seguenti codici di risposta per confermare la ricezione della notifica.
102200201202204
Puoi utilizzare lo stesso URI di callback per più abbonamenti. Ti consigliamo di utilizzare un URI di callback univoco per account avanzato e per tipo di evento per ridurre al minimo il carico delle richieste push a un singolo URI.
Ecco una richiesta di esempio per abbonarsi alle notifiche relative 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"
}
Sostituisci quanto segue:
- ACCOUNT_ID: l'identificatore univoco dell'account che deve ricevere le notifiche.
- TARGETACCOUNT_ID: l'identificatore univoco dell'account per il quale vuoi ricevere le notifiche.
Se il tuo account Merchant Center è un account autonomo senza account collegati e vuoi ricevere notifiche per il tuo account, sostituisci entrambe queste variabili con l'ID account.
Le chiamate riuscite restituiscono un
name
per l'abbonamento, incluso un ID abbonamento:
{
"name":"accounts/{ACCOUNT_ID}/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/{TARGETACCOUNT_ID}",
"callBackUri": "https://example.com"
}
Puoi utilizzare questo name per GET e DELETE i singoli abbonamenti.
Puoi abbonarti alle notifiche per le modifiche dello stato del prodotto per tutti i tuoi
account collegati includendo "allManagedAccounts": true anziché un
targetAccount nella richiesta:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
Per aggiornare un abbonamento esistente, utilizza PATCH con un update_mask per specificare i campi che vuoi aggiornare e i nuovi valori nel corpo HTTP:
PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
Decodificare le notifiche
Dopo aver creato un abbonamento, riceverai le notifiche all'indirizzo callBackUri specificato nel seguente formato:
{"message":{"data":"{base64_encoded_string}"}}
I dati di notifica sono codificati. Puoi decodificare i dati in un formato di testo leggibile da utilizzare nella tua implementazione. Ecco un controller Spring Boot di esempio che potresti utilizzare per elaborare i dati codificati:
@RestController
public class ExampleController {
@RequestMapping(value = "/push",
method = RequestMethod.POST,
consumes = {"application/json"},
produces = {"text/plain"})
@ResponseStatus(HttpStatus.OK)
public void doStuff(@RequestBody String message) {
//wrapped message
JSONObject jsonObject = new JSONObject(message);
JSONObject jsonMessage = jsonObject.getJSONObject("message");
message = jsonMessage.getString("data");
byte[] decodedBytes = Base64.getDecoder().decode(message);
String decodedMessage = new String(decodedBytes);
// Implement your business logic here
}
}
Ecco un esempio di base64_encoded_string che è stato decodificato:
{
"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"
}
Se nella notifica non è presente il campo oldValue, significa che è stato aggiunto un nuovo prodotto al tuo account. Se non è presente il campo newValue, il prodotto è stato eliminato dal tuo account.
Il campo expirationTime non sarà presente se il prodotto è stato eliminato.
Il campo reportingContext supporta solo (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE, FREE_LISTINGS_UCP_CHECKOUT) dal valore di enumerazione ReportingContextEnum.
Per l'evento di modifica dello stato del prodotto, i campi oldValue e newValue avranno uno
di questi valori : (approved, pending, disapproved, ``).
Il campo eventTime contiene l'ora di creazione dell'evento stesso. Se vuoi ordinare i messaggi, devi fare affidamento sul valore di questo campo e non sull'ordine di ricezione dei messaggi.
Per maggiori dettagli, consulta il formato ProductStatusChangeMessage.
Verificare la tua implementazione
Ecco una notifica di esempio che puoi utilizzare per testare l'URI di callback e la decodifica:
curl --request POST \
'https://{callBackUri}' \
--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 risposta riuscita. Il messaggio decodificato deve avere il seguente valore:
{
"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"
}