É possível usar a API Merchant Notifications para receber notificações push sobre mudanças nos dados de produtos. Por exemplo, se você se inscrever para receber notificações de mudança de status de produtos, poderá ser avisado em tempo real quando um produto for reprovado. Você pode se inscrever para receber notificações de qualquer uma das suas subcontas ou outras contas vinculadas.
Este guia mostra exemplos de como gerenciar notificações sobre mudanças no status do produto. Use esses exemplos para gerenciar notificações de outros eventos mudando o valor do campo registeredEvent nas suas solicitações. Para conferir uma lista completa dos tipos de eventos, consulte a referência da API Merchant Notifications.
Inscrever-se
Para receber notificações, você precisa de um callBackUri. O URI de retorno de chamada precisa atender aos seguintes requisitos:
- Precisa ser um endereço HTTPS de acesso público com um certificado SSL válido, assinado por uma autoridade de certificação.
- Precisa aceitar solicitações HTTP
POSTcom o cabeçalhoContent-Typee o valorapplication/json. - Precisa retornar um dos seguintes códigos de resposta para confirmar que a
notificação foi recebida.
102200201202204
É possível usar o mesmo URI de callback para várias assinaturas. Recomendamos usar um URI de callback exclusivo por conta avançada e por tipo de evento para minimizar a carga de solicitações push em um único URI.
Confira um exemplo de solicitação para se inscrever nas notificações sobre mudanças no status de produtos de 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"
}
Substitua:
- ACCOUNT_ID: o identificador exclusivo da conta que vai receber as notificações.
- TARGETACCOUNT_ID: o identificador exclusivo da conta sobre a qual você quer receber notificações.
Se a conta do Merchant Center for independente, sem contas vinculadas, e você quiser receber notificações da sua conta, substitua as duas variáveis pelo ID dela.
As chamadas bem-sucedidas retornam um
name para sua
assinatura, incluindo um ID de assinatura:
{
"name":"accounts/ACCOUNT_ID/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/TARGETACCOUNT_ID",
"callBackUri": "https://example.com"
}
Você pode usar esse name para GET e DELETE assinaturas individuais.
Para se inscrever nas notificações de mudanças no status do produto em todas as suas contas vinculadas, inclua "allManagedAccounts": true em vez de targetAccount na solicitação:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/ACCOUNT_ID/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
Para atualizar uma assinatura, use PATCH com um update_mask para especificar
os campos que você quer atualizar e os novos valores no corpo JSON:
PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/ACCOUNT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
Decodificar notificações
Depois de criar uma assinatura, você vai receber notificações no callBackUri especificado no seguinte formato:
{"message":{"data":"{base64_encoded_string}"}}
Os dados de notificação são codificados. É possível decodificar os dados em um formato de texto legível para usar na sua implementação. Confira um exemplo de controlador do Spring Boot que você pode usar para processar os dados codificados:
@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
}
}
Confira um exemplo de um base64_encoded_string decodificado:
{
"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 não houver um campo oldValue na notificação, um novo produto foi adicionado à sua conta. Se não houver um campo newValue, o produto foi excluído da sua conta.
O campo expirationTime não vai existir se o produto tiver sido excluído.
O campo reportingContext aceita apenas (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE) do valor de enumeração ReportingContextEnum.
Para o evento de mudança de status do produto, os campos oldValue e newValue terão um
destes valores : (approved, pending, disapproved, ``).
O campo eventTime contém o horário de criação do evento. Se você quiser
ordenar as mensagens, use o valor desse campo e não a ordem
de recebimento das mensagens.
Siga o formato ProductStatusChangeMessage para mais detalhes.
Como testar a implementação
Confira um exemplo de notificação que você pode usar para testar o URI de callback e a decodificação:
curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}' https://{callBackUri}
Em resposta a essa chamada, o URI de callback precisa retornar um código de resposta bem-sucedida. A mensagem decodificada deve ter o seguinte valor:
{
"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"
}