La App Store Connect API en 2026: guía paso a paso sobre claves, tokens JWT y límites de
La API de App Store Connect es la capa REST que hay detrás de la interfaz web de App Store Connect: el propio resumen de Apple dice que "permite automatizar las acciones que realizas en App Store Connect", y advierte explícitamente de que lo que cambies a través de ella son datos de producción. Esa sola frase es la razón de ser de esta guía: una clave válida y un token válido bastan para invitar usuarios, cambiar ID de paquete, subir compilaciones, editar los metadatos de App Store y descargar informes de ventas, todo sin un navegador. Esta guía de 2026 cubre únicamente la solicitud de acceso que puede presentar el titular de la cuenta, las claves de equipo frente a las individuales, el JWT ES256 que autoriza cada llamada, el límite de peticiones por hora móvil y el HTTP 429, la lectura de errores, la paginación, las subidas de recursos y la revocación de claves.
La versión en una línea: el titular de la cuenta solicita acceso a la API una vez; un administrador genera una clave de equipo con rol limitado (o cada usuario genera una clave individual); tu código firma un JWT ES256 de corta duración cuyo kid es el ID de la clave y cuyo aud es appstoreconnect-v1; cada respuesta incluye una cabecera X-Rate-Limit, y superar el límite por hora devuelve 429 RATE_LIMIT_EXCEEDED.
Paso 1 — Conoce a qué llega realmente la API
Antes de solicitar nada, define el alcance que pretendes automatizar, porque el rol de la clave determina a qué puedes acceder. Apple documenta recursos para compras dentro de la app y suscripciones de renovación automática, compilaciones beta de TestFlight, testers y grupos, datos y flujos de trabajo de Xcode Cloud, Users and Access, Provisioning (ID de paquete, capacidades, certificados, dispositivos, perfiles), datos y envíos de la app en Meta, experiencias de App Clip, informes (de ventas y financieros), métricas de rendimiento y consumo, y reseñas de clientes con sus respuestas. Hay dos hechos estructurales que importan: los recursos devuelven JSON coherente con enlaces de relación para navegar entre ellos y, si tu cuenta pertenece al Apple Developer Enterprise Program, Apple te remite a la API del Enterprise Program en lugar de a esta. No desarrolles contra la API equivocada y lo descubras durante un lanzamiento.
Paso 2 — La solicitud de acceso que solo puede hacer el titular de la cuenta
El acceso a la API no se activa de forma predeterminada y no es un interruptor por clave. El Titular de la cuenta inicia sesión, abre Usuarios y acceso > Integraciones (la página se abre con la API de App Store Connect seleccionada), hace clic en Solicitar acceso, acepta los términos y envía la solicitud. Después, Apple revisa la solicitud y la aprueba «caso por caso», lo que significa que la secuencia correcta es presentarla antes de prometer a nadie una fecha de automatización, no el día del lanzamiento. Una vez aprobada, esa misma página contiene el ID del emisor y la lista de claves.
Paso 3: Elige claves de equipo o claves individuales, correctamente
Apple define dos tipos de clave y no son intercambiables:
- Claves de equipo: las genera el titular de la cuenta o un administrador, se aplican a todas las apps de la cuenta y su acceso se define según el rol que elijas. No puedes limitar una clave de equipo a apps concretas: "las claves de API de equipo se aplican a todas las apps, por lo que el acceso por app no se puede limitar para una clave de API".
- Individual keys: las genera un usuario en su perfil y llevan las apps y el rol de ese usuario. Los roles que pueden crear una son Account Holder, Admin, App Manager, Customer Support, Developer y Marketing, y cada usuario solo puede tener una clave activa a la vez. La documentación de Apple añade dos límites estrictos que conviene tener en cuenta al diseñar: las claves individuales no pueden usar los endpoints de aprovisionamiento ni
notaryTool.
De ello se derivan dos reglas operativas. El nombre y el nivel de acceso de una clave no se pueden editar después de generarla: para cambiar cualquiera de los dos, revoca la clave y genera una nueva. Y la mitad privada se puede descargar una sola vez: si tu pipeline la pierde, la solución es una clave nueva, no volver a descargarla. Mantén un almacén de secretos en el servidor y trata el archivo .p8 exactamente como una contraseña de base de datos.
Paso 4 — Genera el token ES256 que Apple realmente acepta
Cada solicitud necesita un JWT firmado con la clave privada que descargaste. La documentación de tokens de Apple fija los campos de la cabecera: alg debe ser ES256, kid es el ID de tu clave privada (por ejemplo, 2X9R4HXF34) y typ es JWT. En una clave de equipo, el payload lleva iss (el ID del emisor, por ejemplo, 57246542-96fe-1a63-e053-0824d011072a), iat y exp en hora epoch de UNIX, y aud definido como appstoreconnect-v1. La regla de caducidad es la que duele en producción: los tokens que caducan con más de 20 minutos de antelación no son válidos, salvo para los recursos que Apple indica como exentos. Genera tokens cortos, reutilízalos dentro de la ventana y nunca guardes uno en caché más allá de ella. Si tienes varias claves de equipo, el kid debe pertenecer a la misma clave privada que firma el token: una pareja que no coincide falla en la autenticación, no en la autorización.
Las claves personales usan una carga útil ligeramente distinta: sin iss y, en su lugar, una declaración sub cuyo valor es user. Si escribes un único generador de tokens para ambos tipos de clave, haz explícita esa diferencia en el código en lugar de inferirla en tiempo de ejecución.
Paso 5 — Limita el alcance del token en lugar de confiar en que no se filtre
Apple admite una reclamación opcional de ámbito: una lista de las solicitudes que este token puede realizar, donde cada entrada es un método HTTP más una ruta de URL más una cadena de consulta opcional; por ejemplo, GET /v1/apps/123 o GET /v1/apps?filter[platform]=IOS. Un token presentado con un ámbito que no cubre la solicitud se rechaza. El razonamiento que da Apple merece citarse a quien argumente que el ámbito es una sobrecarga: si compartes un token sin querer con una parte no autorizada, un ámbito limitado reduce lo que esa parte puede hacer con él. La automatización que solo lee informes de ventas debería llevar un ámbito de solo lectura, no la autoridad plena del rol de la clave.
Paso 6: respeta la hora móvil y trata el 429 como un estado, no como un error
Los límites de tasa de esta API son por clave y no están documentados como un único número fijo. Cada respuesta incluye un encabezado X-Rate-Limit con user-hour-lim (solicitudes permitidas por hora para esa clave) y user-hour-rem (solicitudes restantes); el propio ejemplo de Apple muestra un límite de 3500 solicitudes por hora con 500 restantes, y señala que los límites reales pueden variar. La ventana es una hora móvil: en cualquier momento, la cifra restante es tu límite menos todo lo que enviaste en los 60 minutos anteriores. Si lo superas, la API responde HTTP 429 con el código de error RATE_LIMIT_EXCEEDED. Dos consecuencias para el diseño: lee user-hour-rem y limita el ritmo de forma preventiva cuando sea bajo, y trata un 429 como «regístralo y pon el trabajo en cola para más tarde» en lugar de como un error fatal: una exportación nocturna que falla de forma ruidosa ante un 429 fallará todas las noches en que se acerque al techo.
Paso 7 — Lee los fallos desde el código de estado y, después, desde el objeto de error
Según la guía de errores de Apple, un código de estado del rango 200 significa éxito y el cuerpo contiene los datos; un código del rango 400 o 500 significa que la solicitud falló y el cuerpo contiene los detalles. El objeto de error también incluye un code para el tratamiento programático y, en muchos casos, un objeto source que señala exactamente qué estaba mal en tu solicitud: un puntero JSON dentro del payload o el parámetro de consulta que produjo el error. Lee el source antes de reescribir la solicitud; la diferencia entre "mi JSON está mal formado en esta ruta" y "mi rol no puede hacer esto" es la diferencia entre un arreglo de cinco minutos y un ticket de soporte.
Paso 8 — Pagina los conjuntos de resultados grandes en lugar de probar con un límite mayor
Las respuestas de las colecciones incluyen información de paginación y enlaces relacionados: un objeto de paginación más los enlaces de respuesta que te llevan hacia delante. Escribe el bucle que sigue esos enlaces hasta agotar el cursor; no des por hecho que una sola llamada devuelve todas las compilaciones, testers o versiones de App Store, y no fijes en el código un tamaño de página que creas «suficientemente grande». Un informe que se trunca en silencio es peor que uno lento.
Paso 9 — Sube los recursos en el orden que exige Apple
Recursos binarios: capturas de pantalla, vistas previas de la app, archivos adjuntos para la revisión de la app y archivos de cobertura de rutas de la app siguen un flujo de cuatro pasos: haz una reserva del recurso (tipo de recurso, nombre de archivo, tamaño en bytes), sube los bytes con las operaciones devueltas en esa respuesta, confirma la subida y luego verifica que App Store Connect haya procesado el recurso. Una reserva correcta devuelve un ID de reserva, un conjunto de operaciones de subida, los atributos del archivo y un estado de entrega AWAITING_UPLOAD. Los archivos grandes se devuelven como varias operaciones que indican el desplazamiento y la longitud de cada parte: la API los divide a propósito para que una conexión inestable no te cueste el archivo completo. Ten en cuenta también que los recursos de captura de pantalla de la app, vista previa de la app y captura de pantalla de eventos dentro de la app están obsoletos: gestiona las capturas de pantalla, las vistas previas y los contenidos multimedia de eventos dentro de la app a través de App Asset Library y de las ubicaciones. Y no dejes una reserva a medias; Apple indica que tienes tiempo limitado para completar la subida después de reservar.
Paso 10 — Rotar y revocar como si la clave fuera una credencial
El titular de la cuenta o un administrador pueden revocar las claves del equipo y las claves individuales de cualquier miembro del equipo; los usuarios pueden revocar las suyas propias. La revocación es inmediata y permanente: una clave revocada no puede restablecerse, lo que convierte la revocación en la acción de emergencia correcta, no en el último recurso. Las claves revocadas siguen visibles en la página de claves de API bajo un encabezado de Revocadas durante 30 días, tiempo suficiente para responder «¿qué clave era esa?» tras un incidente, pero no tanto como para servir de registro de auditoría, así que registra los ID de las claves junto con tus ejecuciones de automatización. Por último, si una persona no debería obtener acceso a la API en absoluto, un administrador puede quitarle el permiso Generar claves de API individuales en Personas: el control existe, así que úsalo en lugar de confiar en la política.
La lista de verificación
- El titular de la cuenta ha presentado la solicitud de acceso y está aprobada.
- Tipo de clave elegido a propósito: clave de equipo para la automatización de toda la cuenta, clave individual para el ámbito de un solo usuario.
- Clave privada almacenada una sola vez, en un gestor de secretos, con un responsable documentado.
- Generador de tokens:
ES256,kidque coincida con la clave de firma,aud=appstoreconnect-v1,expdentro de 20 minutos,scopetan limitado como permita la tarea. - El cliente lee
X-Rate-Limit, reduce el ritmo antes del límite y encola en 429. - Las llamadas de recopilación siguen los enlaces de paginación; nada asume una primera página completa.
- Reserva de subidas de recursos, partes, confirmación y estado de verificación comprobados.
- Claves revocadas registradas con el motivo y la fecha; la visibilidad de 30 días no se trata como un registro de auditoría.
Apple mantiene un registro de cambios de notas de la versión para la API. Apple añade campos y recursos con el tiempo, así que vuelve a leerlo antes de dar tu integración por terminada.
Fuentes
- Apple Developer — Descripción general de la API de App Store Connect: developer.apple.com/documentation/appstoreconnectapi
- Apple Developer — API de App Store Connect (ayuda, solicitud de acceso y claves): developer.apple.com/help/app-store-connect/get-started/app-store-connect-api
- Apple Developer — Crear claves de API: creating-api-keys-for-app-store-connect-api
- Desarrollador de Apple — Generar tokens para solicitudes a la API: generating-tokens-for-api-requests
- Apple Developer — Identificar los límites de frecuencia: identifying-rate-limits
- Apple Developer — Interpretación y gestión de errores: interpreting-and-handling-errors
- Apple Desarrollador — Grandes conjuntos de datos (paginación): large-data-sets
- Apple Developer — Subir recursos: uploading-assets-to-app-store-connect
- Apple Developer — Revocar claves de API: revoking-api-keys
- Apple Developer — notas de la versión de la API de App Store Connect: app-store-connect-api-release-notes
¿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