Entender o que é uma CONSUMPTION_REQUEST leva mais ou menos um parágrafo. Construir algo que lide com uma delas de forma confiável leva bem mais, e as partes que pegam as pessoas de surpresa não são as que você esperaria.
A verificação de assinatura é uma delas. O consentimento é outra, porque ele precisa existir antes de a notificação chegar. E o cronograma de novas tentativas interage com a janela de resposta de um jeito que surpreende a maioria das equipes na primeira vez que olham de perto.
Este artigo percorre o handler desde o momento em que a solicitação chega ao seu endpoint até a atualização de entitlement que encerra o processo.
Principais pontos
• A CONSUMPTION_REQUEST pede informações durante a análise de um reembolso. A decisão continua sendo da Apple.
• Verifique o payload assinado antes de agir com base nele. Nunca confie em uma notificação não verificada.
• O consentimento já precisa existir no seu app. Não dá para coletá-lo depois que a solicitação chega.
• A Apple pede uma resposta em até 12 horas após a notificação.
• A Apple repete entregas que falharam em um cronograma fixo, e a segunda nova tentativa chega depois que a janela de resposta já fechou.
• Acompanhe o resultado e atualize o entitlement depois. Responder não é a última etapa.
O que é uma notificação CONSUMPTION_REQUEST da Apple?
Uma notificação CONSUMPTION_REQUEST da Apple é uma App Store Server Notification que informa ao seu servidor que um cliente solicitou um reembolso e que a Apple está convidando você a enviar informações de consumo sobre essa compra. Ela chega na URL de notificação que você configurou, traz a transação relevante e dá a você um tempo limitado para responder.
Não é um reembolso nem uma decisão. A Apple está no meio de uma análise e coletando contexto. Seu papel é fornecer informações precisas sobre o que aconteceu com a compra; o papel da Apple é decidir.
Por que a Apple envia uma CONSUMPTION_REQUEST?
Porque a Apple não consegue enxergar dentro do seu app. Ela conhece a transação, a conta e o histórico de compras. Não sabe se o conteúdo foi entregue, se funcionou ou quanto dele o cliente usou.
As informações de consumo preenchem essa lacuna. São um dos vários fatores que a Apple pondera, não o decisivo, e um percentual de consumo alto não é um botão de recusa. Trate isso como contexto que você está contribuindo, não como um caso que você está defendendo.
O que os desenvolvedores devem fazer ao receber uma CONSUMPTION_REQUEST?
Validar a notificação, identificar a transação e o cliente, confirmar o consentimento, montar dados de consumo precisos, enviá-los dentro da janela da Apple e, então, registrar o que aconteceu.
Dez etapas na prática:
1. Receba a notificação no endpoint de servidor configurado e persista-a imediatamente.
2. Verifique o payload assinado antes de tratar qualquer campo como real.
3. Leia o tipo da notificação e faça o roteamento. Uma solicitação de consumo não é o resultado de um reembolso.
4. Identifique a transação relacionada a partir do payload decodificado.
5. Associe a transação a uma conta de cliente no seu próprio sistema.
6. Verifique se o consentimento desse cliente permite uma resposta.
7. Reúna dados de entrega e uso a partir dos seus registros, não de estimativas.
8. Prepare a resposta e confira-a contra as regras de validação dos campos.
9. Envie ao endpoint de consumo da Apple e capture o resultado.
10. Acompanhe o resultado do reembolso que vem em seguida e, então, atualize o entitlement e os registros.
Como os desenvolvedores devem validar uma CONSUMPTION_REQUEST?
Verifique a assinatura antes de confiar no conteúdo. As notificações chegam como payloads JWS assinados, documentados na documentação de App Store Server Notifications da Apple, e seu handler deve conferi-los contra a cadeia de certificados da Apple e confirmar que o bundle ID corresponde ao seu app.
O motivo é simples. Sua URL de notificação é um endpoint público. Uma implementação que interpreta o que quer que chegue e age com base nisso é uma implementação que qualquer pessoa que encontrar a URL pode controlar.
Três detalhes do handler importam tanto quanto a assinatura:
Responda com o código de status certo. A Apple trata HTTP 200 a 206 como sucesso. Um 40x ou 50x diz à App Store para tentar de novo. Retorne sucesso assim que tiver armazenado a notificação, não quando terminar de processá-la — são momentos diferentes, e acoplá-los significa que um job lento mais adiante pode disparar novas tentativas desnecessárias.
Trate duplicatas. Novas tentativas significam que a mesma notificação pode chegar mais de uma vez, e cada uma traz um UUID de notificação que você pode usar para deduplicar. Confirme o recebimento das repetições em vez de retornar erro; uma resposta de falha só reinicia o ciclo de novas tentativas.
Lembre-se de que o sandbox se comporta de forma diferente. As novas tentativas valem em produção. No sandbox, a App Store tenta a entrega uma única vez, então um handler que parece bem nos testes ainda pode estar perdendo eventos em produção, e o inverso também é verdade.
O que os desenvolvedores devem verificar antes de responder?
Quatro coisas, nesta ordem.
Consentimento primeiro, porque é o que pode travar tudo. A Apple exige consentimento válido do cliente antes de você compartilhar os dados dele, obtê-lo é responsabilidade sua e não da Apple, e a notificação em si não traz nenhum indicador de consentimento. A Apple também deixa claro que o prompt do App Tracking Transparency não é o mecanismo para isso. Se o consentimento não existe, a orientação é não responder.
Identidade da transação em segundo. Você precisa saber qual compra é esta e qual conta está por trás dela. Esse mapeamento é o assunto de appAccountToken e defesa contra reembolsos da Apple — sem um vínculo estável entre transação e conta, você está inferindo contra um prazo.
Tipo de produto em terceiro, já que ele afeta quais opções estão disponíveis para você. E, por fim, se você realmente tem dados utilizáveis. Se seus sistemas não conseguem dizer se o conteúdo foi entregue, vale saber disso antes de começar a montar uma resposta.
Quais informações de consumo os desenvolvedores podem enviar à Apple?
A atual documentação de Send Consumption Information da Apple define cinco campos. Três são obrigatórios e dois, opcionais.
Campo | Obrigatório | Em termos simples |
customerConsented | Sim | O cliente concordou com isso? Precisa ser true, ou a solicitação é rejeitada. |
deliveryStatus | Sim | Seu app realmente entregou uma compra funcionando e, se não, por quê? |
sampleContentProvided | Sim | O cliente pôde experimentar antes de comprar? |
consumptionPercentage | Não | Quanto ele usou? Em miliunidades — metade é 50000, não 50. |
refundPreference | Não | O que você preferiria: conceder integralmente, recusar ou ratear. |
Duas regras costumam confundir. Se o status de entrega for qualquer coisa diferente de entregue, o percentual de consumo precisa ser zero. E a preferência de reembolso é uma preferência, não uma instrução; a Apple pode decidir de forma diferente, e decide.
Vale conferir em qual endpoint você está. A Apple também documenta a documentação de ConsumptionRequestV1 da Apple, a versão anterior com um corpo de doze campos que a maioria dos artigos de terceiros ainda descreve. A nota da Apple ali direciona as In-App Purchases padrão para o endpoint atual e restringe a V1 às compras da Advanced Commerce API. Se sua integração é anterior à mudança, essa é a primeira coisa a verificar.
Quanto tempo os desenvolvedores têm para responder a uma CONSUMPTION_REQUEST?
A documentação atual da Apple pede uma resposta em até 12 horas após a notificação.
Aqui está a parte que merece atenção. A Apple repete entregas que falharam cinco vezes, em 1, 12, 24, 48 e 72 horas após a tentativa anterior. Compare isso com uma janela de 12 horas e a conta fica desconfortável: se seu endpoint perde a primeira entrega, a primeira nova tentativa chega uma hora depois e está tudo bem. Se perde essa também, a próxima tentativa chega por volta de treze horas depois — quando a janela já fechou.
Então a confiabilidade do endpoint não é uma questão de higiene geral aqui. Para solicitações de consumo especificamente, cerca de uma hora fora do ar é recuperável e meio dia não é.
A Apple não afirma que perder a janela significa que o reembolso é aprovado automaticamente, e seria errado afirmar isso. O que significa é simplesmente que a Apple decide sem informações que você poderia ter fornecido.
O que acontece depois que o desenvolvedor responde?
A Apple leva suas informações para a análise, pondera junto com todo o resto e decide. O resultado chega como uma notificação separada: concedido, recusado ou revertido, caso a Apple depois desfaça um reembolso que aprovou.
Três coisas distintas acontecem aqui, e ajuda mantê-las separadas. Sua resposta é informação. A decisão da Apple é uma decisão. A atualização do seu sistema é uma mudança de estado. Só a do meio pertence à Apple, e a terceira não acontece a menos que você a construa.
Como os desenvolvedores lidam com reembolsos da Apple depois da resposta
Quando o resultado chega, o trabalho volta para você.
Registre o resultado na transação e no cliente. Atualize o status da assinatura, já que um período reembolsado normalmente encerra a assinatura em vez de deixá-la ativa. Revogue o entitlement em um reembolso concedido, restaure-o em uma reversão e trate o caso rateado, em que só parte de uma transação é revogada.
Depois, concilie o valor no período de relatório correto e mantenha o reembolso em um histórico consultável. É esse histórico que mais tarde mostra se um produto ou faixa de preço está gerando uma parcela desproporcional, e é também o que o suporte precisa quando um cliente pergunta o que aconteceu com o acesso dele.
Quais são os erros comuns ao lidar com CONSUMPTION_REQUEST?
Os que aparecem repetidamente:
• Tratar a notificação como um reembolso e revogar o acesso imediatamente. Nada foi decidido ainda.
• Pular a verificação de assinatura porque o payload parece bem nos testes.
• Descobrir que não existe fluxo de consentimento no momento em que a resposta precisa ser enviada.
• Enviar percentuais de consumo estimados em vez de reais.
• Disparar a solicitação e nunca conferir se ela teve sucesso. Depois, um envio que falhou parece idêntico a um que deu certo.
• Confundir um cancelamento com um reembolso. São eventos diferentes, com efeitos diferentes sobre o acesso.
• Tratar os resultados concedido e recusado, mas esquecer o caso de reversão, o que deixa clientes pagantes sem acesso.
• Depender de alguém notar uma notificação manualmente, contra um relógio de 12 horas.
O tratamento de CONSUMPTION_REQUEST pode ser automatizado?
Sim, e quase todo ele deveria ser, porque praticamente todas as etapas são determinísticas.
A automação cobre monitoramento e validação de notificações, busca de transações, verificações de consentimento, preparação dos dados de consumo, envio, registro das respostas, acompanhamento dos resultados, alertas internos e relatórios. Nada disso exige julgamento no momento.
O que continua humano está antes disso: desenhar o fluxo de consentimento no seu app e decidir qual deve ser sua política de preferência de reembolso. E a automação não tem nenhuma influência na decisão da Apple, independentemente do que algumas ferramentas sugerem.
Como o RefundSensor ajuda desenvolvedores a lidar com fluxos de reembolso da Apple
Gestão de reembolsos da App Store é a categoria, e o RefundSensor cobre o lado do desenvolvedor: monitorar os fluxos de reembolso da Apple, tratar o caminho de resposta suportado para solicitações de consumo, acompanhar eventos e resultados de reembolso e tirar as partes repetitivas das mãos das pessoas.
Na prática, as respostas saem dentro da janela sem ninguém olhando um dashboard às 3 da manhã, e os registros de reembolso continuam precisos conforme o volume cresce. Ele não impede reembolsos e não pode influenciar o que a Apple decide. Ele elimina o monitoramento manual e as etapas esquecidas.
Onde essas regras estão documentadas
Send Consumption Information — o endpoint atual. Requisito de consentimento, a janela de 12 horas e os cinco campos da solicitação. Construa com base nele para In-App Purchases padrão.
Send Consumption Information V1 — o endpoint anterior, com o corpo de doze campos. Útil para identificar qual versão sua integração chama e para compras da Advanced Commerce API.
App Store Server Notifications — entrega de notificações, o formato do payload assinado, os códigos de resposta esperados e o cronograma de novas tentativas.
Se isso ainda é feito manualmente
Uma janela de 12 horas, um cronograma de novas tentativas que pode ultrapassá-la e notificações chegando de madrugada não combinam com monitoramento manual. O RefundSensor cuida do lado do desenvolvedor nesses fluxos — validando notificações, preparando e enviando respostas dentro da janela e acompanhando os resultados até os seus registros de entitlement.
Perguntas frequentes
Uma App Store Server Notification que informa ao seu servidor que um cliente solicitou um reembolso e que a Apple está convidando você a enviar informações de consumo sobre a compra. Não é uma notificação de reembolso nem uma decisão. A Apple decide separadamente, tratando sua resposta como um dos vários fatores considerados.
Porque a Apple não consegue ver o que aconteceu dentro do seu app. Ela conhece a transação e o histórico da conta, mas não sabe se o conteúdo foi entregue, se funcionou ou quanto o cliente usou. Esse contexto está nos seus sistemas, então a Apple pede por ele durante a análise.
Verifique a notificação assinada, identifique a transação e o cliente por trás dela, confirme que existe consentimento, reúna dados reais de entrega e uso a partir dos seus registros e, então, envie ao endpoint de consumo da Apple dentro da janela. Capture o resultado da resposta em vez de presumir que a chamada teve sucesso.
Cinco campos no endpoint atual. Três obrigatórios: consentimento do cliente, status de entrega e se foi fornecido conteúdo de amostra. Dois opcionais: percentual de consumo e sua preferência de reembolso. O endpoint V1 anterior pedia doze campos, e é por isso que orientações mais antigas descrevem uma lista mais longa.
A documentação atual da Apple descreve a notificação em conexão com pedidos de reembolso para todos os tipos de produto, um escopo mais amplo do que a documentação antiga sugeria. A Apple não publica uma garantia para todos os casos, então construa um handler que responda quando uma solicitação chegar, em vez de uma lógica que presume que ela sempre chegará.
A Apple pede uma resposta em até 12 horas após a notificação. Vale notar que o cronograma de novas tentativas da Apple para entregas que falharam é de 1, 12, 24, 48 e 72 horas, então um endpoint que fica fora do ar além da primeira nova tentativa pode receber a notificação só depois que a janela já fechou.
A Apple pondera essas informações junto com outros fatores e decide. O resultado chega como uma notificação separada indicando que o reembolso foi concedido, recusado ou revertido posteriormente. A partir daí, cabe a você atualizar o entitlement, o status da assinatura e os registros de receita para refletir o novo estado da transação.
Sim. Validação, busca de transações, verificações de consentimento, preparação dos dados, envio, registro e acompanhamento dos resultados são todos determinísticos. O que continua humano é desenhar o fluxo de consentimento e definir sua política de preferência de reembolso. A automação não tem nenhum efeito na decisão de reembolso da Apple.
