Blog SMSBulk.pt

SMS Via API

Qualquer que seja a linguagem de programação que utiliza para desenvolvimento da sua aplicação / website, a API HTTP do SMSBulk serve para si. Esta API funciona sobre chamadas HTTP (GET ou POST) e é totalmente independente da linguagem de programação.

Neste tutorial são dados exemplos utilizando PHP.

Seja para procedimentos de opt-in, confirmação de número de telemóvel ou envio de notificações, o SMS é a forma mais simples de chegar aos seus utilizadores/clientes.

A solução Low cost do SMSbulk torna esta funcionalidade ainda mais interessante do ponto de vista dos seus custos.

Mostramos de seguida um exemplo em PHP para a implementação da API. Se a sua linguagem de programação não é o PHP, isso não será problema. O código abaixo está detalhadamente explicado, para que possa replicar a implementação em qualquer outra linguagem de programação. Se ainda assim tiver dúvidas ou problemas na implementação, contacte-nos para podermos dar uma ajuda.

Utilização da API HTTP do SMSBulk a partir da sua aplicação

Partimos dos seguintes pressupostos:

• A servidor/equipamento onde a sua aplicação é executada possui acesso Internet e possibilidade de aceder via HTTP ao servidor www.smsbulk.pt;
• A sua aplicação possui uma mecânica que de algum modo produz uma mensagem para envio para um ou mais destinos (números móveis).

Passo 1 - Conta SMSBulk.pt

Para poder utilizar a API, terá que estar registado no serviço SMSBulk.pt. Aceda à página de registo e complete o procedimento de registo e ativação de conta. O registo é gratuito e sem quaisquer compromissos.

Passo 2 - Ativar a API na sua conta SMSBulk.pt

Por motivos de segurança, a API está desativada por defeito. Aceda à sua área pessoal SMSBulk.pt e entre na opção:

Minha Conta > API HTTP

Coloque o "Estado da API" em "On" e, caso a sua aplicação seja executada num servidor / computador com IP fixo, recomendamos que utilize a opção "Limitar por IP" para maior segurança.

Registe o código "UID - Identificador de utilizador de API", vai precisar dele mais tarde.

Ainda neste módulo, possui para download a documentação detalhada da API - todas as funcionalidades e como as utilizar - assim como exemplos de código em PHP também para download.

Passo 3 - Configure o(s) seu(s) Remetente(s)

O SMSBulk.pt permite a personalização do remetente das suas mensagens. Poderá ser um número móvel ou um nome até 11 caractetes. Aceda em:

Minha Conta > Remetentes 

E siga as instruções para a configuração dos remetentes que necessita.
Os remetentes são aprovados manualmente e podem demorar até 48h a ser ativados. Receberá uma notificação por SMS quando o seu remetente for autorizado.

Passo 4 - Exemplo de Utilização da API

Segue-se um exemplo de utilização da API em PHP. Abaixo cada uma das partes é detalhadamente explicada.

// Parâmetros a submeter ao servidor SMSBulk
$sms_content = array(
    'uid' => 'xxxxxxxxxxxxxxxxxxxx', // Obtenha o UID em: Minha Conta > API HTTP
    'pwd' => 'xxxxxx',               // A sua password de acesso à conta SMSBulk
    'tel' => '900000000',            // Número de destino, SEM prefixo internacional
    'msg' => 'Aqui vai uma mensagem de teste', // Conteúdo da mensagem a enviar
    'rem' => 'SMSBulk',             // Remetente a utilizar. Opcional.
    'dth' => '2015-07-30 15:00',    // Data e Hora de Envio. Opcional. Formato: AAAA-MM-DD HH:MI
    'uni' => '',                    // Enviar Mensagem Unicode. Opcional. Quando especificado, enviar valor: 1
    'lct' => '',                    // Utilizar rota "Low Cost". Opcional. Quando especificado, enviar valor: 1
    'flh' => '',                    // Enviar "SMS Flash". Opcional. Quando especificado, enviar valor: 1. 
	        		    // Se for ativada a opção "uni", este parâmetro será ignorado.
    'dbg' => '1',                   // Modo Debug. Opcional. Quando especificado, enviar valor: 1.
);


// URL da API HTTP 1.x
$url = 'http://www.smsbulk.pt/api-http-v1/sms_send.php';

// ================================================
//
//    EXEMPLO DE ENVIO PELO MÉTODO "GET"
//
// Adicionar parâmetros ao URL
$url .= '?';
foreach($sms_content as $k => $v) 
    if($v)
        $url .= $k.'='.urlencode($v).'&';

// Inicializar CURL
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_TIMEOUT, 20);
    
// Enviar pedido ao servidor
$resposta = curl_exec( $ch );
curl_close ( $ch );

// Se estamos em debug, mostrar a resposta integral do servidor
if($sms_content['dbg'] == 1) {
    header("Content-type: text/plain; charset=utf-8");
    print $resposta;
}

// Em produção deveremos interpretar a resposta
else {
    // Interpretar a resposta
    $res = explode('|', $resposta);

    // Envio OK
    if($res[0] == 'OK') {
        print "Envio foi OK - ID da mensagem: ".$res[1]." - Custo de Envio: ".$res[2];
    } 
    // Erro de envio
    else {
        print "Erro de envio - Código do Erro: ".$res[1]." - Custo de Envio: ".$res[2];
    }
}

Explicação da Utilização da API Exemplificada Acima

1 - Definição do "sms_content":

"sms_content" é um array associativo / dicionário que utilizamos no nosso exemplo para simplificar a especificação dos vários parâmetros a submeter à API.
Não tem que fazer desta forma... pode produzir o URL de comunicação com a API de qualquer outra forma.

Vejamos em detalhe cada um dos parâmetros:

'uid' => 'xxxxxxxxxxxxxxxxxxxx', // Obtenha o UID em: Minha Conta > API HTTP

No acesso via API a sua conta não é identificada pelo seu número móvel (como faz quando acede via Web). Assim, deve utilizar este código para identificar corretamente a sua conta. Atenção que este código deve ser colocado sem espaços e respeitando maiúsculas/minúsculas.

'pwd' => 'xxxxxx',               // A sua password de acesso à conta SMSBulk

Aqui deve colocar a mesma password que utiliza para acesso à sua conta via web.

'tel' => '900000000',            // Número de destino, SEM prefixo internacional

Número de telemóvel de destino para onde a mensagem vai ser enviada. Não coloque o prefixo internacional, esta versão da API só suporta envio de SMS para Portugal. Caso pretenda envio internacional, por favor contacte-nos para podermos ajudar.

'msg' => 'Aqui vai uma mensagem de teste', // Conteúdo da mensagem a enviar

Aqui coloca o conteúdo da mensagem a enviar. Atenção que o SMSBulk suporta 2 tipos de conteúdo nas mensagens:

• GSM 7 Bits - Cada SMS suporta até 160 caracteres, mas não suporta acentos nem alguns símbolos especiais. Acima dos 160 caracteres a mensagem é partida em partes de 153 caracteres / SMS, num máximo de 5 partes por mensagem.
• Unicode - Cada SMS suporta até 70 caracteres, com possibilidade de envio de acentos e quaisquer símbolos especiais. Acima dos 70 caracteres a mensagem é partida em partes de 67 caracteres, num máximo de 10 partes por mensagem.

No campo "msg" coloque o conteúdo da mensagem que pretende enviar. Por defeito é assumido o tipo de conteúdo "GSM 7Bits". Se pretende enviar "Unicode" deve ativar o campo "uni" explicado abaixo.

'rem' => 'SMSBulk',             // Remetente a utilizar. Opcional.

O remetente que pretente utilizar na sua mensagem. Note que apenas os remetentes previamente configurados e autorizados podem ser configurados. Caso coloque aqui um remetente não autorizado, receberá um erro como resposta à chamada.
Este campo é opcional. Por defeito será utilizado o remetente "SMSBulk".

'dth' => '2015-07-30 15:00',    // Data e Hora de Envio. Opcional. Formato: AAAA-MM-DD HH:MI

Opcional - Para especificar a data e hora de envio da sua mensagem. Se for dada uma data já ultrapassada, a mensagem é enviada imediatamente.

'uni' => '',                    // Enviar Mensagem Unicode. Opcional. Quando especificado, enviar valor: 1

Opcional. Envie este parâmetro com o valor "1" para que seja enviada uma mensagem Unicode (ver acima a explicação do parâmetro "msg")

'lct' => '',                    // Utilizar rota "Low Cost". Opcional. Quando especificado, enviar valor: 1

Enviar a mensagem pela rota "Low Cost". Esta rota é cerca de 30% mais barata, mas deve ser utilizada com cuidado. Veja aqui as suas especificidades.

'flh' => '',                    // Enviar "SMS Flash". Opcional. Quando especificado, enviar valor: 1. 

Esta opção só pode ser utilizada para mensagens "GSM 7 Bits", ou seja, se ativar o parâmetro "uni=1" esta opção será ignorada.
Um SMS Flash é exibido no écrã do telemóvel no momento da receção e não fica gravado na caixa de mensagens.

'dbg' => '1',               // Modo Debug. Opcional. Quando especificado, enviar valor: 1.

Este parâmetro só deve ser utilizado em ambiente de desenvolvimento/testes e mostra informação adicional do tratamento/teste/envio da sua mensagem para que possa perceber melhor o que acontece, especialmente no caso de estar a ter problemas no envio das suas mensagens.

2 - URL para invocação da API

Sendo a API implementada sobre HTTP, tudo se resume a produzir um URL para submissão via HTTP ao serviço SMSBulk.pt.
Este é o URL base da chamada de envio de mensagem, ao qual iremos depois acrescentar os parâmetros configurados acima:

// URL da API HTTP 1.x
$url = 'http://www.smsbulk.pt/api-http-v1/sms_send.php';

3 - Preparação da Chamada com o método "HTTP GET"

É possível invocar o serviço por "GET" ou por "POST". Neste exemplo estamos a utilizar o "GET".
O código abaixo adiciona ao URL base definido acima todos os parâmetros especificados na parte inicial.

// ================================================
//
//    EXEMPLO DE ENVIO PELO MÉTODO "GET"
//
// Adicionar parâmetros ao URL
$url .= '?';
foreach($sms_content as $k => $v) 
    if($v)
        $url .= $k.'='.urlencode($v).'&';

Este bloco de código adiciona ao "url" cada um dos parâmetros definidos no array associativo "sms_content", configurando assim o nosso URL com toda a informação para submissão ao SMSBulk.pt.
Note a utilização da função "urlencode". Esta função processa os caracteres especiais como acentos, espaços ou "&" para que cheguem corretamente ao destino sem serem corrompidos pelo facto de serem colocados no URL. Diferentes linguagem de programação utilizam diferentes funções para este fim.

4 - Submeter o URL ao serviço SMSBulk.pt

// Inicializar CURL
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_TIMEOUT, 20);
    
// Enviar pedido ao servidor
$resposta = curl_exec( $ch );
curl_close ( $ch );

Neste exemplo utilizamos as funções "CURL" Muitas linguagens de programação disponibilizam esta mesma biblioteca que se utiliza de forma muito semelhante ao PHP. Se não está a utilizar PHP, procure na documentação qual a melhor forma se submeter um pedido HTTP para o seu caso específico. Certamente vai encontrar online muitos exemplos de como o fazer.
Muito importante é a recepção da resposta do servidor remoto. No nosso exemplo, guardamos a resposta na variável "resposta", para análise posterior. Configurar um "timeout" para a ligação pode ser também muito importante, pois a sua aplicação pode ficar "encravada" por tempo indeterminado caso existem problemas de ligação.

5 - Verificar a resposta do serviço SMSBulk.pt

Deve sempre confirmar que a sua mensagem foi enviada com sucesso.
O código abaixo permite-lhe saber se a resposta foi de sucesso ou de erro.

// Se estamos em debug, mostrar a resposta integral do servidor
if($sms_content['dbg'] == 1) {
    header("Content-type: text/plain; charset=utf-8");
    print $resposta;
}

// Em produção deveremos interpretar a resposta
else {
    // Interpretar a resposta
    $res = explode('|', $resposta);

    // Envio OK
    if($res[0] == 'OK') {
        print "Envio foi OK - ID da mensagem: ".$res[1]." - Custo de Envio: ".$res[2];
    } 
    // Erro de envio
    else {
        print "Erro de envio - Código do Erro: ".$res[1]." - Custo de Envio: ".$res[2];
    }
}

Atenção que se a opção "modo debug" for ativada no seu pedido (enviado o parâmetro "dbg=1") a resposta é para leitura humana e não poderá facilmente automatizar a interpretação da mesma no seu software. O modo debug deve ser utilizado apenas para despiste de problemas.

Se não estiver em "modo debug", a resposta é sempre composta por 3 partes, separadas pelo caractere "|". Analisando a primeira componente da resposta, terá um "OK" caso a mensagem seja enviada com sucesso ou alternativamente um "ERROR".

Descarregue o PDF com a documentação detalhada para aceder à lista completa das respostas possíveis, assim como às restantes funcionalidades oferecidas pela API.

Caso tenha problemas de implementação ou dúvidas no funcionamento da API ou do nosso serviço, entre em contacto para que possamos ajudar.

• SMSBulk.pt
• 2015-09-07
• sms, sms api, php sms api, php api