Listado del registro de mensajes de la plataforma SMS de

Listado del registro de mensajes de la
plataforma SMS de LleidaNetworks vı́a HTTP
LleidaNetworks Serveis Telemàtics, S.L.
[email protected]
3 de agosto de 2007
ÍNDICE
2
Índice
1. Introducción
4
2. Invocación
5
3. Resultado de la operación
6
4. Listar los mensajes
4.1. Parámetros comunes para el listado de mensajes . . . . . . .
4.2. Parámetros opcionales para el listado de mensajes . . . . . .
4.3. Subelementos del elemento <list> para la operación de listado
de mensajes . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4. Ejemplos . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1. Listado de mensajes enviados . . . . . . . . . . . . .
4.4.2. Consulta de número de mensajes enviados . . . . . .
4.4.3. Listado de mensajes recibidos . . . . . . . . . . . . .
4.4.4. Listado de mensajes programados . . . . . . . . . . .
.
.
7
7
7
.
.
.
.
.
.
8
10
10
11
12
13
5. Borrar mensajes del registro
14
5.1. Ejemplo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Copyright
(c) 2007 - LleidaNetworks Serveis Telematics, S.L.
Todos los derechos reservados
Este documento contiene información propietaria y confidencial. Queda totalmente prohibido distribuir sus contenidos total o parcialmente por cualquier
medio, sea fı́sico o electrónico, sin la autorización expresa de su titular.
1 INTRODUCCIÓN
1.
4
Introducción
El objetivo del siguiente documento es proporcionar la explicación necesaria para comprender el funcionamiento del sistema para ver el listado del
registro de los mensajes enviados, recibidos y programados de la plataforma
SMS de LleidaNet para una facil integración.
La URL del CGI de administración es la siguiente:
http://sms.lleida.net/xmlapi/registro.pike
El sistema permite las siguientes operaciones:
Listar los mensajes (enviados, programados, recibidos premium y recibidos a numeración larga).
Borrar mensajes del registro (enviados, programados y recibidos a numeración larga).
2 INVOCACIÓN
2.
5
Invocación
El CGI se invoca mediante los métodos GET o POST de HTTP, pasando
como variables de la consulta los parámetros requeridos. Los parámetros de
cada operación se especifican en las subsecciones siguientes. Sin embargo los
siguientes parámetros son comunes y deben enviarse en todas las operaciones:
act: Es la operación que se invoca.
usr: Es el login de la cuenta del proveedor.
pwd: Contraseña de la cuenta del proveedor.
3 RESULTADO DE LA OPERACIÓN
3.
6
Resultado de la operación
Los resultados de las operaciones invocadas son devueltos en formato
XML, cuyo DTD se puede encontrar en http://sms.lleida.net/xmlapi/
docs/list.dtd
El root element del XML de respuesta es siempre el tag list.
4 LISTAR LOS MENSAJES
4.
4.1.
7
Listar los mensajes
Parámetros comunes para el listado de mensajes
Esta operación devuelve el listado de los mensajes enviados entre dos fechas. Para invocar la operación, el valor del parámetro action puede contener
los siguientes valores:
mt: Para listar los mensajes enviados
mop: Para listar los mensajes recibidos a numeración corta (PREMIUM)
mo: Para listar los mensajes recibidos a numeración larga
df : Para ver los mensajes programados
En todos los tipos de los mensajes, a parte de enviar los parámetros
comunes debe enviarse también los parámetros from y to. El formato de
estos campos es YYYYMMDDhhmmss (en formato GMT+1).
4.2.
Parámetros opcionales para el listado de mensajes
count: Si existe el parámetro count se adjuntará la información del
número de mensajes y en el caso de los mensajes enviados, también el
crédito.
nolist: No mostrará el listado de los mensajes (si se envı́a este parámetro deberá enviarse el parámetro count para tener el resultado de los
mensajes enviados/recibidos, o de lo contrario sólo se recibirá el root
element <list>).
limit: Se utiliza para limitar el número de mensajes a mostrar, para
poder paginar los mensajes. Se envı́a dos valores separados por coma, el
primer valor es el incio de la lista y el segundo el número de mensajes
a mostrar.
4 LISTAR LOS MENSAJES
4.3.
8
Subelementos del elemento <list> para la operación de listado de mensajes
El root element del resultado de la búsqueda de mensajes es el elemento
<list>, que incluye los subelementos <count> y <totalcredit> en caso de
enviar el parámetro count y el elemento <sms>.
En caso de listar los mensajes recibidos el subelemento <totalcredit>
no se incluye.
El elemento <sms> contiene el atributo id con el identificador del mensaje. En caso de ser un MMS, el id tiene el formato MMSxxx|34666666666,
dónde xxx es el identificador del MMS. El elemento <sms> también contiene
distintos subelementos según el tipo de mensaje que se está listando.
Mensajes enviados (mt):
status: Estado del mensaje.
date: Fecha de envı́o del mensaje.
dst: Destinatario del mensaje.
credit: Coste del mensaje en créditos.
txt: Contenido del mensaje.
Mensajes recibidos (mop y mo):
date: Fecha de recepción del mensaje.
src: Remitente del mensaje.
txt: Contenido del mensaje.
Mensajes programados (df ):
status: Estado del mensaje.
send date: Fecha que se programó el envı́o.
sche date: Fecha que se enviará el mensaje.
dst: Destinatario del mensaje.
credit: Coste del mensaje en créditos.
txt: Contenido del mensaje.
4 LISTAR LOS MENSAJES
9
Los códigos de estado posibles para un mensaje enviado son los siguientes:
Código Descripción Significado
N
New
El mensaje aún no ha sido procesado
P
Pending
El mensaje aún no ha sido enviado
S
Sent
El mensaje ha sido enviado
D
Delivered
El mensaje ha sido entregado al destinatario (se ha recibido confirmación
por parte del teléfono móvil). Este estado sólo está disponible si se activó la
notificación de entrega en el envı́o
B
Buffered
El mensaje ha sido entregado a la operadora pero aún no al destinatario (el
teléfono móvil estaba apagado o fuera
de cobertura. La operadora lo entregará
en cuanto el móvil esté disponible. Este
estado sólo está disponible si se activó
la notificación de entrega en el envı́o
F
Failed
El mensaje no ha sido entregado
C
Cancelled
El mensaje programado fué cancelado
por el usuario.
4 LISTAR LOS MENSAJES
4.4.
Ejemplos
4.4.1.
Listado de mensajes enviados
10
En este ejemplo listaremos los mensajes enviados durante mayo de 2007,
con información del número de mensajes enviados y limitando los primeros
1000 mensajes.
http://sms.lleida.net/xmlapi/registro.pike?act=mt&usr=usuario&pwd=
contrase~
na&from=20070501000000&to=20070531235900&count=1&limit=0,
1000
Resultado:
<list>
<count>2301</count>
<totalcredit>2891.50</totalcredit>
<sms id="32111882">
<status>S</status>
<date>01/05/07 10:03:10</date>
<dst>+34666666666</dst>
<credit>1</credit>
<txt>Mensaje 1</txt>
</sms>
<sms id="32111015">
<status>S</status>
<date>01/05/07 12:15:23</date>
<dst>+34666666666</dst>
<credit>1</credit>
<txt>Mensaje 2</txt>
</sms>
...
</list>
El resultado de la búsqueda contiene 2301 mensajes, pero sólo se mostrarán los primeros 1000 mensajes, para listar las dos páginas siguientes los
valores de limit serı́an:
limit=1000,1000 para la segunda página.
limit=2000,1000
1
1
para la tercera y última página.
El segundo número es el número de mensajes a mostrar
4 LISTAR LOS MENSAJES
4.4.2.
11
Consulta de número de mensajes enviados
En este ejemplo consultaremos el número de mensajes enviados y los créditos consumidos durante el mes de mayo de 2007.
http://sms.lleida.net/xmlapi/registro.pike?act=mt&usr=usuario&pwd=
contrase~
na&from=20070501000000&to=20070531235900&count=1&nolist=
1
Resultado:
<list>
<count>2301</count>
<totalcredit>2891.50</totalcredit>
</list>
4 LISTAR LOS MENSAJES
4.4.3.
12
Listado de mensajes recibidos
En este ejemplo listaremos los mensajes premium recibidos durante el
mes de mayo de 2007, con información del número de mensajes enviados y
limitando los primeros 1000 mensajes.
http://sms.lleida.net/xmlapi/registro.pike?act=mop&usr=usuario&pwd=
contrase~
na&from=20070501000000&to=20070531235900&count=1&limit=0,
1000
Resultado:
<list>
<count>238</count>
<sms id="312335">
<date>01/05/07 14:23:20</date>
<src>+34666666666</src>
<txt>Mensaje 1</txt>
</sms>
<sms id="312368">
<date>03/05/07 12:15:23</date>
<src>+34666666666</src>
<txt>Mensaje 2</txt>
</sms>
...
</list>
Para listar los mensajes recibidos a la numeración larga cambiaremos el
valor del parámetro act a mo.
4 LISTAR LOS MENSAJES
4.4.4.
13
Listado de mensajes programados
En este ejemplo listaremos los mensajes programados para el mes de junio
de 2007, con información del número de mensajes y limitando los primeros
1000 mensajes.
http://sms.lleida.net/xmlapi/registro.pike?act=df&usr=usuario&pwd=
contrase~
na&from=20070601000000&to=20070630235900&count=1&limit=0,
1000
Resultado:
<list>
<count>250</count>
<totalcredit>250.00</totalcredit>
<sms id="1740459">
<status>N</status>
<send_date>16/03/07 16:28:12</send_date>
<sche_date>07/06/07 10:00:00</sche_date>
<dst>+34666666666</dst>
<credit>1</credit>
<txt>Feliz cumplea~
nos Antonio</txt>
</sms>
<sms id="1740570">
<status>N</status>
<send_date>19/04/07 14:19:14</send_date>
<sche_date>09/06/07 10:00:00</sche_date>
<dst>+34666777888</dst>
<credit>1</credit>
<txt>Feliz cumplea~
nos Felipe</txt>
</sms>
...
</list>
5 BORRAR MENSAJES DEL REGISTRO
5.
14
Borrar mensajes del registro
Esta operación elimina los mensajes enviados y recibidos por la numeración larga del registro de los mensajes y cancela los mensajes programados.
Para eliminar los mensajes, ya sean enviados o recibidos, el usuario debe
tener permisos para poder borrar mensajes. En caso que no tenga permisos
para borrar los mensajes, el resultado de la consulta será:
<error txt="User can not delete"/>
Para invocar la operación, el valor del parámetro action puede contener
los siguientes valores:
delmt: Para eliminar mensajes enviados del registro.
delmo: Para eliminar mensajes recibidos a numeración larga del registro.
deldf : Para cancelar mensajes programados. El crédito del coste del
mensaje no se devuelve.
Para eliminar los mensajes debe enviarse también el parámetro ids con
el listado de los identificativos (contenido del atributo del elemento <sms>)
todos los mensajes a eliminar separados por coma.
Cuando se cancela un mensaje programado se incluye en el listado de
mensajes enviados con el estado C.
5.1.
Ejemplo
Este ejemplo eliminaremos un listado de mensajes que contiene un MMS:
http://sms.lleida.net/xmlapi/registro.pike?act=delmt&usr=usuario&pwd=
contrase~
na&ids=32111882,32111925,MMS172312|34666666666,32112012
Resultado:
<ok />