App Store Server Notifications V2 em 2026
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 subtiposINITIAL_BUY,RESUBSCRIBE,UPGRADEeDOWNGRADE. Libere o acesso e registre o identificador do produto, não apenas "subscribed".DID_RENEW— com os subtiposBILLING_RECOVERYeBILLING_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 subtipoGRACE_PERIODquando 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 subtiposVOLUNTARY,BILLING_RETRYePRODUCT_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) eDID_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 emAUTO_RENEW_DISABLED.REFUND,REFUND_DECLINED,REFUND_REVERSED,REVOKEeRESCIND_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_EXTENDEDeRENEWAL_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,TESTeEXTERNAL_PURCHASE_TOKEN(com o subtipoUNREPORTEDquando 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
ambienteantes 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
SUBSCRIBEDeDID_RENEW, e ignoraREFUND,REVOKEeREFUND_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
- Desenvolvedor Apple — Notificações do Servidor do App Store: developer.apple.com/documentation/appstoreservernotifications
- Desenvolvedor Apple — Notificações do Servidor V2 do App Store: app-store-server-notifications-v2
- Apple Developer — Como ativar as App Store Server Notifications: enabling-app-store-server-notifications
- Apple Developer — enums notificationType e subtype: notificationtype / subtype
- Apple Desenvolvedor — responseBodyV2DecodedPayload: responsebodyv2decodedpayload
- Desenvolvedor Apple — API do Servidor do App Store: developer.apple.com/documentation/appstoreserverapi
- Apple — Biblioteca do Servidor do App Store (Python): github.com/apple/app-store-server-library-python
- Apple — autoridade certificadora: www.apple.com/certificateauthority
Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.
Recebemos sua mensagem e responderemos em até 24 horas.
← Voltar para editar