API - SMS

De uTech Tecnologia
Ir para: navegação, pesquisa

Tabela de conteúdo


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

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

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).


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

Para receber as informações do gateway, sejam mensagens recebidas ou status de envio, a aplicação cliente deverá ' escutar ' (fazer bind) uma porta para receber as informações via conexão TCP e Protocolo HTTP. No caso do cenário apresentado, a porta utilizada foi a 6502.

Normalmente, o cliente da API utiliza um servidor HTTP para receber esses informações. Por exemplo um servidor Apache escutando na porta 80. Nesse caso, a porta cliente, configurado do Gateway deve ser alterada para 80 (Servidor HTTP)



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

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
Cenario.png


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


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.

Parâmetros para envio de SMS

Parâmetros para envio de SMS
sourceaddr Parâmetro utilizado para identificar quem está enviando a mensagem SMS. Ex. sms_server.
NOTA: Esse campo será utilizado nas respostas de confirmação do Gateway.
destaddr Parâmetro utilizado para inserir o numero destino da mensagem. Ex: 48XXXXYYYY.
message_id Parâmetro utilizado para inserir um identificador da mensagem, que será utilizado para mapear as respostas do gateway, informado se a mensagem foi enviada e recebida pelo destino.
message Parâmetro utilizado para inserir a mensagem a ser enviada.
NOTA: o campo deve ter os caracteres especiais escapados, conforme RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax. A mensagem deve conter apenas caracteres da Table imprimíveis ASCII.
interface Seleciona por qual interface GSM (0 ou 1) a mensagem será enviada.
Parâmetro Opcional - Caso não seja selecionado, o Gateway fará a distribuição automática de acordo com a configuração do equipamento.
sim_card Seleciona por qual C - SIM Card (0 ou 1) a mensagem será enviada.
Parâmetro Opcional - Caso não seja selecionado, o Gateway fará a distribuição automática de acordo com a configuração do equipamento.
Parâmetros recebidos pela aplicação - Status de envio e recebimento
sourceaddr Parâmetro utilizado para identificar quem está enviando a mensagem SMS. Ex. sms_server.
NOTA: Esse campo terá o mesmo valor que foi incluído na requisição de envio.
destaddr Numero destino, utilizado no envio da mensagem. Ex: 48XXXXYYYY.
message_id Parâmetro utilizado no envio da mensagem utilizado para mapear as respostas do gateway.
message_ref Essa parâmetro deve ser salvo! Ele será utilizado para mapear o status de recebimento da mensagem (Status-Report). Ao receber um status-report, o valor do campo message_id será o mesmo recebido no status de envio mas no campo message_ref.
status Parâmetro identificando se a mensagem foi aceita pela operadora ( e será enviada ou não)
status=sent : Envio OK
status=error : Erro no envio da mensagem
status=received : Mensagem recebida pelo destino
board Parâmetro utilizado para identificar o endereço IP da placa que enviou a mensagem.
interface Parâmetro utilizado para identificar por qual interface GSM ( 0 ou 1 ) a mensagem foi enviada.
sim_card Parâmetro utilizado para identificar por qual Sim Card ( 0 ou 1 ) a mensagem foi enviada.
error Parâmetro utilizado para identificar qual o erro reportado pela operadora no envio de uma mensagem (Somente recebido quando o parâmetro status for igual a sent). Ver tabela completa de error em API_-_SMS/Codigos_de_Erro_-_Operadora

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:

Códigos de retorno do Gateway SMS
200 Requisição foi aceita pelo gateway e será inserida na fila de envio.
400 (Bad Request) Erro nos parâmetros da requisição
401 (Unauthorized) Erro na autenticação (usuário e senha) com o servidor HTTP do Gateway.
404 (Not Found) Erro no envio - Interface não configurada corretamente ou interface fora rede - não registrada na rede GSM.
413 (Request Entity Too Large) Erro no envio - Mensagem excedeu o tamanho máximo de 160 caracteres.
500 (Internal Server Error) Erro no envio - Erro interno do Servidor HTTP do gateway.
507 Erro no envio - Fila de envio cheia.


Cenários de Envio

Abaixo, 3 cenários de envio de mensagem:

Diagrama envio.png


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.


Enviando Mensagem (Aceita)


Enviando diagrama ok.png


  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:
  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)



Enviando Mensagem (Erro pela Operadora)


Enviando diagrama erro.png


  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:
  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.



Enviando Mensagem (Erro pelo Gateway)


Enviando diagrama erro 2.png


  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:


Recebendo Mensagem


Recebendo sms.png


  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:


Códigos / Exemplos

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;
?>


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);
 
?>


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 ();
        }
    }
}


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");
    }
}



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"


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"


Obtida de "https://wiki.utech.com.br/wiki/index.php?title=API_-_SMS&oldid=757"
Ferramentas pessoais
Espaços nominais

Variantes
Visualizações
Ações
Navegação
Ferramentas