Se você leu algo sobre CONSUMPTION_REQUEST nos últimos anos, provavelmente viu uma lista de doze campos: tempo de conta, valor total comprado, tempo de jogo, plataforma e assim por diante.
Essa lista pertence à versão antiga do endpoint. A versão atual da Apple usa cinco campos, três deles obrigatórios, e cobre mais tipos de produto do que a original. Muitas integrações em produção ainda seguem o formato antigo.
Então este é um guia sobre o que a notificação realmente é, o que a Apple espera receber hoje e como construir um caminho de resposta que funcione de verdade.
Principais pontos
• CONSUMPTION_REQUEST é uma notificação que pede informações durante a análise de um reembolso. Não é um reembolso nem uma decisão.
• A Apple toma a decisão sobre o reembolso. Sua resposta é apenas um dos fatores considerados.
• O endpoint atual usa cinco campos, três obrigatórios, e cobre todos os tipos de produto.
• O consentimento do cliente é obrigatório. A Apple rejeita requisições sem consentimento confirmado.
• A Apple pede uma resposta em até 12 horas após a notificação.
• Existem duas versões do endpoint. Verifique qual delas sua integração chama.
O que é o CONSUMPTION_REQUEST da Apple?
O CONSUMPTION_REQUEST da Apple é uma App Store Server Notification que informa ao seu servidor que um cliente pediu reembolso e convida você a enviar informações de consumo sobre essa compra. Ela chega na URL de notificação que você configurou, traz a transação relacionada e dá a você uma janela limitada para responder.
Não é uma notificação de reembolso. Nada foi decidido quando ela chega: a Apple está no meio da avaliação do pedido, reunindo contexto antes de concluir. Para o desenvolvedor, o significado prático é simples: uma tarefa acabou de chegar ao seu backend, ela tem prazo e precisa de dados que só os seus sistemas têm.
Por que a Apple envia um CONSUMPTION_REQUEST?
Porque a Apple só enxerga metade da transação.
A Apple sabe o que foi comprado, quando, por qual conta e como é o histórico dessa conta. O que ela não consegue ver é o que acontece dentro do seu app: se as moedas foram creditadas, se o desbloqueio funcionou ou quanto o cliente usou antes de pedir o dinheiro de volta.
“Consumo”, aqui, significa até onde o cliente chegou com o que comprou. Uma assinatura usada todos os dias por três semanas e outra que nunca foi aberta parecem idênticas para a Apple. Para você, não.
Vale deixar os limites claros. A Apple não aprova nem recusa com base apenas em um número de consumo. A informação alimenta uma decisão que pesa vários fatores, e um percentual alto de consumo não é um botão de recusa.
Como funciona o CONSUMPTION_REQUEST da Apple?
A sequência é esta:
O cliente inicia um pedido de reembolso
↓
A Apple começa a análise do reembolso
↓
O CONSUMPTION_REQUEST chega ao seu endpoint de notificações
↓
Você verifica a notificação e identifica a transação
↓
Você confere o consentimento e reúne os dados de uso
↓
Você envia as informações de consumo, quando os requisitos são atendidos
↓
A Apple pondera as informações
↓
A Apple toma a decisão sobre o reembolso
↓
Você acompanha o estado resultante da transação
Uma ressalva. A documentação atual da Apple descreve essa notificação em relação a pedidos de reembolso de todos os tipos de produto, um escopo mais amplo do que a documentação antiga sugeria. Mas a Apple não publica nenhuma garantia de que ela chegue em todos os casos, então construa um handler que responda quando uma requisição aparecer, em vez de uma lógica que presuma que ela sempre virá.
Quais informações a Apple pede aos desenvolvedores?
O endpoint atual Send Consumption Information da Apple usa cinco campos. Três são obrigatórios e dois são opcionais.
Campo | Obrigatório | O que significa |
customerConsented | Sim | Precisa ser true. Caso contrário, a Apple rejeita a requisição. |
deliveryStatus | Sim | Se o seu app entregou uma compra funcional e, se não, por quê. |
sampleContentProvided | Sim | Se o cliente pôde experimentar o conteúdo antes de comprar. |
consumptionPercentage | Não | Quanto foi consumido, em miliunidades (50% é 50000). |
refundPreference | Não | Conceder integralmente, recusar ou conceder proporcionalmente — sua preferência, não uma decisão. |
Duas regras de validação pegam muita gente de surpresa. Se o status de entrega for qualquer coisa diferente de entregue, o percentual de consumo precisa ser zero, ou a requisição falha. E miliunidades não são porcentagem: metade consumida é 50000.
A preferência de reembolso é a parte mais recente e a mais fácil de interpretar errado. Você pode dizer à Apple que prefere que o reembolso seja concedido integralmente, recusado ou concedido proporcionalmente, e a Apple pondera isso junto com todo o resto. O resultado pode ser diferente. Se um reembolso proporcional for aprovado, a parte revogada vem no payload da transação, então sua lógica de entitlement precisa lidar com revogação parcial.
A diferença de versão que vale conferir
A Apple documenta duas versões desse endpoint, e a nomenclatura confunde. Send Consumption Information V1 é a versão anterior, com o corpo de doze campos que a maioria dos artigos de terceiros ainda descreve. A própria nota da Apple nessa página direciona as compras dentro do app padrão para o endpoint atual e restringe a V1 a compras feitas com a Advanced Commerce API.
| Endpoint atual | Endpoint V1 |
Campos da requisição | 5 (3 obrigatórios) | 12 |
Tipos de produto | Todos os quatro tipos | Consumível e assinatura com renovação automática |
Use para | Compras dentro do app padrão | Compras via Advanced Commerce API |
Se sua integração é anterior à mudança, comece por aqui.
O que são informações de consumo?
Informações de consumo são os dados que você envia à Apple descrevendo o que aconteceu com uma compra depois que o cliente a fez: se foi entregue, se ele pôde experimentar antes e quanto dela usou.
Elas importam porque são a única parte do quadro que a Apple não consegue ver. Para um app de assinatura, descrevem se o cliente usou o serviço depois de comprar. Para um consumível, quanto do saldo foi gasto. Para um não consumível, se o desbloqueio funcionou.
A palavra importante é precisas. São dados que você obteve consentimento para compartilhar, extraídos dos seus registros. Não é um argumento que você está construindo, e distorcê-los em direção a um resultado preferido traz risco real sem nenhum ganho confiável.
Como os desenvolvedores devem responder ao CONSUMPTION_REQUEST?
Nove etapas, e a maior parte do trabalho acontece antes de qualquer requisição chegar.
1. Receba a notificação
As requisições chegam na URL que você definiu para as App Store Server Notifications V2. A documentação das App Store Server Notifications da Apple cobre a configuração e a estrutura do payload. Um endpoint mal configurado significa que a requisição nunca chega até você, silenciosamente.
2. Valide a notificação
Os payloads são assinados. Verifique contra a cadeia de certificados da Apple e confirme o bundle ID antes de agir sobre qualquer coisa dentro dele.
3. Identifique a transação relacionada
Extraia os identificadores da transação do payload decodificado e faça a correspondência com seus registros de compra. Sem registro armazenado, não há consulta, e não há base para descrever o consumo.
4. Verifique se o consentimento permite uma resposta
A Apple exige consentimento válido do cliente antes de você compartilhar os dados dele, e obtê-lo é responsabilidade sua. A notificação não traz nenhum indicador de consentimento, então você precisa saber pelos seus próprios registros. A Apple também afirma que o prompt do App Tracking Transparency não é o mecanismo para isso: é um consentimento separado, coletado no seu app. Se o consentimento não existir, a orientação da Apple é não responder. Nosso artigo sobre appAccountToken e defesa contra reembolsos da Apple cobre a parte de identificação que torna essa consulta possível.
5. Reúna as informações de consumo relevantes
Leia o status de entrega e o uso nos seus próprios sistemas. Se você acompanha o saldo de um consumível, o número já existe. Se um desbloqueio falhou, seus logs sabem.
6. Prepare a resposta suportada
Monte os campos obrigatórios, adicione os opcionais quando tiver valores reais e confira as regras de validação antes.
7. Envie dentro da janela da Apple
Envie um PUT para o endpoint de consumo usando o identificador da transação original que veio na notificação.
8. Registre a resposta
Armazene o que você enviou, quando e o que voltou. Um envio que falhou na validação parece idêntico a um bem-sucedido, a menos que você tenha capturado o resultado.
9. Acompanhe o resultado final do reembolso
A Apple envia a decisão como uma notificação separada. Registre-a vinculada à transação e ao cliente.
Quanto tempo os desenvolvedores têm para responder?
A documentação atual da Apple pede uma resposta em até 12 horas após o recebimento da notificação.
Doze horas parece generoso até você considerar quando as notificações chegam. As requisições chegam de madrugada, nos fins de semana, em feriados, e o relógio não para. Uma requisição que chega às 23h de uma sexta-feira já expirou antes de segunda.
A Apple não afirma que perder a janela significa automaticamente que o reembolso é concedido, e seria errado dizer isso. O que isso significa é mais simples: você não forneceu informações que a Apple estava disposta a considerar, e a decisão é tomada sem elas.
O que acontece depois que o desenvolvedor responde?
A Apple leva as informações para a análise e decide. Você verá o resultado como uma notificação: concedido, recusado ou, mais tarde, revertido, se a Apple desfizer um reembolso aprovado anteriormente.
A partir daí, o trabalho é seu. Revogue o entitlement em um reembolso concedido, restaure-o em uma reversão e trate o caso proporcional, em que só parte da transação volta.
O estado da assinatura também merece atenção, já que um período reembolsado geralmente encerra a assinatura em vez de deixá-la ativa, e o reembolso deve chegar aos registros de receita do período correto.
Vale explicitar a divisão: você fornece informações, a Apple decide e, depois, você mantém seus sistemas sincronizados com o resultado. Três responsabilidades separadas, e só a do meio pertence à Apple.
Por que tratar o CONSUMPTION_REQUEST manualmente é difícil?
Cada restrição desse fluxo de trabalho joga contra uma pessoa fazendo isso à mão.
As notificações chegam a qualquer hora. A janela é de 12 horas. Cada requisição exige verificação de assinatura, consulta da transação, correspondência com o usuário, verificação de consentimento, cálculo de uso, uma chamada de API autenticada e um resultado registrado. Nada disso é difícil. Tudo isso tem prazo, é repetitivo e não produz nada visível quando dá certo.
A escala piora tudo: vários apps, dados de transação em um sistema e dados de uso em outro, logs de resposta cheios de lacunas, estado de entitlement se distanciando do estado da transação sem ninguém perceber. Isso não significa que o tratamento manual sempre custe dinheiro, mas o risco é real e se acumula em silêncio.
O CONSUMPTION_REQUEST da Apple pode ser automatizado?
Sim, e o formato do fluxo de trabalho pede isso, já que quase todas as etapas são determinísticas.
A automação pode monitorar e verificar notificações, identificar especificamente as requisições de consumo, associar transações a contas, montar a resposta a partir dos seus registros, acompanhar a janela, enviar, registrar o resultado, gravar a decisão e enviar atualizações de entitlement.
O que ela não pode fazer é influenciar a decisão da Apple. Nenhuma ferramenta muda isso, e qualquer produto que sugira o contrário está descrevendo o processo de forma errada. O que a automação muda é se a sua parte acontece de forma consistente e dentro da janela.
Como o RefundSensor ajuda desenvolvedores a lidar com fluxos de reembolso da Apple
Gestão de reembolsos da App Store é a categoria à qual esse trabalho pertence. O RefundSensor cobre o lado do desenvolvedor: monitora os fluxos de trabalho relacionados a reembolsos da Apple, cuida do caminho de resposta suportado ao CONSUMPTION_REQUEST e mantém eventos e resultados de reembolso em um só lugar, em vez de espalhados por dashboards e planilhas.
Na prática, as respostas saem dentro da janela sem que alguém precise ficar de olho nas notificações, e os registros de reembolso continuam precisos à medida que o volume cresce. Ele não impede reembolsos nem pode garantir uma decisão específica da Apple. O que faz é reduzir o monitoramento manual e as etapas esquecidas.
Onde essas regras estão documentadas
Três fontes da Apple sustentam tudo o que foi dito acima. Leia-as diretamente e volte a consultá-las: essa área mudou recentemente, e fontes secundárias ficam para trás.
Send Consumption Information — o endpoint atual. O requisito de consentimento, a janela de 12 horas, o corpo de requisição com cinco campos e os tipos de produto que ele cobre. Construa sobre este para compras dentro do app padrão.
Send Consumption Information V1 — o endpoint anterior, com o corpo de doze campos. Útil para descobrir em qual versão sua integração está e para equipes que usam a Advanced Commerce API.
App Store Server Notifications — como as notificações chegam ao seu backend, o formato do payload assinado e os tipos de notificação, incluindo o CONSUMPTION_REQUEST e os resultados de reembolso.
Se isso ainda está sendo feito à mão
Uma janela de 12 horas e notificações que chegam às 3 da manhã combinam mal com um processo que depende de alguém conferindo um dashboard.
Se é aí que sua equipe está, o RefundSensor cuida do lado do desenvolvedor nesses fluxos de trabalho: monitora as notificações, prepara e envia as respostas dentro da janela e acompanha os resultados até os seus registros de entitlement.
Perguntas frequentes
É uma App Store Server Notification que informa ao seu servidor que um cliente pediu 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, usando sua resposta como um entre vários fatores.
Porque a Apple não consegue ver o que acontece 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, e a Apple pede por ele antes de concluir a análise.
Um cliente pede reembolso, a Apple começa a análise e uma notificação chega ao endpoint que você configurou. Você a verifica, identifica a transação, confirma o consentimento, reúne os dados de uso e envia as informações de consumo dentro da janela. A Apple pondera tudo, decide e envia o resultado como uma notificação separada.
No endpoint atual, cinco campos. Três obrigatórios: consentimento do cliente, status de entrega e se foi oferecido conteúdo de amostra. Dois opcionais: quanto da compra foi consumido e sua preferência quanto ao reembolso. O endpoint V1 anterior pedia doze, e é por isso que artigos mais antigos descrevem uma lista bem mais longa.
A documentação atual da Apple descreve a notificação em relação a pedidos de reembolso de todos os tipos de produto, um escopo mais amplo do que a documentação antiga sugeria. Mas a Apple não publica nenhuma garantia para todos os casos, então construa um handler que responda quando uma requisição chegar, em vez de uma lógica que dependa de ela sempre chegar.
A documentação da Apple pede uma resposta em até 12 horas após a notificação. As requisições chegam a qualquer hora, inclusive nos fins de semana, então essa é a etapa que um processo manual tem mais chance de perder. Confira a página da Apple para o requisito atual em vez de confiar em uma integração antiga.
Você pode informar a decisão, não controlá-la. Dados de consumo precisos dão à Apple um contexto que ela não teria de outra forma, e o endpoint atual permite indicar uma preferência de reembolso. A Apple pondera os dois junto com outros fatores e pode decidir de forma diferente. Não existe mecanismo para um desenvolvedor aprovar ou negar um reembolso.
Sim. Verificar notificações, identificar transações, checar o estado do consentimento, montar os dados a partir dos registros, cumprir a janela, enviar e registrar os resultados são etapas determinísticas. O que continua sendo humano é projetar o fluxo de consentimento no seu app e definir qual deve ser sua política de preferência de reembolso.
