PagSeguro Subscription SDK

SDK para integração com a API de Assinaturas do PagSeguro.

Instalação

npm install pagseguro-subscription-sdk

Configuração

Para utilizar o SDK, você precisa inicializá-lo com suas credenciais do PagSeguro:

import { PagSeguro } from 'pagseguro-subscription-sdk';

// Inicialização com token
const pagseguro = new PagSeguro({
  token: 'seu-token-aqui',
  sandbox: true // use false para ambiente de produção
});

// Ou inicialização com appId e appKey
const pagseguro = new PagSeguro({
  appId: 'seu-app-id',
  appKey: 'sua-app-key',
  sandbox: true // use false para ambiente de produção
});

Módulos Disponíveis

Planos

O módulo de Planos permite gerenciar os planos de assinatura.

Criar um Plano

const plano = await pagseguro.plans.create({
  reference_id: 'plano-001',
  name: 'Plano Premium',
  description: 'Plano de assinatura premium',
  amount: {
    currency: 'BRL',
    value: 9990 // R$ 99,90
  },
  interval: {
    unit: 'MONTH',
    length: 1
  },
  trial: {
    days: 7,
    enabled: true,
    hold_setup_fee: false
  },
  payment_method: ['CREDIT_CARD']
});

console.log('Plano criado:', plano);

Consultar um Plano por ID

const plano = await pagseguro.plans.getById('PLAN_ID');
console.log('Plano:', plano);

Listar Planos

// Listar todos os planos
const planos = await pagseguro.plans.list();
console.log('Planos:', planos);

// Listar planos filtrando por reference_id
const planosFiltrados = await pagseguro.plans.list('reference_id');
console.log('Planos filtrados:', planosFiltrados);

Atualizar um Plano

const planoAtualizado = await pagseguro.plans.update('PLAN_ID', {
  name: 'Novo Nome do Plano',
  description: 'Nova descrição do plano',
  amount: {
    currency: 'BRL',
    value: 12990 // R$ 129,90
  }
});

console.log('Plano atualizado:', planoAtualizado);

Ativar um Plano

const planoAtivado = await pagseguro.plans.activate('PLAN_ID');
console.log('Plano ativado:', planoAtivado);

Inativar um Plano

const planoInativado = await pagseguro.plans.inactivate('PLAN_ID');
console.log('Plano inativado:', planoInativado);

Assinantes

O módulo de Assinantes permite gerenciar os assinantes (clientes) das assinaturas.

Criar um Assinante

const assinante = await pagseguro.subscribers.create({
  reference_id: 'assinante-001',
  name: 'João da Silva',
  email: '[email protected]',
  tax_id: '12345678909', // CPF (apenas números)
  phones: [
    {
      area: '11',
      country: '55',
      number: '999999999'
    }
  ],
  birth_date: '1990-01-01',
  address: {
    street: 'Avenida Paulista',
    number: '1578',
    complement: 'Apto 302',
    locality: 'Bela Vista',
    city: 'São Paulo',
    region_code: 'SP',
    country: 'BRA',
    postal_code: '01310200'
  }
});

console.log('Assinante criado:', assinante);

Consultar um Assinante por ID

const assinante = await pagseguro.subscribers.getById('CUSTOMER_ID');
console.log('Assinante:', assinante);

Listar Assinantes

// Listar todos os assinantes
const assinantes = await pagseguro.subscribers.list();
console.log('Assinantes:', assinantes);

// Listar assinantes com filtros
const assinantesFiltrados = await pagseguro.subscribers.list({
  reference_id: 'id-de-referencia',
  q: 'termo de busca' // Busca por nome, email ou documento
});
console.log('Assinantes filtrados:', assinantesFiltrados);

Atualizar um Assinante

const assinanteAtualizado = await pagseguro.subscribers.update('CUSTOMER_ID', {
  name: 'Novo Nome do Assinante',
  email: '[email protected]',
  phones: [
    {
      area: '21',
      country: '55',
      number: '988888888'
    }
  ]
});

console.log('Assinante atualizado:', assinanteAtualizado);

Atualizar Dados de Pagamento

const assinanteComPagamentoAtualizado = await pagseguro.subscribers.updateBillingInfo('CUSTOMER_ID', [
  {
    type: 'CREDIT_CARD',
    card: {
      token: 'CARD_TOKEN',
      holder: {
        name: 'JOAO DA SILVA'
      }
    }
  }
]);

console.log('Dados de pagamento atualizados:', assinanteComPagamentoAtualizado);

Assinaturas

O módulo de Assinaturas permite criar e gerenciar assinaturas, vinculando assinantes a planos.

Criar uma Assinatura

const assinatura = await pagseguro.subscriptions.create({
  reference_id: 'assinatura-001',
  plan: {
    id: 'PLAN_ID' // ID do plano criado anteriormente
  },
  customer: {
    id: 'CUSTOMER_ID' // ID do assinante criado anteriormente
  },
  payment_method: [
    {
      type: 'CREDIT_CARD',
      card: {
        token: 'CARD_TOKEN',
        security_code: '123'
      }
    }
  ],
  pro_rata: true,
  best_invoice_date: {
    day: 15 // Dia 15 de cada mês
  }
});

console.log('Assinatura criada:', assinatura);

Consultar uma Assinatura por ID

const assinatura = await pagseguro.subscriptions.getById('SUBSCRIPTION_ID');
console.log('Assinatura:', assinatura);

Listar Assinaturas

// Listar todas as assinaturas
const assinaturas = await pagseguro.subscriptions.list();
console.log('Assinaturas:', assinaturas);

// Listar assinaturas com filtros
const assinaturasFiltradas = await pagseguro.subscriptions.list({
  status: ['ACTIVE', 'TRIAL'],
  payment_method_type: ['CREDIT_CARD'],
  created_at_start: '2023-01-01',
  created_at_end: '2023-12-31'
});
console.log('Assinaturas filtradas:', assinaturasFiltradas);

Atualizar uma Assinatura

const assinaturaAtualizada = await pagseguro.subscriptions.update('SUBSCRIPTION_ID', {
  next_invoice_at: '2023-12-01',
  amount: {
    currency: 'BRL',
    value: 12990 // R$ 129,90
  },
  best_invoice_date: {
    day: 10 // Dia 10 de cada mês
  },
  pro_rata: true
});

console.log('Assinatura atualizada:', assinaturaAtualizada);

Cancelar uma Assinatura

const assinaturaCancelada = await pagseguro.subscriptions.cancel('SUBSCRIPTION_ID');
console.log('Assinatura cancelada:', assinaturaCancelada);

Suspender uma Assinatura

const assinaturaSuspensa = await pagseguro.subscriptions.suspend('SUBSCRIPTION_ID');
console.log('Assinatura suspensa:', assinaturaSuspensa);

Ativar uma Assinatura

const assinaturaAtivada = await pagseguro.subscriptions.activate('SUBSCRIPTION_ID');
console.log('Assinatura ativada:', assinaturaAtivada);

Listar Faturas de uma Assinatura

const faturas = await pagseguro.subscriptions.listInvoices('SUBSCRIPTION_ID', {
  status: ['PAID', 'UNPAID', 'WAITING', 'OVERDUE'],
  offset: 0,
  limit: 10
});
console.log('Faturas da assinatura:', faturas);

Pagamentos

O módulo de Pagamentos permite gerenciar faturas, pagamentos e estornos relacionados às assinaturas.

Consultar uma Fatura

const fatura = await pagseguro.payments.getInvoice('INVOICE_ID');
console.log('Fatura:', fatura);

Listar Pagamentos de uma Fatura

const pagamentos = await pagseguro.payments.listInvoicePayments('INVOICE_ID');
console.log('Pagamentos da fatura:', pagamentos);

Consultar um Pagamento

const pagamento = await pagseguro.payments.getPayment('PAYMENT_ID');
console.log('Pagamento:', pagamento);

Criar um Estorno

// Estorno total
const estorno = await pagseguro.payments.createRefund('PAYMENT_ID');
console.log('Estorno criado:', estorno);

// Estorno parcial (quando disponível)
const estornoParcial = await pagseguro.payments.createRefund('PAYMENT_ID', {
  amount: {
    currency: 'BRL',
    value: 5000 // R$ 50,00
  }
});
console.log('Estorno parcial criado:', estornoParcial);

Consultar um Estorno

const estorno = await pagseguro.payments.getRefund('REFUND_ID');
console.log('Estorno:', estorno);

Listar Estornos de um Pagamento

const estornos = await pagseguro.payments.listPaymentRefunds('PAYMENT_ID');
console.log('Estornos do pagamento:', estornos);

Listar Estornos do Vendedor

const estornos = await pagseguro.payments.listRefunds();
console.log('Estornos do vendedor:', estornos);

Listar Pagamentos

// Listar todos os pagamentos
const pagamentos = await pagseguro.payments.listPayments();
console.log('Pagamentos:', pagamentos);

// Listar pagamentos com filtros
const pagamentosFiltrados = await pagseguro.payments.listPayments({
  status: ['PAID', 'REFUNDED'],
  created_at_start: '2023-01-01',
  created_at_end: '2023-12-31'
});
console.log('Pagamentos filtrados:', pagamentosFiltrados);

Idempotência

Todas as operações de criação, atualização, ativação e inativação aceitam uma chave de idempotência opcional como segundo parâmetro:

const plano = await pagseguro.plans.create({
  // ... parâmetros do plano
}, 'chave-de-idempotencia-unica');

Tratamento de Erros

O SDK lança exceções do tipo PagSeguroApiError quando ocorre um erro na API:

try {
  const plano = await pagseguro.plans.getById('PLAN_INEXISTENTE');
} catch (error) {
  if (error.name === 'PagSeguroApiError') {
    console.error('Erro na API do PagSeguro:', error.message);
    console.error('Status HTTP:', error.status);
    console.error('Detalhes:', error.data);
  } else {
    console.error('Erro desconhecido:', error);
  }
}

Desenvolvimento

Pré-requisitos

• Node.js 14 ou superior
• npm ou yarn

Instalação das dependências

npm install

Compilação

npm run build

Testes

npm test

Licença

ISC