asaas-sdk-node

SDK em Node.js (TypeScript/JavaScript) para integração com a API Asaas v3. Uso em Express, NestJS ou qualquer app Node.

• Documentação Asaas
• API Key em Minha Conta > Integração (produção) ou Sandbox.

Instalação

npm install asaas-sdk-node

Configuração

A API Key pode ser definida de duas formas (ou ambas; a config da instância tem prioridade):

1. Variáveis de ambiente

ASAAS_API_KEY=sua_chave_api
ASAAS_ENV=sandbox

• ASAAS_ENV: sandbox ou production (padrão: sandbox).

2. Parâmetros na instância

import { AsaasClient } from 'asaas-sdk-node';

const client = new AsaasClient({
  apiKey: 'sua_chave_api',
  environment: 'sandbox', // ou 'production'
});

// Ou URL base customizada
const clientCustom = new AsaasClient({
  apiKey: 'sua_chave_api',
  baseUrl: 'https://www.asaas.com',
});

Uso

TypeScript / JavaScript (CommonJS)

const { AsaasClient } = require('asaas-sdk-node');

const asaas = new AsaasClient({ apiKey: process.env.ASAAS_API_KEY, environment: 'sandbox' });

// Clientes
const customer = await asaas.customers.create({
  name: 'João',
  cpfCnpj: '24971563792',
  email: '[email protected]',
});
const list = await asaas.customers.list({ limit: 10 });

// Cobranças
const payment = await asaas.payments.create({
  customer: customer.id,
  billingType: 'BOLETO',
  dueDate: '2025-12-31',
  value: 100,
  description: 'Pedido 001',
});
const pixQr = await asaas.payments.getPixQrCode(payment.id);

Express

import express from 'express';
import { AsaasClient } from 'asaas-sdk-node';

const app = express();
const asaas = new AsaasClient(); // usa ASAAS_API_KEY e ASAAS_ENV do env

app.post('/clientes', async (req, res) => {
  try {
    const customer = await asaas.customers.create(req.body);
    res.json(customer);
  } catch (err) {
    res.status(err.status ?? 500).json({ error: err.message });
  }
});

NestJS

Injete o AsaasClient onde precisar (ex.: factory com ConfigService):

import { AsaasClient } from 'asaas-sdk-node';

// No módulo ou provider
const asaas = new AsaasClient({
  apiKey: configService.get<string>('ASAAS_API_KEY'),
  environment: configService.get('ASAAS_ENV') ?? 'sandbox',
});

Módulos

Esta seção é atualizada conforme novos serviços são implementados.

✅ Prontos

| Módulo | Acesso no client | Principais métodos | |--------|------------------|--------------------| | Clientes | asaas.customers | create, getById, list, update, delete, restore | | Cobranças | asaas.payments | create, getById, list, update, delete, restore, refund, getDigitableLine, getPixQrCode, receiveInCash, undoReceivedInCash | | Antecipações | asaas.anticipations | simulate, create, getById, list | | Parcelamentos | asaas.installments | getById, list, delete, refund | | Notificações | asaas.notifications | update | | Assinaturas | asaas.subscriptions | create, getById, list, listPayments, listInvoices, update, delete, createInvoiceSettings, getInvoiceSettings, updateInvoiceSettings, deleteInvoiceSettings | | Transferências | asaas.transfers | createToBank, createToAsaas, getById, list | | Webhooks | asaas.webhooks | getPayment, updatePayment, getInvoice, updateInvoice | | Links de pagamento | asaas.paymentLinks | create, getById, list, update, delete, restore, addImage, listImages, getImage, deleteImage, setImageAsMain | | Informações da conta | asaas.account | getCommercialInfo, updateCommercialInfo, getFees, getWallets, getPaymentCheckoutConfig, updatePaymentCheckoutConfig, updatePaymentCheckoutConfigFormData | | Pix (chaves, QR estático, transações) | asaas.pix | createAddressKey, listAddressKeys, getAddressKeyById, deleteAddressKey, createStaticQrCode, listTransactions | | Recuperações (negativações) | asaas.dunnings | create, simulate, listPaymentsAvailable, list, getById, cancel, resendDocuments, listHistory, listPartialPayments | | Extrato | asaas.statement | list | | Informações fiscais | asaas.fiscalInfo | get, getMunicipalOptions, createOrUpdate | | Notas fiscais | asaas.invoices | list, getById, schedule, update, authorize, cancel, listMunicipalServices | | Pagamento de contas | asaas.bills | list, getById, simulate, create, cancel | | Contas Asaas (subcontas) | asaas.subAccounts | list, getById, create | | Consulta Serasa | asaas.creditBureau | consult, getById, list |

Erros

Em falhas da API (4xx/5xx) é lançado AsaasApiError com message, status e body (quando houver):

import { AsaasApiError } from 'asaas-sdk-node';

try {
  await asaas.payments.getById('id_invalido');
} catch (err) {
  if (err instanceof AsaasApiError) {
    console.log(err.status, err.message, err.body);
  }
}

Em erros de configuração (ex.: apiKey ausente), é lançado AsaasConfigError (apenas message).

Scripts do projeto

• npm run build – gera dist/
• npm run test – testes
• npm run test:ci – testes com cobertura (mín. 75%)
• npm run lint – ESLint
• npm run format – Prettier (escreve)
• npm run format:check – Prettier (apenas verifica)

Contribuindo

• Problemas ou pedidos de funcionalidade: abra uma issue descrevendo o problema ou a sugestão, ou entre em contato por e-mail ou LinkedIn.
• Correções e melhorias: envie um pull request. Faça um fork do repositório, crie uma branch para sua alteração e abra o PR referenciando a issue (se houver).

Autor

Hallison Melo — Desenvolvedor Full Stack com foco em JavaScript/TypeScript, Node.js, Vue, React e React Native. Atua em frontend, backend e mobile.

• E-mail: [email protected]
• GitHub: github.com/hallss93
• LinkedIn: linkedin.com/in/hallss93

Licença

MIT