App Store Server Notifications V2 en 2026
Apple ha cerrado la vía de la versión 1: las notificaciones de la versión 1 de y el endpoint de recibos de App Store están obsoletos, y ahora la instrucción dice "implementa el endpoint de la versión 2 en tu servidor". Para una app con suscripciones activas, esto no es una migración cosmética: el flujo de notificaciones es cómo tu servidor se entera de que una renovación se ha completado, de que se ha emitido un reembolso, de que se está reintentando el cobro o de que Apple te pide que justifiques una solicitud de reembolso. Este tutorial recorre la configuración completa para 2026: habilitar la versión 2 en App Store Connect, verificar el JWS, mapear cada tipo y subtipo de notificación y usar la API de servidor de App Store para el estado que una notificación solo describe en un momento dado.
La versión en una línea: App Store Connect envía un bloque JSON firmado con JWS a tu URL HTTPS; verifica la cadena de firmas, decodifica signedPayload, actúa según notificationType y subtype, responde 200-206 con rapidez y llama a la Server API de App Store siempre que necesites el estado actual en lugar del estado del evento.
Paso 1 — Corrige los dos endpoints antes de tocar 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.
Paso 2 — Activa la versión 2 por entorno
En App Store Connect, abre tu app y ve a Información de la app > App Store Notificaciones del servidor. Producción y sandbox se configuran por separado, y cada entorno elige de forma independiente la versión 2 o la versión 1 obsoleta, lo que te permite usar el nuevo formato en producción mientras el antiguo todavía tiene que funcionar en otro lado, o al revés. La ruta de migración indicada por Apple consiste en probar primero la versión 2 en el entorno sandbox y solo después pasar producción. Un comportamiento que conviene conocer antes de empezar a depurar: la notificación TEST siempre se envía en formato de versión 2, sin importar qué versión espere la URL que hayas configurado.
Paso 3 — Responde con el código de estado correcto y luego trabaja de forma asíncrona
Responde con un código de estado HTTP 200-206 si la solicitud POST se procesó correctamente. Si no se procesó, envía un 50x o un 40x para que App Store reintente la notificación. El patrón práctico es: leer el cuerpo, verificarlo, encolarlo, responder 200 y hacer el trabajo real en un worker. No mantengas la conexión abierta mientras llamas a tu propia base de datos, a tu proveedor de correo o a la App Store Server API. Los reintentos están para protegerte de fallos de infraestructura, no de un handler lento, y cada reintento que provocas es un evento duplicado que luego tienes que suprimir.
Paso 4 — Decodifica el payload
El cuerpo es un objeto responseBodyV2 cuyo único campo relevante es signedPayload, un JWS. Analízalo en sus representaciones de encabezado, carga útil y firma, y luego decodifica la carga útil en Base64URL para obtener el responseBodyV2DecodedPayload. En ese nivel obtienes notificationType, subtype, version, signedDate y notificationUUID. Está presente exactamente uno de cuatro objetos de datos: data para eventos de compra dentro de la app, que incluye un signedTransactionInfo y —para suscripciones de renovación automática— un signedRenewalInfo; summary, que aparece solo para un RENEWAL_EXTENSION con el subtipo SUMMARY; appData; o externalPurchaseToken, que aparece solo en una notificación EXTERNAL_PURCHASE_TOKEN.
Paso 5: Verifica cada firma, no solo la externa
Las tres representaciones firmadas —signedPayload, signedTransactionInfo y signedRenewalInfo— llevan su propia firma JWS, y cada una debe validarse; usa el algoritmo indicado en el parámetro alg de la cabecera. En la práctica, esto significa comprobar la cadena de certificados x5c hasta la raíz publicada por Apple, que descargas desde la página de la autoridad de certificación de Apple (la raíz actual para este servicio es AppleRootCA-G3.cer). No lo implementes por tu cuenta: Apple publica la App Store Server Library para Python, Java, Node.js y Swift, que realiza la verificación y la decodificación por ti. Un controlador que decodifica la carga útil en Base64 y omite la verificación se puede falsificar con suma facilidad: cualquiera que conozca tu URL de notificaciones puede concederse una suscripción.
Paso 6: asigna notificationType y subtype a tus derechos de acceso
La enumeración de la versión 2 define 23 tipos de notificación y 19 subtipos que matizan algunos de ellos; ambas listas se publican en notificationType y subtype. Los que deciden si un cliente de pago conserva el acceso:
SUBSCRIBED— con los subtiposINITIAL_BUY,RESUBSCRIBE,UPGRADEyDOWNGRADE. Concede acceso y registra el identificador del producto, no solo "suscrito".DID_RENEW, con los subtiposBILLING_RECOVERYyBILLING_RETRY. Una renovación que llegó tras un problema de pago también llega aquí, así que trátala como una extensión normal del acceso.DID_FAIL_TO_RENEW— con el subtipoGRACE_PERIODcuando el cliente está dentro de un periodo de gracia. El acceso suele continuar aquí, que es precisamente el sentido de los periodos de gracia.GRACE_PERIOD_EXPIRED: el periodo de gracia terminó. Este es el momento de bajar de categoría, no cuando falla el cobro.EXPIRED— con los subtiposVOLUNTARY,BILLING_RETRYyPRODUCT_NOT_FOR_SALE. El último importa si retiras un producto de la venta mientras la gente aún lo tiene.DID_CHANGE_RENEWAL_STATUS(AUTO_RENEW_ENABLED/AUTO_RENEW_DISABLED) yDID_CHANGE_RENEWAL_PREF(UPGRADE/DOWNGRADE) — un cliente que desactivó la renovación automática sigue teniendo derecho hasta que termine el periodo, así que nunca revoques el acceso conAUTO_RENEW_DISABLED.REFUND,REFUND_DECLINED,REFUND_REVERSED,REVOKEyRESCIND_CONSENT: el lado de la revocación. Un reembolso revertido significa que el dinero volvió a ti, así que el derecho de acceso también tiene que volver al cliente.CONSUMPTION_REQUEST— Apple solicita pruebas sobre cómo se usó la compra; consulta el paso 7.OFFER_REDEEMED,PRICE_CHANGE,PRICE_INCREASE(ACCEPTED/PENDING),RENEWAL_EXTENDEDyRENEWAL_EXTENSION(SUMMARY/FAILURE): cambios comerciales y de fechas que normalmente requieren avisar al cliente más que modificar su acceso.METADATA_UPDATE,MIGRATION,ONE_TIME_CHARGE,TESTyEXTERNAL_PURCHASE_TOKEN(con el subtipoUNREPORTEDcuando Apple generó un token del que no tiene informe).
El catálogo completo con las incorporaciones actuales está en el registro de cambios de notificaciones — Apple añade campos y valores con el tiempo, así que vuelve a leerlo antes de dar por completo tu controlador.
Paso 7 — Responde a una CONSUMPTION_REQUEST en un plazo de 12 horas
Cuando un cliente solicita un reembolso por cualquier tipo de producto —consumible, no consumible, no renovable o de renovación automática—, Apple envía un CONSUMPTION_REQUEST. Si el cliente dio su consentimiento, puedes responder llamando a Send Consumption Information con los datos de uso que pide Apple, y Apple documenta una ventana de respuesta de 12 horas desde el momento en que llega la notificación. Si el cliente no dio su consentimiento, no respondes en absoluto. Hay dos reglas fáciles de equivocar: el consentimiento que necesitas para esta API es distinto del que recopilaste para el seguimiento o la publicidad, y tú eres la parte responsable de obtener un consentimiento válido antes de compartir datos de uso con Apple.
Paso 8 — Usa la API de servidor de App Store para el estado, no para el evento
Una notificación describe un momento. Antes de redactar los derechos, resuelve el presente:
- Obtener información de la transacción de una sola transacción, incluido su motivo y fecha de revocación.
- Get All Subscription Statuses para obtener la vista autorizada de las suscripciones de un cliente.
- Obtén el historial de reembolsos cuando necesites los reembolsos de un identificador de transacción original.
- Ampliar la fecha de renovación de una suscripción para compensar una interrupción del servicio. Dos características hacen que esto sea una decisión irreversible: una vez que la ampliación surte efecto no hay forma de revertirla, y las suscripciones de los miembros de la familia se amplían automáticamente, mientras que no se admiten solicitudes directas para la suscripción de un miembro de la familia. Además, el periodo de ampliación no cuenta para el año de servicio de pago que Apple utiliza al calcular la tasa de comisión.
Paso 9 — Demuestra que el flujo funciona antes de depender de él
Llama a Request a Test Notification y App Store enviará una notificación TEST a tu endpoint. Esa llamada devuelve un token que pasas a Get Test Notification Status dentro de seis meses para ver cómo respondió realmente tu servidor. Por otro lado, si tu endpoint estaba caído a las 3 de la mañana, Get Notification History devuelve las notificaciones de la versión 2 que App Store intentó enviar: 180 días en producción, 30 días en el entorno de pruebas, 20 registros por página con un token de continuación y el contenido completo de las notificaciones. Recuerda qué es ese historial: cada registro refleja el estado en el momento en que se envió originalmente la notificación, no el estado actual.
Paso 10 — Las reglas operativas que mantienen correcto el flujo de trabajo
- Lee el
entornoantes de escribir nada. El tráfico del sandbox llega a las URL de sandbox; si un controlador compartido escribe derechos de producción a partir de un evento de sandbox, las pruebas se convierten en un incidente de datos. - Elimina duplicados por
notificationUUID. Los reintentos y tu propio reprocesamiento generan el mismo evento más de una vez; guarda el identificador y descarta las repeticiones. - Nunca tomes una notificación como un recibo. Una compilación que solo escucha
SUBSCRIBEDyDID_RENEW, e ignoraREFUND,REVOKEyREFUND_REVERSED, filtra el acceso de pago de forma permanente. Gestiona todo el ciclo de vida o delega la verificación en la librería de Apple y consulta la Server API. - Lleva tu propio registro de eventos. Cuando un cliente impugne un acceso, el historial de notificaciones y tu propio registro son lo que te permite reconstruir la decisión.
- Ten en cuenta que el endpoint forma parte de producción. Necesita monitorización, un tiempo de espera de solicitud muy inferior al presupuesto de conexión y una cola, no una cadena de llamadas síncronas hacia tu sistema de facturación.
Fuentes
- Apple Developer — Notificaciones del servidor de App Store: developer.apple.com/documentation/appstoreservernotifications
- Desarrollador de Apple — App Store Server Notifications V2: app-store-server-notifications-v2
- Desarrollador de Apple — Habilitar las notificaciones de servidor de App Store: enabling-app-store-server-notifications
- Apple Developer: enumeraciones notificationType y subtype: notificationtype / subtype
- Apple Desarrollador — responseBodyV2DecodedPayload: responsebodyv2decodedpayload
- Apple Developer — App Store API del servidor: developer.apple.com/documentation/appstoreserverapi
- Apple — Biblioteca de servidor App Store (Python): github.com/apple/app-store-server-library-python
- Apple — autoridad de certificación: www.apple.com/certificateauthority
¿Gestionas cuentas de desarrollador a escala? Nosotros nos encargamos de la parte operativa.
Hemos recibido tu mensaje y responderemos en un plazo de 24 horas.
← Volver a editar