Integração SMS API

Visão geral

Nossa API oferece a oportunidade de configurar notificações automatizadas por SMS diretamente de qualquer software, CRM ou aplicativo.

Para a comunicação do servidor API, é utilizado um protocolo HTTP, incluindo suporte SSL seguro. As solicitações são enviadas usando os métodos GET e POST, e o servidor responde no formato XML ou JSON, dependendo da sua preferência.

Conexão com a API

Para poder executar solicitações de API, é necessário ativar e configurar esta função em Painel de Controle:

1. Abrir API Configurações no painel de controle:
   
2. Marque Habilitar acesso à API:
   
3. Especifique endereços IP que devem ter permissão para enviar solicitações à API.

Após habilitar o acesso, você verá sua API Key. Utilize esta key em sua aplicação para executar solicitações de API.

Para garantir a segurança da sua conta, é recomendável especificar uma lista de endereços IP atribuídos aos seus servidores com permissão para acessar a API. Liste os endereços separados por vírgula como no exemplo: 192.12.34.56,23.45.67.89,123.123.123.123.

Você pode alterar a key da API clicando no botão Alterar API Key. Todas as aplicações que utilizam a key antiga não poderão mais acessar a API. Você precisará substituir a key antiga pela nova na configuração de suas aplicações.

Usando a API

Ponto de entrada da API

Todas as solicitações de API são realizadas pelo endereço: https://api.mobizon.com.br/service/

Parâmetros necessários

Cada solicitação API deve conter pelo menos o nome do módulo, o método e a API Key:

https://api.mobizon.com.br/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

• user é o módulo API,
• getownbalance é o método API,

e parâmetros adicionais são listados após o ponto de interrogação; neste caso, há apenas um parâmetro adicional, apiKey.

Parâmetros opcionais

• Saída: formato de resposta do servidor.
  Suportamos dois formatos atualmente:
  • JSON (padrão);
  • XML.
  
  Exemplo de solicitação:
  

  https://api.mobizon.com.br/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

  
  
• api: Versão da API.
  v1 é a versão atual da API e o valor padrão.
  Exemplo de solicitação:
  

  https://api.mobizon.com.br/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

• Outros parâmetros.
  Quaisquer outros parâmetros, incluindo os relacionados ao método, podem ser enviados como parâmetros GET ou POST. Como existe uma limitação ao tamanho máximo de uma solicitação GET, e as respostas a essas solicitações podem ser armazenadas em cache pelos nós da rede intermediária, recomendamos o uso apenas de solicitações POST para acesso à API.

Formato de resposta do servidor API

A resposta do servidor é uma string no formato de dados escolhido (XML ou JSON) que contém um objeto que compreende três elementos: código, dados e mensagem. Exemplos:

{
    "code":0,
    "data":{
        "balance":"4043.0656",
        "currency":"BRL"
    },
    "message":""
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <code>0</code>
    <data>
        <balance>123.4567</balance>
        <currency>BRL</currency>
    </data>
    <message></message>
</root>

• code é o código de resposta da API (consulte a documentação da API para obter os valores do código de resposta);
• data são os dados retornados em um formato correspondente ao método API invocado ou, no caso de um erro, podem conter dados relacionados à causa do erro (por exemplo, uma lista de campos contendo dados incorretos);
• message é o texto de status que geralmente descreve o erro, caso ocorra um.

Códigos de resposta da API

O resultado retornado por uma chamada de API sempre contém um campo de código com um valor numérico indicando o resultado do processamento da solicitação:

• 0 significa sucesso.
• 100 significa que não há erro e a operação está sendo processada no modo de segundo plano. Nesse caso, o campo de dados contém o ID do processo em segundo plano. Você pode acompanhar o andamento e o status da operação usando as solicitações de API taskqueue/getstatus.
• Qualquer outro código de resposta significa que ocorreu um erro ao processar a solicitação. Por favor, consulte esta página de documentação para os códigos de erro.

Biblioteca PHP client

Você pode usar nosso client PHP MobizonApi oficial. Exemplos de uso.

Outra opção é conectar este módulo via Composer.

Exemplos de uso do módulo client PHP API

Se você tiver seus próprios exemplos de trabalho, envie-os para nós e teremos o maior prazer em publicá-los no site. Basta enviar seu link ou exemplo de código para support@mobizon.gmbh

• Disparo único de SMS
• Disparo de SMS em massa
• Obter saldo da conta
• Obtenha a lista de Sender IDs (assinaturas alfanuméricas) disponíveis para uso
• Salvar um relatório de envio de SMS usando os critérios de busca fornecidos
• Salvar um relatório conjunto de campanha SMS usando os critérios de busca fornecidos

Exemplo de utilização com requisição GET

Se seu aplicativo não suportar solicitações POST, use solicitações GET no seguinte formato:

https://api.mobizon.com.br/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

• NNN...NNN é o número de telefone do destinatário em formato internacional (sem incluir o caractere +), ex.: 5511963928063.
• PPP...PPP - é seu Sender ID (assinatura alfanumérica). Se nenhum for fornecido, seu Sender ID padrão será usado ou, se você não tiver nenhum, o Sender ID padrão do sistema.
• Message+text+here%21 - é o texto da sua mensagem SMS no formato de string URL encoded: "Texto da mensagem aqui!".
• KKK...KKK - é sua Key da API (você precisa obtê-la em seu painel de controle).