Saltar a: navegación, buscar

API de envío de faxes

Descripción API de fax

Con este servicio web, usted puede automatizar los envíos de mensajes de fax vía Telefácil desde su infraestructura web. Este servicio replica la funcionalidad descrita en Enviar faxes desde la web.

Recuerde que también puede usar Envío de faxes vía SMTP para automatizar este proceso.

Si no sabe lo que es una API lea ¿Qué son las APIs de Telefácil?

Activación API Fax

Este servicio debe activarse explícitamente dentro de la web, en Oficina Virtual > Fax 9XXXXXXXX > Enviar Fax > Servicio web para integración (abajo del todo). O bien en Desarrolladores > Permisos de las APIs y los servicios web. En esa sección también se pueden restringir las direcciones IP desde las que se puede llamar a esta aplicación web. Si usted tiene una dirección IP fija por favor introdúzcala aquí, aumenta la seguridad.

Forma de uso

La URL es:

https://scgi.duocom.es/cgi-bin/telefacil2/api_enviar_fax

Para los clientes de Canarias sería:

https://cgi.duocom.es/cgi-bin/telefacil2/api_enviar_fax

A esta URL hay que pasarle los siguientes parámetros en forma "multipart/form-data":

  • 'principal' es su número de usuario de Telefácil.
  • 'pass' es la contraseña de la cuenta.
  • 'remitente' es el número de fax contratado en Telefácil desde el que quiere realizar el envío.
  • 'tipo_fichero' puede ser 'pdf' para archivos PDF o 'doc' para archivos Word, Excel, Powerpoint u OpenDocument.
  • 'fichero' es el archivo PDF (o DOC, o XLS, etc.) que desea enviar por Fax.
  • 'destino' es el número de fax al que le va a enviar el documento. Puede ser un conjunto de números separados por comas.

Opcionalmente, también se pueden pasar los siguientes parámetros:

  • 'encabezado': una pequeña frase que irá en la cabecera del Fax.
  • 'diferido=1': que indica que el fax no se enviará inmediatamente, sino que se retrasa su envío hasta la fecha y hora indicada por los parámetros 'anyo', 'mes', 'dia', 'hora' y 'minuto'. 'minuto' sólo puede tener 4 valores: 0, 15, 30 y 45.
  • 'portada=1': que indica que se envíe la portada configurada previamente en la web. Los campos para rellenar la portada serían:
    • 'para': receptor del fax.
    • 'nombre_remitente': nombre del remitente.
    • 'telefono': número del teléfono del remitente.
    • 'asunto': asunto del Fax.
    • 'comentarios': comentarios del Fax.
  • 'referencia=xxxxxxxx': una referencia que puede ser de hasta 17 caracteres, y sirve para seguirle la pista a su envío, puesto que en el cuerpo del e-mail de confirmación (en el caso de que lo haya activado) le vendrá la misma referencia que usted haya escrito. También saldrá en la API de registro de faxes enviados.
  • 'grupos=1': esto indica que el remitente del fax es de uno de los Grupos de fax y que el PIN enviado es el de ese grupo (no la contraseña de la cuenta).

Formulario de ejemplo

Aquí hay un ejemplo de un formulario HTML que hace uso de la API para el envío de mensajes de fax en línea:

 <html>
 <head>
 <title>Prueba de API</title>
 </head>
 <body>
 <form name="envio" enctype="multipart/form-data" method="POST" action="https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/api_enviar_fax">
 <input type="hidden" name="principal" value="xxxxxxxxx">
 <input type="hidden" name="pass" value="xxxxxxxx">
 <input type="hidden" name="remitente" value="xxxxxxxxx">
 <input type="hidden" name="tipo_fichero" value="pdf">
 Fichero: <input type="file" name="fichero">
 Destino: <input type="text" name="destino" value="xxxxxxxxx,xxxxxxxxx,xxxxxxxxx">
 <input type="submit" name="submit" value="Enviar">
 </form>
 </body>
 </html>

Ejemplo

Tenga presente que, aunque la aplicación web es accesible mediante una URL, no debe poner nunca enlaces a esta aplicación directamente en el código fuente de sus páginas web, ya que sus visitantes podrían descubrir datos sensibles como su número de usuario y su contraseña simplemente mirando el código HTML.

La aplicación web debe ser llamada siempre desde el servidor, usando para ello alguna de las librerías que permite llamadas a servicios HTTPS.

He aquí un ejemplo en PHP usando cURL, cortesía de tuayudainformatica.com:

 <?php
   $principal = '666111666';
   $pass = 'MiClaveSecreta';
   $remitente = '911000222';
   $destino = '930000000,987666555,928400956';
   $tipo_fichero = 'pdf';
   $file = 'C:\\temp\\fichero.pdf';

   $cfile = new CURLFile($file,'application/pdf','fichero');

   $ch = curl_init(); 
 
   curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
   curl_setopt($ch, CURLOPT_URL, "https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/api_enviar_fax");
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($ch, CURLOPT_POST, 1);
   $data = array('principal' => $principal, 'pass' => $pass, 'remitente' => $remitente, 'destino' => $destino, 'tipo_fichero' => $tipo_fichero, 'fichero' => $cfile);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
   $output = curl_exec ($ch);
   curl_close ($ch);
 ?>

Dependiendo de las librerías que utilice puede que le surja algún conflicto de nombre en:

  $cfile = new CURLFile($file,'application/pdf','fichero');

se soluciona añadiendo:

  $cfile = new \CURLFile($file,'application/pdf','fichero');

$data = array('principal' => $principal, 'pass' => $pass, 'remitente' => $remitente, 'destino' => $destino, 'tipo_fichero' => $tipo_fichero, 'fichero' => '@' . $file);

Lista de errores

  • "Login incorrecto": usuario y/o contraseña incorrectos.
  • "API no activa": no se ha activado la API en la página web.
  • "API no activa para esta IP": la API está activa, pero la IP que hace la petición no está dentro de las IPs permitidas.
  • "'xxxyyyzzz' no es un numero de fax": el número especificado no es un fax.
  • "El fichero de entrada no se puede procesar": el fichero enviado no parece un PDF o un DOC correcto.


Indice

Página principal >> Desarrolladores >> API de envío de faxes.