pixup-node-sdk/README.md

SDK para integração com o gateway Pixup

# 📦 pixup-node-sdk

SDK Node.js para facilitar a integração com o gateway de pagamentos [Pixup](https://pixup.com.br), com suporte a autenticação via OAuth2 e geração de cobranças via Pix (QRCode dinâmico).

---


## 🚀 Instalação

```bash
npm i pixup-node-sdk
```

---


## 🔐 Licenciamento

Este SDK requer uma **chave de licença válida** para gerar cobranças Pix.

Você pode obter uma licença em:  
"👉 Entre em contato via WhatsApp: [https://wa.me/5548991300326](https://wa.me/5548991300326)"

### 🧰 Como usar sua licença

Adicione sua chave ao ambiente `.env`:

```env
PIXUP_LICENSE_KEY=sua_chave_licenca
```

Ou passe diretamente no `initPixup`:

```js
const context = await initPixup({
  clientId: process.env.PIXUP_CLIENT_ID,
  clientSecret: process.env.PIXUP_CLIENT_SECRET,
  licenseKey: process.env.PIXUP_LICENSE_KEY
});
```

### 💸 Planos e Licenciamento

Atualmente, o licenciamento da SDK é avaliado **individualmente**, com base no volume de uso e no tipo de aplicação.

Não existem planos fixos no momento.

📌 O modelo é flexível e pode incluir:

- Cobrança por quantidade de cobranças mensais
- Licenciamento fixo mensal para projetos estáveis
- Condições especiais para agências ou revendedores

👉 Entre em contato via WhatsApp para avaliação e liberação de licença:  
[https://wa.me/5548991300326](https://wa.me/5548991300326)


### ❌ SDK sem licença

Caso a licença seja inválida ou expirada, o SDK lançará:

```
Erro: Licença inválida ou expirada.
```

---


## ⚙️ Configuração

Crie um arquivo `.env` com suas credenciais:

```env
PIXUP_CLIENT_ID=seu_client_id
PIXUP_CLIENT_SECRET=seu_client_secret
PIXUP_LICENSE_KEY=sua_chave_licenca
```

---


## 🧱 Estrutura recomendada

```js
// index.js
const { initPixup, PixupPix } = require('pixup-node-sdk');


const context = await initPixup({
    clientId: process.env.PIXUP_CLIENT_ID,
    clientSecret: process.env.PIXUP_CLIENT_SECRET,
    //baseUrl: process.env.PIXUP_BASE_URL || "https://api.pixupbr.com/v2",
    licenseKey: process.env.PIXUP_LICENSE_KEY || "LEXLUTHOR"
  });

  const pix = new PixupPix(context);
```

---


## 📤 Gerar uma cobrança Pix (QRCode)

```js
const resposta = await pix.criarQrCode({
    amount: 59.9,
    external_id: "PEDIDO-1001",
    postbackUrl: "https://meusite.com/webhook/pixup",
    payerQuestion: "Qual o nome do produto?",
    payer: {
      name: "Fulano de Tal",
      document: "12345678900", // CPF ou CNPJ
    },
  });

  console.log("Payload (copia e cola):", resposta.qrcode);
  console.log("External ID:", resposta.external_id);
  console.log("Status inicial:", resposta.status);
```

---


## 🛡️ Autenticação automática com cache

O token é gerado e renovado automaticamente quando expira:

---


## 🔁 Exemplo de webhook (Pix pago)

```js
app.post('/webhook/pixup', express.json(), (req, res) => {
  const evento = req.body;

  console.log('Pagamento recebido!', evento);

  // Exemplo: evento.status === 'CONFIRMED'

  res.sendStatus(200);
});
```

> ⚠️ A assinatura do webhook ainda não é documentada oficialmente pela Pixup, então validações adicionais podem ser implementadas no futuro.

---


## 📘 Referência de campos

| Campo         | Tipo    | Obrigatório | Descrição                         |
|---------------|---------|-------------|-----------------------------------|
| `amount`      | number  | ✅           | Valor da cobrança em reais        |
| `external_id` | string  | ✅           | ID do pedido gerado por você      |
| `postbackUrl` | string  | ✅           | URL para receber callback         |
| `payer`       | object  | ❌           | Dados do pagador (nome, CPF)      |

---


## 📌 Roadmap

- [x] Autenticação com cache
- [x] Criação de QR Code
- [ ] Webhook assinado
- [ ] Transferências Pix (em breve)
- [x] `PixupClient` unificado

---


## 🪪 Licença

MIT © [LexLuthor](https://github.com/LexLuthorDev)