Sms Rest Api Developers Guide 2n723m

Guía del API SMS REST

Página 1 de 27 movistar © 2009 Reservados todos los derechos.

Contenido 1

INTRODUCCIÓN ................................................................................................................... 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 ESPECÍFICAS PARA LA API REST DE SMS .......................... 6 2.2.1 Consideraciones de Seguridad ................................................................................. 8 3

DEFINICIÓN DE LAS OPERACIONES ............................................................................... 10 3.1 ENVÍO DE SMS........................................................................................................... 10 3.1.1 Petición .................................................................................................................... 10 3.1.2

RESPUESTA ........................................................................................................... 11

3.2 CONSULTA DEL ESTADO DE ENVÍO ....................................................................... 12 3.2.1 PETICIÓN ................................................................................................................ 12 3.2.2

Respuesta ............................................................................................................... 13

4 5

NAMESPACES .................................................................................................................... 15 DEFINICIÓN 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 ENUMERACIÓN DEL DeliveryStatusType ................................................................. 17 5.7 ENUMERACIÓN DEL AltType .................................................................................... 18 5.8 OPCIÓN IdType ................................................................................................... 18 6 LIBRERÍAS CLIENTE DE USO DE LAS APIS .................................................................... 19 6.1 CLIENTE JAVA ........................................................................................................... 19 6.1.1 Directrices de Programación ................................................................................... 19 6.1.2

Ejemplo para el envío con el cliente SMS ............................................................... 19

6.1.3

Paquetes del Cliente ............................................................................................... 20

6.1.4

Prerrequisitos .......................................................................................................... 21

6.2 CLIENTE C# ................................................................................................................ 21 6.2.1 Directrices de Programación ................................................................................... 21 6.2.2

Ejemplo para el envío con el cliente SMS ............................................................... 21

6.2.3

Paquetes del Cliente ............................................................................................... 22

6.2.4

Prerrequisitos .......................................................................................................... 22

6.3 CLIENTE PHP ............................................................................................................. 22 6.3.1 Dependencias .......................................................................................................... 22

7 A

6.3.2

Directrices de Programación ................................................................................... 22

6.3.3

Ejemplo para el envío con el cliente SMS ............................................................... 22

6.3.4

Paquetes del Cliente ............................................................................................... 23

DETALLE DE LAS DESCRIPCIONES DE ERROR ............................................................ 24 CONSIDERACIONES GENERALES ................................................................................... 25 A.1 Métodos HTTP ............................................................................................................ 25 A.1.1 POST ....................................................................................................................... 25 A.1.2

GET ......................................................................................................................... 25

A.1.3

PUT.......................................................................................................................... 25

A.1.4

DELETE ................................................................................................................... 26

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

Página 2 de 27 movistar © 2009 Reservados todos los derechos.

A.2.2 B

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

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

Página 3 de 27 movistar © 2009 Reservados todos los derechos.

1 INTRODUCCIÓN Este documento sirve como guía para el uso de la API REST de envío de SMS que proporciona Movistar Developers PlatformBETA. Las funcionalidades que se exponen son el envío de SMS y la consulta del estado de envío de un SMS. Estas funcionalidades se exponen a través de una interfaz REST (REpresentational State Transfer) que expone el servicio simplificando las peticiones a través de sencillas peticiones HTTP. 1.1

ALCANCE

El API SMS de Movistar Developers PlatformBETA permite el envío de mensajes SMS a los siguientes países. • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

ALEMANIA ARGENTINA BRASIL COLOMBIA CHILE CHINA ECUADOR EL SALVADOR ESPAÑA ESTADOS UNIDOS FINLANDIA FRANCIA HONK KONG INDIA IRLANDA ISRAEL ITALIA JAPÓN KOREA DEL SUR GUATEMALA MARRUECOS MÉXICO NICARAGUA PAÍSES BAJOS PANAMÁ PERÚ PORTUGAL REINO UNIDO REPÚBLICA CHECA RUSIA SUECIA

Página 4 de 27 movistar © 2009 Reservados todos los derechos.

• • •

1.2

TAIWÁN URUGUAY VENEZUELA

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

Página 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 obtención, creación, modificación y eliminación de recursos utilizando el protocolo HTTP.

La implementación 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 propósito la implementación de servicios ligeros, inteligibles y fácilmente implementables que se definen en base a una serie de operaciones RESTful, que implica el intercambio de información acorde a los formatos de los datos REST. 2.2

CONSIDERACIONES ESPECÍFICAS PARA LA API REST DE SMS 1. La petición de envío de SMS es una petición 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 petición irá en el formato expresado en la petición, excepto cuando la petición sea url-encoded, en cuyo caso las respuestas serán XML. 3. La petición de SMSDeliveryStatus es una petición GET, en la que se indica el SMS a consultar a través de un parámetro indicado en la URI que forma la petición. Por defecto la respuesta tiene formato XML, aunque se puede pedir que la respuesta esté en formato JSON a través de un parámetro “alt”, incluido en la URI que forma la petición. 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 aplicación general: a. Los elementos XML que aparecen al mismo nivel jerárquico XML (tanto los elementos de primer nivel como los que están dentro del mismo elemento XML padre), se mapean a un conjunto de pares nombre:valor dentro de un objeto JSON, como se describe a continuación:

Página 6 de 27 movistar © 2009 Reservados todos los derechos.

i. Cada elemento XML que aparece una sola vez en el mismo nivel jerárquico 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 más de una vez en el mismo nivel jerárquico 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 irán entre comillas “”. Además, cualquier representación 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 continuación: 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 específica 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 conversión 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
Ejemplo de transformación XML a JSON. <dog> Rufus labrador <dog> Marty whippet <dog/>

{"Animals": { "a": null, Página 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 petición HTTP. El encabezado contendrá los siguientes datos: Authorization: SDPBasicAuth realm="SDPAPIs", consumer_key= "serviceId@spId", signature_method="MD5", signature="MD5(spId+sp+timeStamp)", timestamp="YYYYMMDDHHMMSS", version="0.1", token="AccessToken", requestor_id ="MSISDN ", requestor_type ="1"

Los términos serviceId, spID y sp se pueden obtener en la información del desarrollador en la Web de Movistar Developers PlatformBETA. Requestor_id es el MSISDN (número de teléfono) del en nombre del cual la aplicación invocará el API. AccessToken es un conjunto de 8 caracteres entre los siguientes {a-z, A-Z, 0-9} que el podrá obtener y actualizar en la sección “Mi perfil” del portal de Movistar Developers PlatformBETA y que la aplicación debe incluir en la cabecera Authorization para invocar el API en nombre del . Puesto que le aplicación debe incluir el requestor_id y token del , es responsabilidad del developer solicitar estos datos al antes de invocar el API de la forma que considere más conveniente. Un ejemplo de un Authorization Header sería: 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" Página 8 de 27 movistar © 2009 Reservados todos los derechos.

Cuando una petición 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 erróneos, se aceptará la petición pero el mensaje no se enviará. Esta situación podrá comprobarse mediante la operación GetSMSDeliveryStatus (ver 3.2 CONSULTA DEL ESTADO DE ENVÍO).

Página 9 de 27 movistar © 2009 Reservados todos los derechos.

3 DEFINICIÓN DE LAS OPERACIONES En este punto se describen las operaciones de envío y consulta de recepción de mensajes. A través de la API no sólo se pueden enviar SMS sino que también se puede consultar el resultado de la petición. Las operaciones disponibles con el tipo de datos a la entrada y a la salida se describen en el siguiente cuadro. Operación SendSMS GetSMS DeliveryStatus

3.1 3.1.1

Entrada SMSTextType SMSDeliveryStatusPollType

Salida SMSTextResultType SMSDeliveryStatusType

ENVÍO DE SMS Petición

Operación HTTP Method URL

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

Content

Los formatos de codificación 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" -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" Página 10 de 27 movistar © 2009 Reservados todos los derechos.

-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" -Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443 Content-Length: 497 <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 <ns1:message>This is the message content.

3.1.2

RESPUESTA

Operación HTTP Response Code Content-Type Headers

Location Header Body

Entrada 201 Created

Application/json, si la petición incluyó el contenido en JSON Application/xml, si la petición incluyó el contenido en XML o en URLencoded Contiene el localizador que permite realizar la operación de consulta de estado de envío. Elemento SMSTextResultType en el formato indicado en la cabecera Content-Type

En caso de producirse algún error relacionado con: -

spId o serviceId no válidos

-

sp no válido

-

La aplicación no tiene permisos para utilizar el API

-

Parámetros no válidos

-

Violación de los SLA

se responderá con un código de estado HTTP del tipo 4XX/5XX. Sin embargo, si de produce un error relacionado con: Página 11 de 27 movistar © 2009 Reservados todos los derechos.

-

token no válido

-

El MSISDN no tiene permisos para utilizar el API

se responderá con un código de estado HTTP 201, pero al consultar el estado del envío se obtendrá el valor DeliveryImpossible (ver 3.2 CONSULTA DEL ESTADO DE ENVÍO).

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"> 10000910151000384995

3.2 3.2.1

CONSULTA DEL ESTADO DE ENVÍO PETICIÓN

La URL necesaria para la petición de consulta se obtiene en el header de Location incluido en la respuesta a la operación SendSMS.

Operación HTTP Method URL Content

Entrada GET https://200.39.21.12:8443/osg/UNICA-SMSREST/SMSDeliveryStatus La petición GET de consulta no incluye body, la información necesaria debe ser pasada como parámetros de consulta.

Página 12 de 27 movistar © 2009 Reservados todos los derechos.

Ejemplo de una petición de consulta del Estado de Envío 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" -Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443

Ejemplo de una petición de consulta del Estado de Envío 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" -Agent: Jakarta Commons-HttpClient/3.1 Host: 200.39.21.12:8443

3.2.2

Respuesta

Operación HTTP Response Code Content-Type Headers Body

Entrada 200 OK

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

Página 13 de 27 movistar © 2009 Reservados todos los derechos.

tel:+5213 851866417

DeliveredToTerminal

Página 14 de 27 movistar © 2009 Reservados todos los derechos.

4 NAMESPACES Los tipos de datos están 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 están 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 están definidas en el siguiente namespace. http://www.telefonica.com/UNICA_CommonTypes/v0_1 Otros tipos de datos comunes adoptados de ParlayX están definidos en el siguiente namespace: http://www.csapi.org/schema/parlayx/common/v3_1

Página 15 de 27 movistar © 2009 Reservados todos los derechos.

5 DEFINICIÓN DE TIPOS DE DATOS En este capítulo 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 definición 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

Información para el envío de un SMS.

Parámetro

Opcion al No

message

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

encode

xsd:string

Sí

sourceport

xsd:int

Sí

destinationpo rt esm_class

xsd:int

Sí

xsd:int

Sí

data_coding

xsd:int

Sí

address

5.2

No

Descripción Lista de direcciones a las cuáles se van a enviar los SMS. IdToken y valores de IP no son aceptadas. El mensaje a enviar. Longitud máxima 160 caracteres (tenga en cuenta que los caracteres acentuados ocupan dos caracteres a la hora del envío). En algunas ocasiones, los caracteres acentuados podrían no visualizarse correctamente en el terminal. Cuando la codificación es base64, esta operación permite enviar un SMS de aviso o push SMS, con los siguientes parámetros extensibles: sourceport, destinationport, esm_class y data_coding. Indica el número de puerto de la aplicación asociado con la dirección origen del mensaje. Opcional para MyMail service. Indica el número de puerto de la aplicación asociado con la dirección destion del mensaje. Este parámetro es utilizado para indicar atributos especiales a con un mensaje corto. Define la codificación de los datos de del mensaje corto.

ESTRUCTURA DEL SMSTextResultType

Respuesta de la operación REST SendSMS para consulta del estado de entrega.

Parámetro result

5.3

Elemento tipo xsd: string

Opcion al No

Descripción Es un identificador correlado con el SMS enviado que se utiliza en una operación GetSMSDeliveryStatus

ESTRUCTURA DEL SMSDeliveryStatusPollType

Utilizado como entrada para la consulta o recepción síncrona del estado de entrega de un SMS.

Página 16 de 27 movistar © 2009 Reservados todos los derechos.

Parámetro

Elemento tipo

smsIdentifier xsd: string uct:AltType

alt

Opcion al No Sí

Descripción Identificador relacionado con el estado de entrega del SMS. Parámetro 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 petición. De esta manera, no se utiliza XML ni JSON para la codificación de este tipo de datos.

5.4

ESTRUCTURA DEL SMSDeliveryStatusType

Información del estado de entrega del SMS. Nota: Se utiliza como base GSMA OneAPI [3] y ParlayX 3.1 [2].

Parámetro

Elemento tipo

smsDeliveryStat us

DeliveryInform ationType [0..unbounded]

5.5

Opcion al Sí

Descripción Describe las variaciones del estado de entrega del SMS. Valores posibles son: • DeliveredToNetwork • DeliveryUncertain • DeliveryImpossible • MessageWaiting • DeliveredToTerminal

ESTRUCTURA DEL DeliveryInformationType

Información de la entrega del SMS Nota: Tomado de ParlayX 3.1 [2]

Parámetro

Elemento tipo

address

uct:IdType No

Indica la dirección de destino con la que la notificación está relacionada.

deliveryStatus

DeliveryStatus Type xsd:string

No

Indica el resultado de la entrega para las direcciones de destino.

Sí

Utilizado junto al estado de entrega (i.e. DeliveryImpossible) para proporcionar información adicional.

description

5.6

Opcion al

Descripción

ENUMERACIÓN DEL DeliveryStatusType

Lista de valores posible del estado de Entrega. Nota: Tomados de ParlayX 3.1 [2]

Enumeración

DeliveredToNetwork DeliveryUncertain

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

Página 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 transición a otro estado mencionado. Entrega exitosa Imposible proveer la notificación de entrega. Se usa para indicar que la recepción de entrega para la dirección especificada en una operación SendSMS no está soportada.

Nota: En los envíos fuera de México podría no llegar a obtenerse un estado DeliveredToTerminal, aunque el mensaje se haya entregado correctamente.

5.7

ENUMERACIÓN DEL AltType

Parámetro para solicitar una respuesta en formato JSON.

Enumeración

JSON

5.8

Descripción El formato del contenido de la respuesta debe ser JSON

OPCIÓN IdType

Parámetro

Elemento tipo

Opcion al

Descripción

phoneNumber anyUri ipAddress alias otherId

E164Type xsd:anyURI IpAddressType AliasType OtherIdType

Sí Sí Sí Sí Sí

Número de teléfono

Página 18 de 27 movistar © 2009 Reservados todos los derechos.

Cualquier URI Dirección IP Alias Cualquier otro tipo de identidad de

6 LIBRERÍAS CLIENTE DE USO DE LAS APIS 6.1

CLIENTE JAVA

6.1.1

Directrices de Programación

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

6.1.2

SMS API Client Factory: es.tid.unica.rest.sms.SMSClientFactory

Ejemplo para el envío con el cliente 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

En primer lugar se realiza la construcción del objeto cliente (SMSClient), mediante el uso de una factory (SMSClientFactory) A continuación se configura el cliente con los datos necesarios, tanto para el establecimiento de la conexión 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 autenticación 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 envío de un SMS, utilizando el método sendSMS. Dicho método toma como parámetros 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 codificación empleada. Una vez enviado el SMS se obtiene como respuesta un objeto, de la clase SMSResult, que contiene el resultado de la operación de envío, incluyendo la URI que podrá ser utilizada para consultar el delivery status de dicho SMS.

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.IdType; 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_ = "123456"; String access_token = "2SDO4gAL"; String requestor_id = "5213907550011";

Página 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.setSp(sp_); 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 IdType address = new IdType(); 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 librería Java de cliente SMS está formada por los siguientes paquetes:

Enumeración

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

Descripción 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 parámetros utilizados por las APIs. Este paquete contiene los tipos de datos básicos de ParlayX, que pueden ser utilizados en las APIs Paquete que contiene los tipos de datos específicos de la API de SMS

Página 20 de 27 movistar © 2009 Reservados todos los derechos.

6.1.4

Prerrequisitos

Para el correcto funcionamiento de la librería de cliente de Java de SMS es necesario tener instalada la versión 1.5 o superior del JRE (Java Runtime Environment) o JDK (Java Development Kit). También es necesario utilizar las librerías contenidas en los archivos .jar situados en el directorio lib de la distribución del cliente Java.

6.2

CLIENTE C#

6.2.1

Directrices de Programación

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 más o menos datos iniciales dependiendo de la operación de creación 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: • •

6.2.2

SMS Client Factory: SMS Client Interface API:

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

Ejemplo para el envío 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.Sp = sp; 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 IdType address = new IdType(); 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);

}

Página 21 de 27 movistar © 2009 Reservados todos los derechos.

6.2.3

Paquetes del Cliente

Se describen los paquetes

Enumeración

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

6.2.4

Descripción 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 parámetros utilizados por las APIs. Este paquete contiene los tipos de datos básicos de ParlayX, que pueden ser utilizados en las APIs Paquete que contiene los tipos de datos específicos de la API de SMS

Prerrequisitos

Para el correcto funcionamiento de las APIs C# son necesarios lo siguientes 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/s

Esta librería no ha sido diseñada para otros entornos como Mono o Portable.NET.

6.3

CLIENTE PHP

6.3.1

Dependencias

•

PHP ≥ 5.2.6

•

PHP5-CURL ≥ 5.2.6

•

CURL ≥ 7.18.2

6.3.2

Directrices de Programación

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 codificación): • • •

smsRESTlibraryXML.php smsRESTlibraryJSON.php smsRESTlibraryURLEnc.php

Esta librería 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 envío con el cliente SMS

El siguiente ejemplo muestra el uso del cliente para el uso de la API REST de SMS:
Página 22 de 27 movistar © 2009 Reservados todos los derechos.

//Clase para el envio de SMS mediante URL encode include_once "./smsRESTlibraryURLEnc.php"; //Creación del cliente para el envio de SMS $smsClient = new smsRESTclient($spId,$serviceId,$sp,$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

Enumeración

smsRESTlibraryXML.php smsRESTlibraryJSON.php smsRESTlibraryURLEnc.php

Descripción Paquete que contiene la clase principal para el cliente SMS REST API con codificación XML. Paquete que contiene la clase principal para el cliente SMS REST API con codificación JSON. Paquete que contiene la clase principal para el cliente SMS REST API con codificación URL encode.

Página 23 de 27 movistar © 2009 Reservados todos los derechos.

7 DETALLE DE LAS DESCRIPCIONES DE ERROR Las operaciones descritas en esta guía pueden devolver una serie de códigos de error HTTP, como se explica a continuación. En caso de producirse algún error relacionado con: -

spId o serviceId no válidos

-

sp no válido

-

La aplicación no tiene permisos para utilizar el API

-

Parámetros no válidos

-

Violación de los SLA

se responderá con un código de estado HTTP del tipo 4XX/5XX. Sin embargo, si de produce un error relacionado con: -

token no válido

-

El MSISDN no tiene permisos para utilizar el API

se responderá con un código de estado HTTP 201, pero al consultar el estado del envío se obtendrá el valor DeliveryImpossible.

Página 24 de 27 movistar © 2009 Reservados todos los derechos.

A

CONSIDERACIONES GENERALES

En esta sección se describen elementos necesarios para el normal funcionamiento de la API REST SMS: • •

A.1

Métodos HTTP: que constituyen las operaciones RESTful, de acuerdo con los principios REST. Representaciones comunes.

Métodos HTTP

Las siguientes descripciones se han extraído de la RFC de HTTP 1.1.

A.1.1

POST

El método POST se utiliza para solicitar que el servidor de origen acepte la entidad contenida en la petición como un nuevo recurso identificado por la URI de la petición en la Request-Line. POST está diseñado para permitir un método uniforme que cubra las siguientes funciones: •

Anotación de recursos existentes.

•

Postear un mensaje en un boletín, grupo de noticias, lista de correo, o grupo similar de artículos.

•

Proveer un bloque de datos, como el resultado del envío de un formulario, para que sea procesado.

•

Extender una base de datos a través del añadido de una operación.

La actual funcionalidad desarrollada por el método 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 artículo 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 método GET intenta extraer cualquier información (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 método 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 Página 25 de 27 movistar © 2009 Reservados todos los derechos.

debe ser considerada como una versión 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 método Delete solicita que el servidor de origen borre el recurso identificado con la Request-URI. Este método puede ser reescrito por intervención humana (u otros métodos) en el servidor de origen. El cliente no puede garantizar que la operación haya sido llevada a término, incluso si el código de estado devuelto desde el origen indica que la acción 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 localización inaccesible.

A.2

REPRESENTACIONES COMUNES

A.2.1

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 parámetro ‘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 petición POST incluye datos en formato XML o si la correspondiente petición GET no incluía el parámetro ‘alt=json’. En estos casos, la cabecera Content-Type: Application/xml debe estar presente en la respuesta.

Página 26 de 27 movistar © 2009 Reservados todos los derechos.

B

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]

GSMA OneAPI, http://gsma.securespsite.com/access/default.aspx

[4]

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

Página 27 de 27 movistar © 2009 Reservados todos los derechos.