Receber notificações push sobre mudanças no serviço da conta

Você pode se inscrever para receber notificações do ACCOUNT_SERVICE_CHANGE e alertas em tempo real quando recursos do AccountService forem criados, atualizados ou excluídos. Isso é especialmente valioso para provedores terceirizados e empresas que gerenciam relacionamentos de serviço com várias contas.

Ao se inscrever para receber mudanças no serviço de conta, você detecta imediatamente quando um serviço de conta é proposto, aprovado, atualizado ou removido, sem fazer polling da API.

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 mudanças no serviço de conta

Para se inscrever nas mudanças do serviço de conta, envie uma solicitação POST ao recurso notificationsubscriptions com registeredEvent definido como ACCOUNT_SERVICE_CHANGE.

Inscrever-se em uma conta de destino específica

A solicitação de amostra a seguir se inscreve nas mudanças do serviço de conta de uma conta de comerciante específica:

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

{
  "registeredEvent": "ACCOUNT_SERVICE_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.

Assinar todas as contas gerenciadas

Os provedores e empresas que gerenciam várias contas de comerciante podem assinar mudanças no serviço de conta em todas as contas gerenciadas definindo allManagedAccounts: true:

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

{
  "registeredEvent": "ACCOUNT_SERVICE_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": "ACCOUNT_SERVICE_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com/callback"
}

Decodificar payloads de mudança do serviço de conta

Quando ocorre uma mudança no serviço de conta, o URI de callback recebe uma mensagem codificada em base64. Quando decodificado, o payload está de acordo com o formato ResourceChangeMessage:

{
  "account": "accounts/{TARGETACCOUNT_ID}",
  "managingAccount": "accounts/{ACCOUNT_ID}",
  "resourceType": "ACCOUNT_SERVICE",
  "resource": "accounts/{TARGETACCOUNT_ID}/services/{SERVICE_ID}",
  "operation": "CREATE",
  "eventTime": "2026-08-25T10:00:00Z"
}

Campos e regras de payload

• account: a conta de destino proprietária da entidade de serviço alterada (accounts/{merchant_id}).
• managingAccount: a conta que gerencia a conta do comerciante (accounts/{service_provider_id}).
• resourceType: o tipo de recurso que mudou (ACCOUNT_SERVICE).
• resource: o nome completo do recurso do serviço de conta (por exemplo, accounts/{account}/services/{service}).
• operation: a operação realizada no recurso:
  • CREATE: uma nova relação de serviço de conta foi criada.
  • UPDATE: uma configuração de serviço ou permissão de conta existente foi alterada.
  • DELETE: uma relação de serviço de conta foi removida.
• 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.

Notificações de mudança de serviço da conta de teste

Use o exemplo de solicitação a seguir para testar se o endpoint de callback recebe, confirma e decodifica corretamente as mensagens de mudança do serviço de conta:

curl --request POST \
'https://{YOUR_CALLBACK_URI}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"message":{"data": "ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJBQ0NPVU5UX1NFUlZJQ0UiLAogICJyZXNvdXJjZSI6ICJhY2NvdW50cy8xMjM0L3NlcnZpY2VzLzEyMyIsCiAgIm9wZXJhdGlvbiI6ICJDUkVBVEUiLAogICJldmVudFRpbWUiOiAiMjAyNi0wOC0yNVQxMDowMDowMFoiCn0="}}'

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": "ACCOUNT_SERVICE",
  "resource": "accounts/1234/services/123",
  "operation": "CREATE",
  "eventTime": "2026-08-25T10:00:00Z"
}