Para este artículo, se requieren unos ciertos conocimientos de programación. Para ilustrar las diferentes herramientas, mostraremos ejemplos usando código PHP. También usaremos ciertas librerías tales como cURL y SimpleXML. Nota: tenga en cuenta que varias de las APIs y utilidades que le vamos a presentar deben ser activadas en su panel de control web, yendo a Opciones > Permisos APIs.
Recepción automatizada de faxes
Normalmente, cuando recibimos un fax lo podemos abrir tanto en el correo electrónico que hayamos establecido como en la propia web (donde se mantienen durante 45 días). Sin embargo, tenemos una serie de herramientas que nos permiten acceder a los faxes recibidos de forma automatizada:
- API de faxes recibidos vía servicio web: API de buzones.
- Recepción de faxes en un servidor FTP.
- Recepción de faxes en un servicio web (HTTP/HTTPS): Disparador de eventos.
API de faxes recibidos
Para ver los faxes recibidos en cualquier momento, usamos la API de buzones, que también sirve para leer los buzones de voz de números virtuales y centralitas, las grabaciones, etc. Esta API se ofrece mediante un servicio web, de manera que nos aseguramos que esté bien soportada en cualquier entorno y, al ser ofrecida mediante HTTPS, tenemos cifrado incluido.
El siguiente ejemplo en PHP hace uso de las librerías cURL y SimpleXML para simplificar el manejo de lo que devuelve la API.
<?php
$principal = '666111666';
$pin = '0000';
$fax = '902009956';
$peticion = "https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=".$principal.
"&pin=".$pin."&origen=".$fax;
// Hacemos la petición vía cURL
$curl = curl_init($peticion);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_TIMEOUT, 5);
$output = curl_exec($curl);
curl_close($curl);
// Procesamos el XML que nos devuelve la API
$buzones = simplexml_load_string($output,'SimpleXMLElement', LIBXML_NOCDATA);
if ((string)$buzones->error == '0') {
foreach ($buzones->entrada as $buzon) {
$estado = $buzon->estado;
$fecha = $buzon->fecha;
$hora = $buzon->hora;
$fichero = $buzon->fichero;
$bytes = $buzon->bytes;
$llamante = $buzon->llamante;
$llamado = $buzon->llamado;
echo "Fax $estado, recibido a las $hora el día $fecha. Llamante = $llamante, ".
"llamado = $llamado. Fichero = $fichero ($bytes bytes).\n"
}
}
?>
Recepción de faxes por FTP o HTTP
¿Qué hacemos si queremos enterarnos del momento exacto en el que nos llega un fax? Una solución (no eficiente) sería llamar a la API de faxes recibidos vista anteriormente cada cierto tiempo (polling). Pero claro, no nos enteraríamos de la llegada de un nuevo fax en tiempo real (aparte de la poca eficiencia, repetimos).Para solucionar esto, hay una sección llamada "Opciones avanzadas de aviso" dentro de la pestaña Avisos (vea nuestro wiki). Básicamente se trata de introducir una URL (FTP, HTTP o HTTPS) y, opcionalmente, un usuario y una contraseña. La URL será de un servicio donde queramos recibir el nuevo fax. Es decir, tendrá que ser una URL nuestra (o, al menos, una URL que podamos administrar). El usuario y la contraseña están para soportar URLs con seguridad adicional.
Si la URL es un FTP, el sistema Telefácil simplemente pondrá el fax nuevo en el FTP. En cambio, si es una URL HTTP (o HTTPS) podremos hacer muchas más cosas, diseñando nuestro propio servicio web. Entre las múltiples cosas que se pueden hacer en dicho servicio web estarían: meter el fax en una base de datos o sistema de almacenamiento, generar correos electrónicos de alerta, etc. De esta manera, podemos recibir fax en nuestro propio sistema. El siguiente código podría servir como nuestro servicio web que responde a las llamadas que hace Telefácil cuando se recibe un nuevo fax. Simplemente, coge los datos y los escribe en un fichero de texto, y copia el fax (en PDF) en un subdirectorio.
Si la URL es un FTP, el sistema Telefácil simplemente pondrá el fax nuevo en el FTP. En cambio, si es una URL HTTP (o HTTPS) podremos hacer muchas más cosas, diseñando nuestro propio servicio web. Entre las múltiples cosas que se pueden hacer en dicho servicio web estarían: meter el fax en una base de datos o sistema de almacenamiento, generar correos electrónicos de alerta, etc. De esta manera, podemos recibir fax en nuestro propio sistema. El siguiente código podría servir como nuestro servicio web que responde a las llamadas que hace Telefácil cuando se recibe un nuevo fax. Simplemente, coge los datos y los escribe en un fichero de texto, y copia el fax (en PDF) en un subdirectorio.
<?php
$fecha = $_POST["fecha"];
$llamante = $_POST["llamante"];
$llamado = $_POST["llamado"];
$nllamante = $_POST["nombre_llamante"];
$nllamado = $_POST["nombre_llamado"];
$fichero = $_POST["fichero"];
$fd = fopen("/tmp/miregistro.txt", "a");
if ($fd == true) {
fprintf($fd, "-----------------------\n");
fprintf($fd, "Fecha local = %s\n", date("d/m/Y H:i:s"));
fprintf($fd, "Fecha = %s\n", $fecha);
fprintf($fd, "Llamante = %s (%s)\n", $llamante, $nllamante);
fprintf($fd, "Llamado = %s (%s)\n", $llamado, $nllamado);
fclose($fd);
}
system(sprintf("cp %s /tmp/mibasedeficheros/", $fichero));
?>
Envío de faxes
Para enviar fax, además de las múltiples herramientas que requieren de la interacción con el usuario (Impresora Fax, envío desde la web, Fax Duocom, etc.), tenemos dos APIs:- Envío de fax vía e-mail (SMTP): API SMTP para envío de faxes.
- Envío de fax vía servicio web: API Servicio web de envío de faxes.
Envío de fax vía e-mail
Aunque muchos usuarios usan el envío de faxes desde el e-mail por comodidad, su uso está realmente pensado para que los desarrolladores puedan enviar faxes desde sus aplicaciones usando sus librerías para enviar e-mails. No obstante, aconsejamos siempre hacer uso del servicio web para enviar faxes, puesto que incluye cifrado.Enviar por e-mail un fax es muy sencillo. Lo primero que tiene que hacer es activar el servicio de envíos por e-mail (pestaña "Enviar fax", abajo del todo) y luego es tan sencillo como enviar un e-mail a su número de usuario (teléfono principal) seguido de "@fax.telefacil.com". Ponemos como asunto el número fax destinatario y en el cuerpo del mensaje ponemos el texto a enviar, o adjuntamos uno o varios ficheros PDF, DOC, XLS, etc. Algo como esto:
En el siguiente ejemplo de código, mandamos un e-mail con texto y un PDF adjunto.
En el siguiente ejemplo de código, mandamos un e-mail con texto y un PDF adjunto.
<?php
$cuenta = "666111666@telefacil.com";
$destino_remitente = "930000000,987666555,928400956 911000222";
$texto = "Texto para enviar.\n\nEsto es una prueba.\n";
// Esto es para adjuntar ficheros
$fichero = "C:\\temp\\fichero.pdf";
$file = fopen($fichero, "r");
$size = filesize($fichero);
$content = fread($file, $size);
$encoded_content = chunk_split(base64_encode($content));
$num = md5(time());
$cabecera = "From:dbautista@duocom.es\r\n";
$cabecera .= "MIME-Version: 1.0\r\n";
$cabecera .= "Content-Type: multipart/mixed; ";
$cabecera .= "boundary=$num\r\n";
$cabecera .= "--$num\r\n";
$cabecera .= "Content-Type: text/plain\r\n";
$cabecera .= "Content-Transfer-Encoding:8bit\r\n\n";
$cabecera .= "$texto\r\n";
$cabecera .= "--$num\r\n";
$cabecera .= "Content-Type: multipart/mixed; ";
$cabecera .= "name=\"prueba.pdf\"\r\n";
$cabecera .= "Content-Transfer-Encoding:base64\r\n";
$cabecera .= "Content-Disposition:attachment; ";
$cabecera .= "filename=\"prueba.pdf\"\r\n\n";
$cabecera .= "$encoded_content\r\n";
$cabecera .= "--$num--";
// Por fin, enviamos
mail($cuenta, $destino_remitente, "", $cabecera);
?>
Envío de fax por servicio web
Esta es la mejor forma de enviar faxes desde una aplicación, puesto que los servicios web están ampliamente soportados. Además, se incluye cifrado de la comunicación vía HTTPS.En el siguiente ejemplo, hacemos un envío usando la librería cURL.
<?php
$principal = '666111666';
$pin = '0000';
$remitente = '911000222';
$destino = '930000000,987666555,928400956';
$tipo_fichero = 'pdf';
$file = 'C:\\temp\\fichero.pdf';
// Envíamos usando cURL. El envío debe ser POST porque incluye un fichero.
$ch = curl_init();
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($ch, CURLOPT_URL, "https://scgi.duocom.es/cgi-bin/telefacil2/api_enviar_fax");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
$data = array('principal' => $principal, 'pin' => $pin, 'remitente' => $remitente,
'destino' => $destino, 'tipo_fichero' => $tipo_fichero,
'fichero' => '@' . $file);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$output = curl_exec ($ch);
curl_close ($ch);
?>
Reporte de faxes enviados
Se pueden ver qué faxes han sido enviados con éxito tanto en la web como por e-mail. Pero si queremos, tenemos disponible una API para procesar el registro de faxes enviados: API de registro de faxes enviados.
API de faxes enviados
Con esta API podemos ver el resultado de los envíos de fax realizados desde nuestro número de fax. Nuevamente se ofrece mediante HTTPS.Volvemos a usar cURL y SimpleXML para agilizar el desarrollo en el siguiente código PHP.
<?php
$principal = '666111666';
$pin = '0000';
$fax = '902009956';
$url = "https://scgi.duocom.es/cgi-bin/telefacil2/api_faxes_enviados?".
"principal={$principal}&pin={$pin}&tipo_salida=xml&finicio={$finicio}&fax={$fax}";
// Envíamos la petición vía cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$resultado = curl_exec($ch);
curl_close($ch);
// Procesamos el resultado XML
$faxes = simplexml_load_string($resultado,'SimpleXMLElement', LIBXML_NOCDATA);
if ((string)$faxes->error == '0') {
foreach ($faxes->envio as $envio) {
$fecha = $envio->fecha;
$hora = $envio->hora;
$destinatario = $envio->destinatario;
$id = $envio->id;
$resultado = $envio->resultado;
echo "fecha:$fecha hora:$hora dest:$destinatario id:$id res:$resultado\n";
}
}
?>
Además, también existe una API de cola de envíos de fax, similar a la anterior, pero que muestra los faxes que todavía están en la cola de envíos.
0 comentarios:
Publicar un comentario