NAV Navbar
javascript

Introdução à api V3

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:

Dadosapi

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.

Consulta de saldo

Para consultar o saldo disponível em cada centro de custo, use o método a seguir

Método

  GET http://v2.bestuse.com.br/api/v1/recargas/getSaldo/ID_CENTRO_CUSTO?token=CHAVE_DA_API

Resposta

{
  "codigoCustom": "Seu centro de custo",
  "descricao": "Seu centro de custo",
  "login": "loginDoCc",
  "saldo": 2609
}

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,
  "err": "",
  "errCode": 200,
  "msg": "Lote recebido com sucesso. ",
  "bloqueadosDuplicidade": 0,
  "naoSeraoEntregues": 0,
  "id": "5d66c182c6cbfc0f2c602d68",
  "bloqueados": 0,
  "validos": 2,
  "invalidos": 0,
  "smsBloqueados": [],
  "numerosNaoConfiaveis": 0
}

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

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",
  "numero": "42999981464",
  "mensagem": "Sr(a) Fulano. Aproveite esta oportunidade e junte-se à aliança rebelde.",
  "dataHoraEnvio": "2017-04-24T13:05:03.908Z"
}

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

Callback de retornos

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

{
  "_id": "58a4dd55ds5c",
  "mensagem": "Retorno recebido pela plataforma",
  "idCustom": "123",
  "numero": "42999999999",
  "sms": "58a3dfssdffdb778746b4",
  "centroCusto": "58981dd11003f8e4c3",
  "arquivo": "58a337ecccab534b771",
  "data": "2019-08-26T18:33:00.523Z"
}

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