API de buzones

Sumario

1 URL
2 Parámetros obligatorios
3 Listar los mensajes de un buzón
4 Descargar un mensaje de buzón
5 Borrar mensajes de buzón
6 Marcar/desmarcar un mensaje de buzón

URL

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

La API de desvíos se ofrece como un servicio web, accesible mediante la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=xxxxxxxx&origen=xxxxxxxxx

Para los clientes de Canarias, la URL es:

https://cgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=xxxxxxxx&origen=xxxxxxxxx

Para acceder a esta API hay que tener dado de alta un número de Oficina Virtual (Número Virtual, Centralita Virtual, Fax Virtual y Botón Web). En la pestaña de "Buzón" de cualquiera de estos números, sección "Opciones Avanzadas" (o en Desarrolladores > Permisos de las APIs), se puede activar esta API (por defecto se encuentra desactivada) y restringir su uso según la IP de acceso a la misma (esto es aconsejable para aumentar la seguridad si se tiene una dirección IP fija).

Parámetros obligatorios

'principal' es el número de teléfono del cliente (con el que se dio de alta), también llamado "usuario de la cuenta Telefácil".
'pass' es la contraseña de la cuenta Telefácil.
'origen':
- Si quiere consultar el buzón de voz de un Número Virtual, 'origen' es el Número Virtual.
- Si quiere consultar el buzón de voz de una extensión de Centralita Virtual, 'origen' es la extensión.
- Si quiere consultar el buzón de faxes de un fax, 'origen' es el número de Fax Virtual.
- Si quiere consultar el buzón de voz de un Botón Web, 'origen' es 'bw' seguido del número de botón (por ejemplo, para el Botón Web 3 ponemos "origen=bw3".
- Si quiere consultar el buzón de Grabaciones de conversación, 'origen' debe tener el valor 'Grabaciones' (origen=Grabaciones).

Adicionalmente, puede consultar los buzones de voz con un usuario y contraseña VoIP. En ese caso, los parámetros obligatorios serían:

'usuario_voip': su Número Virtual o Centralita.ext
'password_voip': la contraseña del VoIP

En este último caso, obviamente sólo es posible consultar los buzones de voz de Números Virtuales y extensiones de Centralita que tengan activado el servicio VoIP. La URL sería así:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?usuario_voip=xxxxxxxxx&password_voip=XXXXXXXXX

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.

Listar los mensajes de un buzón

Para listar los mensajes de un buzón, hemos de pasar los parámetros obligatorios (ver capítulo anterior) y el parámetro accion=listar. Por ejemplo, para listar los mensajes del número virtual 902009955:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009955&accion=listar

O para listar los mensajes de la extensión 34:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=34&accion=listar

Si queremos, por otro lado, los faxes recibidos en el número 902009956:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=listar

O, por ejemplo, las grabaciones de la cuenta:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=grabaciones&accion=listar

Opcionalmente, puede especificar rangos de la siguiente manera:

Rangos de fechas con los parámetros 'finicio' y 'ffin' (en formato DDMMYYYY).
Visualización por páginas indicando el número de página (parámetro 'pagina', empezando en 1) y el número de mensajes por página (parámetro 'mpp'). Por ejemplo, si queremos ver los 15 primeros mensajes del buzón, le pasaríamos a la URL: &pagina=1&mpp=15.

La respuesta a esta petición se suministra en XML:

<?xml version="1.0" encoding="UTF-8" ?>
 
 <buzon>
   <error>0</error>
   <entrada>
     <fecha>09/04/2012</fecha>
     <hora>15:52:58</hora>
     <bytes>2463</bytes>
     <estado>no leido</estado>
     <llamante>912345678</llamante>
     <llamado>902009956</llamado>
     <origen>902009956</origen>
     <nombre_llamante>Juan Ruiz</nombre_llamante>
     <fichero>2012-04-09_15-52-58_Lunes_912345678_902009956.pdf</fichero>
   </entrada>
   <entrada>
     <fecha>09/04/2012</fecha>
     <hora>15:45:04</hora>
     <bytes>2458</bytes>
     <estado>no leido</estado>
     <llamante>987654321</llamante>
     <llamado>902009956</llamado>
     <origen>902009956</origen>
     <nombre_llamante>Pepe Laso</nombre_llamante>
     <fichero>2012-04-09_15-45-04_Lunes_987654321_822200956.pdf</fichero>
   </entrada>
   ...
   <total>10</total>
   <leidos>2</leidos>
   <no_leidos>1</no_leidos>
 </buzon>

A partir del 6 de mayo de 2015, en el buzón de grabaciones puede aparecer un campo llamado 'ref_id'. Este campo numérico referencia unívocamente a la llamada dentro del día correspondiente (las referencias se pueden repetir entre días distintos). Se puede usar este campo para enlazar la grabación con la llamada en la API de consumos.

Descargar un mensaje de buzón

Para descargar un fichero con un mensaje de buzón, deberemos conocer el nombre del fichero. Eso se puede saber mirando el campo <fichero> de cada <entrada> de la respuesta <buzon> que da el listado de mensajes (ver capítulo anterior). Además del nombre del fichero y los parámetros obligatorios, hay que pasar el parámetro accion=descargar, de la siguiente manera:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=descargar&fichero=2012-04-09_15-45-04_Lunes_987654321_822200956.pdf

Los ficheros pueden ser de diferentes tipos:

Los ficheros de faxes se entregan en formato PDF.
Las grabaciones se entregan en formato MP3.
Las grabaciones de buzones de voz, aunque se listan en formato VOX, se entregan en formato MP3.

Si además le pasamos el parámetro "post=marcar", el mensaje además de descargarse se marcará como leído/visto.

Borrar mensajes de buzón

Para eliminar un solo mensaje de buzón, deberemos conocer el nombre del fichero de ese mensaje. Eso se puede saber mirando el campo <fichero> de cada <entrada> de la respuesta <buzon> que da el listado de mensajes (ver capítulo de Listar mensajes). Además del nombre del fichero y los parámetros obligatorios, hay que pasar el parámetro accion=borrar, de la siguiente manera:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=borrar&fichero=2012-04-09_15-45-04_Lunes_987654321_822200956.pdf

Para borrar varios mensajes de buzón, ponemos accion=borrar_varios, especificamos el número de ficheros con el parámetro "n" y enviamos los ficheros como fichero0, fichero1, fichero2... fichero(n-1). Por ejemplo:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=borrar_varios&n=2&fichero0=2012-04-09_15-45-04_Lunes_987654321_822200956.pdf&fichero1=2013-02-11_16-43-12_Lunes_912345678_822200956.pdf

Por último, también se pueden borrar todos los mensajes de un buzón con accion=borrar_todo:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=borrar_todo

Marcar/desmarcar un mensaje de buzón

Para marcar/desmarcar como escuchado (o leído en el caso de los faxes) un mensaje de buzón, deberemos conocer el nombre del fichero de ese mensaje. Eso se puede saber mirando el campo <fichero> de cada <entrada> de la respuesta <buzon> que da el listado de mensajes (ver capítulo de Listar mensajes). Además del nombre del fichero y los parámetros obligatorios, hay que pasar el parámetro accion=marcar (o accion=desmarcar), de la siguiente manera:

https://scgi.duocom.es/cgi-bin/telefacil2/api_buzon?principal=xxxxxxxxx&pass=miclavesecreta&origen=902009956&accion=marcar&fichero=2012-04-09_15-45-04_Lunes_987654321_822200956.pdf

Indice

Página principal >> Desarrolladores >> API de buzones.

Página principal >> Oficina Virtual >> Fax virtual >> Recepción de faxes >> Opciones avanzadas de la recepcion de fax >> API de buzones.