Administración de usuarios de la plataforma SMS de

Administración de usuarios de la plataforma
SMS de LleidaNetworks vı́a HTTP
LleidaNetworks Serveis Telemàtics, S.L.
[email protected]
19 de marzo de 2012
ÍNDICE
2
Índice
1. Introducción
4
2. Invocación
5
3. Resultado de la operación
6
4. Especificación de las operaciones
4.1. Ver el crédito disponible . . . . . . . . . . . .
4.2. Listar todos los usuarios . . . . . . . . . . . .
4.3. Crear usuarios . . . . . . . . . . . . . . . . . .
4.3.1. Tabla de prefijos según provı́ncia . . .
4.4. Editar usuarios . . . . . . . . . . . . . . . . .
4.5. Ver la información de la cuenta de un usuario
4.6. Habilitar y deshabilitar usuarios . . . . . . . .
4.7. Sumar créditos . . . . . . . . . . . . . . . . .
4.8. Restar créditos . . . . . . . . . . . . . . . . .
4.9. Añadir números de retorno . . . . . . . . . . .
4.10. Quitar números de retorno . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7
7
7
7
9
10
12
13
13
14
15
15
Copyright
(c) 2006 - 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 de administración de
usuarios de la plataforma SMS de LleidaNet para una facil integración.
La URL del CGI de administración es la siguiente:
http://mobile.lleida.net/cgi-bin/admin.pike
El sistema permite las siguientes operaciones:
Ver el crédito disponible
Listar todos los usuarios
Crear usuarios
Editar usuarios
Ver la información de la cuenta de un usuario
Habilitar usuarios
Deshabilitar usuarios
Sumar créditos
Restar créditos
Añadir números de retorno
Quitar números de retorno
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:
action Es la operación que se invoca.
login Es el login de la cuenta del proveedor.
pass 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://mobile.lleida.net/admin/
result.dtd
El root element del XML de respuesta es siempre el tag result. El
parámetro status siempre está presente en este tag, e indica el éxito (.OK”)
o fallo de la operación (.ERROR”).
En el caso de se produzca un fallo en la operación el tag result conendrá
el tag errormsg con la descripción del error que se ha producido.
4 ESPECIFICACIÓN DE LAS OPERACIONES
4.
7
Especificación de las operaciones
4.1.
Ver el crédito disponible
Esta operación devuelve el crédito del proveedor. Para invocar la operación, el parámetro action debe contener el valor credit.
El XML del resultado sigue el siguiente formato:
<result action=’credit’ status=’OK’>
<provider="nombre_proveedor">
<credit>el credito del proveedor</credit>
</provider>
</result>
4.2.
Listar todos los usuarios
Esta operación devuelve el nombre de usuario, el crédito y el estado de
todos los usuarios. Para invocar la operación, el parámetro action debe
contener el valor list. El número de usuarios listados es un máximo de 1000
usuarios. Para listar los usuarios siguientes debe pasarse el parámetro start,
el listado empezará a partir del número que se pase a este parámetro.
El XML del resultado sigue el siguiente formato:
<result action=’list’ status=’OK’>
<userlist total=’total_usuarios’ start=’incio’ end=’fin’>
<user login="login_usuario1" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
<status>estado del usuario</status>
</user>
<user login="login_usuario2" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
<status>estado del usuario</status>
</user>
...
</userlist>
</result>
4.3.
Crear usuarios
Esta operación permite la creación de cuentas de usuario bajo su cuenta de
proveedor. El nombre de usuario que deberán especificar los usuarios creados
para acceder a la plataforma SMS de Lleida Networks será el nombre del
4 ESPECIFICACIÓN DE LAS OPERACIONES
8
nuevo usuario que se especifica en la operación, seguido de una arroba (@),
seguido de su nombre de proveedor. Ejemplo: nuevousuario@miproveedor.
Para invocar esta operación el parámetro action debe contener el valor
create. El resto de parámetros admitidos, a parte de los comunes, son los
siguientes (los marcados con un * son obligatorios):
Parámetro
user (*)
Tipo
string
Descripción
El nombre de usuario de la nueva
cuenta (ej: nuevousuario)
userpass (*) string La contraseña del nuevo usuario
credit (*)
float
El crédito que se suma a la nueva
cuenta. El número de créditos especificado se restará de su cuenta de
proveedor
phone prefix string Prefijo seleccionado para la asignación del número de teléfono al
usuario. Debe especificar uno de
los prefijos especificados en la tabla
según la provı́ncia (ver 4.3.1)
contact
string Nombre de la persona de contacto
phone
string Teléfono de la persona de contacto
organization string Nombre de la empresa
mail
string e-mail de contacto
cif
string El CIF de la empresa
country
string El paı́s del usuario (deberá ser en Inglés)
city
string La localidad del usuario
address
string La dirección del usuario
zip
string El código postal del usuario
minium
integer Saldo mı́nimo para ejecutar la recarga automática
topup
integer Recarga automática
candelete
integer Permitir al usuario borrar sus mensajes (0 ó 1)
El XML del resultado sigue el siguiente formato:
<result action=’create’ status=’OK’>
4 ESPECIFICACIÓN DE LAS OPERACIONES
<user login="login_usuario" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
<phone_number>
<num>+34666666666</num>
</phone_number>
</user>
<provider name="nombre_proveedor">
<credit>credito resultante del proveedor</credit>
</provider>
</result>
4.3.1.
Tabla de prefijos según provı́ncia
Provı́ncia
A Coruña
Álava
Albacete
Alicante
Almerı́a
Asturias
Ávila
Badajoz
Balears
Barcelona
Bizkaia
Burgos
Cáceres
Cádiz
Cantabria
Castellón
Ciudad Real
Córdoba
Cuenca
Gipuzkoa
Girona
Granada
Guadalajara
Huelva
Huesca
Prefijo
+3498109
+3494507
+3496706
+3496519
+3495005
+3498402
+3492005
+3492406
+3497111
+3493107
+3494429
+3494708
+3492706
+3495619
+3494216
+3496411
+3492606
+3495787
+3496906
+3494387
+3497292
+3495847
+3494906
+3495911
+3497406
9
4 ESPECIFICACIÓN DE LAS OPERACIONES
Jaén
La Rioja
Las Palmas
León
Lleida
Lugo
Madrid
Málaga
Murcia
Navarra
Ourense
Palencia
Pontevedra
Salamanca
Santa Cruz de Tenerife
Segovia
Sevilla
Soria
Tarragona
Teruel
Toledo
València
Valladolid
Zamora
Zaragoza
4.4.
10
+3495314
+3494106
+3492810
+3498715
+3497390
+3498205
+3491106
+3495114
+3496809
+3494894
+3498805
+3497908
+3498608
+3492303
+3492211
+3492103
+3495516
+3497506
+3497714
+3497805
+3492503
+3496016
+3498306
+3498006
+3497626
Editar usuarios
Esta operación permite editar las cuentas de usuario bajo su cuenta de
proveedor. Para invocar la operación, el parámetro action debe contener el
valor edit. El resto de parámetros admitidos, a parte de los comunes, son los
siguientes (los marcados con un * son obligatorios):
Parámetro
user (*)
newuserpass
Descripción
El nombre de usuario de la cuenta
La nueva contraseña del usuario
4 ESPECIFICACIÓN DE LAS OPERACIONES
contact
phone
organization
mail
cif
country
state
city
address
zip
minium
topup
candelete
11
Nombre de la persona de contacto
Teléfono de la persona de contacto
Nombre de la empresa
e-mail de contacto
El CIF de la empresa
El paı́s del usuario
La provı́ncia/estado del usuario (deberá ser en inglés)
La localidad del usuario
La dirección del usuario
El código postal del usuario
Saldo mı́nimo para ejecutar la recarga automática
Recarga automática
Permite al usuario borrar sus mensajes (0 ó 1)
El XML del resultado sigue el siguiente formato:
<result action=’edit’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
<status>estado del usuario</status>
<created>timestamp de la fecha de creacion</created>
<lastop>timestamp de la ultima operacion</lastop>
<contact_name>persona de contacto</contact_name>
<phone>telefono</phone>
<email>mail de contacto</email>
<organization>nombre de la empresa</organization>
<cif>CIF de la empresa</cif>
<country>El paı́s del usuario</country>
<state>La provı́ncia/estado del usuario</state>
<city>La localidad del usuario</city>
<address>La dirección del usuario</address>
<zip>El código postal del usuario</zip>
<minium>Saldo mı́nimo para ejecutar la recarga automática</minium>
<topup>Recarga automática</topup>
<candelete>Permitir al usuario borrar sus mensajes</candelete>
4 ESPECIFICACIÓN DE LAS OPERACIONES
12
<phone_number>
<num>numero de teléfono asignado al usuario</num>
</phone_number>
</user>
</result>
4.5.
Ver la información de la cuenta de un usuario
Esta operación devuelve los datos y el estado de una cuenta de usuario.
Para invocar la operación, el parámetro action debe contener el valor userinfo. A parte de los parámetros comunes, el único parámetro de la operación
es user, que debe contener el nombre de usuario sobre el cual se realiza la
consulta.
El XML del resultado sigue el siguiente formato:
<result action=’userinfo’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
<status>estado del usuario</status>
<created>timestamp de la fecha de creacion</created>
<lastop>timestamp de la ultima operacion</lastop>
<contact_name>persona de contacto</contact_name>
<phone>telefono</phone>
<email>mail de contacto</email>
<organization>nombre de la empresa</organization>
<cif>CIF de la empresa</cif>
<country>El paı́s del usuario</country>
<state>La provı́ncia/estado del usuario</state>
<city>La localidad del usuario</city>
<address>La dirección del usuario</address>
<zip>El código postal del usuario</zip>
<minium>Saldo mı́nimo para ejecutar la recarga automática</minium>
<topup>Recarga automática</topup>
<candelete>Permitir al usuario borrar sus mensajes</candelete>
<phone_number>
<num>numero de teléfono asignado al usuario</num>
</phone_number>
</user>
</result>
4 ESPECIFICACIÓN DE LAS OPERACIONES
4.6.
13
Habilitar y deshabilitar usuarios
Las operaciones enableuser y disableuser permiten, respectivamente,
habilitar y deshabilitar cuentas de usuario.
La operación de deshabilitar marca una cuenta como inactiva y como
consecuencia cualquier intento de conexión con ella falla (aunque la cuenta
no se borra fı́sicamente). Para invocar esta operación el parámetro action
debe contener el valor disableuser.
La operación de habilitar una cuenta realiza el efecto contrario. Para invocar esta operación, el parámetro action debe contener el valor enableuser.
A parte de los parámetros comunes, el único parámetro de las operaciones
es user, que debe contener el nombre de usuario sobre el cual se realiza la
acción.
El XML de resultado para la operación enableuser es el siguiente:
<result action=’enableuser’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<status>A</status>
</user>
</result>
Y para la operación disableuser:
<result action=’disableuser’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<status>I</status>
</user>
</result>
4.7.
Sumar créditos
Esta operación permite añadir créditos en el saldo de una cuenta de
usuario. Los créditos que se añadan se restarán de los créditos de la cuenta
del proveedor.
Para invocar la operación, el parámetro action debe contener el valor
sum. El resto de parámetros son los siguientes (todos obligatorios):
Parámetro Tipo Descripción
user (*)
string El nombre de usuario de la cuenta
sobre la que se ejecuta la acción
credit (*)
float
El crédito que se suma a la cuenta.
El número de créditos especificado se
restará de su cuenta de proveedor
4 ESPECIFICACIÓN DE LAS OPERACIONES
14
El XML del resultado es el siguiente:
<result action=’sum’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
</user>
<provider name="nombre_proveedor">
<credit>credito resultante del proveedor</credit>
</provider>
</result>
4.8.
Restar créditos
Esta operación permite restar créditos del saldo de una cuenta de usuario.
Los créditos que se substraen se sumarán a los créditos de la cuenta del
proveedor.
Para invocar la operación, el parámetro action debe contener el valor
substract. El resto de parámetros son los siguientes (todos obligatorios):
Parámetro Tipo Descripción
user (*)
string El nombre de usuario de la cuenta
sobre la que se ejecuta la acción
credit (*)
float
El crédito que se resta a la cuenta.
El número de créditos especificado se
sumará a su cuenta de proveedor
El XML del resultado es el siguiente:
<result action=’substract’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<credit>el credito del usuario</credit>
</user>
<provider name="nombre_proveedor">
<credit>credito resultante del proveedor</credit>
</provider>
</result>
4 ESPECIFICACIÓN DE LAS OPERACIONES
4.9.
15
Añadir números de retorno
Esta operación permite añadir un número de teléfono a un usuario.
Para invocar la operación, el parámetro action debe contener el valor
addnumber. El resto de los parámetreos son los siguientes:
Parámetro
user (*)
Tipo Descripción
string El nombre de usuario de la cuenta
sobre la que se ejecuta la acción
phone prefix
string Prefijo seleccionado para la asignación del número de teléfono al
usuario. Debe especificar uno de
los prefijos especificados en la tabla
según la provı́ncia (ver 4.3.1)
phone number string Número de teléfono seleccionado
para la asignación al usuario. Debe
especificar uno de los prefijos especificados en la tabla según la provı́ncia (ver 4.3.1) seguido por los cuatro
digitos deseados.
NOTA: Es necesario especificar el parámetro phone prefix o phone number
obligatoriamente.
El XML del resultado es el siguiente (devuelve únicamente el nuevo teléfono asignado):
<result action=’addnumber’ status=’OK’>
<user login="login_usuario" provider="nombre_proveedor">
<phone_number>
<num>+34973900000</num>
</phone_number>
</user>
</result>
4.10.
Quitar números de retorno
Esta operación permite quitar un número de teléfono asignado a un
usuario.
Para invocar la operación, el parámetro action debe contener el valor
delnumber. El resto de los parámetreos son los siguientes (todos obligatorios):
4 ESPECIFICACIÓN DE LAS OPERACIONES
Parámetro
user (*)
Tipo Descripción
string El nombre de usuario de la cuenta
sobre la que se ejecuta la acción
phone number (*) string Número de teléfono que se desea desasignar al usuario epecificado
El XML del resultado es el siguiente:
<result action=’delphone’ status=’OK’ />
16