node-asaas-api

Statements	Branches	Functions	Lines

Módulo para integração com o serviço de cobrança Asaas.com.

Índice

• Versões Asaas API
• Endpoints
• Instalação
• Utilização
  • Importação
  • Configuração
• Integração de Clientes
  • Adicionar um novo cliente
  • Editar um cliente
  • Excluir um cliente
  • Restaurar um cliente excluído
  • Obter um cliente
  • Listar os clientes
• Integração de Assinaturas
  • Adicionar uma assinatura
  • Editar uma assinatura
  • Excluir uma assinatura
  • Obter uma assinatura
  • Listar as assinaturas
• Contribuições

Versões Asaas API

V2	V3
✗	✔

Endpoints

Endpoint	Estado
customers	✔
subscriptions	✔ Criar ✔ Obter ✔ Listar ✔ Alterar ✔ Remover ✗ Listar Notas Fiscais ✗ Configurar Emissão de Nota Fiscal ✗ Atualizar Configuração Emissão de Nota Fiscal ✗ Obter Configuração Emissão de Nota Fiscal ✗ Remover Configuração Emissão de Nota Fiscal
payments	✗
installments	✗
notifications	✗
finance	✗
transfers	✗
anticipations	✗
paymentDunnings	✗
bill	✗
financialTransactions	✗
myAccount	✗
invoices	✗
customerFiscalInfo	✗
webhook	✗
accounts	✗

Instalação

$ npm install node-asaas-api --save

Utilização

Importação

Inicialmente deve ser feito a importação do pacote dentro do arquivo fonte onde será utilizado, conforme código abaixo. O retorno é uma instância de asaasAPI.

const asaasAPI = require('node-asaas-api');

Configuração

A configuração é realizada por meio do método .config(), que recebe como parâmtro um objeto com os seguintes atributos:

let params = {
    environment: asaasAPI.SANDBOX,
    apiKey: '<Chave-da-API-Gerada-para-o-Ambiente>',
    version: 'v3',
    debug: false
};
 
asaasAPI.config(params);

Caso não seja passado um objeto para o método .config() os valores padrão de configuração são:

{
  environment: asaasAPI.SANDBOX,
  apiKey: '',
  version: 'v3',
  debug: false
}

O objeto asaasAPI fornece duas constantes para indicar o ambiente que o componente acessará, que são: asaasAPI.SANDBOX e asaasAPI.PRODUCTION. Assim, pode-se configurar o componente da seguinte forma:

let params = {
    environment: asaasAPI.SANDBOX,
    apiKey: '<Chave-da-API-SANDBOX>'
};
 
asaasAPI.config(params);

OU

let params = {
    environment: asaasAPI.PRODUCTION,
    apiKey: '<Chave-da-API-PRODUCTION>'
};
 
asaasAPI.config(params);

Para obter a configuração atual do componente pode-se invocar o método .config() sem a passagem de parâmetro.

let conf = asaasAPI.config();

Observação: Quando o parâmetro debug = true o componente imprime no console o método executado, o recurso do Asaas invocado e os parâmetros fornecidos.

Integração de Cliente (customers)

A integração de clientes é realizada por meio do atributo asaasAPI.customers, utilizando os respectivos métodos para cada operação desejada.

Adicionar um novo cliente

Para adicionar um novo cliente utiliza-se o método asaasAPI.customers.post(), ele recebe um objeto com os dados do cliente e retorna uma Promise com a chamada da API.

const asaasAPI = require('node-asaas-api');
 
asaasAPI.config({environment: asaasAPI.SANDBOX, apiKey: 'CHAVE-SANDBOX'});
 
let cliente = {
    externalReference: 1234, 
    name: 'Nome do cliente', 
    cpfCnpj: '12345678901',
    email: '[e-mail]',
    mobilePhone: '11988776655',
    ..., /* demais atributos do cliente */
    ...
};
 
asaasAPI.customers.post(cliente).then((res)=>{
    console.log('Cliente Cadastrado');
    /* O retorno é todos os dados do cliente cadastrado */
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro no cadastro do cliente');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Os atributos disponíveis para o cliente são:

{
  name: String, // Obrigatório
  cpfCnpj: String, // Obrigatório
  email: String,
  phone: String,
  mobilePhone: String,
  postalCode: String,
  address: String,
  addressNumber: String,
  complement: String,
  province: String,
  externalReference: String,
  notificationDisabled: Boolean,
  additionalEmails: String,
  municipalInscription: String,
  stateInscription: String,
  observations: String,
  groupName: String,
  company: String
}

Nota:

Para obter a lista completa de campos disponíveis para o cliente acesse a documentação do Asaas clicando aqui.

Editar um cliente

Para editar um cliente cadastrado utiliza-se o método asaasAPI.customers.put(), este método recebe o ID do registro a ser editado e um objeto com os dados atualizados do cliente, o retorno é uma Promise.

// *** Importação e Configuração do componente ***
 
let cliente = {
    name: 'Nome do cliente alterado',
    company: 'Empresa S/A',
    ..., /* demais atributos alterados */ 
    ...
};
 
// O ID 'cus_000002875000' foi retornado quando o cliente foi criado com o .post()
asaasAPI.customers.put('cus_000002875000', cliente).then((res)=>{
    console.log('Cliente Atualizado');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro no cadastro do cliente');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Excluir um cliente

A exclusão de um cliente é realizada por meio do método asaasAPI.customers.delete(), este método recebe o ID do cliente a ser excluído e retorna uma Promise.

// O ID 'cus_000002875000' foi retornado quando o cliente foi criado com o .post()
asaasAPI.customers.delete('cus_000002875000').then((res)=>{
    console.log('Cliente removido');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao remover o cliente');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Restaurar um cliente excluído

Para restaurar o registro de um cliente excluído utiliza-se o método asaasAPI.customers.restore(), este método recebe o ID do cliente a ser restaurado e retorna uma Promise.

// O ID 'cus_000002875000' foi retornado quando o cliente foi criado com o .post()
asaasAPI.customers.restore('cus_000002875000').then((res)=>{
    console.log('Cliente restaurado');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao restaurar o cliente');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Obter um cliente

Para obter o registro de um cliente utiliza-se o método asaasAPI.customers.get(), este método recebe o ID do cliente e retorna uma Promise.

let id = 'cus_000002872237';
 
asaasAPI.customers.get(id).then((res)=>{
    console.log('Obtem um Cliente');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao obter cliente');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Listar os clientes

Para listar os registros de clientes utiliza-se o método asaasAPI.customers.list(), este método recebe um objeto com os filtros da pesquisa e retorna uma Promise.

let filtro = {
    cpfCnpj: '12345678901',
    offset: 0,
    limit: 10
};
 
asaasAPI.customers.list(filtro).then((res)=>{
    console.log('Lista de Clientes');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao obter clientes');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Os atributos possíveis para o filtro de clientes são:

{
   name: String,
   email: String,
   cpfCnpj: String,
   groupName: String,
   externalReference: String,
   offset: Number, // Opcional: Elemento inicial da lista (default: 0)
   limit: Number   // Opcional: Quantidade de elementos da lista (default: 10, máx: 100)
}

Nota:

Para obter a lista completa de filtros disponíveis para o cliente acesse a documentação do Asaas clicando aqui.

Integração de Assinaturas (subscriptions)

A integração de assinaturas é realizada por meio do atributo asaasAPI.subscriptions, utilizando os respectivos métodos para cada operação desejada.

Adicionar uma assinatura

Para adicionar uma nova assinatura para um cliente utiliza-se o método asaasAPI.subscriptions.post(), ele recebe um objeto com os dados da assinatura e retorna uma Promise com a chamada da API.

let assinatura = {
    customer: 'cus_000002872237', // ID retornado pela integração de cliente
    billingType: 'BOLETO', 
    value: 15,
    nextDueDate: '2020-09-15',
    cycle: 'MONTHLY',
    description: 'Descrição da assinatura'
};
 
asaasAPI.subscriptions.post(assinatura).then((res)=>{
    console.log('Assinatura adicionada para o Cliente');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro no cadastro da assinatura');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Nota:

Para obter a lista completa de campos disponíveis para a assinatura acesse a documentação do Asaas clicando aqui.

Editar uma assinatura

Para alterar os dados de uma assinatura utiliza-se o método asaasAPI.subscriptions.put(), este método recebe o ID do registro a ser editado e um objeto com os dados atualizados da assinatura, o retorno é uma Promise.

let id = 'sub_k55Oi2Sv6MiZ'; // ID retornado quando a Assinatura foi criada.
 
let assinatura = {
    value: 25, // Alterando o valor da assinatura.
    description: 'Nova descrição para a assinatura',
    updatePendingPayments: true // Indica que devem ser alteradas as faturas pendentes.
};
 
asaasAPI.subscriptions.put(id, assinatura).then((res)=>{
    console.log('Assinatura alterada!');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro na alteração da assinatura');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Nota:

Mais informações sobre a alteração de assinaturas pode ser obtidas na documentação do Asaas clicando aqui.

Excluir uma assinatura

A exclusão de uma assinatura é realizada por meio do método asaasAPI.subscriptions.delete(), este método recebe o ID da assinatura a ser excluída e retorna uma Promise.

// O ID 'sub_XdehrfHjGzPL' foi retornado quando a assinatura foi criada com o .post()
asaasAPI.subscriptions.delete('sub_XdehrfHjGzPL').then((res)=>{
    console.log('Assinatura removida');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao remover a assinatura');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Obter uma assinatura

Para obter o registro de uma assinatura utiliza-se o método asaasAPI.subscriptions.get(), este método recebe o ID da assinatura e retorna uma Promise.

let id = 'sub_k55Oi2Sv6MiZ1';
 
asaasAPI.subscriptions.get(id).then((res)=>{
    console.log('Obtem uma assinatura');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao obter assinatura');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Listar as assinaturas

Para listar os registros de assinaturas utiliza-se o método asaasAPI.subscriptions.list(), este método recebe um objeto com os filtros da pesquisa e retorna uma Promise.

let filtros = {
    customer: 'cus_000002872237',
    offset: 0,
    limit: 10
};
 
asaasAPI.subscriptions.list(filtros).then((res)=>{
    console.log('Lista de Assinaturas');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao obter assinaturas');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Os atributos possíveis para o filtro de assinaturas são:

{
   customer: String,
   billingType: Enum,
   includeDeleted: Boolean,
   offset: Number, // Opcional: Elemento inicial da lista (default: 0)
   limit: Number // Opcional: Quantidade de elementos da lista (default: 10, máx: 100)
}

Nota:

Para obter mais informações sobre a pesquisa de assinaturas acesse a documentação do Asaas clicando aqui.

Contribuições

Este é um módulo não oficial e ainda está em desenvolvimento.

Se desejar contribuir para o desenvolvimento favor entrar em contato com [e-mail]!