KappS Base de conhecimento · Blog

App Store Server Notifications V2 em 2026

Blog Tutorial

O Apple encerrou o caminho da versão 1: as notificações da versão 1 e o endpoint Receipts do App Store estão obsoletos, e a instrução agora diz "implemente o endpoint da versão 2 no seu servidor". Para um app com assinaturas ativas, isso não é uma migração cosmética — o fluxo de notificações é como seu servidor fica sabendo que uma renovação foi concluída, que um reembolso foi emitido, que a cobrança está sendo tentada novamente ou que o Apple está pedindo que você justifique uma solicitação de reembolso. Este tutorial percorre toda a configuração de 2026: ativar a versão 2 no App Store Connect, verificar o JWS, mapear cada tipo e subtipo de notificação e usar a App Store Server API para o estado que uma notificação só descreve em um determinado momento.

A versão em uma linha: o App Store Connect envia um blob JSON assinado com JWS para a sua URL HTTPS; verifique a cadeia de assinatura, decodifique signedPayload, aja com base em notificationType mais subtype, responda 200-206 rapidamente e chame a App Store Server API sempre que precisar do estado atual em vez do estado do evento.

Etapa 1 — Corrija os dois endpoints antes de mexer no App Store Connect

You need one HTTPS URL for production and, optionally, a second one for sandbox; Apple explicitly allows you to use the same URL for both environments. Your server must support TLS 1.2 or later. If the URL contains a port, it must be either 443 or 1024 and above — https://example.com:1234/notifications is a valid shape, a low privileged port is not. And if your edge terminates behind an IP allow list, add Apple's 17.0.0.0/8 subnet, which applies to sandbox and production alike. All of this is documented in Enabling App Store Server Notifications.

Etapa 2 — ative a versão 2 por ambiente

No App Store Connect, abra seu app e vá em Informações do app > App Store Notificações do servidor. Produção e sandbox são configurados separadamente, e cada ambiente escolhe de forma independente a versão 2 ou a versão 1 descontinuada — é isso que permite rodar o novo formato em produção enquanto o antigo ainda precisa funcionar em outro lugar, ou o contrário. O caminho de migração indicado pelo Apple é testar a versão 2 primeiro no ambiente sandbox e só depois migrar a produção. Um comportamento que vale conhecer antes de começar a depurar: a notificação TEST é sempre enviada no formato da versão 2, independentemente da versão que a URL configurada espera.

Passo 3 — Responda com o código de status correto e depois trabalhe de forma assíncrona

Responda com um código de status HTTP 200-206 se o POST foi processado com sucesso. Se não foi processado, envie um 50x ou 40x para que o App Store tente novamente a notificação. O padrão prático é: ler o corpo, verificá-lo, enfileirá-lo, responder 200 e fazer o trabalho de verdade em um worker. Não mantenha a conexão aberta enquanto você chama seu próprio banco de dados, seu provedor de e-mail ou a App Store Server API. As novas tentativas existem para proteger você de falhas de infraestrutura, não de um handler lento — e cada nova tentativa que você dispara é um evento duplicado que depois você precisa suprimir.

Etapa 4 — Decodifique o payload

O corpo é um objeto responseBodyV2 cujo único campo relevante é signedPayload, um JWS. Faça o parse dele em suas representações de cabeçalho, payload e assinatura e, em seguida, decodifique o payload em Base64URL para obter o responseBodyV2DecodedPayload. Nesse nível você obtém notificationType, subtype, version, signedDate e notificationUUID. Exatamente um de quatro objetos de dados está presente: data para eventos de compra dentro do app, carregando um signedTransactionInfo e — para assinaturas com renovação automática — um signedRenewalInfo; summary, que aparece apenas para um RENEWAL_EXTENSION com o subtipo SUMMARY; appData; ou externalPurchaseToken, que aparece apenas em uma notificação EXTERNAL_PURCHASE_TOKEN.

Etapa 5 — Verifique todas as assinaturas, não só a externa

As três representações assinadas — signedPayload, signedTransactionInfo e signedRenewalInfo — carregam sua própria assinatura JWS, e cada uma precisa ser validada; use o algoritmo indicado no parâmetro alg do cabeçalho. Na prática, isso significa verificar a cadeia de certificados x5c até a raiz publicada pela Apple, que você baixa da Apple página da autoridade certificadora (a raiz atual para este serviço é AppleRootCA-G3.cer). Não faça isso manualmente: a Apple publica a App Store Server Library para Python, Java, Node.js e Swift, que realiza a verificação e a decodificação para você. Um manipulador que decodifica o payload em Base64 e ignora a verificação é trivialmente falsificável — qualquer pessoa que descubra sua URL de notificação pode conceder a si mesma uma assinatura.

Etapa 6 — Mapeie notificationType e subtype para seus direitos de acesso

O enum da versão 2 define 23 tipos de notificação e 19 subtipos que qualificam alguns deles; ambas as listas são publicadas em notificationType e subtype. Os que decidem se um cliente pagante mantém o acesso:

  • SUBSCRIBED — com os subtipos INITIAL_BUY, RESUBSCRIBE, UPGRADE e DOWNGRADE. Libere o acesso e registre o identificador do produto, não apenas "subscribed".
  • DID_RENEW — com os subtipos BILLING_RECOVERY e BILLING_RETRY. Uma renovação que chegou após um problema de pagamento ainda chega aqui, então trate-a como uma extensão normal do acesso.
  • DID_FAIL_TO_RENEW — com o subtipo GRACE_PERIOD quando o cliente está dentro de um período de tolerância. Normalmente o acesso continua nesse caso, que é justamente o propósito dos períodos de tolerância.
  • GRACE_PERIOD_EXPIRED — o período de tolerância acabou. É aqui que se faz o downgrade, não no momento da cobrança recusada.
  • EXPIRED — com os subtipos VOLUNTARY, BILLING_RETRY e PRODUCT_NOT_FOR_SALE. O último importa se você retirar um produto da venda enquanto as pessoas ainda o possuem.
  • DID_CHANGE_RENEWAL_STATUS (AUTO_RENEW_ENABLED / AUTO_RENEW_DISABLED) e DID_CHANGE_RENEWAL_PREF (UPGRADE / DOWNGRADE) — um cliente que desativou a renovação automática ainda tem direito até o fim do período, então nunca revogue o acesso em AUTO_RENEW_DISABLED.
  • REFUND, REFUND_DECLINED, REFUND_REVERSED, REVOKE e RESCIND_CONSENT — o lado da revogação. Um reembolso revertido significa que o dinheiro voltou para você, então o direito de acesso também precisa voltar para o cliente.
  • CONSUMPTION_REQUEST — o Apple está pedindo evidências sobre como a compra foi usada; veja o passo 7.
  • OFFER_REDEEMED, PRICE_CHANGE, PRICE_INCREASE (ACCEPTED / PENDING), RENEWAL_EXTENDED e RENEWAL_EXTENSION (SUMMARY / FAILURE) — mudanças comerciais e de datas que normalmente exigem uma notificação ao cliente, e não uma alteração de acesso.
  • METADATA_UPDATE, MIGRATION, ONE_TIME_CHARGE, TEST e EXTERNAL_PURCHASE_TOKEN (com o subtipo UNREPORTED quando Apple gerou um token para o qual não tem relatório).

O catálogo completo, com as adições mais recentes, fica no changelog de notificações — Apple acrescenta campos e valores com o tempo, então releia antes de presumir que seu handler está completo.

Etapa 7 — Responda a um CONSUMPTION_REQUEST em até 12 horas

Quando um cliente solicita reembolso de qualquer tipo de produto — consumível, não consumível, não renovável ou com renovação automática —, a Apple envia um CONSUMPTION_REQUEST. Se o cliente deu consentimento, você pode responder chamando Send Consumption Information com os dados de uso que a Apple pede, e a Apple documenta uma janela de resposta de 12 horas a partir do momento em que a notificação chega. Se o cliente não deu consentimento, você não responde nada. Duas regras são fáceis de errar: o consentimento exigido para essa API é separado do consentimento que você coletou para rastreamento ou publicidade, e é você o responsável por obter consentimento válido antes de compartilhar dados de uso com a Apple.

Etapa 8 — Use a App Store Server API para estado, não para o evento

Uma notificação descreve um momento. Antes de escrever os direitos, resolva o presente:

  • Obter informações da transação de uma única transação, incluindo o motivo e a data do seu estorno.
  • Get All Subscription Statuses para ter a visão oficial das assinaturas de um cliente.
  • Obter histórico de reembolsos quando você precisar dos reembolsos de um identificador de transação original.
  • Estender a data de renovação de uma assinatura para compensar uma indisponibilidade do serviço. Duas características fazem disso uma via de mão única: depois que a extensão entra em vigor, não há como revertê-la, e as assinaturas dos membros da família são estendidas automaticamente, enquanto solicitações diretas para a assinatura de um membro da família não são aceitas. O período de extensão também não conta para o um ano de serviço pago que o Apple considera ao calcular a taxa de comissão.

Etapa 9 — Prove que o fluxo funciona antes de depender dele

Chame Request a Test Notification e o App Store envia uma notificação TEST para o seu endpoint. Essa chamada retorna um token que você passa para Get Test Notification Status dentro de seis meses para ver como o seu servidor realmente respondeu. Separadamente, se o seu endpoint estava fora do ar às 3h da manhã, Get Notification History retorna as notificações versão 2 que o App Store tentou enviar: 180 dias em produção, 30 dias no sandbox, 20 registros por página com um token de continuação e o conteúdo completo das notificações. Lembre-se do que esse histórico é: cada registro reflete o estado no momento em que a notificação foi originalmente enviada, não o estado atual.

Passo 10 — As regras operacionais que mantêm o pipeline correto

  • Leia o ambiente antes de escrever qualquer coisa. O tráfego de sandbox chega às URLs de sandbox; se um handler compartilhado gravar direitos de produção a partir de um evento de sandbox, o teste vira um incidente de dados.
  • Elimine duplicatas pelo notificationUUID. Novas tentativas e o seu próprio reprocessamento geram o mesmo evento mais de uma vez; armazene o identificador e descarte as repetições.
  • Nunca trate uma notificação como recibo. Um build que só escuta SUBSCRIBED e DID_RENEW, e ignora REFUND, REVOKE e REFUND_REVERSED, vaza acesso pago permanentemente. Trate todo o ciclo de vida ou delegue a verificação à biblioteca do Apple e consulte a Server API.
  • Mantenha seu próprio registro de eventos. Quando um cliente contesta um acesso, o histórico de notificações e o seu próprio registro são o que permitem reconstruir a decisão.
  • Considere que o endpoint faz parte da produção. Ele precisa de monitoramento, de um timeout de requisição bem abaixo do orçamento de conexão e de uma fila — não de uma cadeia de chamadas síncronas para o seu sistema de cobrança.

Fontes

Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar