node-asaas-api v1.0.17
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
- Integração de Clientes
- Integração de 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: 'nome@dominio.com.br',
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 leonardo.davi.machado@gmail.com!