NAV Navbar
javascript

Introdução

Bem vindo à documentação da API da Bestuse SMSs.

Aqui você vai encontar os métodos de envio e consulta disponíveis em nosso sistema.

Nossa API é toda desenvolvida em NodeJS, certifique-se de configurar corretamente seus requests conforme esta documentação.

Para entrar ou se cadastrar no nosso sistema acesse Bestuse SMS.

Autenticação

Para poder enviar/receber dados você deve sempre informar o campo 'token' ou 'Authorization' em suas requisições:

Na header da sua requisição:

  Authorization: a1b2c3d4c5

Ou na sua URL:

  {{url da api}}?token=a1b2c3d4c5

Não esqueça de trocar a1b2c3d4c5 pela chave de API(Token) fornecida a você.

Para autenticação dos usuários da API usamos um token de validação que deve ser enviado em todos os requests.

Esse token de validação é informado a pelo nosso setor comercial quando é feita a solicitação de integração via API.

Sem esse token de validação você não podera fazer nenhuma consulta/envio ao nosso sistema:

Content-Type

Nossa API é toda desenvolvida em Javascript usando JSON para o trâmite de dados.

Se o Content-Type não for especificado provalmente sua aplicação não vai funcionar.

Centros de custo

Os Centros de Custo(CC) são muito importantes no nosso sistema, é com ele que fazemos todo o gerenciamento dos envios.

Buscar todos

Método da API:

GET http://v2.bestuse.com.br/api/v1/centrocusto?skip=25&&limit=50&&token=CHAVE_DA_API

Nesse exemplo estaremos buscando os centros de custo do número 25 ao 75.

O método retorna um objeto no seguinte formato em caso de sucesso:

{
  "total": 100, // total de centros de custo cadastrados
  "data": [
    {
      "descricao": "Tatooine", // descrição do centro de custo
      "codigoCustom": "Deserto", // código customizado do centro de custo (se houver)
      "_id": "as5d4f5d5s654", // _id interno do centro de custo, você usará nas requisições
      "ligado": true // se o centro de custo está visível no painel
      "emailsResponsaveis": [ // array dos contatos cadastrados
        {
          "_id": "a54d5s565sdf5d555", // _id do contato
          "numero": 1122223333, // numero de telefone do contato
          "nome": "Luke Skywalker", // nome do contato
          "email": "lukeSkywalker@rebeldes.com", // email do contato
          "recebeConfirmacaoEnvio": false, // se ele recebe os emails de confirmação de envio
          "recebeRetornos": true, // se ele recebe os emails dos retornos
          "recebeInvalidos": false // se ele recebe os emails dos números inválidos
        }
      ],
    },
  ],
  ...
}

E o seguinte formado em caso de erro:

{
  "success": false, // status da requisição
  "err": "Você não tem permissão suficiente para executar este procedimento", // Mensagem de erro. EX: quando o usuário nao tem permissão de acesso ao centro de custo
}

Para buscar todos os centros de custo cadastrados.

Este método funciona como uma paginação onde o padrão do sistema é retornar 25 itens. Porém é possível passar dois parâmetros, skip e limit, estes parâmetros determinarão quantos itens serão retornados e a partir de qual item a busca devera começar.

Cadatrar novo CC

Método da API:

POST http://v2.bestuse.com.br/api/v1/centrocusto?token=CHAVE_DA_API

Parâmetros:

{
  "emailsResponsaveis": [
    {
      "recebeConfirmacaoEnvio": true,
      "recebeInvalidos": true,
      "recebeRetornos": true,
      "nome": "Han Solo",
      "email": "hansolo@piloto.com",
      "numero": "5566667777"
    }
  ],
  "descricao": "Contrabandista",
  "codigoCustom": "Pilotos"
}

Resposta:

{
  "success": true, // status da requisição
  "data": {
      "_id": "a54d5s565sdf5d566",
      "descricao": "Contrabandista",
      "codigoCustom": "Pilotos"
  },
  "err": null // mensagem de erro se ocorreu algum
}

Para cadastrar um novo centro de custo você deve seguir o exemplo ao lado.

Após o cadastro você pode usar o _id retornado para fazer buscas e envios.

Editar um CC

Método da API:

PUT http://v2.bestuse.com.br/api/v1/centrocusto?token=CHAVE_DA_API

Parâmetros:

{
  "emailsResponsaveis": [
    {
      "recebeConfirmacaoEnvio": false,
      "recebeInvalidos": false,
      "recebeRetornos": false,
      "nome": "Han Solo",
      "email": "hansolo@piloto.com",
      "numero": "66555554444"
    }
  ],
  "descricao": "Mercador",
  "_id": "a54d5s565sdf5d566"
}

Resposta:

{
    "success": true, // status da requisição
    "err": null, // mensagem de erro se ocorreu algum
    "form": { // dados enviados para edição
      "emailsResponsaveis": [
          {
            "recebeConfirmacaoEnvio": false,
            "recebeInvalidos": false,
            "recebeRetornos": false,
            "nome": "Han Solo",
            "email": "hansolo@piloto.com",
            "numero": "66555554444"
          }
      ],
      "descricao": "Mercador",
      "_id": "a54d5s565sdf5d566",
    }
}

Para alterar um centro de custo o processo é muito similar ao cadastro, porém voce deve fazer uma requisição PUT e passar o _id do centro de custo que deseja alterar

Envio de SMSs - POST

Método

    POST http://v2.bestuse.com.br/api/v1/envioApi?token=CHAVE_DA_API

Exemplo envio agendado

{
  "smss":[
      {
        "numero": "11999998888",
        "idCustom": "1",
        "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde."
      },
      {
        "numero": "1199999999",
        "idCustom": "2",
        "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde."
      }
   ],
   "envioImediato": false,
   "centroCusto": "a54d5s565sdf5d566",
   "agendamento": [
       {
          "quantidade": "100",
          "dataHoraInicio": "2019-09-25 08:00:00",
          "dataHoraFim": "2019-09-25 08:10:00"
       }
   ]
}

Exemplo envio imediato

{
  "smss":[
      {
        "numero": "11999998888",
        "idCustom": "1",
        "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde."
      },
      {
        "numero": "+551199999999",
        "idCustom": "2",
        "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde."
      }
   ],
   "envioImediato": true,
   "centroCusto": "a54d5s565sdf5d566"
}

Para fazer o envio de um ou mais smss de uma única vez ultilizando o metodo POST você deve ultilizar os seguintes parâmetros:

Parâmetros


Centro de custo de destino

centroCusto - (string - campo _id da listagem dos centros de custo) Identificação do centro de custo (Obrigatório).


Smss

smss - Array contendo as mensagens a enviar (Obrigatório).

smss.numero - (string) Número de destino da mensagem

smss.mensagem - (string) Mensagem

smss.idCustom - (string) Id único customizado pelo cliente


Agendamentos

agendamento - Array com os agendamentos (Opcional).

agendamento.quantidade - (string) Quantidade em porcentagem do envio.

agendamento.dataHoraInicio - (string) Data e hora para começar o envio, formato yyyy-mm-dd hh:mm:ss

agendamento.dataHoraFim - (string) Data e hora para começar o envio, formato yyyy-mm-dd hh:mm:ss


Envio imediato

envioImediato - (bool) Iniciar o envio imediatamente, ignora o agendamento (Obrigatório se não tiver agendamento).

Respostas

Em caso de sucesso no envio do lote via POST

{
  "success": true, // status da requisição
  "err": "", // mensagem de erro se ocorreu algo
  "errCode": 200, // código de status
  "msg": "Lote recebido com sucesso. ", // mensagem de recepção
  "bloqueadosDuplicidade": 0, // total de smss bloqueado devido a ja terem sido enviados nos ultimos dias (Entre em contato para liberar essa opção)
  "naoSeraoEntregues": 0, // numeros que não tiveram a operadora identificada
  "id": "5d66c182c6cbfc0f2c602d68", // identificador do lote gerado
  "bloqueados": 0, // total de numeros bloqueados devido à tamanho da mensagem
  "validos": 2, // total de números válidos
  "invalidos": 0, // total de números inválidos
  "smsBloqueados": [], // array com os smss bloqueados
  "numerosNaoConfiaveis": 0 // total de números não confiáveis (blacklists)
}

Caso existam smss bloqueados (devido a bloqueio no número ou tamanho da mensagem), o sistema devolve um array com os smss bloqueados

{
  ...
    "bloqueados": [
    {
      "numero": "11999998888",
      "idCustom": "2",
      "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde."
    }
  ]
}

Em caso de erro no envio do lote via POST

{
    "success": false,
    "data": "",
    "errCode": 104,
    "err": "Nenhum sms recebido/válido para envio"
}

Campo errCode da resposta

A a resposta do envio via post pode conter os seguintes códidos:

Códigos de sucesso

Códigos de erro

Status do SMS pelo idCustom

Método

  GET http://v2.bestuse.com.br/api/v1/envioApi/getStatus?token=CHAVE_DA_API&id=IDCUSTOMENVIADO

Resposta do método

{
  "success": true,
  "status": "ENVIADO", // status da mensagem
  "numero": "42999981464",
  "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
  "dataHoraEnvio": "2017-04-24T13:05:03.908Z" // horário do envio da mensagem
}

Para saber o status de uma mensagem enviada, ultilize o seguinte método passando o idCustom enviado

Relatórios

Relatório de SMSs por lote/arquivo

Método

GET http://v2.bestuse.com.br/api/v1/resumoArquivoApi?arquivo=ID_DO_ARQUIVO&token=CHAVE_DA_API

Resposta do método com os smss do lote

[
  {
    "_id": "5d6417fe2fa9c05af4470d64",
    "numero": "11999998888",
    "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
    "dataHoraEnvio": "2019-08-26T18:13:00.523Z",
    "status": "ENVIADO"
  },
  {
    "_id": "5d6417fe2fa9c05af4470d65",
    "numero": "11999998888",
    "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
    "dataHoraEnvio": "2019-08-26T18:23:00.523Z",
    "status": "NAO ENVIADO"
  },
  {
    "_id": "5d6417fe2fa9c05af4470d66",
    "numero": "11999998888",
    "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
    "dataHoraEnvio": "2019-08-26T18:33:00.523Z",
    "status": "ENVIADO"
  }
]

Em caso de erro ao buscar o relatório

{
  "success": false,
  "err": "Erro ao encontrar arquivo"
}

Para buscar um relatório com os SMSs de um lote ultilize o _id retornado no POST do lote

Relatório analítico de SMSs

Método

  • Nesse exemplo estamos pegando o relatorio do dia 01 ao 10 mês de Agosto
GET http://v2.bestuse.com.br/api/v1/relatorio?centroCusto=idCentroCusto&dataInicio=2019-08-01&dataTermino=2019-08-10&token=TOKEN

Resposta

{
  "success": true,
  "total": 250, // total de smss enviados nesse período
  "data": [
      "_id": "5d6417s5d45d4",
      "numero": "11999998888",
      "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
      "dataHoraEnvio": "2019-08-26T18:13:00.523Z",
      "status": "ENVIADO"
    },
    {
      "_id": "5d6417s5d45d6",
      "numero": "11999998888",
      "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
      "dataHoraEnvio": "2019-08-26T18:23:00.523Z",
      "status": "NAO ENVIADO"
    },
    {
      "_id": "5d6417s5d45d5",
      "numero": "11999998888",
      "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
      "dataHoraEnvio": "2019-08-26T18:33:00.523Z",
      "status": "ENVIADO"
    }
    ...
  ]
}

O relatório analítico tráz todos os smss enviados em um determinado período de tempo

Possíveis status dos SMSS

Os smss dos relatórios pode conter os seguintes status:

Callback de retornos

Sempre que houver um retorno, nossa API enviará um POST para essa url com o seguinte formato.

{
  "_id": "58a4dd55ds5c", // _id interno do retorno
  "mensagem": "Retorno recebido pela plataforma",
  "idCustom": "123",
  "numero": "42999999999",  // numero que enviou a resposta
  "sms": "58a3dfssdffdb778746b4", // a qual sms esse retorno pertence
  "centroCusto": "58981dd11003f8e4c3", // centro de custo do sms do retorno
  "arquivo": "58a337ecccab534b771", // arquivo/lote que recebeu o retorno
  "data": "2019-08-26T18:33:00.523Z", // data do recebimento do retorno pela nossa plataforma
}

Caso você queira que direcionemos os retornos recebidos para seu sistema, podemos configurar as ULRs de callback.

Para saber mais ou solicitar a integração, entre em contato com nossa equipe

javascript