> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Configurar as compras da RevenueCat

Crie um projeto RevenueCat, ligue os seus produtos da App Store e do Play, e ligue as chaves SDK mais os segredos de servidor que verificam as compras.

## Passo a passo para iniciantes

Porque existe isto: a Apple e a Google exigem que as compras digitais dentro de uma app passem pela sua própria faturação — nunca pelo Stripe Checkout — e o kit impõe esse limite. A RevenueCat fica por cima das duas lojas para que uma única integração cubra iOS e Android: segue recibos, assinaturas e restaurações, e o seu servidor pergunta à RevenueCat se um workspace pagou.

Pré-requisitos: as contas Apple Developer Program (99 $ por ano) e Google Play Console (25 $ uma vez) do guia de contas mobile — os produtos de loja têm de existir antes de a RevenueCat os poder ligar — mais um development build de EAS para testar de verdade, porque o Expo Go não consegue correr de todo o módulo nativo de compras. O nível gratuito da RevenueCat cobre os testes; nada disto lhe cobra antes de os produtos estarem em produção.

Terminologia rápida: um projeto RevenueCat guarda as suas apps ligadas às lojas. Os produtos são os artigos de loja espelhados dentro da RevenueCat. Um entitlement é o flag que a RevenueCat concede enquanto uma assinatura está ativa — `pro` por predefinição. Um offering agrupa produtos no paywall que a app apresenta. As chaves SDK públicas vão no env mobile; uma secret API key e a autorização do webhook ficam no servidor.

O que cria: um projeto, duas apps ligadas às lojas, produtos, um entitlement, um offering — cerca de uma hora, a maior parte à espera da configuração dos produtos de loja.

[Criar as contas mobile](https://supastack.dev/pt/docs/mobile/external-accounts.md)

[Compilar um cliente de desenvolvimento](https://supastack.dev/pt/docs/mobile/eas-setup.md)


## Criar a conta e o projeto RevenueCat

1. Abra [app.revenuecat.com](https://app.revenuecat.com) → Sign up e crie um projeto com o nome do seu produto.

Esperado: um painel de projeto vazio com separadores para Apps, Products, Entitlements, Offerings e API keys — as secções seguintes preenchem-nos por ordem.


## Criar os produtos de loja e depois ligar as duas apps

Os produtos do lado da loja têm de existir antes de a RevenueCat os poder referenciar. iOS: [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → My Apps → crie a ficha da app com o seu `ios.bundleIdentifier` → In-App Purchases ou Subscriptions → crie os produtos de assinatura que planeia vender (podem ficar em rascunho enquanto testa). Android: [play.google.com/console](https://play.google.com/console) → crie a app → Monetize → Products → Subscriptions (ou produtos in-app).

Depois ligue as duas dentro da RevenueCat: Apps → New app. Para iOS escolha App Store, introduza o bundle id e forneça as credenciais App Store Connect que o formulário pede — liga a documentação de configuração da própria RevenueCat para cada campo. Para Android escolha Play Store, introduza o package name e carregue o JSON de conta de serviço do Play — a documentação ligada guia a criação dele no Google Cloud.

Esperado: as duas apps listadas debaixo do projeto, e as consolas das lojas mostram os seus produtos existentes — o estado de rascunho serve nesta fase.


## Produtos, entitlement, offering

1. Products → New: crie um produto RevenueCat por produto de loja e anexe o id de produto App Store ou Play correspondente — os ids têm de corresponder exatamente aos das consolas.

2. Entitlements → New: dê-lhe o nome a condizer com `REVENUECAT_ENTITLEMENT_ID` — a predefinição do kit é `pro` — e anexe os produtos que o concedem.

3. Offerings → New: crie um offering, adicione packages que apontam para os seus produtos e marque-o como Current — a app lê `offerings.current` ao renderizar o paywall.

Mantenha `REVENUECAT_ENTITLEMENT_KEY` na sua predefinição `ai.reference-task`: essa é a chave de registo interna do kit — a mesma chave que os planos web incluídos concedem — e o acesso RevenueCat é escrito debaixo dela. Mude o nome apenas quando a chave de plano do seu produto mudar.


## Copiar as chaves e registar o webhook

Project → API keys lista os três tipos abaixo. As chaves SDK públicas por plataforma (`appl_…` para iOS, `goog_…` para Android) vão para `apps/mobile/.env.local` — identificam a app, não carregam autoridade de gasto, e o prefixo `EXPO_PUBLIC_` é o correto para elas.

A secret API key (`sk_…`, a chave v1) e a autorização do webhook são apenas do servidor em `apps/web/.env.local` — nunca `EXPO_PUBLIC_`, nunca commitadas. O servidor chama a subscriber API da RevenueCat com a chave secreta para verificar o estado de compra de cada workspace.

Webhook: RevenueCat → Integrations → Webhooks → defina o URL `{APP_URL}/api/billing/webhook/revenuecat` e um valor de cabeçalho Authorization — qualquer cadeia aleatória longa que invente — e depois ponha exatamente a mesma cadeia em `REVENUECAT_WEBHOOK_AUTHORIZATION`. O kit compara o cabeçalho à letra e rejeita qualquer outra coisa, por isso renovações, cancelamentos e reembolsos chegam ao servidor sem esperar pelo próximo arranque da app.

As compras sandbox são aceites automaticamente fora de produção; `REVENUECAT_ALLOW_SANDBOX=true` num env de produção é rejeitado no arranque, por isso deixe-o por definir uma vez em produção.

```
# apps/mobile/.env.local
EXPO_PUBLIC_MOBILE_PURCHASES_PROVIDER=revenuecat
EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=appl_…
EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY=goog_…

# apps/web/.env.local — server side
MOBILE_PURCHASES_PROVIDER=revenuecat
REVENUECAT_SECRET_API_KEY=sk_…
REVENUECAT_WEBHOOK_AUTHORIZATION=<the exact Authorization value set on the webhook>
REVENUECAT_ENTITLEMENT_ID=pro
REVENUECAT_ENTITLEMENT_KEY=ai.reference-task
```


## Verificar com uma compra sandbox

As compras só correm dentro de um build de desenvolvimento ou de produção — ao Expo Go falta por completo o módulo nativo, por isso este passo assume que `eas build --profile development` produziu um dev client (o guia EAS compila-o).

1. Instale o dev build num dispositivo ou simulador com sessão iniciada numa conta sandbox: App Store Connect → Users and Access → Sandbox Testers para iOS; Play Console → license testing para Android.

2. Na app abra o paywall e compre com a conta sandbox. Esperado: a compra conclui-se em sandbox — sem cobrança real — Restore purchases funciona, e o entitlement do workspace aparece ativo, registado no servidor debaixo da chave `ai.reference-task`.

Falhas comuns: um paywall vazio significa que o offering não é Current ou os produtos estão por ligar; uma compra em dispositivo que falha significa que o produto de loja ainda está em rascunho ou que a conta sandbox errada tem sessão iniciada; um entitlement que nunca muda significa que `MOBILE_PURCHASES_PROVIDER`/`EXPO_PUBLIC_MOBILE_PURCHASES_PROVIDER` estão desligados ou que o Authorization do webhook não corresponde — o painel da RevenueCat lista o estado de cada entrega de webhook.

[Compilar e verificar em dispositivos](https://supastack.dev/pt/docs/mobile/builds.md)

[O checkout web usa Stripe em alternativa](https://supastack.dev/pt/docs/web/stripe-payments.md)


Para continuar a configuração, leia [Builds e verificação em dispositivos](https://supastack.dev/pt/docs/mobile/builds.md).


## Seguinte

[Builds e verificação em dispositivos](https://supastack.dev/pt/docs/mobile/builds.md)