API - Arsys

Manual de uso del API de la Plataforma Dedicada de Correo
Manual de uso del API
de la Plataforma
Dedicada de Correo
Manual de usuario: API XML
Índice
1. Descripción del funcionamiento
2. Descripción de las llamadas
3. Anexos
© Copyright Arsys Internet S.L.
Página 1 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
El presente documento presenta las funciones (API) que permiten gestionar
buzones de forma automática en la Plataforma Dedicada de Correo, así como una
explicación de su funcionalidad y modo de uso.
Estas funciones permiten integrar en los programas del cliente las tareas más
comunes en la gestión de recursos como son:


Alta de buzones (AltaBuzonesXML.asp).
Baja de Buzones (BajaBuzonesXML.asp).
En los siguientes apartados se detalla su funcionamiento y forma de uso.
El objetivo de este documento es únicamente describir cada una de las funciones,
no su implementación en distintos lenguajes.
1. Descripción del funcionamiento
Cada una de las funciones está en un fichero ASP, accesible desde:


http://pc.arsys.es/sdc/nombrescript.asp
https://pc.arsys.es/sdc/nombrescript.asp
La llamada a las funciones se realizará a través de una petición por método POST.
El contenido de la petición será un documento XML con la sintaxis y parámetros
especificados más adelante en este documento.
Identificación.
Todas las peticiones que se hagan a las funciones deberán acreditarse. Para ello
han de incluir obligatoriamente entre las etiquetas <user></user> los siguientes
parámetros:

login: nombre del dominio principal.
o El nombre de usuario que se utiliza en el Panel de Control.

time: fecha y hora de la petición en formato DD/MM/AAAA HH:MM:SS.

ticket: resumen en MD5 (algoritmo de seguridad) generado con el login y la
contraseña de entrada al Panel de Control del Servidor, más la hora de
llamada para que la petición caduque en un tiempo razonable.
El formato que deberá tener el ticket es login:hora:password en MD5:
© Copyright Arsys Internet S.L.
Página 2 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
o Permite autentificarse sin necesidad de enviar la contraseña sin cifrar
por Internet.
o La duración del ticket es de 2 horas.
o Un ticket válido sería:
md5("dominio.com:dd/mm/yyyy hh:mm:ss:mipassword")
Ejemplo de Identificación
<user>
<login>usuario</login>
<time>23/12/2004 9:33:22</time>
<ticket>ticket</ticket> Ticket generado
</user>
Respuesta.
Cada una de las funciones devuelve, también en formato XML, el resultado de las
operaciones solicitadas, indicando:


El estado (si el proceso ha concluido de manera satisfactoria).
Descripción del estado:
o Si se ha producido un error, incluirá una descripción del error con
mensajes análogos a los obtenidos a través del Panel de Control.
o Si se ha ejecutado correctamente, incluirá un mensaje de operación
procesada con éxito.
Funciones del API.
En este apartado se detallan cada una de las llamadas que es posible realizar
mediante XML a la API. Es decir, cada una de las funciones.
Para cada una de las funciones se indica:



El nombre de archivo (script) sobre el que se hará la llamada.
La descripción del proceso que ejecutará.
El formato XML con el que hacer la llamada.
El formato XML de respuesta de la función será idéntico al de entrada, salvo que se
añadirán las etiquetas de estado y descripción (‘status’ y ‘description’), tanto en el
campo de identificación (<user>…</user>) como en cada operación solicitada.
© Copyright Arsys Internet S.L.
Página 3 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
Ejemplo de un error de autentificación
<request>
<status>KO</status>
<description>Error de autentificación</description>
</request>
Ejemplo de un estado de operación: alta de dos buzones
Por cada operación solicitada se incluirán las variables ‘status’ y ‘description’.
<request>
<status>OK</status>
<user>
<login>usuario</login>
<time>23/12/2004 9:33:22</time>
<ticket>ticket</ticket> Ticket generado
</user>
<email>
<user>prueba</user>
<address>[email protected]</address>
<password>pass</password>
<quota>0</quota>
<status>OK</status> Alta correcta
<description>Alta procesada.</description>
</email>
<email>
<user>prueba2</user>
<address>[email protected]</address>
<password>pass2</password>
<cuota>10</cuota>
<status>KO</status> Alta incorrecta
<description>La dirección de correo ya existe.</description>
</email>
</request>
© Copyright Arsys Internet S.L.
Página 4 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
2. Descripción de las llamadas
Alta de buzones.
Script
AltaBuzonesXML.asp
Descripción
Función que permite dar de alta buzones asociados a dominios que dispongan
de servicio de correo.
Código XML de la petición
<request>
<status>OK</status>
<user>
<login>usuario</login> Usuario de entrada al panel de control
<time>23/12/2004 9:33:22</time> Fecha y Hora
<ticket>ticket</ticket> Ticket generado
</user>
<email>
<user>prueba</user> Usuario de la cuenta (login)
<address>[email protected]</address> Dirección de correo
<password>pass</password> Contraseña
<quota>0</quota> Cuota en MB. (0 es ilimitada)
</email>
...
</request>
Baja de buzones.
Script
BajaBuzonesXML.asp
Descripción
Función que permite dar de baja buzones asociados a dominios que
dispongan de servicio de correo.
© Copyright Arsys Internet S.L.
Página 5 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
Código XML de la petición
<request>
<status>OK</status>
<user>
<login>usuario</login> Usuario de entrada al panel de control
<time>23/12/2004 9:33:22</time> Fecha y Hora
<ticket>ticket</ticket> Ticket generado
</user>
<email>
<address>[email protected]</address> Direccion de correo
</email>
...
</request>
3. Anexos
Ejemplo de uso: alta de buzones en Perlscript.
<%@LANGUAGE=PerlScript%>
<%
use LWP::UserAgent;
use XML::Simple;
use Digest::MD5;
# Login y password del panel de control del servidor
my $login='midominio.com';
my $password='password';
# URL script de alta de buzones
my $urlalta='https://pc.arsys.es/API/AltaBuzon.asp';
#Obtención de la fecha y hora actual
my (
$sec,$min,$hour,
$mday,$mon,$year,
$wday,$yday,$isdst
) = localtime(time);
$mon = $mon + 1;
$mon = "0$mon" if $mon < 10;
$mday = "0$mday" if $mday < 10;
$year += 1900;
© Copyright Arsys Internet S.L.
Página 6 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
my $hora = "$mday/$mon/$year $hour:$min:$sec";
#Generación de ticket de autentificación
my $ticket= Digest::MD5::md5_hex(
"$login:$hora:$password"
);
#XML de prueba
my $xml_str = "
<request>
<status>OK</status>
<user>
<login>$login</login>
<time>$hora</time>
<ticket>$ticket</ticket>
</user>
<email>
<user>nombreusuario</user>
<address>nombreususario\@dominio.com</address>
<password>ejemplopassw</password>
<quota>0</quota>
</email>
<email>
<user>nombreusuario2</user>
<address>nombreususario2\@dominio.com</address>
<password>ejemplopassw</password>
<quota>0</quota>
</email>
</request>
";
#Envío los datos
my $solicitud = new HTTP::Request('POST', $urlalta);
$solicitud->content_type('text/xml');
$solicitud->content($xml_str);
my $ua = new LWP::UserAgent;
my $respuesta = $ua->request($solicitud);
my $contenido = $respuesta->content();
#Interpretación de la respuesta
my $contxml = XMLin($contenido);
$estado = $contxml->{status};
if ($estado eq 'OK') {
© Copyright Arsys Internet S.L.
Página 7 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
#Obtenemos los datos devueltos por el servidor
#para cada buzón
my @buzones;
if (ref($contxml->{email}) eq 'HASH'){
#Si solo hay un buzón, lo metemos en el array
@buzones=($contxml->{email});
}else{
# hay más de uno
@buzones=@{$contxml->{email}}
}
foreach $item (@buzones){
$texto.=”\n”;
$texto.="<h3>Dominio:</h3>\n";
$texto.=" User: $item->{user}<br>\n";
$texto.=" Address: $item->{address}<br>\n";
$texto.=" Password: $item->{password}<br>\n";
$texto.=" Quota: $item->{quota}<br>\n";
$texto.=" Status: $item->{status}<br>\n";
$texto.=" Description: $item->{description}<br>\n";
}
} elsif ($estado eq 'KO') {
$texto=
"Se ha producido un error en la petición:<br>\n".
"Descripción: $contxml->{description}<br>\n"
;
}else{
$texto = "Error de comunicación\n";
}
$::Response->Write($texto);
%>
Enlaces de interés.
A continuación se muestran algunos enlaces en los que se puede encontrar código
para crear el MD5 de una cadena de texto y para gestionar documentos XML.
Perl


http://www.perldoc.com/perl5.6/lib/Digest/MD5.html
 Digest::Md5 para Perl
http://aspn.activestate.com/ASPN/CodeDoc/XML-Simple/Simple.html
 XML::Simple
© Copyright Arsys Internet S.L.
Página 8 de 9
Manual de uso del API de la Plataforma Dedicada de Correo
Visual Basic



http://www.frez.co.uk/freecode.htm#md5
 Ejemplo de código para codificar MD5
http://msdn.microsoft.com/library/default.asp?url=/library/enus/dnxml/ht
ml/beginer.asp
 Descripción del módulo Microsoft.XMLDOM
http://www.ostrosoft.com/download.asp
 oswinsock.dll Librería para enviar y recibir información de una URL
© Copyright Arsys Internet S.L.
Página 9 de 9