@criapix/saas-assinaturas-client
Version:
SDK JavaScript/TypeScript para o AssinaturasService - Sistema de gestão de assinaturas SaaS com processamento de pagamentos de faturas (cartão, PIX, débito), gerenciamento de métodos de pagamento, pagamentos recorrentes e análise de falhas de pagamento
444 lines • 16.2 kB
JavaScript
import axios from 'axios';
import { normalizeCardExpiryDate } from '../utils/cardExpiryDateValidator';
export class AssinaturasServiceClient {
constructor(baseURL) {
this.authToken = null;
this.client = axios.create({
baseURL,
timeout: 30000,
headers: {
'Content-Type': 'application/json',
},
});
// Interceptor para adicionar token de autenticação
this.client.interceptors.request.use((config) => {
if (this.authToken) {
config.headers.Authorization = `Bearer ${this.authToken}`;
}
return config;
});
// Interceptor para tratamento de erros
this.client.interceptors.response.use((response) => response, (error) => {
if (error.response?.status === 404) {
// Retornar null para 404 em alguns casos específicos
return Promise.resolve({ data: null });
}
return Promise.reject(error);
});
}
/**
* Define o token de autenticação JWT
*/
setAuthorizationToken(token) {
this.authToken = token;
}
// ==================== Customers ====================
/**
* Cria um novo cliente
*/
async createCustomer(request) {
const { data } = await this.client.post('/Customers', request);
return data;
}
/**
* Busca um cliente por ID
* @returns O cliente encontrado ou null se não existir
*/
async getCustomer(id) {
const { data } = await this.client.get(`/Customers/${id}`);
return data;
}
// ==================== Subscription Plans ====================
/**
* Cria um novo plano de assinatura
*/
async createSubscriptionPlan(request) {
const { data } = await this.client.post('/SubscriptionPlans', request);
return data;
}
/**
* Busca um plano de assinatura por ID
* @returns O plano encontrado ou null se não existir
*/
async getSubscriptionPlan(id) {
const { data } = await this.client.get(`/SubscriptionPlans/${id}`);
return data;
}
/**
* Lista planos de assinatura com filtros opcionais
*/
async listSubscriptionPlans(filter) {
const params = {
page: filter?.page ?? 1,
pageSize: filter?.pageSize ?? 10,
};
if (filter?.name)
params.name = filter.name;
if (filter?.isActive !== undefined)
params.isActive = filter.isActive;
if (filter?.isDefault !== undefined)
params.isDefault = filter.isDefault;
const { data } = await this.client.get('/SubscriptionPlans', { params });
return data;
}
/**
* Atualiza um plano de assinatura existente
*/
async updateSubscriptionPlan(id, request) {
const { data } = await this.client.put(`/SubscriptionPlans/${id}`, request);
return data;
}
/**
* Deleta um plano de assinatura
*/
async deleteSubscriptionPlan(id) {
await this.client.delete(`/SubscriptionPlans/${id}`);
}
// ==================== Subscriptions ====================
/**
* Cria uma nova assinatura
*/
async createSubscription(request) {
const { data } = await this.client.post('/Subscriptions', request);
return data;
}
/**
* Busca uma assinatura por ID
* @returns A assinatura encontrada ou null se não existir
*/
async getSubscription(id) {
const { data } = await this.client.get(`/Subscriptions/${id}`);
return data;
}
/**
* Lista assinaturas com filtros opcionais
*/
async listSubscriptions(filter) {
const params = {
page: filter?.page ?? 1,
pageSize: filter?.pageSize ?? 10,
};
if (filter?.customerId)
params.customerId = filter.customerId;
if (filter?.subscriptionPlanId)
params.subscriptionPlanId = filter.subscriptionPlanId;
if (filter?.status !== undefined)
params.status = filter.status;
const { data } = await this.client.get('/Subscriptions', {
params,
});
return data;
}
/**
* Atualiza uma assinatura existente
*/
async updateSubscription(id, request) {
const { data } = await this.client.put(`/Subscriptions/${id}`, request);
return data;
}
/**
* Cancela uma assinatura
*/
async cancelSubscription(id, cancellationReason) {
const { data } = await this.client.post(`/Subscriptions/${id}/cancel`, {
cancellationReason,
});
return data;
}
/**
* Ativa uma assinatura com primeiro pagamento após período de trial
* Este endpoint encontra a fatura pendente atual e processa o pagamento
* @param subscriptionId - ID da assinatura
* @param request - Requisição com detalhes do cartão para ativação
* @returns Resultado da ativação da assinatura
*/
async activateSubscriptionWithPayment(subscriptionId, request) {
const { data } = await this.client.post(`/Subscriptions/${subscriptionId}/activate-with-payment`, request);
return data;
}
/**
* Atualiza o método de pagamento de uma assinatura
* Pode opcionalmente processar um pagamento de fatura pendente ao atualizar o método
* @param subscriptionId - ID da assinatura
* @param request - Requisição com novos detalhes do cartão
* @returns Resultado do processamento do pagamento (se fatura fornecida) ou confirmação de sucesso
*/
async updatePaymentMethod(subscriptionId, request) {
// Normalize cardExpiryDate to ISO 8601 format before sending to API
const normalizedRequest = {
...request,
cardExpiryDate: normalizeCardExpiryDate(request.cardExpiryDate),
};
const { data } = await this.client.put(`/Subscriptions/${subscriptionId}/payment-method`, normalizedRequest);
return data;
}
// ==================== Invoices ====================
/**
* Busca uma fatura por ID
* @returns A fatura encontrada ou null se não existir
*/
async getInvoice(id) {
const { data } = await this.client.get(`/Invoices/${id}`);
return data;
}
/**
* Lista faturas com filtros opcionais
*/
async listInvoices(filter) {
const params = {
page: filter?.page ?? 1,
pageSize: filter?.pageSize ?? 10,
};
if (filter?.subscriptionId)
params.subscriptionId = filter.subscriptionId;
if (filter?.status !== undefined)
params.status = filter.status;
if (filter?.dueDateFrom)
params.dueDateFrom = filter.dueDateFrom;
if (filter?.dueDateTo)
params.dueDateTo = filter.dueDateTo;
const { data } = await this.client.get('/Invoices', { params });
return data;
}
/**
* Gera uma nova fatura
*/
async generateInvoice(request) {
const { data } = await this.client.post('/Invoices/generate', request);
return data;
}
/**
* Atualiza o status de uma fatura
*/
async updateInvoiceStatus(id, request) {
const { data } = await this.client.put(`/Invoices/${id}/status`, request);
return data;
}
/**
* Gera faturas em lote para todas as assinaturas ativas
*/
async generateBatchInvoices(request) {
const { data } = await this.client.post('/Invoices/generate-batch', request);
return data;
}
/**
* Obtém estatísticas agregadas de faturas
* @param startDate - Data inicial do filtro (opcional)
* @param endDate - Data final do filtro (opcional)
* @param condominiumId - ID do condomínio para filtrar (opcional)
* @returns Estatísticas das faturas
*/
async getInvoiceStatistics(startDate, endDate, condominiumId) {
const params = {};
if (startDate)
params.startDate = startDate;
if (endDate)
params.endDate = endDate;
if (condominiumId)
params.condominiumId = condominiumId;
const { data } = await this.client.get('/Invoices/statistics', { params });
return data;
}
// ==================== Invoice Payments ====================
/**
* Processa o primeiro pagamento após período de trial com tokenização de cartão
* Armazena o método de pagamento para pagamentos recorrentes futuros
* @param invoiceId - ID da fatura
* @param request - Requisição com token do cartão e informações do cliente
* @returns Resultado do processamento do pagamento
*/
async processFirstPayment(invoiceId, request) {
// Normalize cardExpiryDate to ISO 8601 format before sending to API
const normalizedRequest = {
...request,
cardExpiryDate: normalizeCardExpiryDate(request.cardExpiryDate),
};
const { data } = await this.client.post(`/Invoices/${invoiceId}/process-first-payment`, normalizedRequest);
return data;
}
/**
* Processa pagamento recorrente mensal usando método de pagamento armazenado
* @param invoiceId - ID da fatura
* @param request - Requisição de pagamento recorrente (vazio, apenas invoiceId na URL)
* @returns Resultado do processamento do pagamento
*/
async processRecurringPayment(invoiceId, request = {}) {
const { data } = await this.client.post(`/Invoices/${invoiceId}/process-recurring-payment`, request);
return data;
}
/**
* Processa pagamento PIX
* Gera QR Code para pagamento instantâneo
* @param invoiceId - ID da fatura
* @param request - Requisição de pagamento PIX com informações do cliente
* @returns Resultado do processamento com QR Code
*/
async processPixPayment(invoiceId, request) {
const { data } = await this.client.post(`/Invoices/${invoiceId}/process-pix-payment`, request);
return data;
}
/**
* Processa pagamento com cartão de débito
* Pagamento imediato, sem capacidade de recorrência
* @param invoiceId - ID da fatura
* @param request - Requisição de pagamento com token do cartão de débito e informações do cliente
* @returns Resultado do processamento do pagamento
*/
async processDebitPayment(invoiceId, request) {
// Normalize cardExpiryDate to ISO 8601 format before sending to API
const normalizedRequest = {
...request,
cardExpiryDate: normalizeCardExpiryDate(request.cardExpiryDate),
};
const { data } = await this.client.post(`/Invoices/${invoiceId}/process-debit-payment`, normalizedRequest);
return data;
}
// ==================== Subscription Status ====================
/**
* Obtém o status completo da assinatura de um cliente
* @returns Status completo ou null se não encontrado
*/
async getSubscriptionStatus(customerId) {
const { data } = await this.client.get(`/subscription-status/${customerId}`);
return data;
}
/**
* Verifica se o cliente está ativo (status simples)
*/
async getSimpleStatus(customerId) {
const { data } = await this.client.get(`/subscription-status/${customerId}/is-active`);
return data;
}
/**
* Verifica se o cliente está inadimplente
*/
async isDelinquent(customerId) {
const { data } = await this.client.get(`/subscription-status/${customerId}/is-delinquent`);
return data;
}
// ==================== Payments ====================
/**
* Cria um pagamento avulso (one-time)
*/
async createOneTimePayment(request) {
const { data } = await this.client.post('/Payments/one-time', request);
return data;
}
/**
* Cria um pagamento recorrente
*/
async createRecurringPayment(request) {
const { data } = await this.client.post('/Payments/recurring', request);
return data;
}
/**
* Processa um pagamento com token de cartão
*/
async processPayment(paymentId, request) {
const { data } = await this.client.post(`/Payments/${paymentId}/process`, request);
return data;
}
/**
* Busca um pagamento por ID
* @returns O pagamento encontrado ou null se não existir
*/
async getPayment(paymentId) {
const { data } = await this.client.get(`/Payments/${paymentId}`);
return data;
}
/**
* Lista pagamentos com filtros opcionais
* @param query - Filtros de busca (customerId, subscriptionId, status)
*/
async listPayments(query) {
const params = {};
if (query?.customerId)
params.customerId = query.customerId;
if (query?.subscriptionId)
params.subscriptionId = query.subscriptionId;
if (query?.status !== undefined)
params.status = query.status;
if (query?.page)
params.page = query.page;
if (query?.pageSize)
params.pageSize = query.pageSize;
const { data } = await this.client.get('/Payments', { params });
return data;
}
/**
* Obtém o método de pagamento de uma assinatura
* @param subscriptionId - ID da assinatura
* @returns Informações do método de pagamento ou null se não existir
*/
async getPaymentMethod(subscriptionId) {
const { data } = await this.client.get(`/Subscriptions/${subscriptionId}/payment-method`);
return data;
}
/**
* Cancela um pagamento recorrente
*/
async cancelPayment(paymentId, request) {
const { data } = await this.client.delete(`/Payments/${paymentId}`, { data: request });
return data;
}
// ==================== Payment Accounts ====================
/**
* Cria uma nova conta de pagamento (credenciais Mercado Pago)
*/
async createPaymentAccount(request) {
const { data } = await this.client.post('/PaymentAccounts', request);
return data;
}
/**
* Busca uma conta de pagamento por ID
* @returns A conta encontrada ou null se não existir
*/
async getPaymentAccount(accountId) {
const { data } = await this.client.get(`/PaymentAccounts/${accountId}`);
return data;
}
/**
* Busca a conta de pagamento padrão
* @returns A conta padrão ou null se não existir
*/
async getDefaultPaymentAccount() {
const { data } = await this.client.get('/PaymentAccounts/default');
return data;
}
/**
* Lista todas as contas de pagamento
*/
async listPaymentAccounts() {
const { data } = await this.client.get('/PaymentAccounts');
return data;
}
// ==================== Subscription Access ====================
/**
* Verifica se um cliente tem acesso ao sistema
* @param customerId - ID do cliente
* @returns Informações de acesso do cliente
*/
async checkAccess(customerId) {
const { data } = await this.client.get(`/SubscriptionAccess/check-access`, { params: { customerId } });
return data;
}
/**
* Verifica acesso para um cliente específico (rota alternativa)
* @param customerId - ID do cliente
* @returns Informações de acesso do cliente
*/
async checkAccessByCustomer(customerId) {
const { data } = await this.client.get(`/SubscriptionAccess/customers/${customerId}/access`);
return data;
}
/**
* Verifica acesso para múltiplos clientes em uma única requisição
* @param request - Lista de IDs de clientes (máx 100)
* @returns Lista de status de acesso para cada cliente
*/
async checkAccessBatch(request) {
const { data } = await this.client.post('/SubscriptionAccess/check-access-batch', request);
return data;
}
}
//# sourceMappingURL=AssinaturasServiceClient.js.map