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