Edição atual tal como 19h23min de 18 de novembro de 2015

API para integração com serviço de SMS

[editar] Sobre este Guia

Este documento descreve a API para envio e recebimento de mensagens SMS via Protocolo HTTP (Hypertext Transfer Protocol) com o Gateway uTech UNIFIED

[editar] Informações necessárias

Para enviar e receber mensagens SMS será necessário realizar requisições HTTP - GET (Ver RFC 2616) e RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax..

• Endereço IP do equipamento MGC-22E / UNIFIED.
• Porta do Servidor HTTP do MGC (configurado no Menu Global => HTTP do MGC/UNIFIED)
• Usuário e senha do servidor HTTP do MGC-22E (configurado no Menu Global => HTTP do MGC/UNIFIED).

[editar] Informações necessárias para aplicação Cliente

[editar] Configuração do Gateway uTech

Antes de utilizar a API, deve-se verificar se as configurações do servidor HTTP do Gateway estão habilitadas. Ver em: Servidor HTTP
Tambem é necessário habilitar e configurar os canais GSM0 e/ou GSM1 para o envio de mensagens. Ver em: Menu SMS

[editar] Cenário de Uso

A seguir é apresentado um cenário de uso e seus parâmetros:

• Gateway uTech UNIFIED/MGC
  • Endereço IP: 10.0.0.1
  • Porta: 6500

• Aplicação SMS
  • Endereço IP: 10.0.0.2
  • Porta: 6501
  • URL: /smsserver/app

Baseado nesse cenário, todas as requisições que a aplicação SMS realizar, deverão ser direcionadas para o endereço IP 10.0.0.1 e porta 6500 e todas as requisições do gateway para a aplicação SMS serão direcionadas para o IP 10.0.0.2, porta 6501 e URL /smsserver/app

• Exemplo 1: - Envio de SMS da Aplicação para o Gateway uTech

http://10.0.0.1:6500/?sourceaddr=teste&destaddr=048XXXXYYYY&message=teste

• Exemplo 2: - Envio de SMS da Operadora para a aplicação SMS (Recebimento de mensagens)

http://10.0.0.2:6501/smsserver/app/?sourceaddr=teste&destaddr=048XXXXYYYY&message=teste

[editar] Envio de Mensagens

Para envio de mensagens, devem ser utilizado os parâmetros listados abaixo. Os parâmetros sourceaddr, destaddr e message são mandatórios. Demais parâmetros são opcionais e devem ser utilizados de acordo com a necessidade da aplicação. O campo message_id, deve ser enviado na requisição, se a aplicação desejar receber eventos de status de envio e status de recebimentos da mensagem. Caso não sejam enviado os parâmetros interface e sim_card, o gateway fará a distribuição automática entre os canais e SIM Card's configurados. Se selecionado os parâmetros, a mensagem será enviada pela interface GSM e chip selecionados.

[editar] Parâmetros para envio de SMS

[editar] Códigos de retorno do Servidor HTTP

Ao enviar uma requisição de envio de SMS, o servidor HTTP responde com um código específico para cada situação. Esse retorno deve ser tratado de acordo com a tabela abaixo:

[editar] Cenários de Envio

Abaixo, 3 cenários de envio de mensagem:

1 Mensagem aceita

Nesse cenário, a aplicação enviou uma requisição para o Gateway, que respondeu com o código 200 informando que a mensagem foi aceita (lista de códigos). Após o envio do 200 OK, o Gateway enviou duas requisições, uma informando o status de envio (status=sent) e outra com o stauts de recebimento (status=received).

2 Mensagem não aceita

Nesse cenário, a aplicação enviou uma requisição para o Gateway, que respondeu com o código diferente de 200 (lista de códigos), o que caracteriza um erro de envio.

3 Mensagem não aceita

Nesse cenário, a aplicação enviou uma requisição para o Gateway, que respondeu com o código 200 informando que a mensagem foi aceita (lista de códigos). Após o envio do 200 OK, o Gateway enviou uma requisição informando o status de erro no envio (status=error), informando que a mensagem não foi aceita pela operadora. Veja em Lista de Erros a lista completa.

[editar] Enviando Mensagem (Aceita)

1. Aplicação envia requisição de mensagem para o gateway:

   • http://10.0.0.1:6500/?sourceaddr=app&destaddr=048XXXXYYYY&message=teste&message_id=d7cb4cb0

2. Gateway responde com código HTTP:
   • 200 - OK (Lista completa)
3. Gateway envia a mensagem para a operadora
4. Operadora responde para o gateway com 'Mensagem Enviada'
5. Gateway envia para a aplicação status de envio (OK => status=sent):

   http://10.0.0.2:6501/smsserver/app/?sourceaddr=app&destaddr=048XXXXYYYY&message_id=d7cb4cb0&status=sent&message_ref=XXXX-48XXXXYYYY-ZZZ&board=10.0.0.1&interface=0&sim_card=0

6. Operadora encaminha mensagem para o destino
7. Gateway recebe da operadora a confirmação de recebimento pelo destino
8. Gateway envia para a aplicação status de recebimento (status=received):

   http://10.0.0.2:6501/smsserver/app/?sourceaddr=app&destaddr=048XXXXYYYY&message_id=XXXX-48XXXXYYYY-ZZZ&status=received

   Note que o valor do campo message_id é o mesmo para do campo message_ref (recebido no passo 5)

[editar] Enviando Mensagem (Erro pela Operadora)

1. Aplicação envia requisição de mensagem para o gateway:

   • http://10.0.0.1:6500/?sourceaddr=app&destaddr=048XXXXYYYY&message=teste&message_id=d7cb4cb0

2. Gateway responde com código HTTP:
   • 200 - OK (Lista completa)
3. Gateway envia a mensagem para a operadora
4. Operadora responde para o gateway com 'Mensagem não Enviada'
5. Gateway envia para a aplicação status de envio (Erro => status=error):

   http://10.0.0.2:6501/smsserver/app/?sourceaddr=app&destaddr=048XXXXYYYY&message_id=d7cb4cb0&status=sent&message_ref=XXXX-48XXXXYYYY-ZZZ&board=10.0.0.1&interface=0&sim_card=0&errno=123

   O parâmetro errno contem um numero de identificação do erro reportado pela operadora. Veja lista completa de erros.

[editar] Enviando Mensagem (Erro pelo Gateway)

1. Aplicação envia requisição de mensagem para o gateway:

   • http://10.0.0.1:6500/?sourceaddr=app&destaddr=048XXXXYYYY&message=teste&message_id=d7cb4cb0

2. Gateway responde com código HTTP:
   • 4XX ou 5XX - Erro (Lista completa)

[editar] Recebendo Mensagem

1. Gateway GSM envia requisição para a aplicação:

   • http://10.0.0.2:6501/?sourceaddr=48XXXXYYYY&destaddr=smsserver&message=teste&board=10.0.0.1&interface=0&sim_card=0

2. Aplicação responde com dódigo HTTP:
   • 200 - OK (Lista completa)

[editar] Códigos / Exemplos

[editar] PHP - Enviando

<?php
 
$user = "test";
$pass = "1234";
$port = "6500";
$ipaddr = "10.0.0.1";
 
$src  = "app";
$dst  = "48XXXXYYYY";
$msg  = "test";
 
$url = "";
$url = "$ipaddr:$port?sourceaddr=$src&destaddr=$dst&message=$msg";
$url .= urlencode($msg);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$user:$pass");
$result = curl_exec($ch);
if(!$result) {
    echo "error!\n";
    return 2;
}
 
$fs = preg_replace("/<html><body>/", "", "$result");
$rc = preg_replace("/<\/body><\/html>/", "", "$fs");
 
echo $rc;
?>

[editar] PHP - Recebendo SMS e Stauts de envio e entrega

<?php
 
$to = null;
$from = null;
$board = null;
$status = null;
$sim_card = null;
$interface = null;
$message_id = null;
 
$str = null;
$hdr = null;
$txt = null;
 
if(isset($_REQUEST['sourceaddr']))
    $from = $_REQUEST['sourceaddr'];
 
if(isset($_REQUEST['destaddr']))
    $to = $_REQUEST['destaddr'];
 
if(isset($_REQUEST['message_id']))
    $message_id = $_REQUEST['message_id'];
 
if(isset($_REQUEST['status']))
    $status = $_REQUEST['status'];
 
if(isset($_REQUEST['board']))
    $board = $_REQUEST['board'];
 
if(isset($_REQUEST['interface']))
    $interface = $_REQUEST['interface'];
 
if(isset($_REQUEST['sim_card']))
    $sim_card = $_REQUEST['sim_card'];
 
if(isset($_REQUEST['message_ref']))
    $message_ref = $_REQUEST['message_ref'];
 
    if(!isset($from)) {
        echo "Format error!\n";
        exit(0);
    }
 
    $fp = fopen("recv.txt", "a");
    if(!$fp) {
        echo "Open file log errro!\n";
        exit(0);
    }
 
    if($board && $interface && $sim_card)
        $hdr = sprintf("BOARD:%s|Interface:%s|SIM_CARD:%s|", $board, $interface, $sim_card );
 
    if($status == "received") {
        $txt = sprintf("Status de Receb => message_id:%s|status:%s (Recebida pelo usuario)\n",
                        $message_id, $status);
 
    } else if($stauts == "sent" || $status == "error") {
 
        $txt = sprintf("Status de Envio => Origem:%s|Destino:%s|message_id:%s|message_ref:%s|status:%s (enviada para operadora)\n",
                        $from, $to, $message_id, $message_ref, $status);
    } else {
 
        $txt = sprintf("Recebendo Mesg. => Origem:%s|Destino:%s|message:%s\n",
                        $from, $to, $message);
    }
 
    if($hdr)
        $str = $hdr;
    $str .= $txt;
 
    $wb = fwrite($fp, $str);
    fclose($fp);
 
?>

[editar] C# - Enviando

using System;
using System.IO;
using System.Net;
using System.Text;
 
namespace SMS.System.Net
{
    public class WebRequestGetExample
    {
        public static void Main ()
        {
            WebRequest request = WebRequest.Create (
              "http://10.0.0.1:6500?sourceaddr=app&destaddr=048XXXXYYYY&message=test&message_id=1234567890");
 
            request.PreAuthenticate=true;
            string UserName = "test";
            string Password = "1234";
 
            NetworkCredential networkCredential=new NetworkCredential(UserName,Password);
            request.Credentials=networkCredential;
            WebResponse response = request.GetResponse ();
            Console.WriteLine (((HttpWebResponse)response).StatusDescription);
            Stream dataStream = response.GetResponseStream ();
            StreamReader reader = new StreamReader (dataStream);
            string responseFromServer = reader.ReadToEnd ();
            Console.WriteLine (responseFromServer);
            reader.Close ();
            response.Close ();
        }
    }
}

[editar] JAVA - Enviando

import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;
 
import org.apache.commons.codec.binary.Base64;
 
/*
 * HTTP GET METHOD
 */
class HttpGetRequest {
    private int responseCode = -1;
 
    public HttpGetRequest(String urlString, String user, String passwd)
        throws java.net.MalformedURLException, java.io.IOException {
        /* Open a URL connection */
        final java.net.URL url = new java.net.URL(urlString);
        final java.net.URLConnection uconn = url.openConnection();
        if (!(uconn instanceof java.net.HttpURLConnection))
            throw new java.lang.IllegalArgumentException(
                "URL protocol must be HTTP" );
        final java.net.HttpURLConnection conn =
            (java.net.HttpURLConnection)uconn;
 
        /* Set up a request */
        conn.setConnectTimeout(10000);    // 10 sec
        conn.setReadTimeout(10000);       // 10 sec
        conn.setInstanceFollowRedirects(true);
 
        if (user != null && passwd != null) {
            String authString = user + ":" + passwd;
            byte[] authEncBytes = Base64.encodeBase64(authString.getBytes());
            String authStringEnc = new String(authEncBytes);
            conn.setRequestProperty("Authorization", "Basic " + authStringEnc);
        }
 
        /* Send the request */
        conn.connect();
 
        /* Get the response code */
        responseCode = conn.getResponseCode();
 
/* Disconnect */
        conn.disconnect();
    }
 
    /* Get the response code */
    public int getResponseCode() {
        return responseCode;
    }
}
 
class HttpClient {
    public static void main(String [ ] args) throws java.io.IOException {
        int responseCode = -1;
        String url = null;
        String user = null;
        String passwd = null;
 
        if (args.length == 0) {
            System.err.println("URL not defined!");
            System.exit(1);
        }
 
        url = args[0];
        if (args.length == 3) {
            user = args[1];
            passwd = args[2];
        }
 
        HttpGetRequest client = new HttpGetRequest(url, user, passwd);
 
        responseCode = client.getResponseCode();
 
        if (responseCode != 200) {
            System.out.printf("HTTP GET error status [%d]!%n", responseCode);
            System.exit(1);
        }
 
        System.out.printf("HTTP GET 200 OK%n");
    }
}

[editar] SHELL / CURL - Enviando

#!/bin/bash
 
if [ $# -ne 5 -a $# -ne 7 ]
then
    echo "Use $0 <ipaddr> <port> <sourceaddr> <destaddr> <message=...>"
    echo "or"
    echo "Use $0 <ipaddr> <port> <sourceaddr> <destaddr> <message> <user> <pass>"
    echo ""
    exit 1;
fi
 
URL="http://$1:$2?sourceaddr=$3&destaddr=$4&message=\'$5\'"
 
if [ $# -eq 7 ]
then
   BASIC="--user $6:$7"
fi
 
DATA=`curl $BASIC -G --max-time 5 -o /dev/null --silent --write-out '%{http_code}' $URL`
EC=$?
if [ $EC -ne 0 ]
then
    echo "Erro ao executar curl! Erro $EC."
    exit $EC
fi
 
echo "$DATA"

[editar] SHELL / WGET - Enviando

#!/bin/bash
 
if [ $# -ne 5 -a $# -ne 7 ]
then
    echo "Use $0 <ipaddr> <port> <sourceaddr> <destaddr> <message=...>"
    echo "or"
    echo "Use $0 <ipaddr> <port> <sourceaddr> <destaddr> <message> <user> <pass>"
    echo ""
    exit 1;
fi
 
URL="http://$1:$2?sourceaddr=$3&destaddr=$4&xxxxxmessagexxx=$5"
 
if [ $# -eq 7 ]
then
   BASIC="--http-user=$6 --http-password=$7 "
fi
 
r=`wget --auth-no-challenge -O /dev/null -o /dev/null $BASIC -SO- "$URL"`
rc=$?
echo RC=$rc
if [ $rc -ne 0 ]
then
    [ $rc -eq 6 ] && echo "401"
    [ $rc -eq 8 ] && echo "400"
    exit $rc
fi
 
echo "RESP=$r"