Um cliente pede reembolso à Apple. Doze horas depois, uma janela se fecha no seu servidor — e a maioria das equipes nunca soube que ela tinha sido aberta.
Essa janela pertence ao CONSUMPTION_REQUEST da Apple — uma notificação que a App Store envia quando quer informações suas enquanto avalia um pedido de reembolso. Não é um reembolso. Não é uma decisão. A Apple toma a decisão final sobre o reembolso de qualquer forma. O que a notificação oferece é uma oportunidade limitada de descrever o que realmente aconteceu com a compra.
Lidar bem com isso é um problema de backend, não de suporte. A notificação precisa chegar, a transação precisa ser identificável, o status de consentimento precisa ser conhecido e uma resposta precisa sair a tempo.
Este artigo explica o que a notificação significa, o que a Apple pede hoje (a lista de campos é bem menor do que costumava ser) e como montar um fluxo de trabalho em torno dela. Para o processo mais amplo, nosso guia de gestão de reembolsos da App Store dá o contexto.
Principais pontos
• CONSUMPTION_REQUEST é a Apple pedindo informações durante a avaliação de um reembolso. Não é uma notificação de reembolso.
• A Apple toma a decisão final sobre o reembolso. Sua resposta é apenas um dos fatores considerados.
• O endpoint atual recebe cinco campos, três deles obrigatórios — contra doze na versão anterior.
• O consentimento é obrigatório. A Apple rejeita requisições em que customerConsented não seja true.
• A Apple pede uma resposta em até 12 horas após a notificação.
• Como a janela é curta e as notificações chegam a qualquer hora, essa etapa combina mais com automação do que com um processo manual.
O que é o CONSUMPTION_REQUEST da Apple?
CONSUMPTION_REQUEST é uma App Store Server Notification que informa que um cliente pediu reembolso à Apple e que a App Store está convidando você a enviar informações de consumo sobre aquela compra.
O consumption request da Apple para desenvolvedores existe por causa de uma lacuna de informação. A Apple vê a transação, a conta e o histórico de compras. Ela não consegue ver o que aconteceu dentro do seu app — se o conteúdo foi entregue, se funcionou, quanto o cliente realmente usou. Você consegue.
Uma coisa que ele não é: um veto. Uma resposta não bloqueia um reembolso, e a Apple é explícita ao dizer que pondera uma série de fatores.
Como funciona o CONSUMPTION_REQUEST da Apple?
A sequência é esta:
O cliente pede reembolso
↓
A Apple começa a avaliar o pedido
↓
O CONSUMPTION_REQUEST chega ao seu endpoint de notificações
↓
Você verifica a notificação e identifica a transação
↓
Você checa o consentimento e reúne dados reais de uso
↓
Você envia as informações de consumo, se os requisitos forem atendidos
↓
A Apple toma a decisão sobre o reembolso
↓
REFUND ou REFUND_DECLINED chega; você atualiza o estado
Vale destacar: no endpoint atual da Apple, um pedido de reembolso para qualquer tipo de produto pode disparar essa notificação — consumível, não consumível, assinatura não renovável ou assinatura com renovação automática. A documentação antiga e a maioria dos textos de terceiros ainda descrevem o recurso como restrito a consumíveis e assinaturas com renovação automática. Se o seu handler filtra por tipo de produto com base nisso, está descartando requisições.
Que informações a Apple pede aos desenvolvedores?
Menos do que antes. Essa é a parte que a maioria dos guias existentes erra, então vale ser preciso. O endpoint atual Send Consumption Information da Apple recebe cinco campos — três obrigatórios, dois opcionais.
Campo | Obrigatório | O que significa para você |
customerConsented | Sim | Deve ser true. Caso contrário, a Apple rejeita a requisição. |
deliveryStatus | Sim | Se o seu app entregou com sucesso uma compra funcionando. |
sampleContentProvided | Sim | Se o cliente recebeu conteúdo de amostra antes de comprar. |
consumptionPercentage | Não | Quanto da compra foi consumido, em milliunits. |
refundPreference | Não | Seu resultado preferido: conceder integralmente, recusar ou reembolsar proporcionalmente. |
Duas restrições pegam as pessoas de surpresa. Se deliveryStatus for qualquer valor diferente de delivered, consumptionPercentage precisa ser zero, ou a requisição falha. E milliunits não são porcentagem — metade consumida é 50000, não 50.
A preferência de reembolso opcional é mais recente e vale a pena entender. Você pode indicar se prefere que o reembolso seja concedido integralmente, recusado ou proporcional. É uma preferência, não uma instrução — a Apple a pondera junto com todo o resto, e o resultado pode ser diferente do que você pediu.
Se a Apple aprovar um reembolso proporcional, a parte revogada vem no payload da transação, então sua lógica de entitlements pode precisar lidar com revogação parcial em vez de tratar todo reembolso como tudo ou nada.
Por que a Apple precisa de informações de consumo?
Porque a Apple está decidindo algo que ela só consegue ver em parte.
A Apple sabe o que foi comprado, quando, por qual conta e como é o histórico dessa conta. Ela não sabe se o seu servidor entregou as moedas, se o recurso desbloqueado funcionou ou se o cliente usou o produto intensamente antes de pedir o dinheiro de volta. Esse contexto vive nos seus sistemas.
O fluxo de reembolso via CONSUMPTION_REQUEST é a forma que a Apple tem de trazer esse contexto antes de decidir. É também por isso que precisão importa mais do que argumentação. Os dados descrevem o que aconteceu. Não é uma causa que você está defendendo, e tratá-los assim traz risco real sem retorno garantido.
Como os desenvolvedores respondem ao CONSUMPTION_REQUEST
Oito etapas. A maior parte do trabalho acontece antes de qualquer requisição chegar.
1. Receba a notificação
As notificações CONSUMPTION_REQUEST da App Store chegam à URL do servidor que você configura para as App Store Server Notifications V2. Se esse endpoint não existe, não está verificado ou está falhando silenciosamente, a requisição nunca chega até você. A documentação das App Store Server Notifications da Apple cobre a configuração e o formato do payload.
2. Verifique a notificação
As notificações chegam como payloads JWS assinados. Verifique a assinatura contra a cadeia de certificados da Apple antes de agir sobre qualquer coisa no conteúdo, e confira se o bundle ID corresponde ao seu app. Um endpoint não verificado que aceita qualquer coisa que recebe é uma porta para que outra pessoa controle sua lógica de reembolso.
3. Identifique a transação
O payload decodificado traz os identificadores da transação. Você precisa de um registro de compra armazenado para cruzar com eles. Sem registro, não há consulta — e não há como dizer nada útil sobre o consumo.
4. Associe a transação ao usuário correto
Você não consegue descrever o uso de um cliente sem saber qual cliente é. É para esse mapeamento que o appAccountToken existe: um UUID que o seu app anexa no momento da compra e que volta no payload da notificação. Sem ele, as equipes acabam associando por horário e heurísticas, o que é lento e pouco confiável justamente no momento em que a velocidade importa.
5. Verifique os requisitos de consentimento aplicáveis
A Apple é inequívoca aqui: você precisa obter consentimento válido antes de compartilhar os dados de um cliente, e obtê-lo é responsabilidade sua, não da Apple. A notificação não traz nenhum indicador de consentimento, então você precisa saber pelos seus próprios registros.
Se o cliente não consentiu, a orientação da Apple é não responder. Enviar a requisição com o consentimento definido como false não funciona — a App Store a rejeita. A Apple também deixa claro que o prompt do App Tracking Transparency não é o mecanismo para isso; é um consentimento separado, coletado no seu app.
6. Reúna informações reais de uso
Extraia o status de entrega e o consumo dos seus registros reais. Se o seu servidor acompanha o saldo de um consumível, você já sabe quanto foi gasto. Se um desbloqueio de recurso falhou, seus logs também sabem disso. Não estime — um número de consumo inventado é dado impreciso enviado à Apple sob um consentimento que você obteve para dados precisos.
7. Envie as informações adequadas
Responda com um PUT ao endpoint de consumo usando o identificador da transação original que veio na notificação. Trate as respostas de erro em vez de disparar e esquecer: falhas de validação retornam HTTP 400 com tipos de erro específicos, e uma chamada que falhou silenciosamente parece idêntica a uma bem-sucedida se ninguém verificar.
8. Registre o resultado
Registre a requisição, a transação, o que você enviou, quando enviou e o que a Apple decidiu no fim. Esse registro é o que permite responder a uma dúvida de suporte semanas depois, identificar padrões entre reembolsos e confirmar que o estado dos seus entitlements está correto. Quando um reembolso acontecer, revogue o acesso após o reembolso — e esteja pronto para restaurá-lo se a Apple reverter a decisão depois.
O que acontece se o desenvolvedor perder o CONSUMPTION_REQUEST?
Nada dramático, e isso é parte do problema.
Perder a resposta significa que você não fornece as informações adicionais que a Apple permitiu enviar durante aquele fluxo. A Apple decide mesmo assim. O reembolso ainda pode ser aprovado, ou recusado, com base nas informações que a Apple já tem. Não há erro, não há alerta e não há nenhum sinal claro de que algo foi pulado.
As formas de perder são corriqueiras. A notificação chega às 2h da manhã. O engenheiro responsável pelo handler está de folga. A consulta da transação demora porque o identificador está em um sistema e os dados de uso em outro. Alguém vê na segunda-feira, muito depois de a janela ter fechado.
Por que o tratamento manual do CONSUMPTION_REQUEST é difícil
Cada restrição desse fluxo aponta para longe do tratamento manual.
As notificações chegam a qualquer hora. A janela é de 12 horas. Cada requisição exige uma consulta de transação, uma associação de usuário, uma checagem de consentimento, um cálculo de uso, uma chamada de API assinada e um resultado registrado — sete etapas, nenhuma delas interessante, todas com prazo.
Com uma requisição por semana, é um incômodo. Com trinta por dia, vira o trabalho de alguém — um trabalho que não produz nada quando bem feito e gera perdas silenciosas quando feito tarde.
Como a automação muda o fluxo de reembolso
A automação não dá a você influência sobre a Apple. Vale repetir, porque muito material de marketing sugere o contrário. A decisão da Apple continua sendo da Apple.
O que a automação faz é tornar o seu lado consistente. As notificações são monitoradas e verificadas. As requisições relevantes são separadas do restante do fluxo. As transações são associadas às contas. Os dados de resposta são montados a partir de registros reais, os prazos são acompanhados, as respostas são enviadas e registradas, e os resultados alimentam as atualizações de entitlements.
Nenhuma dessas etapas exige julgamento. Todas exigem atenção no momento certo, algo que software faz melhor do que pessoas.
O que um software de gestão de reembolsos da App Store deve cobrir?
Se você está avaliando um software de gestão de reembolsos da App Store, a pergunta útil é se ele fecha as lacunas específicas acima.
Ele deve monitorar e verificar as App Store Server Notifications, para que os eventos não desapareçam em um endpoint com falha. Deve acompanhar os eventos CONSUMPTION_REQUEST separadamente, já que eles exigem um tratamento diferente dos resultados de reembolso. Deve associar transações a contas, porque é aí que o tempo manual é gasto. Deve acompanhar as janelas de resposta, porque é esse o prazo que as pessoas perdem.
Além disso: fluxos de dados de consumo que respeitem o estado de consentimento, histórico de reembolsos pesquisável, acompanhamento de resultados, sincronização de entitlements incluindo revogação parcial e relatórios claros o suficiente para mostrar padrões. O que importa é a cobertura do fluxo de trabalho, não o tamanho da lista de recursos.
Onde essas regras estão documentadas
Três fontes da Apple cobrem tudo o que está acima. Leia-as diretamente — essa área mudou recentemente, e muito conteúdo secundário descreve uma versão antiga da API.
Send Consumption Information — o endpoint atual. Cobre o requisito de consentimento, a janela de 12 horas, o corpo da requisição com cinco campos e o fato de que as informações de consumo se aplicam a todos os tipos de produto. É este que você deve usar como base para In-App Purchases padrão.
App Store Server Notifications — como as notificações chegam ao seu backend, o formato do payload assinado e os tipos de notificação, incluindo CONSUMPTION_REQUEST, REFUND e REFUND_DECLINED.
Send Consumption Information V1 — o endpoint anterior, com o corpo de requisição de doze campos que algumas equipes ainda têm implementado. A própria nota da Apple nessa página direciona In-App Purchases padrão para o endpoint atual e restringe o V1 a compras que usam a Advanced Commerce API. Útil para identificar em qual deles a sua integração está, não como alvo de implementação.
Considerações finais
CONSUMPTION_REQUEST não é a decisão de reembolso da Apple. É uma oportunidade curta e com prazo para contar à Apple o que os seus sistemas sabem e os dela não.
Um fluxo que lida com isso de forma confiável precisa de um endpoint de notificações verificado, transações que você consiga identificar, clientes que você consiga mapear, consentimento que você realmente coletou, dados reais de uso, uma resposta dentro da janela e resultados registrados bem o suficiente para atualizar os entitlements depois.
Se você fizer uma única coisa depois de ler isto, verifique qual endpoint a sua integração chama. Se ela ainda envia doze campos para o caminho V1 em In-App Purchases padrão, essa é a lacuna que vale fechar primeiro.
Se o volume de reembolsos já superou o tratamento manual
Quando a atividade de reembolso se torna frequente o bastante para que acompanhar notificações manualmente deixe de ser realista, um sistema dedicado pode monitorar os eventos, preparar e enviar respostas dentro da janela, acompanhar resultados e manter os entitlements sincronizados. RefundSensor automatiza o lado do desenvolvedor nesse fluxo — não a decisão da Apple, apenas a parte pela qual você é responsável.
Perguntas frequentes
É uma App Store Server Notification que avisa ao seu servidor que um cliente pediu reembolso e que a Apple pode querer informações de consumo. Não é uma decisão de reembolso.
A Apple o envia depois que um cliente pede reembolso, enquanto ela ainda está analisando o pedido. Pode se aplicar a diferentes tipos de produto da App Store.
Seu servidor recebe e verifica a notificação, identifica a transação e o cliente, checa o consentimento e envia as informações de consumo exigidas à Apple dentro da janela de resposta.
Verifique a notificação, confira o consentimento do cliente, forneça dados precisos de uso e entrega, envie-os à Apple e mantenha um registro da resposta e do resultado final.
A documentação atual da Apple especifica uma janela de resposta de 12 horas. Os desenvolvedores devem confirmar os requisitos mais recentes da Apple antes de implementar.
São informações sobre como o cliente usou a compra. Dependendo do endpoint atual, podem incluir consentimento, status de entrega, conteúdo de amostra, dados de consumo e uma preferência de resultado do reembolso.
Não. A Apple toma a decisão final. Os desenvolvedores podem fornecer informações de consumo e indicar uma preferência de reembolso, mas a determinação final é da Apple.
Sim. Os desenvolvedores podem automatizar a verificação de notificações, a associação de transações, as checagens de consentimento, a preparação dos dados, o acompanhamento de prazos e o registro das respostas.
