Documentação técnica da Api4Com

Appearance

Documentação técnica de Recargas e Créditos na plataforma Api4Com ​

Introdução ​

A plataforma Api4Com permite a realização de recargas de créditos através do gateway de pagamentos Asaas. A recarga de créditos é uma forma de pagamento pré-pago, onde o cliente adquire um pacote de créditos que pode ser utilizado para realizar chamadas telefônicas.

Os pagamentos são sincronizados com o ERP Omie, que é o sistema de gestão utilizado pela Api4Com.

Todos os dados sensíveis dos clientes estão armazenados no Asaas e Omie, a Api4Com não armazena dados sensíveis dos clientes.

Os créditos são gerenciados pelo SoftSwitch da SipPulse, que é o sistema de telefonia utilizado pela Api4Com.

Arquitetura da configuração dos clientes ​

A configuração dos clientes é feita através da plataforma Api4Com, onde é possível configurar os dados de integração ao Asaas, Omie e SipPulse.

Configuração do Asaas ​

Para configurar o Asaas, é necessário criar uma Integração de Organização (organization_integrations) com o gateway asaas. Os dados necessários para a integração são:

  • id - Identificador da integração
  • organization_id - Identificador da organização
  • gateway - Nome do gateway
  • metadata - Dados de integração com o Asaas
    • customerId - Identificador do cliente no Asaas
    • externalReference - Identificador externo do cliente gerado pela Api4Com
    • needPrepaymentInvoice - Indica se o cliente precisa de uma NF antes do pagamento
    • status - Status do cliente no Asaas
    • financialMails - E-mails para envio de pagamentos e NFs

Exemplo de configuração do Asaas:

json
{
  "id": 1,
  "organization_id": 1,
  "gateway": "asaas",
  "metadata": {
    "customerId": "cus_000000000001",
    "externalReference": "bbc30387-13e3-4704-b2a9-1f7fec96cf8c",
    "needPrepaymentInvoice": false,
    "status": "ACTIVE",
    "financialMails": "financeiro@domain.com"
  }
}

Configuração do Omie ​

Para configurar o Omie, é necessário criar uma Integração de Organização (organization_integrations) com o gateway omie. Os dados necessários para a integração são:

  • id - Identificador da integração
  • organization_id - Identificador da organização
  • gateway - Nome do gateway
  • metadata - Dados de integração com o Omie
    • customerId - Identificador do cliente no Omie
    • externalReference - Identificador externo do cliente gerado pela Api4Com
    • statusCode - Código de status da integração
    • statusDescription - Descrição do status da integração

Exemplo de configuração do Omie:

json
{
  "id": 2,
  "organization_id": 1,
  "gateway": "omie",
  "metadata": {
    "customerId": "1234567890",
    "externalReference": "abc30357-1ce3-4504-b2a9-1fbfec56cf81",
    "statusCode": "0",
    "statusDescription": "Cliente alterado com sucesso!"
  }
}

Configuração do SipPulse ​

Para configurar o SipPulse, é necessário criar uma Integração de Organização (organization_integrations) com o gateway sippulse. Os dados necessários para a integração são:

  • id - Identificador da integração
  • organization_id - Identificador da organização
  • gateway - Nome do gateway
  • metadata - Dados de integração com o SipPulse
    • subscriberId - Identificador do assinante no SipPulse
    • username - Nome de usuário do assinante
    • addressId - Identificador da configuração de Tech Prefix no SipPulse
    • password - Senha do assinante
    • balancerHost - Host do balanceador do SipPulse
    • freeswitchEslHost - Host do ESL do FreeSWITCH
    • freeswitchEslPort - Porta do ESL do FreeSWITCH
    • freeswitchEslPassword - Senha do ESL do FreeSWITCH
    • opensipsHost - Host do OpenSIPS
    • opensipsPort - Porta do OpenSIPS
    • hasDynamicTariff - Indica se o cliente possui plano de tarifação dinâmico
    • receivedBonusCredit - Indica se o cliente recebeu créditos de bônus

Exemplo de configuração do SipPulse:

json
{
  "id": 3,
  "organization_id": 1,
  "gateway": "sippulse",
  "metadata": {
    "subscriberId": "1234",
    "username": "username",
    "addressId": "5678",
    "password": "password",
    "balancerHost": "144.22.134.184",
    "freeswitchEslHost": "10.0.0.200",
    "freeswitchEslPort": "8021",
    "freeswitchEslPassword": "ClueCon",
    "opensipsHost": "10.0.0.124",
    "opensipsPort": "8000",
    "hasDynamicTariff": true,
    "receivedBonusCredit": true
  }
}

Configuração do Cliente ​

Toda nova conta de cliente criada na plataforma Api4Com, além de criar uma organização e usuário, também cria uma integração com o Asaas, Omie e SipPulse. Até esse ponto o usuário ainda não informou seus dados financeiros, então a integração com o Asaas é criada com status PENDING.

Quando o usuário informa seus dados financeiros no Portal da Api4com, caso o documento informado seja válido, e não tenha sido utilizado em outra conta, a integração com o Asaas é atualizada para status ACTIVE, e todos os dados relacionados ao documento informado pelo cliente são enviados para o Asaas e Omie. Após esse processo, o cliente pode realizar recargas de créditos.

Até aqui toda conta na Api4Com, possui uma conta no Asaas, Omie e SipPulse, porém existe um cenário em que essa composição pode ser alterada, que é quando o cliente deseja utilizar o mesmo documento financeiro em mais de uma conta. Nesse caso, a conta do cliente no Asaas e SipPulse é mantida, porém a conta no Omie é unificada em apena uma conta, pois não é possível ter mais de uma conta no Omie com o mesmo documento financeiro.

Exemplo de 2 contas utilizando o mesmo documento financeiro:

Cenário inicial:

  • Conta 1

    • Asaas: cus_000000000001
    • Omie: 1234567890
    • SipPulse: 1234

  • Conta 2

    • Asaas: cus_000000000002
    • Omie: 1234567891
    • SipPulse: 5678

Após a unificação das contas, a conta 2 é removida do Omie e do banco de dados da Api4Com, a conta 1 é mantida, e a conta 2 é mantida no Asaas e SipPulse e replicado a integração do Omie da conta 1 para a conta 2 no banco de dados da Api4Com.

Cenário final:

  • Conta 1

    • Asaas: cus_000000000001
    • Omie: 1234567890
    • SipPulse: 1234

  • Conta 2

    • Asaas: cus_000000000002
    • Omie: 1234567890
    • SipPulse: 5678

Recargas de Créditos ​

As recargas de créditos são realizadas através do endpoint https://api.api4com.com/api/v1/charges ou Portal da Api4com. Para realizar uma recarga de créditos, é necessário informar os seguintes dados:

  • paymentMethod - Método de pagamento (UNDEFINED, BOLETO, CREDIT_CARD, DEBIT_CARD, PIX)
  • dueDate - Data de vencimento do pagamento (formato: YYYY-MM-DD), precisa ser maior ou igual a data atual e menor ou igual a 7 dias
  • amount - Valor da recarga
  • description - Descrição da recarga

Exemplo de recarga de créditos:

json
{
  "paymentMethod": "UNDEFINED",
  "dueDate": "2025-01-01",
  "amount": 9.99,
  "description": "Crédito adicionado via API"
}

Já pelo Portal da Api4com, o usuário pode visualizar o histórico de recargas de créditos, e realizar uma nova recarga de créditos informando apenas o valor da recarga.

Fluxo de Recarga de Créditos ​

O fluxo de recarga de créditos é composto pelas seguintes etapas:

  1. O cliente realiza uma recarga de créditos através do endpoint https://api.api4com.com/api/v1/charges ou Portal da Api4com
  2. A Api4Com cria uma cobrança no Asaas com status PENDING
  3. O cliente realiza o pagamento da cobrança
  4. O Asaas notifica a Api4Com sobre o pagamento da cobrança
  5. A Api4Com atualiza a cobrança no Asaas com status PAID
  6. A Api4Com faz o processamento da Nota Fiscal no Asaas
  7. A Api4Com insere os créditos na conta do cliente no SipPulse
  8. O cliente pode utilizar os créditos para realizar chamadas telefônicas

Nota Fiscal ​

A Api4Com gera uma Nota Fiscal no Asaas para cada recarga de créditos realizada. A Nota Fiscal é gerada após o pagamento da cobrança no Asaas.

A Nota Fiscal é enviada para o e-mail financeiro do cliente, que é informado no Portal da Api4com.

ERP Omie ​

A Api4Com sincroniza os pagamentos com o ERP Omie uma vez ao mês, sempre no primeiro dia do mês. A sincronização é feita através de um processo interno da Api4Com e curado pela equipe de desenvolvimento.

Consumo de Créditos ​

Os créditos são consumidos de acordo com o plano de tarifação do cliente. O consumo de créditos é feito em tempo real, e é descontado do saldo de créditos do cliente. Caso o saldo de créditos do cliente seja insuficiente, não é possível realizar chamadas telefônicas. O cliente pode visualizar o saldo de créditos no Portal da Api4com.

Os crédito nunca expiram, ou seja, o saldo de créditos do cliente é mantido até que o cliente utilize todos os créditos.

Scripts para Suporte ​

A Api4Com possui scripts para suporte que permitem realizar ações específicas na plataforma. Os scripts são executados pela equipe de desenvolvimento da Api4Com, e são utilizados para realizar ações que não são possíveis de serem realizadas pelo cliente.

Script para atualização dos dados do Omie para o Asaas ​

Primeiro é necessário buscar os dados do Omie e Asaas no banco de dados da Api4Com, execute a query abaixo no PostgreSQL:

SQL
SELECT
  CONCAT('{domain:"', o.domain, '",asaasId:"', asaas.metadata::json->>'customerId', '",asaasStatus:"', asaas.metadata::json->>'status', '",omieId:"', omie.metadata::json->>'externalReference', '"},')
FROM
  organizations o
  JOIN organization_integrations asaas ON o.id = asaas.organization_id AND asaas.gateway = 'asaas'
  JOIN organization_integrations omie ON o.id = omie.organization_id AND omie.gateway = 'omie'
WHERE
  o.id IN (1, 2);

Após buscar os dados, execute o script abaixo para atualizar os dados financeiros do Omie para as contas no Asaas:

JavaScript
const axios = require('axios');

const customersToUpdate = [
  {domain:"domain1.api4com.com", asaasId:"cus_000000000001",asaasStatus:"ACTIVE",omieId:"1234567890"},
  {domain:"domain2.api4com.com", asaasId:"cus_000000000002",asaasStatus:"ACTIVE",omieId:"1234567890"},
];

function updateAsaasCustomer(customer) {
  return new Promise((resolve, reject) => {
    const url = `https://www.asaas.com/api/v3/customers/${customer.id}`;
    const headers = {
      'access_token': '$aact_YTU5YTE0M2M2N2I4MTliNzk0YTI5N2U5MzdjNWZmNDQ6OjAwMDAwMDAwMDAwMDAyNzYyNzc6OiRhYWNoXzEzMTFhYzBhLThiNjYtNDZmNy05YTU5LTBmZDBlMmYzZmZkZQ==',
      'Content-Type': 'application/json'
    }
    axios.post(url, customer, { headers }).then(({ data }) => {
      console.log(`customerAsaasID ${customer.id} OK`);
      return resolve(data);
    }).catch(error => {
      return reject(`customerAsaasID ${customer.id} ERROR`, error);
    });
  });
}

function postToOmie(endpoint, action, form) {
  return new Promise((resolve, reject) => {
    const url = 'https://app.omie.com.br/api/v1' + endpoint;
    const headers = {
      'Content-Type': 'application/json'
    }
    const payload = {
      call: action,
      app_key: '2266647733350',
      app_secret: '621475b4115722609b7ea927ef5e399b',
      param: [form]
    }
    axios.post(url, payload, { headers }).then(({ data }) => {
      console.log(`customerOmieID ${form.codigo_cliente_integracao} OK`);
      return resolve(data);
    }).catch(error => {
      return reject(`customerOmieID ${form.codigo_cliente_integracao} ERROR`, error);
    });
  });
}

customersToUpdate.forEach((customer, index) => {
  setTimeout(async () => {
    const customerOmie = await postToOmie(
      '/geral/clientes/',
      'ConsultarCliente',
      { codigo_cliente_integracao: customer.omieId }
    ).catch(console.error);
    const asaasPayload = {
      id: customer.asaasId,
      cpfCnpj: customerOmie.cnpj_cpf,
      name: customerOmie.nome_fantasia,
      company: customerOmie.razao_social,
      address: customerOmie.endereco,
      addressNumber: customerOmie.endereco_numero,
      complement: customerOmie.complemento,
      province: customerOmie.bairro,
      postalCode: customerOmie.cep,
      observations: `Domínio: ${customer.domain} (status: ${customer.asaasStatus})`
    }
    await updateAsaasCustomer(asaasPayload).catch(console.error);
  }, index * 500);
});

Unificação de Contas ​

O script de unificação de contas permite unificar duas contas de cliente em uma única conta. O script é utilizado quando o cliente deseja utilizar o mesmo documento financeiro em mais de uma conta.

O script de unificação de contas é composto pelos seguintes passos:

  1. Validação do documento financeiro informado pelo cliente

Essa verificação pode ser feita diretamente no Omie, onde é possível verificar se o documento financeiro informado pelo cliente é válido e não foi utilizado em outra conta. Também é possível verificar os dados financeiros utilizando a Pesquisar SEFAZ no Omie, onde é possível verificar se o documento financeiro informado pelo cliente está com os dados atualizados na Receita Federal. Após verificar atualize todos os dados, exceto dados de contato como telefone e e-mail e salve.

  1. Unificação das contas

A unificação das contas é feita através do banco de dados da Api4Com, onde é removida a integração do Omie da conta nova, e é replicada a integração do Omie da conta antiga, que já está configurada e utilizando o documento financeiro, para a conta nova.

Também é necessário atualizar os dados da integração com o Asaas da conta nova, onde é necessário atualizar o status para ACTIVE, e incluir o financialMails com o email da conta.

Será necessário também atualizar os dados da integração com o SipPulse para atualizar o receivedBonusCredit para true. Esse crédito bônus será adicionado manualmente pelo Portal da SipPulse em Adicionar/Log Crédito, pesquisando pelo assinante da conta nova, o valor será de R$ 5,00 e em Observações coloque "Crédito bônus".

  1. Atualização dos dados financeiros do Omie para as contas no Asaas

Após a unificação das contas, é necessário atualizar os dados financeiros do Omie para as contas no Asaas, basta executar o Script para atualização dos dados do Omie para o Asaas.

Atualização de Dados Financeiros ​

O script de atualização de dados financeiros permite atualizar os dados financeiros de uma conta de cliente. O script é utilizado quando o cliente deseja atualizar os dados financeiros com dados mais recentes ou ate trocar o documento por um outro que não está sendo utilizado em outra conta.

O script de atualização de dados financeiros é composto pelos seguintes passos:

  1. Validação do documento financeiro informado pelo cliente

Essa verificação pode ser feita diretamente no Omie, onde é possível verificar se o documento financeiro informado pelo cliente é válido e não foi utilizado em outra conta. Também é possível verificar os dados financeiros utilizando a Pesquisar SEFAZ no Omie, onde é possível verificar se o documento financeiro informado pelo cliente está com os dados atualizados na Receita Federal. Após verificar atualize todos os dados, exceto dados de contato como telefone e e-mail e salve.

  1. Atualização dos dados financeiros

A atualização dos dados financeiros é feita através do Script para atualização dos dados do Omie para o Asaas, onde é necessário atualizar os dados financeiros do Omie para as contas no Asaas.