node-asaas-api

v1.0.17

Published

2 years ago

Módulo para integração com a API do asaas.com.

Downloads

0High
0Medium
0Low

leonardo-machado

asaas asaas.com boleto cobrança

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

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);

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: '[email protected]',
    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 [email protected]!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

node-asaas-api

Índice

Versões Asaas API

Endpoints

Instalação

Utilização

Importação

Configuração

Integração de Cliente (customers)

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 (subscriptions)

Adicionar uma assinatura

Editar uma assinatura

Excluir uma assinatura

Obter uma assinatura

Listar as assinaturas

Contribuições