# Apple App Store

Credenciais, API Key e webhooks pra conectar seu app iOS ao Paywallo.

## O que você vai precisar

Pra conectar a App Store ao Paywallo, você vai precisar de:

-   Bundle ID (identificador do app)
-   Key ID (ID da chave de API)
-   Issuer ID (identificador do emissor)
-   Chave privada (.p8)

Abaixo está o guia de onde buscar cada um. Tudo fica no [App Store Connect](https://appstoreconnect.apple.com). Depois de juntar tudo, vá em **Configurações** > **Apps** (grupo Workspace) no Paywallo, selecione o app e abra a plataforma iOS. É lá que ficam os campos de Bundle ID e a seção App Store Connect com Issuer ID, Key ID e o upload do .p8. Depois de preencher, clique em **Salvar alterações** no topo da página.

## Bundle ID

No App Store Connect, abra o app e vá em `Distribuição` > `Informações do app`. Na seção "Informações gerais", o `ID do pacote` é o Bundle ID.

Copie esse valor e cole no campo **Bundle ID**, no topo da tela iOS do app dentro do Paywallo (Configurações > Apps > seu app > iOS).

![Bundle ID no App Store Connect](/docs/apple-bundle-id.png)

## Key ID, Issuer ID e chave .p8

No App Store Connect, vá em `Usuários e acesso` > `Integrações` > `API do App Store Connect`. Só quem tem papel de **Account Holder** ou **Admin** na equipe do App Store Connect vê essa opção de menu.

1. Clique em Gerar chave de API (ou "Generate API Key")

2. Escolha o papel Administrador ou Gerente de apps

3. O Key ID aparece na coluna "ID DA CHAVE" e o Issuer ID fica no topo da página

4. Clique em "Download" ao lado da chave pra baixar o arquivo .p8. A Apple só permite baixar uma vez: se perder o arquivo, precisa revogar essa chave e gerar outra.

5. No Paywallo, na seção App Store Connect da tela iOS do app, cole o Issuer ID e o Key ID nos campos de mesmo nome e envie o arquivo .p8 no campo Apple Private Key (.p8). Clique em "Salvar alterações" e depois em "Testar conexão" para confirmar que o Paywallo conseguiu acessar a App Store Connect API com essas credenciais.

![Key ID e Issuer ID no App Store Connect](/docs/apple-api-keys.png)

## Webhooks (Server Notifications V2)

Pra receber renovação, cancelamento e reembolso em tempo real, configure os webhooks:

1. No Paywallo, em Configurações > Apps > seu app > iOS, role até Webhook de assinaturas (App Store Server Notifications V2) e copie a URL pelo ícone ao lado do campo

2. No App Store Connect, abra o app, vá em Informações do app, desça até Notificações do servidor da App Store

3. Cole a URL nos campos URL do servidor de produção e URL do servidor do sandbox (mesma URL nos dois).

4. Em Versão da notificação, selecione Version 2. O Paywallo processa apenas notificações V2 (campo signedPayload) — se ficar em V1/legado, os eventos de renovação, cancelamento e reembolso são descartados em silêncio e a tabela de assinaturas não popula.

**Atenção:** o botão "Testar conexão" no App Store Connect valida apenas a conectividade de rede com a URL, não a entrega das notificações. A Apple não oferece opção de enviar um evento de teste por app. Para confirmar que os webhooks estão chegando, faça uma renovação ou um reembolso de sandbox e veja se a transação aparece na página **Transações** do Paywallo com tipo **Renovação** ou **Reembolso** poucos minutos depois.

![Server Notifications no App Store Connect](/docs/apple-server-notifications.png)

## URL da ficha na App Store (iOS App Store URL)

Quando o app sai na App Store, cadastre o link público da ficha dele. Os links de campanha do Growth Hub usam essa URL pra levar quem clica até a loja. Sem nenhuma URL de loja cadastrada, o Growth Hub pede essas URLs antes de deixar você criar links.

1. Em Configurações > Apps, selecione o app. Na tela do app, acima das plataformas iOS e Android, clique no card Ficha na App Store

2. No campo URL padrão, cole o link da ficha no formato https://apps.apple.com/app/id123456789

3. Opcional: se a ficha muda por idioma, adicione uma URL em English ou Español. Quem não tem URL específica pro idioma vai pra URL padrão

4. Clique em Salvar URLs