KappS Base de conhecimento · Blog

A App Store Connect API em 2026: um guia passo a passo sobre chaves, tokens JWT e limites

Blog Guia

A API App Store Connect é a camada REST por trás da interface web do App Store Connect: o próprio resumo do Apple diz que ela "permite automatizar as ações que você realiza no App Store Connect" e alerta explicitamente que o que você altera por meio dela são dados de produção. É por causa dessa única frase que este guia existe — uma chave válida e um token válido bastam para convidar usuários, alterar IDs do bundle, enviar builds, editar metadados do App Store e baixar relatórios de vendas, tudo sem navegador. Este guia de 2026 cobre a solicitação de acesso que só o titular da conta pode enviar, chaves de equipe versus individuais, o JWT ES256 que autoriza cada chamada, o limite de requisições por hora corrida e o HTTP 429, a leitura de erros, a paginação, o upload de ativos e a revogação de chaves.

A versão em uma linha: o Titular da Conta solicita acesso à API uma vez; um Admin gera uma chave de equipe com escopo de função (ou cada usuário gera uma chave individual); seu código assina um JWT ES256 de curta duração cujo kid é o ID da chave e cujo aud é appstoreconnect-v1; toda resposta traz um cabeçalho X-Rate-Limit, e ultrapassar o limite por hora retorna 429 RATE_LIMIT_EXCEEDED.

Etapa 1 — saiba o que a API realmente alcança

Antes de solicitar qualquer coisa, mapeie a superfície que você pretende automatizar, porque o papel da chave determina o que é acessível. Apple documenta recursos para compras dentro do app e assinaturas com renovação automática, TestFlight builds beta, testadores e grupos, Xcode dados e fluxos de trabalho do Cloud, Usuários e Acesso, Provisionamento (IDs do bundle, recursos, certificados, dispositivos, perfis), dados e submissões do App Meta, experiências de App Clip, Relatórios (relatórios de vendas e financeiros), Métricas de energia e desempenho, e avaliações de clientes com suas respostas. Dois fatos estruturais importam: os recursos retornam JSON consistente com links de relacionamento para navegar entre eles, e se sua conta estiver no Apple Developer Enterprise Program, Apple direciona você para a API do Enterprise Program em vez desta. Não construa contra a API errada e descubra isso durante um lançamento.

Etapa 2 — A solicitação de acesso que só o titular da conta pode fazer

O acesso à API não é ativado por padrão e não é um botão por chave. O Titular da conta faz login, abre Usuários e acesso > Integrações (a página abre com a API App Store Connect selecionada), clica em Solicitar acesso, aceita os termos e envia. O Apple então analisa a solicitação e a aprova "caso a caso" — o que significa que a sequência correta é protocolar isso antes de prometer a alguém uma data de automação, não no dia do lançamento. Uma vez aprovado, a mesma página contém o ID do emissor e a lista de chaves.

Etapa 3 — Escolha chaves de equipe ou chaves individuais, corretamente

O Apple define dois tipos de chave e eles não são intercambiáveis:

  • Chaves de equipe — geradas pelo titular da conta ou por um administrador, aplicadas a todos os apps da conta, e o acesso é definido pelo papel que você escolhe. Você não pode limitar uma chave de equipe a apps específicos: "as chaves de API de equipe são aplicadas a todos os apps, então o acesso por app não pode ser limitado para uma chave de API".
  • Chaves individuais — geradas por um usuário no próprio perfil, carregando os apps e o papel desse usuário. Os papéis que podem criar uma são Account Holder, Admin, App Manager, Customer Support, Developer e Marketing, e cada usuário pode ter apenas uma chave ativa por vez. A documentação do Apple acrescenta dois limites rígidos que vale considerar no projeto: chaves individuais não podem usar os endpoints de provisionamento nem o notaryTool.

Duas regras operacionais decorrem disso. O nome e o nível de acesso de uma chave não podem ser editados após a geração — para alterar qualquer um dos dois, revogue a chave e gere uma nova. E a metade privada pode ser baixada exatamente uma vez: se o seu pipeline perdê-la, a solução é uma nova chave, não um novo download. Mantenha um cofre de segredos no servidor e trate o arquivo .p8 exatamente como uma senha de banco de dados.

Etapa 4 — Construa o token ES256 que o Apple realmente aceita

Toda requisição precisa de um JWT assinado com a chave privada que você baixou. A documentação de tokens do Apple fixa os campos do cabeçalho: alg deve ser ES256, kid é o ID da sua chave privada (por exemplo, 2X9R4HXF34) e typ é JWT. Para uma chave de equipe, o payload carrega iss (o ID do emissor, por exemplo, 57246542-96fe-1a63-e053-0824d011072a), iat e exp em tempo epoch UNIX, e aud definido como appstoreconnect-v1. A regra de expiração é a que pega em produção: tokens que expiram mais de 20 minutos no futuro não são válidos, exceto para os recursos que o Apple lista como isentos. Gere tokens curtos, reutilize-os dentro da janela e nunca guarde um em cache além dela. Se você tem várias chaves de equipe, o kid deve pertencer à mesma chave privada que assina o token — um par incompatível falha na autenticação, não na autorização.

Chaves individuais usam um payload um pouco diferente: sem iss e, em vez disso, uma claim sub cujo valor é user. Se você escrever um único construtor de token para os dois tipos de chave, deixe essa diferença explícita no código em vez de inferi-la em tempo de execução.

Etapa 5 — Restrinja o escopo do token em vez de torcer para que não vaze

O Apple oferece suporte a uma claim opcional de escopo: uma lista das requisições que esse token tem permissão de fazer, em que cada entrada é um método HTTP mais o caminho da URL mais uma query string opcional — por exemplo GET /v1/apps/123 ou GET /v1/apps?filter[platform]=IOS. Um token apresentado com um escopo que não cobre a requisição é rejeitado. O raciocínio que o Apple apresenta vale ser repetido para quem argumenta que escopo é sobrecarga: se você compartilhar um token sem querer com uma parte não autorizada, um escopo limitado reduz o que essa parte pode fazer com ele. Automações que só leem relatórios de vendas devem ter um escopo somente leitura, não toda a autoridade do papel da chave.

Etapa 6 — Respeite a janela móvel de uma hora e trate o 429 como estado, não como erro

Os limites de taxa nesta API são por chave e não estão documentados como um número fixo único. Toda resposta traz um cabeçalho X-Rate-Limit contendo user-hour-lim (requisições permitidas por hora para aquela chave) e user-hour-rem (requisições restantes); o próprio exemplo do Apple mostra um limite de 3500 requisições por hora com 500 restantes e afirma que os limites reais podem variar. A janela é uma hora móvel: a qualquer momento, o número restante é o seu limite menos tudo o que você enviou nos 60 minutos anteriores. Se ultrapassar, a API responde HTTP 429 com o código de erro RATE_LIMIT_EXCEEDED. Duas consequências para o design: leia user-hour-rem e limite o ritmo de forma preventiva quando ele estiver baixo, e trate um 429 como "registre e coloque o job na fila para depois" em vez de erro fatal — uma exportação noturna que falha ruidosamente em um 429 vai falhar toda noite em que se aproximar do teto.

Etapa 7 — Leia as falhas pelo código de status e depois pelo objeto de erro

Segundo as orientações de erro do Apple, um código de status na faixa 200 significa sucesso e o corpo contém os dados; um código na faixa 400 ou 500 significa que a requisição falhou e o corpo contém os detalhes. O objeto de erro também traz um code para tratamento programático e, em muitos casos, um objeto source que aponta exatamente o que estava errado na sua requisição — um ponteiro JSON para o payload ou o parâmetro de consulta que gerou o erro. Leia o source antes de reescrever a requisição; a diferença entre "meu JSON está malformado neste caminho" e "meu perfil não pode fazer isso" é a diferença entre uma correção de cinco minutos e um ticket de suporte.

Etapa 8 — Pagine grandes conjuntos de resultados em vez de adivinhar um limite maior

As respostas para coleções incluem informações de paginação e links relacionados — um objeto de paginação mais os links de resposta que levam você adiante. Escreva o loop que segue esses links até o cursor se esgotar; não presuma que uma única chamada retorna todas as compilações, testadores ou App Store versão, e não fixe no código um tamanho de página que você acha "grande o suficiente". Um relatório que trunca em silêncio é pior do que um lento.

Etapa 9 — Envie os ativos na ordem que o Apple exige

Ativos binários — capturas de tela, prévias de app, anexos para a revisão do app, arquivos de cobertura de rotas de app — seguem um fluxo de quatro etapas: faça uma reserva do ativo (tipo de ativo, nome do arquivo, tamanho em bytes), envie os bytes usando as operações retornadas nessa resposta, confirme o upload e então verifique se o App Store Connect processou o ativo. Uma reserva bem-sucedida retorna um ID de reserva, um conjunto de operações de upload, os atributos do arquivo e um estado de entrega AWAITING_UPLOAD. Arquivos grandes voltam como várias operações que informam o deslocamento e o comprimento de cada parte — a API os divide de propósito para que uma conexão instável não custe o arquivo inteiro. Observe também que os recursos de captura de tela do app, prévia de app e captura de tela de evento dentro do app estão descontinuados: gerencie capturas de tela, prévias e mídia de eventos dentro do app pela App Asset Library e pelos posicionamentos. E não deixe uma reserva pela metade; o Apple determina que você tem tempo limitado para concluir o upload após a reserva.

Etapa 10 — Rotacione e revogue como se a chave fosse uma credencial

O Titular da conta ou um Admin pode revogar as chaves de equipe e as chaves individuais de qualquer membro da equipe; os usuários podem revogar as próprias. A revogação é imediata e permanente — uma chave revogada não pode ser reativada —, o que faz da revogação a ação de emergência correta, e não o último recurso. As chaves revogadas permanecem visíveis na página Chaves de API, sob o título Revogadas, por 30 dias, o que é tempo suficiente para responder "qual chave era aquela?" depois de um incidente, mas não o bastante para servir como sua trilha de auditoria, então registre os IDs das chaves junto com as execuções da sua automação. Por fim, se uma pessoa nunca deve obter acesso à API, um Admin pode remover dela a permissão Gerar chaves de API individuais em Pessoas — o controle existe, então use-o em vez de confiar na política.

O checklist

  • O titular da conta enviou a solicitação de acesso e ela foi aprovada.
  • Tipo de chave escolhido de forma deliberada: chave de equipe para automação de toda a conta, chave individual para o escopo de um usuário.
  • Chave privada armazenada uma única vez, em um gerenciador de segredos, com um responsável documentado.
  • Construtor de token: ES256, kid correspondente à chave de assinatura, aud=appstoreconnect-v1, exp dentro de 20 minutos, scope o mais restrito que a tarefa permitir.
  • O cliente lê X-Rate-Limit, recua antes do limite e enfileira no 429.
  • As chamadas de coleta seguem os links de paginação; nada pressupõe uma primeira página completa.
  • Reserva de upload de ativos, partes, commit e estado de verificação verificados.
  • Chaves revogadas registradas com o motivo e a data; visibilidade de 30 dias não tratada como log de auditoria.

O Apple mantém um changelog de notas da versão para a API. O Apple adiciona campos e recursos com o tempo, então releia-o antes de considerar sua integração concluída.

Fontes

Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar