SDK CentralCart

SDK oficial em Node.js para integração com a API do CentralCart - Plataforma de pagamentos e gestão de produtos digitais.

📦 Instalação

npm install sdk-centralcart

🚀 Início Rápido

import centralcart, { payments } from 'sdk-centralcart';

// 1. Inicializar o SDK com sua API Key
centralcart.init({
    apiKey: 'sua-api-key-aqui',
    debug: true // Ativa logs no console (opcional)
});

// 2. Criar um pagamento PIX
const result = await payments.createPixPayment(123); // 123 = ID do produto

if (result.status === 'success') {
    console.log('PIX Code:', result.data.pix_code);
    console.log('QR Code:', result.data.qr_code);
    console.log('Order ID:', result.data.order_id);
}

// 3. Monitorar pagamentos
payments.monitorTransactions({
    onApproved: (data) => {
        console.log('✅ Pagamento aprovado!', data.order_id);
        // Entregar produto ao cliente
    }
});

📖 Documentação Completa

Sumário

• Configuração
• Módulo payments
  • createPixPayment()
  • getTransaction()
  • refundPayment()
  • monitorTransactions()
  • checkExpiredTransactions()
  • getPendingTransactions()
  • getAllTransactions()
  • getCacheStats()
  • clearCache()
• Módulo centralcart
  • Pacotes/Produtos
  • Pedidos
  • Cupons
  • Checkout
  • Estatísticas
• Estrutura de Dados
• Exemplos Completos

Configuração

centralcart.init(options)

Inicializa o SDK com suas credenciais. Deve ser chamado antes de qualquer outra função.

centralcart.init({
    apiKey: 'sua-api-key',
    debug: true
});

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição | |-----------|------|:-----------:|:------:|-----------| | apiKey | string | ✅ | - | Sua chave de API do CentralCart | | debug | boolean | ❌ | false | Ativa logs detalhados no console |

centralcart.getConfig()

Retorna a configuração atual do SDK.

const config = centralcart.getConfig();
// { apiKey: 'xxx...', debug: true }

Módulo payments

O módulo payments fornece funções para criar e gerenciar pagamentos PIX.

createPixPayment(productId, quantity, options)

Cria um novo pagamento PIX para um produto.

const result = await payments.createPixPayment(123, 1, {
    name: 'João Silva',
    email: '[email protected]',
    cpf: '12345678900',
    expirationMinutes: 30
});

Parâmetros

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição | |-----------|------|:-----------:|:------:|-----------| | productId | number/string | ✅ | - | ID do produto no CentralCart | | quantity | number | ❌ | 1 | Quantidade de itens | | options.expirationMinutes | number | ❌ | 10 | Tempo até expirar (minutos) | | options.name | string | ❌ | gerado | Nome do cliente | | options.email | string | ❌ | gerado | Email do cliente | | options.cpf | string | ❌ | gerado | CPF do cliente (apenas números) |

💡 Dica: Se name, email ou cpf não forem informados, serão gerados automaticamente. Você pode informar apenas alguns campos (ex: só o email) e os demais serão gerados.

Retorno (sucesso)

{
    status: 'success',
    data: {
        pix_code: '00020126580014br.gov.bcb.pix...', // Código PIX copia e cola
        qr_code: 'https://api.centralcart.com.br/qr/...', // URL da imagem QR Code
        order_id: 12345, // ID do pedido criado
        amount: 29.90, // Valor do pagamento
        expires_at: 1702234567890 // Timestamp de expiração
    }
}

Retorno (erro)

{
    status: 'error',
    data: 'Erro ao criar pagamento PIX'
}

Exemplos

// Exemplo 1: Pagamento simples (dados gerados automaticamente)
const pix = await payments.createPixPayment(123);

// Exemplo 2: Com quantidade
const pix = await payments.createPixPayment(123, 3); // 3 unidades

// Exemplo 3: Com email do cliente (nome e CPF gerados)
const pix = await payments.createPixPayment(123, 1, {
    email: '[email protected]'
});

// Exemplo 4: Com todos os dados do cliente
const pix = await payments.createPixPayment(123, 1, {
    name: 'Maria Santos',
    email: '[email protected]',
    cpf: '98765432100',
    expirationMinutes: 60 // 1 hora para pagar
});

getTransaction(orderId, forceApi)

Busca informações de uma transação. Primeiro verifica o cache local, se não encontrar busca na API do CentralCart.

const transaction = await payments.getTransaction(12345);

Parâmetros

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição | |-----------|------|:-----------:|:------:|-----------| | orderId | number/string | ✅ | - | ID do pedido | | forceApi | boolean | ❌ | false | Força buscar da API ignorando cache |

Retorno

{
    order_id: 12345,
    product_id: 123,
    product_name: 'Plano VIP',
    amount: 29.90,
    status: 'pending', // pending, approved, expired, cancelled, refunded
    client: {
        name: 'João Silva',
        email: '[email protected]',
        cpf: '12345678900'
    },
    created_at: 1702230000000,
    expires_at: 1702230600000,
    updated_at: 1702230000000,
    paid_at: null, // Preenchido quando aprovado
    raw: { ... } // Dados originais da API (quando buscado da API)
}

Exemplos

// Busca normal (cache primeiro, API se necessário)
const tx = await payments.getTransaction(12345);

// Forçar busca na API (ignora cache)
const txAtualizado = await payments.getTransaction(12345, true);

// Verificar status
if (tx && tx.status === 'approved') {
    console.log('Pagamento confirmado!');
}

refundPayment(orderId)

Solicita o reembolso de um pagamento aprovado.

const result = await payments.refundPayment(12345);

Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|:-----------:|-----------| | orderId | number/string | ✅ | ID do pedido a reembolsar |

Retorno

// Sucesso
{ status: 'success', data: { ... } }

// Erro
{ status: 'error', data: 'Mensagem de erro' }

Exemplo

const result = await payments.refundPayment(12345);

if (result.status === 'success') {
    console.log('Reembolso processado com sucesso!');
} else {
    console.error('Erro no reembolso:', result.data);
}

monitorTransactions(options)

Inicia o monitoramento automático de transações pendentes. Verifica periodicamente o status na API e dispara callbacks quando há mudanças.

const monitorId = payments.monitorTransactions({
    interval: 15000,
    onApproved: (data) => { /* ... */ },
    onExpired: (data) => { /* ... */ },
    onCancelled: (data) => { /* ... */ },
    onStatusChanged: (data) => { /* ... */ }
});

Parâmetros

| Parâmetro | Tipo | Padrão | Descrição | |-----------|------|:------:|-----------| | options.interval | number | 15000 | Intervalo entre verificações (ms) | | options.onApproved | function | null | Callback quando pagamento é aprovado | | options.onExpired | function | null | Callback quando pagamento expira | | options.onCancelled | function | null | Callback quando pagamento é cancelado | | options.onStatusChanged | function | null | Callback para outras mudanças de status |

Retorno

Retorna o ID do setInterval, que pode ser usado para parar o monitoramento:

const monitorId = payments.monitorTransactions({ ... });

// Para parar o monitoramento:
clearInterval(monitorId);

Estrutura dos Callbacks

onApproved:

{
    event: 'payment_approved',
    order_id: 12345,
    product_id: 123,
    product_name: 'Plano VIP',
    amount: 29.90,
    client: { name, email, cpf },
    paid_at: Date
}

onExpired:

{
    event: 'payment_expired',
    order_id: 12345,
    product_id: 123,
    product_name: 'Plano VIP',
    amount: 29.90,
    created_at: 1702230000000,
    expired_at: 1702230600000
}

onCancelled:

{
    event: 'payment_cancelled',
    order_id: 12345,
    product_id: 123,
    product_name: 'Plano VIP'
}

onStatusChanged:

{
    event: 'status_changed',
    order_id: 12345,
    product_id: 123,
    old_status: 'pending',
    new_status: 'refunded'
}

Exemplo Completo

const monitorId = payments.monitorTransactions({
    interval: 10000, // Verificar a cada 10 segundos
    
    onApproved: async (data) => {
        console.log(`✅ Pagamento ${data.order_id} aprovado!`);
        console.log(`   Produto: ${data.product_name}`);
        console.log(`   Valor: R$ ${data.amount}`);
        console.log(`   Cliente: ${data.client.email}`);
        
        // Entregar o produto
        await entregarProduto(data.client.email, data.product_id);
        
        // Enviar email de confirmação
        await enviarEmailConfirmacao(data.client.email, data);
    },
    
    onExpired: (data) => {
        console.log(`⏰ Pagamento ${data.order_id} expirou`);
        // Notificar usuário, cancelar reserva, etc.
    },
    
    onCancelled: (data) => {
        console.log(`❌ Pagamento ${data.order_id} cancelado`);
    }
});

// Parar após 1 hora
setTimeout(() => clearInterval(monitorId), 60 * 60 * 1000);

checkExpiredTransactions(onExpired)

Verifica manualmente transações expiradas e atualiza seus status. É chamado automaticamente pelo monitorTransactions(), mas pode ser usado de forma independente.

const expired = payments.checkExpiredTransactions((tx) => {
    console.log('Expirou:', tx.order_id);
});

Parâmetros

| Parâmetro | Tipo | Descrição | |-----------|------|-----------| | onExpired | function | Callback chamado para cada transação expirada |

Retorno

Array com as transações que foram marcadas como expiradas.

getPendingTransactions()

Retorna a lista de IDs das transações pendentes.

const pendingIds = payments.getPendingTransactions();
console.log(`${pendingIds.length} pagamentos aguardando`);
// [12345, 12346, 12347]

getAllTransactions()

Retorna todas as transações armazenadas no cache (pendentes, aprovadas, expiradas, etc).

const all = payments.getAllTransactions();

// Filtrar por status
const approved = all.filter(tx => tx.status === 'approved');
const pending = all.filter(tx => tx.status === 'pending');

getCacheStats()

Retorna estatísticas do cache de transações.

const stats = payments.getCacheStats();
console.log(stats);
// {
//     total: 150,
//     pending: 5,
//     approved: 120,
//     expired: 20,
//     cancelled: 3,
//     refunded: 2
// }

clearCache()

Limpa todo o cache de transações. Útil para resetar o estado do SDK.

payments.clearCache();

⚠️ Atenção: Isso remove todas as transações do cache, incluindo pendentes. O monitoramento continuará funcionando, mas não terá histórico das transações anteriores.

Módulo centralcart

O módulo centralcart fornece acesso direto à API do CentralCart.

Pacotes/Produtos

// Listar todos os pacotes
const response = await centralcart.getPackages();
const packages = response.data.data;

// Buscar pacote específico por ID
const pkg = await centralcart.getPackageById(123);

// Criar novo pacote
const newPkg = await centralcart.createPackage({
    name: 'VIP Premium',
    price: 49.90,
    // ... outros campos
});

// Atualizar pacote
await centralcart.updatePackage(123, {
    price: 59.90
});

// Deletar pacote
await centralcart.deletePackage(123);

Pedidos

// Buscar pedido por ID
const order = await centralcart.getOrder(12345);

// Listar pedidos com filtros
const orders = await centralcart.listOrders({
    status: 'approved',
    limit: 50
});

// Atualizar pedido
await centralcart.updateOrder(12345, {
    status: 'completed'
});

// Reenviar comandos do pedido
await centralcart.resendOrderCommands(12345);

Cupons

// Criar cupom de desconto
const coupon = await centralcart.createCoupon({
    code: 'DESCONTO20',
    discount: 20,
    type: 'percentage' // ou 'fixed'
});

// Deletar cupom
await centralcart.deleteCoupon(456);

Checkout

// Criar checkout customizado
const checkout = await centralcart.createCheckout({
    gateway: 'PIX',
    client_email: '[email protected]',
    client_document: '12345678900',
    client_name: 'Nome do Cliente',
    terms: true,
    client_discord: 'usuario#1234', // opcional
    variables: {}, // variáveis customizadas
    cart: [
        { package_id: 123, quantity: 1 },
        { package_id: 456, quantity: 2 }
    ]
});

Estatísticas

// Top clientes em um período
const top = await centralcart.getTopCustomers('2024-01-01', '2024-12-31');

// Total gasto por um usuário específico
const spent = await centralcart.getUserSpent('[email protected]');

Estrutura de Dados

Transação (Transaction)

{
    order_id: number,        // ID único do pedido
    product_id: number,      // ID do produto
    product_name: string,    // Nome do produto
    amount: number,          // Valor em reais
    status: string,          // 'pending' | 'approved' | 'expired' | 'cancelled' | 'refunded'
    client: {
        name: string,
        email: string,
        cpf: string
    },
    created_at: number,      // Timestamp de criação
    expires_at: number,      // Timestamp de expiração
    updated_at: number,      // Timestamp da última atualização
    paid_at: number | null,  // Timestamp do pagamento (se aprovado)
    expired_at: number | null, // Timestamp da expiração (se expirado)
    refunded_at: number | null // Timestamp do reembolso (se reembolsado)
}

Status de Transação

| Status | Descrição | |--------|-----------| | pending | Aguardando pagamento | | approved | Pagamento confirmado | | expired | Tempo de pagamento expirou | | cancelled | Pagamento cancelado | | refunded | Pagamento reembolsado |

Exemplos Completos

Bot de Vendas (Discord/Telegram)

import centralcart, { payments } from 'sdk-centralcart';

// Configuração
centralcart.init({
    apiKey: process.env.CENTRALCART_API_KEY,
    debug: process.env.NODE_ENV === 'development'
});

// Iniciar monitoramento global
payments.monitorTransactions({
    interval: 10000,
    onApproved: async (data) => {
        // Entregar produto ao cliente
        await bot.sendMessage(data.client.email, 
            `✅ Pagamento confirmado!\n` +
            `Produto: ${data.product_name}\n` +
            `Valor: R$ ${data.amount}`
        );
        
        // Ativar no sistema
        await ativarProduto(data.client.email, data.product_id);
    },
    onExpired: async (data) => {
        await bot.sendMessage(data.client.email,
            `⏰ Seu pagamento expirou.\n` +
            `Gere um novo PIX para continuar.`
        );
    }
});

// Função para processar compra
async function processarCompra(userId, productId) {
    const result = await payments.createPixPayment(productId, 1, {
        email: `${userId}@bot.local`,
        expirationMinutes: 30
    });
    
    if (result.status === 'success') {
        return {
            success: true,
            pixCode: result.data.pix_code,
            qrCode: result.data.qr_code,
            orderId: result.data.order_id,
            valor: result.data.amount,
            expiraEm: new Date(result.data.expires_at)
        };
    }
    
    return { success: false, error: result.data };
}

// Função para verificar status
async function verificarPagamento(orderId) {
    const tx = await payments.getTransaction(orderId, true); // força API
    return tx?.status || 'not_found';
}

API REST (Express)

import express from 'express';
import centralcart, { payments } from 'sdk-centralcart';

const app = express();
app.use(express.json());

centralcart.init({ apiKey: process.env.API_KEY });

// Iniciar monitor
payments.monitorTransactions({
    onApproved: (data) => {
        // Webhook ou processamento interno
        console.log('Pagamento aprovado:', data.order_id);
    }
});

// Criar pagamento
app.post('/api/payments/pix', async (req, res) => {
    const { productId, quantity, customer } = req.body;
    
    const result = await payments.createPixPayment(productId, quantity, {
        name: customer?.name,
        email: customer?.email,
        cpf: customer?.cpf,
        expirationMinutes: 30
    });
    
    res.json(result);
});

// Consultar pagamento
app.get('/api/payments/:orderId', async (req, res) => {
    const tx = await payments.getTransaction(req.params.orderId);
    
    if (!tx) {
        return res.status(404).json({ error: 'Transação não encontrada' });
    }
    
    res.json(tx);
});

// Estatísticas
app.get('/api/stats', (req, res) => {
    res.json(payments.getCacheStats());
});

app.listen(3000);

📋 Requisitos

• Node.js 18+ (usa fetch nativo)
• Conta no CentralCart
• API Key válida

🤝 Contribuindo

1. Fork o repositório
2. Crie sua branch: git checkout -b feature/minha-feature
3. Commit suas mudanças: git commit -m 'Adiciona minha feature'
4. Push: git push origin feature/minha-feature
5. Abra um Pull Request

📄 Licença

MIT © Triick

🔗 Links

• CentralCart
• NPM Package
• GitHub