É possível usar a API Merchant Notifications para receber notificações push sobre mudanças nos dados do produto. Por exemplo, se você se inscrever nas notificações de mudança de status do produto, será notificado em tempo real quando um produto for reprovado. Você pode se inscrever nas notificações de qualquer uma das suas subcontas ou outras contas vinculadas.
Este guia mostra exemplos de como gerenciar notificações de mudanças no status do produto. Você pode usar 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 callback precisa atender aos seguintes requisitos:
- Ser um endereço HTTPS acessível publicamente com um certificado SSL válido, assinado por uma autoridade certificadora.
- Aceitar solicitações HTTP
POSTcom o cabeçalhoContent-Typee o valorapplication/json. - Retornar um dos seguintes códigos de resposta para confirmar que a notificação foi recebida.
102200201202204
Você pode 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 do produto de uma conta específica do comerciante.
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 própria conta, substitua essas duas variáveis pelo ID da sua conta.
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 de todas as suas
contas vinculadas, inclua "allManagedAccounts": trueem vez de um
targetAccount na sua 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 uma update_mask para especificar os campos que você quer atualizar e os novos valores no 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"
}
Decodificar notificações
Depois de criar uma assinatura, você recebe notificações no callBackUri especificado no seguinte formato:
{"message":{"data":"{base64_encoded_string}"}}
Os dados de notificação são codificados. Você pode decodificar os dados para um formato de texto legível para usar na sua implementação. Confira um exemplo de controlador de inicialização de primavera 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 base64_encoded_string que foi decodificada:
{
"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 caso o produto tenha sido excluído.
O campo reportingContext oferece suporte apenas a (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE, FREE_LISTINGS_UCP_CHECKOUT) 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 fazer a ordenação de mensagens, confie no valor desse campo e não na 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 --request POST \
'https://{callBackUri}' \
--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 resposta bem-sucedido. A mensagem decodificada precisa 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"
}