# Início rápido com npx

> Um comando configura o Perly Pay no seu projeto: a rota de checkout, a rota do webhook com verificação de assinatura, um botão Pay e a sua chave de teste.

`npx perly-pay init` lê o seu projeto, escreve código para o framework dele e deixa você a um clique de um pagamento de teste. Ele só configura o **modo de teste**; a produção é ativada no painel.

## Execute

```bash
npx perly-pay init
```

Ele detecta o framework e o gerenciador de pacotes, abre Dashboard → Developers e pede uma chave de teste (`sk_test_…`). Uma chave de produção é recusada.

## O que ele escreve

| Framework | Como detecta | Arquivos |
| --- | --- | --- |
| Next.js (App Router) | `next` | `lib/perly-pay.ts`, `app/api/perly-pay/checkout/route.ts`, `app/api/perly-pay/webhook/route.ts`, `components/PayButton.tsx`, `app/perly-pay/page.tsx` |
| Express | `express` | `lib/perly-pay.js`, `routes/perly-pay.js` |
| Hono | `hono` | `lib/perly-pay.ts`, `routes/perly-pay.ts` |
| Laravel | `artisan`, `laravel/framework` | `app/Http/Controllers/PerlyPayController.php`, `routes/perly-pay.php`, `config/perly-pay.php`, `resources/views/perly-pay/button.blade.php` |
| Node.js | qualquer outro `package.json` | `lib/perly-pay.js`, `perly-pay.js` (`node:http`) |

TypeScript ou JavaScript, módulos ES ou CommonJS, como o seu projeto, e em `src/` se o seu código está lá. npm, pnpm, yarn, bun e Composer.

- **Checkout.** O botão envia um formulário para `/perly-pay/checkout` (`/api/perly-pay/checkout` no Next.js). Ele abre uma fatura e leva o comprador a pagá-la.
- **Webhook.** `/perly-pay/webhook` verifica `Perly-Signature` sobre o corpo bruto. Com `invoice.fulfilled`, chama `grantAccess()`, o único TODO que você escreve.
- **Planos.** Vendas únicas e pacotes de créditos, em `PLANS` no início do módulo principal. O plano, os créditos dele e o seu id de usuário vão nos metadados da fatura e voltam no webhook.
- **Chaves.** `PERLY_PAY_SECRET_KEY` e `PERLY_PAY_WEBHOOK_SECRET` em `.env.local` (Next.js) ou `.env`, e o arquivo no `.gitignore`. Se o git já rastreia esse arquivo, o init não escreve a chave nele e diz como parar de rastreá-lo.

> **Nota:** O init nunca substitui um arquivo ou um valor que já existe. O `--force` substitui.

## Conecte o webhook

O Perly Pay precisa alcançar o endereço do webhook. Adicione-o em Dashboard → Developers → Webhooks para `invoice.fulfilled` e cole o segredo `whsec_…` dele em `PERLY_PAY_WEBHOOK_SECRET`. Ou deixe o init fazer as duas coisas:

```bash
npx perly-pay init --webhook-url https://your-app.example/perly-pay/webhook
```

Num notebook, um túnel dá a você um endereço público: `cloudflared tunnel --url http://localhost:3000`. Mais em [Webhooks](https://pay.perly.io/docs/webhooks.md).

## Um pagamento no modo de teste

1. **Inicie o seu app** — Express e Node leem o `.env` com `node --env-file=.env` ou dotenv.
2. **Abra /perly-pay** — Clique em **Pay with crypto**. Você está no checkout.
3. **Simulate payment** — A fatura passa a paga e depois a entregue. Veja [Modo de teste](https://pay.perly.io/docs/test-mode.md).
4. **Veja o grantAccess agir** — Seu webhook recebe `invoice.fulfilled`. Agora escreva o que ele libera.

## Com um assistente de IA

`--yes` não pergunta nada, então o Claude Code, o Cursor ou o Codex podem executar por você. Passe a chave e o que você vende:

```bash
npx perly-pay init --yes --key sk_test_… --product "Logo review" --amount 4900
```

`--json` imprime um resultado que o assistente consegue ler.

## Opções

| Flag | O que faz |
| --- | --- |
| `--yes`, `-y` | Sem perguntas. Para assistentes de IA e scripts. |
| `--framework <name>` | `next`, `express`, `hono`, `laravel` ou `node`, se ele não acertou. |
| `--key <sk_test_…>` | Sua chave de teste. Por padrão: `PERLY_PAY_SECRET_KEY`, ou ele pergunta. |
| `--webhook-url <url>` | Registra o endereço para `invoice.fulfilled` e guarda o segredo dele. |
| `--product <name>`, `--amount <cents>`, `--currency <code>` | O que você vende, em USD ou EUR. `--amount 4900` é $49.00. |
| `--install` | Também instala o SDK. Senão, imprime o comando. |
| `--force` | Substitui arquivos e valores que já existem. |
| `--plugin`, `--mcp` | Imprime como adicionar o plugin do Claude Code e o servidor `perly-pay-mcp`. |
| `--dry-run` | Diz o que faria, sem escrever nada. |
| `--json` | Imprime o resultado como JSON. |
| `--api <origin>`, `--dir <path>` | Outro Perly Pay (local), outra pasta. |

## Produção

- Conecte as chaves **reais** da sua carteira em Dashboard → Wallets.
- Crie uma chave de produção (`sk_live_…`) e um webhook de produção.
- Configure-os onde o seu app roda. O código continua igual. O resto da API está nos [SDKs](https://pay.perly.io/docs/sdks.md).