> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appreval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Primeiros passos com a Reval: instale e configure a sua loja
> Instale a Reval na sua loja Shopify, conecte o Mercado Pago e crie o seu primeiro plano de assinatura recorrente em menos de 15 minutos.
A Reval é instalada diretamente no seu admin da Shopify e não exige modificar código nem contratar infraestrutura adicional. Siga este guia passo a passo para deixar a sua loja pronta para vender assinaturas recorrentes cobradas pelo Mercado Pago.
O dashboard da Reval acompanha você: enquanto faltar configuração, você verá o cartão **"Primeiros passos"** com o status real de cada ponto (credenciais salvas, webhook verificado, primeiro plano criado) e um atalho para este guia. Ele desaparece sozinho quando tudo estiver pronto.
A Reval solicita as seguintes permissões na sua loja Shopify no momento da instalação:
* **Leitura**: pedidos, produtos, impostos, valores de frete e dados de clientes.
* **Escrita**: criação e atualização de pedidos recorrentes.
Essas permissões são estritamente necessárias para gerar as cobranças automáticas e calcular frete e impostos em tempo real durante o checkout.
A Reval é um app de **distribuição customizada**: não está publicada na Shopify App Store. Você vai receber um link de instalação gerado especificamente para a sua loja.
Abra-o com a sessão de proprietário da loja e aceite as permissões. Uma vez instalada, a Reval aparece em **Apps** dentro do seu admin, embutida — não há nenhum site externo para acessar.
O link está vinculado ao domínio da sua loja e só serve para ela.
A Reval precisa de acesso à sua conta do Mercado Pago para criar os mandatos de cobrança recorrente e receber a notificação de cada cobrança.
**Não há conexão por OAuth**: as credenciais são copiadas do painel do MP e coladas na Reval, onde ficam salvas de forma criptografada para a sua loja.
Tudo o que segue é feito no **painel de desenvolvedores do Mercado Pago**, dentro da sua aplicação. Se você ainda não a criou, o passo 2.0 orienta; se já tem, pule direto para o 2.1.
**Crie uma aplicação nova e dedicada à Reval. Não reutilize a que você usa para cobrar no seu checkout.**
Por dois motivos:
* **Cada aplicação é criada para um produto do Mercado Pago.** Uma aplicação de checkout não habilita as APIs de Assinaturas, que são as que a Reval precisa para as cobranças recorrentes.
* **Cada aplicação admite uma única URL de webhook por modo.** Se você colar a URL da Reval em uma aplicação que já tem um webhook configurado, você o sobrescreve — e as notificações do seu checkout deixam de chegar onde chegavam, sem nenhum aviso.
Ter duas aplicações **não separa o seu dinheiro nem as suas contas**: ambas pertencem à mesma conta do Mercado Pago e tudo é creditado no mesmo lugar. Uma aplicação é uma credencial de integração, não uma carteira. Não tem custo nem limite.
Se você vende com o Mercado Pago mas **nunca entrou no painel de desenvolvedores**, provavelmente não tem nenhuma aplicação própria: a integração de pagamentos da Shopify é vinculada pelo admin da loja, sem passar por lá. Nesse caso, basta criar a primeira.
#### 2.0 — Crie a aplicação (só na primeira vez)
Acesse o [painel de desenvolvedores do Mercado Pago](https://www.mercadopago.com.br/developers) com a conta do MP que vai cobrar as assinaturas. No canto superior direito, abra **Integrações**: você verá a lista **Suas aplicações**.
As capturas de tela desta página foram feitas em um painel do Mercado Pago em espanhol. No painel brasileiro os rótulos aparecem em português — indicamos os dois: o texto em português primeiro e, entre parênteses, o que você vê na imagem.
1. Clique em **Criar aplicação** (Crear aplicación).
2. **Nome da aplicação** (Nombre de la aplicación — passo 1 de 4): um nome descritivo, por exemplo o da sua loja. Até 50 caracteres. **Continuar**.
3. **Tipo de pagamento** (passo 2 de 4): escolha **Pagamentos on-line** (Pagos online).
Ao selecioná-lo aparece a pergunta **"Como você fez a loja?"** (¿Cómo hiciste la tienda?): escolha **Com um desenvolvimento próprio** (Con un desarrollo propio). A URL da loja é opcional — você pode informar o domínio da sua loja ou deixá-la vazia. **Continuar**.
Mesmo que a sua loja esteja na Shopify, a opção correta é **Com um desenvolvimento próprio** — o checkout de assinaturas da Reval é próprio, não o de uma plataforma.
4. **Solução de cobrança** (passo 3 de 4): na aba **Checkouts**, escolha **Checkout API** (a de "integração avançada" — é a única das três que combina pagamentos dentro da sua loja com pagamentos recorrentes). Se perguntar qual tipo de Checkout API, escolha **API de Pagamentos** (API de Pagos). **Continuar**.
5. **Confirme** (passo 4 de 4): revise o resumo (Pagamentos on-line · Com um desenvolvimento próprio · Checkout API · API de Pagamentos), marque a autorização de dados pessoais, resolva o captcha e clique em **Confirmar**.
Com a aplicação criada, entre nela por **Suas aplicações** e siga para o passo 2.1.
#### 2.1 — Copie as credenciais de produção
No menu lateral, desça até **PRODUÇÃO → Credenciais de produção** (PRODUCCIÓN → Credenciales de producción).
Desta tela você precisa de **dois** valores:
| No Mercado Pago | Onde vai na Reval |
| ----------------------------------------------------- | ----------------- |
| **Public Key** — começa com `APP_USR` | Public key |
| **Access Token** — clique no ícone do olho para vê-lo | Access token |
**Client ID e Client Secret não são usados.** Estão na mesma tela, logo abaixo, e é fácil copiá-los por engano. A Reval não os pede em nenhum momento.
#### 2.2 — Configure o webhook
No menu lateral, entre em **NOTIFICAÇÕES → Webhooks** (NOTIFICACIONES → Webhooks). Confirme que você está na aba **Modo produtivo** e não em "Modo de teste": são duas configurações independentes e a de teste não é usada.
1. Em **URL de produção**, cole a **URL de notificações (webhook)** que a Reval mostra em **Configuração → Integrações — Mercado Pago** (há um botão **Copiar URL** ao lado). A URL já vem montada com a sua loja — não é preciso editá-la.
O `?shop=` do final não é opcional: é o que indica à Reval de qual loja vem a notificação e com qual chave secreta validá-la. Se você o omitir, o Mercado Pago responde `200` de todo modo e tudo parece funcionar, mas você fica dependendo de um mecanismo de respaldo. Copie a URL completa, exatamente como a Reval a mostra.
2. Em **Eventos recomendados para integrações com Assinaturas**, marque exatamente dois:
* **Planos e assinaturas** (Planes y suscripciones)
* **Pagamentos (legacy)** (Pagos (legacy))
Não marque nenhum outro. Os eventos a mais não quebram nada, mas geram tráfego que a Reval descarta.
3. Copie a **Chave secreta** que aparece no final da tela. Esse é o terceiro valor que você vai colar na Reval.
4. Clique em **Salvar configuração**.
O botão de atualizar que fica ao lado da chave secreta **gera uma nova e invalida a anterior**. Se você clicar nele depois de já ter configurado a Reval, os webhooks começam a falhar na validação de assinatura e as cobranças deixam de gerar pedidos na Shopify. Se isso acontecer, copie a chave nova e atualize-a na Reval.
O nome "Pagamentos (legacy)" parece se referir a algo descontinuado, mas é o evento correto: é o que notifica cada cobrança individual do mandato, e é o que a Reval escuta para criar o pedido na Shopify.
#### 2.3 — Cole os três valores na Reval
Na Reval, vá em **Configuração → Integrações — Mercado Pago** e preencha:
* **Public key** (começa com `APP_USR`)
* **Access token** (começa com `APP_USR`)
* **Webhook secret** — a chave secreta do passo anterior
Salve.
O access token e o webhook secret **não voltam a ser exibidos depois de salvos**: os campos ficam mascarados. É o comportamento esperado. Se precisar trocá-los, escreva o valor novo em cima e salve de novo.
#### 2.4 — Teste a conexão
Clique em **Testar conexão**. O teste usa as credenciais salvas, então **salve antes de testar**.
Se tudo estiver certo, aparece uma mensagem verde com o nome da sua conta do Mercado Pago e o código do seu país (`MLA` Argentina, `MLB` Brasil, `MLC` Chile, `MCO` Colômbia, `MLM` México, `MPE` Peru, `MLU` Uruguai).
| O que você vê | O que significa |
| ------------------------------------------ | -------------------------------------------------------------------------------------- |
| "Conexão OK — *sua conta* (MLB)" | Pronto, siga para o passo seguinte. |
| "O Mercado Pago recusou o access token" | O token está incompleto ou é de teste. Copie-o de novo em **Credenciais de produção**. |
| Conexão OK mas com **outro nome de conta** | Pare aqui. Veja o aviso abaixo. |
Se o nome que aparece não é o da sua conta, o access token é de outra conta: **pare aí**. Um token errado não dá erro, simplesmente cobraria na conta incorreta.
Considere também que a Reval opera com credenciais produtivas: **não há modo sandbox**, e os cartões de teste do MP não funcionam. Para validar o fluxo, faz-se uma compra real de valor baixo e depois se estorna.
Os planos definem a frequência de cobrança e o desconto que os assinantes recebem em relação ao preço de tabela.
1. Vá em **Planos** no menu lateral da Reval e preencha a seção **Criar um plano de assinatura**.
2. Preencha os campos:
* **Nome do plano**: por exemplo, "Mensal" ou "Trimestral com desconto".
* **Frequência**: combine um intervalo numérico com uma unidade de tempo — **dias**, **semanas** ou **meses**. Por exemplo: 1 mês para cobrança mensal, 3 meses para trimestral, 14 dias para quinzenal.
* **Tipo de desconto**: *percentual de desconto* (entre 1 e 99, sobre o preço de tabela de cada produto) ou *preço fixo* (o mesmo valor para todos os produtos do plano). Se você não quiser aplicar desconto, use preço fixo com o preço normal do produto.
* **Desconto extra no 1º pedido** (opcional): um percentual adicional que se aplica SOMENTE à primeira cobrança. A partir do segundo ciclo é cobrado o preço normal do plano, e o comprador vê os dois preços antes de assinar.
3. Selecione os produtos e clique em **Criar plano**.
O Mercado Pago tem um **valor mínimo por cobrança** (depende da moeda da sua conta). A Reval não permite salvar planos cujo preço final fique abaixo desse mínimo e mostra o valor exato ao tentar — se você vir esse aviso, aumente o preço ou reduza o desconto.
Você pode criar quantos planos precisar. Os compradores os verão como opções no buy box do produto.
O buy box é o widget que aparece na página do produto e permite ao comprador escolher entre comprar uma única vez ou assinar. Ele é adicionado como um **bloco de app** pelo editor de temas — sem mexer em código:
1. Na Shopify: **Loja virtual → Temas → Personalizar**.
2. Abra uma **página de produto** e, na seção de informações do produto, clique em **Adicionar bloco → Apps → "Reval"**.
3. Salve. O bloco se acomoda sozinho junto aos botões de compra (quantidade → opções → botão de assinar), onde quer que você o deixe.
Nas configurações do bloco você pode editar os **benefícios** exibidos ao escolher a assinatura, ativar a **pré-seleção** da opção de assinar e definir um **logo** para o checkout. A opção **«Mostrar opção de compra avulsa»** (ativada por padrão) controla se o buy box oferece a compra sem assinatura: desative-a para vender o produto **apenas por assinatura**.
**Ícone da aba do navegador:** no checkout da Reval, o ícone que aparece na aba vem do **logo quadrado** da sua loja — carregado na Shopify em **Configurações → Marca → Logo quadrado** (é um ajuste diferente do favicon do tema). Se ele não estiver carregado, a Reval adapta o seu logo principal para um quadrado; fica melhor se você enviar o quadrado — o mesmo arquivo que você usa como favicon do tema serve.
O buy box só aparece em produtos que têm um **plano ativo** — nos demais o bloco fica invisível, então é seguro adicioná-lo ao template geral de produto.
O buy box exige que o tema da sua loja tenha **JavaScript habilitado**. Se você usa um tema muito personalizado ou com scripts bloqueados, verifique se o widget carrega corretamente antes de publicá-lo.
Antes de anunciar a funcionalidade aos seus clientes, verifique se o fluxo completo funciona de ponta a ponta.
Como a Reval opera com credenciais produtivas, o teste é feito com um **cartão real e um valor baixo**, que você estorna depois. Vale criar um plano temporário barato para isso.
1. Abra a página do produto onde o buy box aparece em uma janela anônima.
2. Escolha o plano de teste e finalize o checkout com um cartão real.
3. Verifique se:
* O pedido aparece em **Pedidos** dentro do admin da Shopify, com as tags `Suscripción`, `Primera compra` e `Ciclo 1` (as tags são emitidas em espanhol).
* A assinatura aparece em **Assinaturas** dentro da Reval, com status ativo.
* O mandato consta no seu painel do Mercado Pago.
4. Cancele a assinatura de teste e estorne a cobrança pelo painel do MP.
Se você também oferece add-ons, marque um no checkout de teste: verifique se no Mercado Pago aparecem **duas cobranças separadas** (a do mandato e a do add-on) e se o pedido inclui as duas linhas.
***
## Limitações conhecidas
Antes de lançar o seu programa de assinaturas, considere as seguintes restrições atuais da Reval:
* **Não existe cobrança sob demanda**: você não pode iniciar uma cobrança manual fora do ciclo programado. As cobranças são executadas automaticamente pelo Mercado Pago na data programada.
* **Pular um ciclo existe, mas com data aproximada**: é ativado em Configuração → Pedidos e estoque, e por baixo funciona pausando o débito e reativando-o um ciclo depois, então a data da cobrança seguinte é decidida pelo Mercado Pago ao reativar. O detalhe está em [Limitações](/pt/introducao/limitacoes).
* **Não é possível mudar a data da próxima cobrança**: a data do ciclo seguinte é determinada pelo Mercado Pago conforme a frequência do plano e não pode ser antecipada nem postergada manualmente.
* **Não é possível mudar a frequência de uma assinatura ativa**: se um assinante quiser passar de um plano mensal para um trimestral, o único caminho é cancelar a assinatura atual e criar uma nova com o plano desejado.
* **Não existem cartões de respaldo**: cada assinatura está associada a um único meio de pagamento. Se a cobrança falhar, não se tenta com outro meio.
***
## Próximos passos
Agora que a sua loja está configurada para receber assinaturas, explore as seções a seguir para personalizar e otimizar a sua operação:
Crie, edite e arquive planos de assinatura. Aprenda a configurar frequências, descontos e a atribuí-los a vários produtos.
Ajuste os limites de assinaturas por cliente, o comportamento diante da falta de estoque, a página de agradecimento e mais.