> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

> SDK oficial para Node.js — aceite pagamentos em segundos com uma integração simples

<Card title="Alpa Node.js SDK" icon="node-js" href="https://github.com/anthonymengottii/alpa-nodejs-sdk">
  SDK oficial da Alpa para JavaScript e TypeScript. Compatível com Node.js 18+, Bun e edge runtimes.
</Card>

## Instalação

<Note>
  Este SDK ainda não está publicado no npm. Instale diretamente pelo GitHub:
</Note>

```bash theme={null}
npm install github:anthonymengottii/alpa-nodejs-sdk
```

## Uso Rápido

```ts theme={null}
import AlpaClient from '@alpa/alpa-js';

const alpa = new AlpaClient({ apiKey: process.env.ALPA_API_KEY });
```

## Criar Link de Pagamento

```ts theme={null}
const link = await alpa.paymentLinks.create({
  title: 'Produto Premium',
  amountCents: 9900,
  description: 'Acesso vitalício',
});
```

## Resposta

```ts theme={null}
{
  id: "lnk_abc123",
  title: "Produto Premium",
  description: "Acesso vitalício",
  amount: 9900,
  currency: "BRL",
  status: "ACTIVE",
  slug: "abc123",
  createdAt: "2026-04-08T00:00:00.000Z",
  updatedAt: "2026-04-08T00:00:00.000Z"
}
```

A URL do checkout é montada a partir do `slug`:

```ts theme={null}
const checkoutUrl = alpa.paymentLinks.getCheckoutUrl(link.slug);
// https://checkout.usealpa.com/pay/abc123
```

## Criar Transação PIX

```ts theme={null}
const tx = await alpa.transactions.create({
  product: 'Curso Node.js',
  paymentMethod: 'PIX',
  amountCents: 19900,
  clientName: 'João Silva',
  clientEmail: 'joao@example.com',
  clientDocument: '12345678900',
});

console.log(tx.pixCopiaECola);
```

## Validar Cupom

```ts theme={null}
const result = await alpa.coupons.validate({
  code: 'DESCONTO10',
  amountCents: 19900,
});

// result.valid, result.discountCents, result.finalAmountCents
```

## Validação de Webhooks

```ts theme={null}
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = alpa.verifyWebhookSignature(
    req.body,
    req.headers['x-webhook-signature'] as string,
    process.env.ALPA_WEBHOOK_SECRET!
  );

  if (!isValid) return res.status(401).json({ error: 'Assinatura inválida' });

  const event = JSON.parse(req.body.toString());
  res.json({ received: true });
});
```

## Tratamento de Erros

```ts theme={null}
import { AlpaError, AlpaValidationError } from '@alpa/alpa-js';

try {
  const tx = await alpa.transactions.create({ ... });
} catch (error) {
  if (error instanceof AlpaValidationError) {
    console.error('Dados inválidos:', error.message);
  } else if (error instanceof AlpaError) {
    console.error(`Erro ${error.statusCode}:`, error.message);
  }
}
```