Gua del API SMS REST

Pgina 1 de 27 movistar 2009 Reservados todos los derechos.

Contenido
1 INTRODUCCIN ................................................................................................................... 4 1.1 ALCANCE ...................................................................................................................... 4 1.2 GLOSARIO .................................................................................................................... 5 2 CONVENCIONES GENERALES ........................................................................................... 6 2.1 PAUTAS GENERALES DE UNA INTERFAZ REST ..................................................... 6 2.2 CONSIDERACIONES ESPECFICAS PARA LA API REST DE SMS .......................... 6 2.2.1 Consideraciones de Seguridad ................................................................................. 8 3 DEFINICIN DE LAS OPERACIONES ............................................................................... 10 3.1 ENVO DE SMS........................................................................................................... 10 3.1.1 Peticin .................................................................................................................... 10 3.1.2 RESPUESTA ........................................................................................................... 11 3.2 CONSULTA DEL ESTADO DE ENVO ....................................................................... 12 3.2.1 PETICIN ................................................................................................................ 12 3.2.2 4 5 Respuesta ............................................................................................................... 13 NAMESPACES .................................................................................................................... 15 DEFINICIN DE TIPOS DE DATOS ................................................................................... 16 5.1 ESTRUCTURA DEL SMSTextType ............................................................................ 16 5.2 ESTRUCTURA DEL SMSTextResultType .................................................................. 16 5.3 ESTRUCTURA DEL SMSDeliveryStatusPollType ...................................................... 16 5.4 ESTRUCTURA DEL SMSDeliveryStatusType ............................................................ 17 5.5 ESTRUCTURA DEL DeliveryInformationType ............................................................ 17 5.6 ENUMERACIN DEL DeliveryStatusType ................................................................. 17 5.7 ENUMERACIN DEL AltType .................................................................................... 18 5.8 OPCIN UserIdType ................................................................................................... 18 6 LIBRERAS CLIENTE DE USO DE LAS APIS .................................................................... 19 6.1 CLIENTE JAVA ........................................................................................................... 19 6.1.1 Directrices de Programacin ................................................................................... 19 6.1.2 6.1.3 6.1.4 Ejemplo para el envo con el cliente SMS ............................................................... 19 Paquetes del Cliente ............................................................................................... 20 Prerrequisitos .......................................................................................................... 21

6.2 CLIENTE C# ................................................................................................................ 21 6.2.1 Directrices de Programacin ................................................................................... 21 6.2.2 6.2.3 6.2.4 Ejemplo para el envo con el cliente SMS ............................................................... 21 Paquetes del Cliente ............................................................................................... 22 Prerrequisitos .......................................................................................................... 22

6.3 CLIENTE PHP ............................................................................................................. 22 6.3.1 Dependencias .......................................................................................................... 22 6.3.2 6.3.3 6.3.4 7 A Directrices de Programacin ................................................................................... 22 Ejemplo para el envo con el cliente SMS ............................................................... 22 Paquetes del Cliente ............................................................................................... 23

DETALLE DE LAS DESCRIPCIONES DE ERROR ............................................................ 24 CONSIDERACIONES GENERALES ................................................................................... 25 A.1 Mtodos HTTP ............................................................................................................ 25 A.1.1 POST ....................................................................................................................... 25 A.1.2 A.1.3 A.1.4 GET ......................................................................................................................... 25 PUT.......................................................................................................................... 25 DELETE ................................................................................................................... 26

A.2 REPRESENTACIONES COMUNES ........................................................................... 26 A.2.1 JSON ....................................................................................................................... 26

Pgina 2 de 27 movistar 2009 Reservados todos los derechos.

A.2.2 B

XML ......................................................................................................................... 26

REFERENCIAS .................................................................................................................... 27

Pgina 3 de 27 movistar 2009 Reservados todos los derechos.

1 INTRODUCCIN
Este documento sirve como gua para el uso de la API REST de envo de SMS que proporciona Movistar Developers PlatformBETA. Las funcionalidades que se exponen son el envo de SMS y la consulta del estado de envo de un SMS. Estas funcionalidades se exponen a travs de una interfaz REST (REpresentational State Transfer) que expone el servicio simplificando las peticiones a travs de sencillas peticiones HTTP. 1.1 ALCANCE

El API SMS de Movistar Developers PlatformBETA permite el envo de mensajes SMS a los siguientes pases. ALEMANIA ARGENTINA BRASIL COLOMBIA CHILE CHINA ECUADOR EL SALVADOR ESPAA ESTADOS UNIDOS FINLANDIA FRANCIA HONK KONG INDIA IRLANDA ISRAEL ITALIA JAPN KOREA DEL SUR GUATEMALA MARRUECOS MXICO NICARAGUA PASES BAJOS PANAM PER PORTUGAL REINO UNIDO REPBLICA CHECA RUSIA SUECIA

Pgina 4 de 27 movistar 2009 Reservados todos los derechos.

TAIWN URUGUAY VENEZUELA

1.2

GLOSARIO API: Application Programming Interface ID: Identifier HTTPS: HyperText Transfer Protocol Secure JSON: JavaScript Object Notation REST: Representational State Transfer SMS: Short Messaging Service URI: Uniform Resource Identifier URL: Uniform Resource Locator WSDL: Web Services Description Language XML: eXtended Markup Language

Pgina 5 de 27 movistar 2009 Reservados todos los derechos.

2 CONVENCIONES GENERALES
2.1 PAUTAS GENERALES DE UNA INTERFAZ REST REST (REpresentational States Transfer) es un estilo de arquitectura basado en los siguientes principios: Direccionabilidad: Los recursos son expuestos mediante URIs. Sin Estado. Las peticiones a los recursos son independientes una de la otra. Conectividad. Los recursos pueden incluir enlaces a otros recursos. Una interfaz uniforme: Las operaciones permitidas son obtencin, creacin, modificacin y eliminacin de recursos utilizando el protocolo HTTP.

La implementacin de estos pilares da como resultado servicios RESTful que se basan en el protocolo HTTP, son independientes del lenguaje, pueden usarse en presencia de firewalls, las aplicaciones pueden cachearlos, son altamente escalables, etc. REST tiene como propsito la implementacin de servicios ligeros, inteligibles y fcilmente implementables que se definen en base a una serie de operaciones RESTful, que implica el intercambio de informacin acorde a los formatos de los datos REST. 2.2 CONSIDERACIONES ESPECFICAS PARA LA API REST DE SMS 1. La peticin de envo de SMS es una peticin POST que se puede hacer con los siguiente Content-Types: - application/xml - application/json - application/x-www-form-urlencoded (soportado, aunque se recomienda usar XML o JSON) 2. La respuesta a esa peticin ir en el formato expresado en la peticin, excepto cuando la peticin sea url-encoded, en cuyo caso las respuestas sern XML. 3. La peticin de SMSDeliveryStatus es una peticin GET, en la que se indica el SMS a consultar a travs de un parmetro indicado en la URI que forma la peticin. Por defecto la respuesta tiene formato XML, aunque se puede pedir que la respuesta est en formato JSON a travs de un parmetro alt, incluido en la URI que forma la peticin. 4. Mapeo de XML A JSON. Puesto que XML es el formato por defecto utilizado en la API de SMS, se incluyen archivos XSD que describen los datos necesarios para invocar al API mediante XML. Para pasar estas representaciones a formato JSON, se presentan las siguientes reglas de aplicacin general:
a. Los elementos XML que aparecen al mismo nivel jerrquico XML (tanto los elementos de primer nivel como los que estn dentro del mismo elemento XML padre), se mapean a un conjunto de pares nombre:valor dentro de un objeto JSON, como se describe a continuacin:
Pgina 6 de 27 movistar 2009 Reservados todos los derechos.

i. Cada elemento XML que aparece una sola vez en el mismo nivel jerrquico se mapea a un par nombre:valor individual. El nombre se forma de acuerdo al punto b, mientras que el valor se forma de acuerdo al punto c. ii. Elementos XML que aparezcan ms de una vez en el mismo nivel jerrquico se mapean a un nico par nombre:valor individual. El nombre se forma de acuerdo al punto b, mientras que el valor is un array JSON que contiene un valor por cada ocurrencia del elemento XML. El nombre se forma de acuerdo al punto b, mientras que los valores se forman de acuerdo al punto c. iii. El nombre y el valor de los objetos JSON irn entre comillas . Adems, cualquier representacin JSON ir entre llaves {}, de acuerdo a la RFC de JSON. b. El nombre del par nombre:valor es el nombre de los elementos XML (nombre_elemento_XML:valor). c. El valor se forma como se describe a continuacin: i. Cuando el elemento XML no tiene ni atributos ni elementos XML hijos, el valor es igual al valor del elemento XML. En caso de que el elemento sea nulo (no tenga valor), se indicar poniendo un valor null en el JSON. ii. Cuando el elemento XML tenga elementos hijos y/o atributos, el valor es un objeto JSON que contiene los siguientes pares nombre:valor : Un par nombre:valor por cada atributo, donde el nombre es el nombre del atributo y el valor es el valor del atributo. Un par nombre:valor asociado al valor del elemento XML, donde nombre es la cadena $t y valor es el valor del elemento XML.

Nota: no hay una regla especfica sobre esto en la RFC de JSON o en json.org. Por tanto, se ha seleccionado la cadena $t en base a las reglas de Google para conversin de feeds XML a JSON (http://code.google.com/intl/es/apis/gdata/json.html).
Pares nombre:valor asociados a elementos XML hijos. Estos pares nombre:valor se forman de acuerdo al punto a.

Dentro de JSON no es necesario reflejar:

i. ii. El primer tag <?xml verion="1.0" encoding="UTF-8" ? Declaracin de namespaces o schemaLocations.

Ejemplo de transformacin XML a JSON.

<Animals> <dog> <name attr="1234">Rufus</name> <BReed>labrador</BReed> </dog> <dog> <name>Marty</name> <BReed>whippet</BReed> <a/> </dog> <dog/> <cat name="Matilda"/> <a/> </Animals>

{"Animals": { "a": null,

Pgina 7 de 27 movistar 2009 Reservados todos los derechos.

"cat": {"name": "Matilda"}, "dog": [ { "BReed": "labrador", "name": { "$t": "Rufus", "attr": "1234" } }, { "BReed": "whippet", "a": null, "name": "Marty" }, null ] }}

2.2.1

Consideraciones de Seguridad

El siguiente punto detalla las consideraciones de seguridad que se deben tener en cuenta en las aplicaciones desarrolladas para acceder a la API de SMS REST. La aplicaciones deben incluir un Authorization header en cada peticin HTTP. El encabezado contendr los siguientes datos:
Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key= "serviceId@spId", signature_method="MD5", signature="MD5(spId+spPassword+timeStamp)", timestamp="YYYYMMDDHHMMSS", version="0.1", token="AccessToken", requestor_id ="MSISDN ", requestor_type ="1"

Los trminos serviceId, spID y spPassword se pueden obtener en la informacin del desarrollador en la Web de Movistar Developers PlatformBETA. Requestor_id es el MSISDN (nmero de telfono) del usuario en nombre del cual la aplicacin invocar el API. AccessToken es un conjunto de 8 caracteres entre los siguientes {a-z, A-Z, 0-9} que el usuario podr obtener y actualizar en la seccin Mi perfil del portal de Movistar Developers PlatformBETA y que la aplicacin debe incluir en la cabecera Authorization para invocar el API en nombre del usuario. Puesto que le aplicacin debe incluir el requestor_id y token del usuario, es responsabilidad del developer solicitar estos datos al usuario antes de invocar el API de la forma que considere ms conveniente. Un ejemplo de un Authorization Header sera:
Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key= "35000001000001@35000001", signature_method="MD5", signature="5b941f30e158d2af2df658dd5acca810", timestamp="20090902154157 ", version="0.1", token="1x3rs6n8", requestor_id ="5213907550010", requestor_type ="1"
Pgina 8 de 27 movistar 2009 Reservados todos los derechos.

Cuando una peticin HTTP se realiza sin la cabecera Authorization o con un formato incorrecto, se recibir una respuesta de error HTTP. Sin embargo, si el formato de la cabecera Authorization es correcto pero los valores contenidos en ella son errneos, se aceptar la peticin pero el mensaje no se enviar. Esta situacin podr comprobarse mediante la operacin GetSMSDeliveryStatus (ver 3.2 CONSULTA DEL ESTADO DE ENVO).

Pgina 9 de 27 movistar 2009 Reservados todos los derechos.

3 DEFINICIN DE LAS OPERACIONES

En este punto se describen las operaciones de envo y consulta de recepcin de mensajes. A travs de la API no slo se pueden enviar SMS sino que tambin se puede consultar el resultado de la peticin. Las operaciones disponibles con el tipo de datos a la entrada y a la salida se describen en el siguiente cuadro.
Operacin SendSMS GetSMS DeliveryStatus Entrada SMSTextType SMSDeliveryStatusPollType Salida SMSTextResultType SMSDeliveryStatusType

3.1
3.1.1

ENVO DE SMS
Peticin
Entrada POST https://200.39.21.12:8443/osg/UNICA-SMSREST/SMS

Operacin HTTP Method URL Content

Los formatos de codificacin son los siguientes: application/xml

application/json application/x-www-form-urlencoded

Algunos ejemplos de peticiones con diferentes Content-Type: Content-Type: application/json

POST /osg/UNICA-SMS-REST/SMS HTTP/1.1 Content-Type: application/json Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key="0100105600@000025", signature_method="MD5", signature="A5766BB000AEA947429B07D8F6896019", timestamp="20091015120206", version="0.1", token="2SDO4gAL", requestor_id="5213907550011", requestor_type="1" User-Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443 Content-Length: 155 {"smsText": { "address": {"phoneNumber": "5213851866417"}, "message": "This is the message content." }}

Content-Type: application/x-www-form-urlencoded
POST /osg/UNICA-SMS-REST/SMS HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key="0100105600@000025", signature_method="MD5", signature="D645CDAD8BFE153CCE0DC368970F8042", timestamp="20091015120036", version="0.1", token="2SDO4gAL", requestor_id="5213907550011", requestor_type="1"
Pgina 10 de 27 movistar 2009 Reservados todos los derechos.

User-Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443 Content-Length: 114 address.phoneNumber=5213851866417&message=This+is+the+message+content.

Content-Type: application/xml
POST /osg/UNICA-SMS-REST/SMS HTTP/1.1 Content-Type: application/xml Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key="0100105600@000025", signature_method="MD5", signature="CF753CB3173FC8F343C2B84EFEDE3AED", timestamp="20091015115855", version="0.1", token="2SDO4gAL", requestor_id="5213907550011", requestor_type="1" User-Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443 Content-Length: 497 <?xml version="1.0" encoding="UTF-8" standalone="no"?> <ns0:smsText xmlns:ns0="http://www.telefonica.com/UNICA/sms_bodies/v0_1_1_LITMUS_LA TAM_03102009" xmlns:ns1="http://www.telefonica.com/UNICA/sms_types/v0_1_1_LITMUS_LAT AM_03102009" xmlns:ns2="http://www.telefonica.com/UNICA_CommonTypes/v0_1"> <ns1:address> <ns2:phoneNumber>5213851866417</ns2:phoneNumber> </ns1:address> <ns1:message>This is the message content.</ns1:message> </ns0:smsText>

3.1.2

RESPUESTA
Entrada 201 Created

Operacin HTTP Response Code Content-Type Headers

Application/json, si la peticin incluy el contenido en JSON

Application/xml, si la peticin incluy el contenido en XML o en URLencoded Contiene el localizador que permite realizar la operacin de consulta de estado de envo. Elemento SMSTextResultType en el formato indicado en la cabecera Content-Type

Location Header Body

En caso de producirse algn error relacionado con: spId o serviceId no vlidos spPassword no vlido La aplicacin no tiene permisos para utilizar el API Parmetros no vlidos Violacin de los SLA

se responder con un cdigo de estado HTTP del tipo 4XX/5XX. Sin embargo, si de produce un error relacionado con:
Pgina 11 de 27 movistar 2009 Reservados todos los derechos.

token no vlido El MSISDN no tiene permisos para utilizar el API

se responder con un cdigo de estado HTTP 201, pero al consultar el estado del envo se obtendr el valor DeliveryImpossible (ver 3.2 CONSULTA DEL ESTADO DE ENVO).

Algunos ejemplos de respuestas con diferentes Content-Type:

Content-Type: application/json
HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Location: https://200.39.21.12:8443/osg/UNICA-SMSREST/SMS/SMSDeliveryStatus?smsIdentifier=10000910151003485403 Content-Type: application/json;charset=ISO-8859-1 Content-Length: 51 Date: Thu, 15 Oct 2009 10:03:48 GMT {"smsTextResult":{"result":"10000910151003485403"}}

Content-Type: application/xml
HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Location: https://200.39.21.12:8443/osg/UNICA-SMSREST/SMS/SMSDeliveryStatus?smsIdentifier=10000910151000384995 Content-Type: application/xml;charset=ISO-8859-1 Content-Length: 240 Date: Thu, 15 Oct 2009 10:00:38 GMT <smsTextResult xmlns="http://www.telefonica.com/UNICA/sms_bodies/v0_1_1_LITMUS_LATAM_ 03102009" xmlns:v0="http://www.telefonica.com/UNICA/sms_types/v0_1_1_LITMUS_LATA M_03102009"> <v0:result>10000910151000384995</v0:result> </smsTextResult>

3.2
3.2.1

CONSULTA DEL ESTADO DE ENVO

PETICIN

La URL necesaria para la peticin de consulta se obtiene en el header de Location incluido en la respuesta a la operacin SendSMS.

Operacin HTTP Method URL Content

Entrada GET https://200.39.21.12:8443/osg/UNICA-SMSREST/SMSDeliveryStatus La peticin GET de consulta no incluye body, la informacin necesaria debe ser pasada como parmetros de consulta.

Pgina 12 de 27 movistar 2009 Reservados todos los derechos.

Ejemplo de una peticin de consulta del Estado de Envo con respuesta en XML
GET /osg/UNICA-SMSREST/SMSDeliveryStatus?smsIdentifier=10000910151005185603 HTTP/1.1 Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key="0100105600@000025", signature_method="MD5", signature="4E787BC6A43561968224BD9ACDFCBE3A", timestamp="20091015120337", version="0.1", token="2SDO4gAL", requestor_id="5213907550011", requestor_type="1" User-Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443

Ejemplo de una peticin de consulta del Estado de Envo con respuesta en JSON
GET /osg/UNICA-SMSREST/SMSDeliveryStatus?smsIdentifier=10000910151014046414&alt=json HTTP/1.1 Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key="0100105600@000025", signature_method="MD5", signature="2760345011F7C1B49BEA572EEE235F2A", timestamp="20091015121223", version="0.1", token="2SDO4gAL", requestor_id="5213907550011", requestor_type="1" User-Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443

3.2.2

Respuesta
Entrada 200 OK

Operacin HTTP Response Code Content-Type Headers Body

Application/json
Application/xml (por defecto) Un elemento del tipo SMSDeliveryStatusType indicado en el formato expresado en el Content-Type

Ejemplo de una respuesta en JSON

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: application/json;charset=ISO-8859-1 Content-Length: 126 Date: Thu, 15 Oct 2009 10:14:05 GMT {"smsDeliveryStatus":{"smsDeliveryStatus":{"address":{"anyUri":"tel:+5 213851866417"},"deliveryStatus":"DeliveredToTerminal"}}}

Ejemplo de una respuesta en XML

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: application/xml;charset=ISO-8859-1 Content-Length: 481 Date: Thu, 15 Oct 2009 10:05:19 GMT

Pgina 13 de 27 movistar 2009 Reservados todos los derechos.

<NS1:smsDeliveryStatus xmlns:NS1="http://www.telefonica.com/UNICA/sms_bodies/v0_1_1_LITMUS_LA TAM_03102009"> <NS2:smsDeliveryStatus xmlns:NS2="http://www.telefonica.com/UNICA/sms_types/v0_1_1_LITMUS_LAT AM_03102009"> <NS2:address> <NS3:anyUri xmlns:NS3="http://www.telefonica.com/UNICA_CommonTypes/v0_1">tel:+5213 851866417</NS3:anyUri> </NS2:address> <NS2:deliveryStatus>DeliveredToTerminal</NS2:deliveryStatus> </NS2:smsDeliveryStatus> </NS1:smsDeliveryStatus>

Pgina 14 de 27 movistar 2009 Reservados todos los derechos.

4 NAMESPACES
Los tipos de datos estn definidos en el siguiente namespace: http://www.telefonica.com/UNICA/sms_types/v0_1_1_LITMUS_LATAM_03102009 Los elementos superiores utilizados en los cuerpos de las peticiones y repuestas REST estn definidos en el siguiente namespace: http://www.telefonica.com/UNICA/sms_bodies/v0_1_1_LITMUS_LATAM_03102009 Los tipos de datos comunes para todas las APIs estn definidas en el siguiente namespace. http://www.telefonica.com/UNICA_CommonTypes/v0_1 Otros tipos de datos comunes adoptados de ParlayX estn definidos en el siguiente namespace:
http://www.csapi.org/schema/parlayx/common/v3_1

Pgina 15 de 27 movistar 2009 Reservados todos los derechos.

5 DEFINICIN DE TIPOS DE DATOS

En este captulo se muestran las definiciones de los tipos de datos utilizados por esta API. Las siguientes consideraciones deben tenerse en cuenta: Las definiciones son mapeos directos a XML Schemas La definicin de estos tipos de datos est basada en GSMA OneAPI [3] y ParlayX 3.1 [2]. En algunos casos, el tipo de dato corresponde directamente con un tipo de dato definido en ParlayX. Por lo tanto, en los esquemas proporcionados se importan los tipos de datos de ParlayX.

5.1

ESTRUCTURA DEL SMSTextType

Informacin para el envo de un SMS.

Parmetro address

message

Elemento tipo uct:UserIdTyp e [1..unbounde d] xsd: string

Opcion al No

Descripcin Lista de direcciones a las cules se van a enviar los SMS. IdToken y valores de IP no son aceptadas. El mensaje a enviar. Longitud mxima 160 caracteres (tenga en cuenta que los caracteres acentuados ocupan dos caracteres a la hora del envo). En algunas ocasiones, los caracteres acentuados podran no visualizarse correctamente en el terminal. Cuando la codificacin es base64, esta operacin permite enviar un SMS de aviso o push SMS, con los siguientes parmetros extensibles: sourceport, destinationport, esm_class y data_coding. Indica el nmero de puerto de la aplicacin asociado con la direccin origen del mensaje. Opcional para MyMail service. Indica el nmero de puerto de la aplicacin asociado con la direccin destion del mensaje. Este parmetro es utilizado para indicar atributos especiales a con un mensaje corto. Define la codificacin de los datos de usuario del mensaje corto.

No

encode

xsd:string

sourceport destinationpo rt esm_class data_coding

xsd:int xsd:int xsd:int xsd:int

S S S S

5.2

ESTRUCTURA DEL SMSTextResultType

Respuesta de la operacin REST SendSMS para consulta del estado de entrega.

Parmetro result

Elemento tipo xsd: string

Opcion al No

Descripcin Es un identificador correlado con el SMS enviado que se utiliza en una operacin GetSMSDeliveryStatus

5.3

ESTRUCTURA DEL SMSDeliveryStatusPollType

Utilizado como entrada para la consulta o recepcin sncrona del estado de entrega de un SMS.

Pgina 16 de 27 movistar 2009 Reservados todos los derechos.

Parmetro

Elemento tipo

smsIdentifier xsd: string alt uct:AltType

Opcion al No S

Descripcin Identificador relacionado con el estado de entrega del SMS. Parmetro opcional que sirve para indicar que se realiza la consulta en formato JSON. (alt=JSON)

Debe tenerse en cuenta que el tipo de dato SMSDeliveryStatusPollType se utiliza en las operaciones GET y por lo tanto, debe pasarse en las peticiones en la URI de peticin. De esta manera, no se utiliza XML ni JSON para la codificacin de este tipo de datos.

5.4

ESTRUCTURA DEL SMSDeliveryStatusType

Nota: Se utiliza como base GSMA OneAPI [3] y ParlayX 3.1 [2].

Informacin del estado de entrega del SMS.

Parmetro smsDeliveryStat us

Elemento tipo DeliveryInform ationType [0..unbounded]

Opcion al S

Descripcin Describe las variaciones del estado de entrega del SMS. Valores posibles son: DeliveredToNetwork DeliveryUncertain DeliveryImpossible MessageWaiting DeliveredToTerminal

5.5

ESTRUCTURA DEL DeliveryInformationType

Nota: Tomado de ParlayX 3.1 [2]

Informacin de la entrega del SMS

Parmetro

Elemento tipo

Opcion al

Descripcin
Indica la direccin de destino con la que la notificacin est relacionada.

address deliveryStatus description

uct:UserIdType No DeliveryStatus Type xsd:string No S

Indica el resultado de la entrega para las direcciones de destino. Utilizado junto al estado de entrega (i.e. DeliveryImpossible) para proporcionar informacin adicional.

5.6

ENUMERACIN DEL DeliveryStatusType

Nota: Tomados de ParlayX 3.1 [2]

Lista de valores posible del estado de Entrega.

Enumeracin

DeliveredToNetwork DeliveryUncertain

Descripcin Entrega a la red con xito Estado de entrega desconocido. (p. ej: por haber sido enviado a otra red)

Pgina 17 de 27 movistar 2009 Reservados todos los derechos.

DeliveryImpossible MessageWaiting DeliveredToTerminal DeliveryNotificationNotS upported

Entrega imposible, el mensaje no pudo ser entregado antes de expirar El mensaje est encolado para entrega. Este es un estado temporal, pendiente de transicin a otro estado mencionado. Entrega exitosa Imposible proveer la notificacin de entrega. Se usa para indicar que la recepcin de entrega para la direccin especificada en una operacin SendSMS no est soportada.

Nota: En los envos fuera de Mxico podra no llegar a obtenerse un estado DeliveredToTerminal, aunque el mensaje se haya entregado correctamente.

5.7

ENUMERACIN DEL AltType

Parmetro para solicitar una respuesta en formato JSON.

Enumeracin

JSON

Descripcin El formato del contenido de la respuesta debe ser JSON

5.8
Parmetro

OPCIN UserIdType
Elemento tipo Opcion al Descripcin
Nmero de telfono

phoneNumber anyUri ipAddress alias otherId

E164Type xsd:anyURI IpAddressType AliasType OtherIdType

S S S S S

Cualquier URI Direccin IP Alias Cualquier otro tipo de identidad de usuario

Pgina 18 de 27 movistar 2009 Reservados todos los derechos.

6 LIBRERAS CLIENTE DE USO DE LAS APIS

6.1
6.1.1

CLIENTE JAVA
Directrices de Programacin

De forma general, se define un interface principal para cada API, que define las operaciones REST de cliente permitidas para el correspondiente servicio. Mediante un mecanismo de factories se ofrecen implementaciones de estos interfaces, que funcionan como clientes REST. Estos clientes implementan las operaciones definidas para cada API utilizando un modelo de datos Java acorde con los tipos de datos definidos en las APIs. El interface implementado por los clientes SMS es el siguiente:

SMS API Client: es.tid.unica.rest.sms.SMSClient

La factory que debe ser usada para obtener una instancia de la clase cliente para SMS es la que sigue: SMS API Client Factory: es.tid.unica.rest.sms.SMSClientFactory

6.1.2

Ejemplo para el envo con el cliente SMS

En primer lugar se realiza la construccin del objeto cliente (SMSClient), mediante el uso de una factory (SMSClientFactory) A continuacin se configura el cliente con los datos necesarios, tanto para el establecimiento de la conexin con el servidor (incluyendo el uso de un proxy, si es necesario, as como el endpoint en el que se encuentra el servicio al que se va a invocar), como para permitir la autenticacin del cliente. Esto ltimo supone especificar los elementos que forman las credenciales de seguridad que van a ser utilizadas. Una vez hecho todo lo anterior, ya es posible realizar el envo de un SMS, utilizando el mtodo sendSMS. Dicho mtodo toma como parmetros el mensaje en s, construido utilizando las clases proporcionadas por la API, que siguen exactamente las especificaciones de tipos de datos explicados en las secciones anteriores, as como la codificacin empleada. Una vez enviado el SMS se obtiene como respuesta un objeto, de la clase SMSResult, que contiene el resultado de la operacin de envo, incluyendo la URI que podr ser utilizada para consultar el delivery status de dicho SMS.

El siguiente ejemplo muestra el uso del cliente para el uso de la API REST de SMS:

import import import import import import import import import

es.tid.unica.rest.Encoding; es.tid.unica.rest.sms.SMSClient; es.tid.unica.rest.sms.SMSClientFactory; es.tid.unica.rest.sms.SendSMSResult; es.tid.unica.types.common.E164Type; es.tid.unica.types.common.UserIdType; es.tid.unica.types.sms.SMSDeliveryStatusType; es.tid.unica.types.sms.SMSTextContentType; es.tid.unica.types.sms.SMSTextType;

// General configuration data String base_uri = "https://200.39.21.12:8443/osg/UNICA-SMS-REST"; String proxy_host = null; // No proxy is used int proxy_port = 80; // Security configuration data String service_id = "0100105600"; String sp_id = "000025"; String sp_password = "123456"; String access_token = "2SDO4gAL"; String requestor_id = "5213907550011";

Pgina 19 de 27 movistar 2009 Reservados todos los derechos.

int requestor_type = 1; // String receipt_msisdn = "5213851866417"; String message_text = "This is the text to be sent"; try { // Creating the client SMSClient client = SMSClientFactory.getInstance().createSMSClient(base_uri, proxy_host, proxy_port); // Initialize the client client.setServiceId(service_id); client.setSpId(sp_id); client.setSpPassword(sp_password); client.setAccessToken(access_token); client.setRequestorId(requestor_id); client.setRequestorType(requestor_type); // Enable authentication client.enableAuthentication(true); //----------------------------------------------// Send an SMS // 1. Build the message SMSTextType sms = new SMSTextType(); // 1.1 Receipt address UserIdType address = new UserIdType(); address.setPhoneNumber(new E164Type(receipt_msisdn)); sms.addAddress(address); // 1.2 Text content SMSTextContentType sms_text_content = new SMSTextContentType(message_text); sms.setMessage(sms_text_content); // 2. Send the message. SendSMSResult result = client.sendSMS(sms, Encoding.APPLICATION_XML); System.out.println("The result of the sendSMS opeation is " + result); //----------------------------------------------//----------------------------------------------// Retrieve the delivery status of the sent SMS. SMSDeliveryStatusType status = client.getSMSDeliveryStatus(result.getLocationHeader().toString(), null); System.out.println("The result of the getSMSDeliveryStatus opeation is " + status); //----------------------------------------------} catch (Exception e) { e.printStackTrace(); }

6.1.3

Paquetes del Cliente

La librera Java de cliente SMS est formada por los siguientes paquetes:

Enumeracin

es.tid.unica.rest.sms es.tid.unica.types.common es.tid.unica.types.parlayx.co mmon es.tid.unica.types.sms

Descripcin Paquete que contiene las clases principales para el cliente SMS REST API. Paquete que contiene los tipos de datos principales para los mensajes y los parmetros utilizados por las APIs. Este paquete contiene los tipos de datos bsicos de ParlayX, que pueden ser utilizados en las APIs Paquete que contiene los tipos de datos especficos de la API de SMS

Pgina 20 de 27 movistar 2009 Reservados todos los derechos.

6.1.4

Prerrequisitos

Para el correcto funcionamiento de la librera de cliente de Java de SMS es necesario tener instalada la versin 1.5 o superior del JRE (Java Runtime Environment) o JDK (Java Development Kit). Tambin es necesario utilizar las libreras contenidas en los archivos .jar situados en el directorio lib de la distribucin del cliente Java.

6.2
6.2.1

CLIENTE C#
Directrices de Programacin

Se define una clase factory para cada API actuando como creador de clientes REST. A partir de una instancia nica de la factory se puede obtener un cliente para el API al que pertenece, poblado con ms o menos datos iniciales dependiendo de la operacin de creacin utilizada. El cliente obtenido, por flexibilidad a la hora de proveer diferentes implementaciones, se ofrece en forma de interfaz del lenguaje C#. La interfaz obtenida a partir del factory se comportar como un cliente REST. Estos clientes implementan las operaciones definidas para cada API utilizando un modelo de datos C# acorde con los tipos de datos definidos en las APIs. La factory e interfaz del cliente SMS para la API REST son los siguientes:

SMS Client Factory: SMS Client Interface API:

es.tid.unica.rest.sms.SMSClientFactory es.tid.unica.rest.sms.ISMSClient

6.2.2

Ejemplo para el envo con el cliente SMS

El siguiente ejemplo muestra el uso del cliente para el uso de la API REST de SMS:
try { //1.- instanciate factory and create client from factory instance. //In this example we will use baseUri and proxy data ISMSClient smsClient = SMSClientFactory.GetInstance().CreateSMSClient(baseUri, proxyHost, proxyPort); //2.- Set credentials for authentication smsClient.Credentials.ServiceId = serviceId; smsClient.Credentials.SpId = spId; smsClient.Credentials.SpPassword = spPassword; smsClient.Credentials.RequestorId = accessNumber; smsClient.Credentials.RequestorType = requestorType; smsClient.Credentials.AccessToken = accessToken; //3.-Create text message object SMSTextType sms = new SMSTextType(); //4.- Create at least one destination address and add it to message object UserIdType address = new UserIdType(); address.PhoneNumber = new E164Type("5213851866417"); sms.AddAddress(address); //5.- Create message internal text content and add it to message object SMSTextContentType message = new SMSTextContentType("This is the content"); sms.Message = message; //6.- Define encoding Encoding encoding = Encoding.APPLICATION_URL_ENCODED; //6.- Send message using SMS client SendSMSResult sendSMSResult=smsClient.SendSMS(sms, encoding); //7.- Check delivery result message identifier Console.WriteLine("SMS Identifier: {0}", sendSMSResult.SmsTextResult.Result.Data); } catch (Exception ex) { Console.WriteLine(ex.Message);

Pgina 21 de 27 movistar 2009 Reservados todos los derechos.

6.2.3

Paquetes del Cliente

Se describen los paquetes

Enumeracin

es.tid.unica.rest.sms es.tid.unica.types.common es.tid.unica.types.parlayx.co mmon es.tid.unica.types.sms

Descripcin Paquete que contiene las clases principales para el cliente SMS REST API. Paquete que contiene los tipos de datos principales para los mensajes y los parmetros utilizados por las APIs. Este paquete contiene los tipos de datos bsicos de ParlayX, que pueden ser utilizados en las APIs Paquete que contiene los tipos de datos especficos de la API de SMS

6.2.4

Prerrequisitos
Sistema Operativo Windows XP Service Pack 2 (o superior) o Windows Vista Microsoft .NET Framework 3.5, disponible para descarga gratuita en http://www.microsoft.com/downloads

Para el correcto funcionamiento de las APIs C# son necesarios lo siguientes prerrequisitos:

Esta librera no ha sido diseada para otros entornos como Mono o Portable.NET.

6.3
6.3.1

CLIENTE PHP
Dependencias
PHP 5.2.6 PHP5-CURL 5.2.6 CURL 7.18.2

6.3.2

Directrices de Programacin

Se define una clase para cada API actuando como un cliente REST. Estos clientes implementan las operaciones definidas para cada API utilizando como referencia los tipos de datos definidos en las APIs. Las clases del cliente SMS para la API REST son las que siguen (una clase para cada tipo de codificacin):

smsRESTlibraryXML.php smsRESTlibraryJSON.php smsRESTlibraryURLEnc.php

Esta librera se ha probado en los siguientes sistemas operativos: CentOs 5, Fedora 11, Ubuntu Jaunty, Ubuntu Karmic, Debian Lenny, Windows 7 y Windows XP.
6.3.3 Ejemplo para el envo con el cliente SMS

El siguiente ejemplo muestra el uso del cliente para el uso de la API REST de SMS:
<?php

Pgina 22 de 27 movistar 2009 Reservados todos los derechos.

//Clase para el envio de SMS mediante URL encode include_once "./smsRESTlibraryURLEnc.php"; //Creacin del cliente para el envio de SMS $smsClient = new smsRESTclient($spId,$serviceId,$spPassword,$token,$requestor_id,$apiendpoint); //Destinatario del SMS $address["phoneNumber"]="0000000000"; //Contenido del SMS $message= "Esto es una prueba"; //Envio del SMS y resultado $result = $smsClient->sendSMS($address,$message); ?>

6.3.4

Paquetes del Cliente

Se describen los paquetes

Enumeracin

smsRESTlibraryXML.php smsRESTlibraryJSON.php smsRESTlibraryURLEnc.php

Descripcin Paquete que contiene la clase principal para el cliente SMS REST API con codificacin XML. Paquete que contiene la clase principal para el cliente SMS REST API con codificacin JSON. Paquete que contiene la clase principal para el cliente SMS REST API con codificacin URL encode.

Pgina 23 de 27 movistar 2009 Reservados todos los derechos.

7 DETALLE DE LAS DESCRIPCIONES DE ERROR

Las operaciones descritas en esta gua pueden devolver una serie de cdigos de error HTTP, como se explica a continuacin.
En caso de producirse algn error relacionado con: spId o serviceId no vlidos spPassword no vlido La aplicacin no tiene permisos para utilizar el API Parmetros no vlidos Violacin de los SLA

se responder con un cdigo de estado HTTP del tipo 4XX/5XX. Sin embargo, si de produce un error relacionado con: token no vlido El MSISDN no tiene permisos para utilizar el API

se responder con un cdigo de estado HTTP 201, pero al consultar el estado del envo se obtendr el valor DeliveryImpossible.

Pgina 24 de 27 movistar 2009 Reservados todos los derechos.

CONSIDERACIONES GENERALES

En esta seccin se describen elementos necesarios para el normal funcionamiento de la API REST SMS:
Mtodos HTTP: que constituyen las operaciones RESTful, de acuerdo con los principios REST. Representaciones comunes.

A.1

Mtodos HTTP

Las siguientes descripciones se han extrado de la RFC de HTTP 1.1.

A.1.1

POST

El mtodo POST se utiliza para solicitar que el servidor de origen acepte la entidad contenida en la peticin como un nuevo recurso identificado por la URI de la peticin en la Request-Line. POST est diseado para permitir un mtodo uniforme que cubra las siguientes funciones:
Anotacin de recursos existentes. Postear un mensaje en un boletn, grupo de noticias, lista de correo, o grupo similar de artculos. Proveer un bloque de datos, como el resultado del envo de un formulario, para que sea procesado. Extender una base de datos a travs del aadido de una operacin.

La actual funcionalidad desarrollada por el mtodo POST est determinada por el servidor y es usualmente dependiente de la Request-URI. La entidad posteada est subordinada a esa URI de la misma manera que el archivo est subordinado al directorio que lo contiene, un artculo de noticias est subordinado a un grupo de noticias al que est posteado, como un registro est subordinado a una base de datos.

A.1.2

GET

El mtodo GET intenta extraer cualquier informacin (en la forma de una entidad) identificada por una Request-URI. Si la Request-URI se refiere a un proceso que genera datos, es un dato producido que debe devolverse como la entidad en la respuesta y no el texto origen del proceso, a no ser que el texto sea la salida del proceso.

A.1.3

PUT

El mtodo PUT solicita que la entidad contenida sea almacenada bajo la Request-URI proporcionada. Si la Request-URI se refiere a un recurso existente, la entidad contenida
Pgina 25 de 27 movistar 2009 Reservados todos los derechos.

debe ser considerada como una versin modificada del recurso residente en el servidor. Si la Request-URI no apunta a un recurso existente, y la URI es capaz de ser definida como un nuevo recurso por el agente solicitante, el servidor de origen puede crear el recurso con esa URI.

A.1.4

DELETE

El mtodo Delete solicita que el servidor de origen borre el recurso identificado con la Request-URI. Este mtodo puede ser reescrito por intervencin humana (u otros mtodos) en el servidor de origen. El cliente no puede garantizar que la operacin haya sido llevada a trmino, incluso si el cdigo de estado devuelto desde el origen indica que la accin ha sido completada con xito. Sin embargo, el servidor no debe indicar una respuesta satisfactoria a no ser que, en el momento en que la respuesta es entregada, intente borrar el recurso o moverlo a una localizacin inaccesible.

A.2
A.2.1

REPRESENTACIONES COMUNES
JSON

Las peticiones POST pueden incluir datos en formato JSON. Las respuestas deben incluir el cuerpo en formato JSON, si corresponden a peticiones POST incluidas en formato JSON o si corresponden a peticiones GET incluidas con el parmetro alt=json. En estos casos, la cabecera Content-Type:Application/json debe estar presente en la respuesta.

A.2.2

XML

Las peticiones POST pueden incluir datos en formato XML. En estos casos, se utiliza un cuerpo application/xml. Este formato XML debe cumplir con las especificaciones de XML Schema. Las respuestas deben incluir un cuerpo del XML si la correspondiente peticin POST incluye datos en formato XML o si la correspondiente peticin GET no inclua el parmetro alt=json. En estos casos, la cabecera Content-Type: Application/xml debe estar presente en la respuesta.

Pgina 26 de 27 movistar 2009 Reservados todos los derechos.

REFERENCIAS

[1] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common [2] 3GPP TS 29.199-4: "Open Service Access (OSA); Parlay X Web Services; Part 4: Short Messaging". [3] [4] GSMA OneAPI, http://gsma.securespsite.com/access/default.aspx RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1

[5] W3C Recommendation (26 June 2007): "Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts, https://www.w3.org/TR/2007/REC-wsdl20adjuncts-20070626/#_http_binding_default_rule_method [6] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes", http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.

Pgina 27 de 27 movistar 2009 Reservados todos los derechos.