asaas-sdk

| 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 Pagamentos
  • Adicionar um novo pagamento
  • Listar os pagamentos
  • Obter um pagamento
  • Excluir um pagamento
  • Editar um pagamento
  • Estornar um pagamento
• 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 | ✔ Criar✔ Listar✔ Obter✔ Estornar✔ Alterar✔ Remover | | installments | ✗ | | notifications | ✗ | | finance | ✗ | | transfers | ✗ | | anticipations | ✗ | | paymentDunnings | ✗ | | bill | ✗ | | financialTransactions | ✗ | | myAccount | ✗ | | invoices | ✗ | | customerFiscalInfo | ✗ | | webhook | ✗ | | accounts | ✗ |

Instalação

$ npm install asaas-sdk --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 asaasSDK.

const asaasSDK = require("asaas-sdk");

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: asaasSDK.SANDBOX,
  apiKey: "<Chave-da-API-Gerada-para-o-Ambiente>",
  version: "v3",
  debug: false,
};

asaasSDK.config(params);

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

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

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

let params = {
  environment: asaasSDK.SANDBOX,
  apiKey: "<Chave-da-API-SANDBOX>",
};

asaasSDK.config(params);

OU

let params = {
  environment: asaasSDK.PRODUCTION,
  apiKey: "<Chave-da-API-PRODUCTION>",
};

asaasSDK.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 = asaasSDK.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 asaasSDK.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 asaasSDK.customers.post(), ele recebe um objeto com os dados do cliente e retorna uma Promise com a chamada da API.

const asaasSDK = require('asaas-sdk');

asaasSDK.config({environment: asaasSDK.SANDBOX, apiKey: 'CHAVE-SANDBOX'});

let cliente = {
    externalReference: 1234,
    name: 'Nome do cliente',
    cpfCnpj: '12345678901',
    email: '[email protected]',
    mobilePhone: '11988776655',
    ..., /* demais atributos do cliente */
    ...
};

asaasSDK.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 asaasSDK.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()
asaasSDK.customers.put('cus_000002875000', cliente).then((res)=>{
    console.log('Cliente Atualizado');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao editar o 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 asaasSDK.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()
asaasSDK.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 asaasSDK.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()
asaasSDK.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 asaasSDK.customers.get(), este método recebe o ID do cliente e retorna uma Promise.

let id = "cus_000002872237";

asaasSDK.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 asaasSDK.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,
};

asaasSDK.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 Pagamentos (payments)

A integração de pagamentos é realizada por meio do atributo asaasSDK.payments, utilizando os respectivos métodos para cada operação desejada.

Adicionar um novo pagamento

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

const asaasSDK = require('asaas-sdk');

asaasSDK.config({environment: asaasSDK.SANDBOX, apiKey: 'CHAVE-SANDBOX'});

let payment = {
    customer: "cus_0000047244742",
    billingType: 'BOLETO',
    value: 10.5,
    dueDate: '2021-09-20',
    description: "Pedido 056984",externalReference: "056984",
    ..., /* demais atributos do pagamento */
    ...
};

asaasSDK.payments.post(payment).then((res)=>{
    console.log('Pagamento Cadastrado');
    /* O retorno é todos os dados do pagamento cadastrado */
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro no cadastro do pagamento');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Os atributos disponíveis para pagamentos são:

{
  customer: String, // Obrigatório
  billingType: String, // Obrigatório
  value: Number,
  dueDate: String, // Obrigatório
  externalReference: String,
  installmentCount: Number,
  installmentValue: Number,
  ..., /* Consulte a documentação para mais campos */
}

Nota:

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

Listar os pagamentos

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

let filtro = {
  customer: "Nome do cliente",
  billingType: "CREDIT_CARD",
  offset: 0,
  limit: 10,
};

asaasSDK.payments
  .list(filtro)
  .then((res) => {
    console.log("Lista de Pagamentos");
    console.log(res.data);
  })
  .catch((error) => {
    console.log("Erro ao obter pagamentos");
    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 pagamentos são:

{
   customer: String,
   billingType: String,
   status: String,
   subscription: 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 pagamento acesse a documentação do Asaas clicando aqui.

Obter um pagamento

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

let id = "pay_000002872237";

asaasSDK.payments
  .get(id)
  .then((res) => {
    console.log("Obtem um Pagamento");
    console.log(res.data);
  })
  .catch((error) => {
    console.log("Erro ao obter pagamento");
    console.log("Status: ", error.response.status);
    console.log("StatusText: ", error.response.statusText);
    console.log("Data: ", error.response.data);
  });

Excluir um pagamento

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

// O ID 'pay_000002875000' foi retornado quando o pagamento foi criado com o .post()
asaasSDK.payments
  .delete("pay_000002875000")
  .then((res) => {
    console.log("Pagamento removido");
    console.log(res.data);
  })
  .catch((error) => {
    console.log("Erro ao remover o pagamento");
    console.log("Status: ", error.response.status);
    console.log("StatusText: ", error.response.statusText);
    console.log("Data: ", error.response.data);
  });

Editar um pagamento

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

// *** Importação e Configuração do componente ***

let payment = {
    customer: 'cus_000002875000',
    billingType: 'BOLETO',
    ..., /* demais atributos alterados */
    ...
};

// O ID 'pay_000002875000' foi retornado quando o pagamento foi criado com o .post()
asaasSDK.payments.put('pay_000002875000', payment).then((res)=>{
    console.log('Pagamento Atualizado');
    console.log(res.data);
})
.catch((error)=>{
    console.log('Erro ao editar o pagamento');
    console.log('Status: ', error.response.status);
    console.log('StatusText: ', error.response.statusText);
    console.log('Data: ', error.response.data);
});

Estornar um pagamento

O estorno de um pagamento é realizada por meio do método asaasSDK.payments.refund(), este método recebe o ID do pagamento a ser estornado e retorna uma Promise.

// O ID 'pay_000002875000' foi retornado quando o pagamento foi criado com o .post()
asaasSDK.payments
  .refund("pay_000002875000")
  .then((res) => {
    console.log("Estorno de pagamento");
    console.log(res.data);
  })
  .catch((error) => {
    console.log("Erro ao estornar o pagamento");
    console.log("Status: ", error.response.status);
    console.log("StatusText: ", error.response.statusText);
    console.log("Data: ", error.response.data);
  });

Integração de Assinaturas (subscriptions)

A integração de assinaturas é realizada por meio do atributo asaasSDK.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 asaasSDK.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",
};

asaasSDK.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 asaasSDK.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.
};

asaasSDK.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 asaasSDK.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()
asaasSDK.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 asaasSDK.subscriptions.get(), este método recebe o ID da assinatura e retorna uma Promise.

let id = "sub_k55Oi2Sv6MiZ1";

asaasSDK.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 asaasSDK.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,
};

asaasSDK.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]!