@tittle/sdk

SDK oficial do Tittle Payments para Node.js. Integra cobranças, produtos, relatórios e webhooks nos teus projetos com facilidade.

Instalação

npm install @tittle/sdk

Início Rápido

const TittleSDK = require('@tittle/sdk');

const tittle = new TittleSDK({
  apiKey: 'tk_live_SUA_CHAVE_AQUI'
});

Obtém a tua API key em tittle.ao/dashboard/devtools.

Cobranças

Criar link de cobrança

const charge = await tittle.charges.create({
  amount: 5000,          // valor em AOA
  productName: 'Consultoria Premium',
  currency: 'AOA',       // opcional, padrão: AOA
  expiresIn: 24          // opcional, horas até expirar. padrão: 24
});

console.log(charge.paymentUrl);
// https://tittle-payments.vercel.app/pay/abc123
console.log(charge.id);
console.log(charge.status); // pending

Listar cobranças

// Todas as cobranças
const all = await tittle.charges.list();

// Filtradas por status
const confirmed = await tittle.charges.list({ status: 'confirmed' });
const pending   = await tittle.charges.list({ status: 'pending' });
const expired   = await tittle.charges.list({ status: 'expired' });

// Com limite
const last5 = await tittle.charges.list({ limit: 5 });

console.log(confirmed.data);  // array de cobranças
console.log(confirmed.total); // total de resultados

Obter cobrança por ID

const charge = await tittle.charges.get('5137d76a-66c9-...');
console.log(charge.status);
console.log(charge.amount);

Produtos

Listar produtos

const { data } = await tittle.products.list();
data.forEach(p => console.log(p.name, p.price));

Criar produto

const product = await tittle.products.create({
  name: 'Plano Pro',
  price: 15000
});
console.log(product.id);

Atualizar produto

await tittle.products.update('PRODUCT_ID', { price: 18000 });

Eliminar produto

await tittle.products.delete('PRODUCT_ID');

Relatórios

Resumo financeiro

const summary = await tittle.reports.summary();

console.log(summary.totalReceived); // total recebido em AOA
console.log(summary.confirmed);     // número de pagamentos confirmados
console.log(summary.pending);       // número de pagamentos pendentes
console.log(summary.expired);       // número de pagamentos expirados

Histórico de pagamentos

const { data } = await tittle.reports.payments();
data.forEach(p => console.log(p.product_name, p.amount, p.status));

Webhooks

Registar endpoint

const webhook = await tittle.webhooks.register({
  url: 'https://meusite.com/webhook/tittle',
  events: ['payment.confirmed', 'payment.expired']
});
console.log(webhook.id);

Eventos disponíveis

| Evento | Descrição | |--------|-----------| | payment.confirmed | Pagamento confirmado pelo cliente | | payment.expired | Link expirou sem pagamento | | payment.created | Novo link de cobrança criado | | product.created | Produto adicionado | | product.deleted | Produto removido | | user.registered | Novo utilizador registado |

Listar webhooks

const { data } = await tittle.webhooks.list();

Remover webhook

await tittle.webhooks.delete('WEBHOOK_ID');

Verificar assinatura (segurança)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhook/tittle', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-tittle-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (sig !== expected) {
    return res.status(400).send('Assinatura inválida');
  }

  const { event, data } = JSON.parse(req.body);

  switch (event) {
    case 'payment.confirmed':
      console.log('Pagamento confirmado:', data.id);
      break;
    case 'payment.expired':
      console.log('Pagamento expirou:', data.id);
      break;
  }

  res.json({ received: true });
});

Tratamento de Erros

try {
  const charge = await tittle.charges.create({
    amount: 5000,
    productName: 'Consultoria'
  });
} catch (err) {
  console.error(err.message);
  // Ex: "amount deve ser maior que 0"
  // Ex: "API key inválida ou revogada"
}

Configuração Avançada

const tittle = new TittleSDK({
  apiKey: 'tk_live_...',
  baseUrl: 'https://tittle-api.onrender.com' // opcional
});

Links

• Dashboard
• Dev Portal
• Suporte

Licença

MIT