API de desvíos

Sumario

1 URL de API de desvío

URL de API de desvío

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_desvios?principal=xxxxxxxxx&pass=xxxxxxxx&nv=xxxxxxxxx

Para los clientes de Canarias, la URL es:

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

Para acceder a esta API hay que tener dado de alta un número virtual o un número de centralita virtual. En la pestaña de "Desvíos", 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.
Además, hace falta especificar:
- o bien 'nv' como el número virtual al que se quieren modificar los desvíos.
- o bien 'ext' como la extensión a la que se quieren modificar los desvíos.

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.

Tipo de salida

Por defecto, lo que devuelve esta API es de tipo texto (text/plain), pero si se pasa el parámetro opcional 'tipo_salida=xml' la salida será de tipo XML (text/xml).

Leer los desvíos actuales

Ante cualquier petición, ya sea de lectura o de modificación de desvíos, el sistema ofrecerá los desvíos actuales del número virtual o extensión telefónica especificada. Por ejemplo, si queremos leer los desvíos del número virtual 910911912 de la cuenta 911922933, la petición sería:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&nv=910911912

En el caso de querer los desvíos de la extensión 2345, tendríamos que crear la siguiente petición:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&ext=2345

El sistema ofrecerá una respuesta en texto plano de la siguiente forma:

OK
[por defecto] => #1: desvio1 (esp1) #2: desvio2 (esp2) #3: desvio3 (esp3) #4: desvio4 (esp4) #5: desvio5 (esp5)
HH:MM-HH:MM lmxvsdf => #1: desvio1 (esp1) #2: desvio2 (esp2) #3: desvio3 (esp3) #4: desvio4 (esp4) #5: desvio5 (esp5)
HH:MM-HH:MM lmxvsdf => #1: desvio1 (esp1) #2: desvio2 (esp2) #3: desvio3 (esp3) #4: desvio4 (esp4) #5: desvio5 (esp5)
...

Primero se lista el resultado de la operación ('OK' si todo fue bien). Después se lista el desvío por defecto, con cada uno de los desvíos configurados (desvio1..desvio5). Entre paréntesis se pone el tiempo de espera de cada desvío. No tienen por qué aparecer los 5 desvíos: si sólo hay dos desvíos, aparecerán en la línea desvio1 y desvio2. En el caso de que no hubiera desvíos, la línea aparecería como:

[por defecto] =>

Después se listan los desvíos por horario (si los hubiere), indicando primero el horario y los días del mismo (l: lunes, m: martes, x: miércoles, j: jueves, v: viernes, s: sábados, d: domingos, f: festivos).

Por ejemplo:

HTTP/1.x 200 OK
Date: Fri, 16 Jan 2009 14:24:32 GMT
Server: Apache
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

OK
[por defecto] => #1: 911922933@telefacil.com (0) #2: 655644633 (25) 
12:00-13:00 lmxjvsdf => #1: 911922933@telefacil.com (0) #2: 933844755 (34)

Si llamamos con "tipo_salida=xml" saldría algo así:

HTTP/1.x 200 OK
Date: Fri, 16 Jan 2009 14:24:32 GMT
Server: Apache
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8" ?>

<desvios>
  <res>1</res>
  <desvio>
    <tipo>[por defecto]</tipo>
    <telefono1>911922933@telefacil.com</telefono1>
    <espera1>0</espera1>
    <telefono2>655644633</telefono2>
    <espera2>25</espera2>
  </desvio>
  <desvio>
    <tipo>12:00-13:00 lmxjvsdf</tipo>
    <telefono1>911922933@telefacil.com</telefono1>
    <espera1>0</espera1>
    <telefono2>933844755</telefono2>
    <espera2>34</espera2>
  </desvio>
</desvios>

Si se pasa en la URL el parámetro opcional "post=1", aparecerá un campo "post" indicando qué ocurre después de los desvíos:

[post] => buzon (a los 25 segundos)

o en XML:

<post>
  <tipo>buzon</tipo>
  <segundos>25</segundos>
 </post>

Los posibles valores de "post" son: buzon, solo_buzon, solo_desvio y salto_a_ext. En el caso de "buzon" se especifica el número de segundos que el sistema espera intentando desviar; en el caso de "salto_a_ext" se especifica también la extensión a la que se salta.

Cambiar los desvíos

Para cambiar un desvío, además de los parámetros obligatorios (principal, contraseña y nv/ext), debe especificar los siguientes parámetros:

'accion': que debe tomar el valor 'cambiar'.
'desvio1', 'desvio2', 'desvio3', 'desvio4', 'desvio5': los números de teléfono donde se recibirán las llamadas. Puede especificarlos todos, o sólo algunos, o ninguno.
'espera1', 'espera2', 'espera3', 'espera4', 'espera5': los segundos por los que se espera para realizar cada desvío. Por omisión, 0 segundos.

Opcionalmente:

'horario': en la forma HHMMHHMM, siendo los primeros cuatro dígitos la hora y minutos de inicio, los últimos cuatro dígitos la hora y minutos de finalización. Por ejemplo, un horario 00:00-23:59 sería de la forma 00002359.
'dias': un conjunto de caracteres (l: lunes, m: martes, x: miércoles, j: jueves, v: viernes, s: sábados, d: domingos, f: festivos) que especifican qué dias se ejecuta el horario. Por ejemplo, los días laborables se pondrían de la forma lmxjv. Fines de semana y festivos: sdf.
'mascara': el número de teléfono que le llegará a los desvíos. Puede ser 'privado' (número oculto), 'semiprivado' (parcialmente oculto por ceros), 'numero_virtual', 'centralita' o 'centralita3digitos' (número de centralita seguido de 3 dígitos especificados en el parámetro 'digitos').
'reduccion_espera': si este valor es 1, se activará la opción avanzada "Reducir tiempos de espera si un desvío comunica".

'horario' y 'dias' deben ser especificados conjuntamente.

Por ejemplo, si queremos modificar los desvíos del desvío por defecto del número virtual 910911912, haríamos:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&nv=910911912&accion=cambiar&desvio1=911922933@telefacil.com&espera1=0&desvio2=612345678&espera2=10

Otro ejemplo: modificamos un desvío por horario (días laborables de 12:00 a 13:00) de la extensión 1:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&ext=1&accion=cambiar&horario=12001300&dias=lmxjv&desvio1=911922933@telefacil.com&espera1=0&desvio2=612345678&espera2=10&desvio3=911922933&espera3=15

NOTA: para modificar los días o el horario de un desvío por horario tiene que primero borrar el horario anterior (ver siguiente sección) y después crear el horario nuevo (con los mismos desvíos que tenía el anterior).

Añadir o quitar teléfonos de los desvíos fácilmente

Si lo único que desea es añadir o quitar uno o varios números de teléfono sin modificar todo el desvío, puede usar las acciones "poner" y "quitar", en vez de "cambiar".

Para explicar mejor estas opciones, consideremos el desvío del número virtual 910.911.912. Supongamos que tiene como desvíos los números de teléfono 987654321 y 612345678.

La acción "poner" añade uno o varios números de teléfono al desvío especificado si estos números no estaban ya previamente (y no se han usado ya los 5 desvíos):

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&nv=910911912&accion=poner&desvio1=911922933@telefacil.com&espera1=0&desvio2=612345678&espera2=10

Tras esta llamada, el número virtual 910.911.912 tendrá como desvíos: 911922933@telefacil.com, 987654321 y 612345678.

La acción "quitar" elimina uno o varios números de teléfono del desvío especificado si estos números estaban en el desvío:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&nv=910911912&accion=quitar&desvio1=911922933@telefacil.com&desvio2=999888777

Tras esta llamada, el número virtual 910.911.912 tendrá como desvíos: 987654321 y 612345678.

Borrar los desvíos

Para borrar un desvío (por horario), debe especificar el campo acción como 'borrar'. Por ejemplo:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&ext=1&accion=borrar&horario=12001300&dias=lmxjv

Cambiar el desvío especial (solo extensiones telefónicas)

Vea Desvíos de extensión#Desvíos especiales para llamadas salientes para saber en qué consisten los desvíos especiales.

Para crear (o cambiar) un desvío especial en una extensión (para llamadas salientes), hay que hacerlo de la siguiente manera:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&ext=1&accion=cambiar_desvio_especial&desvio=933922911&mascara=902009955

donde 'desvio' es el número de teléfono real que va a atender la llamada y 'mascara' debe ser un número virtual o de centralita contratado. Si se quiere borrar este desvío especial, basta con enviar el parámetro 'desvio' vacío:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&ext=1&accion=cambiar_desvio_especial&desvio=

Los desvíos especiales se listan junto a los demás desvíos de la forma:

[especial] => desvio:XXXXXXXXX mascara:XXXXXXXXX

Por ejemplo:

HTTP/1.x 200 OK
...

OK
[por defecto] => #1: 911922933@telefacil.com (0) #2: 655644633 (25) 
12:00-13:00 lmxjvsdf => #1: 911922933@telefacil.com (0) #2: 933844755 (34)
[especial] => desvio:933922911 mascara:902009955

Creación y borrado de extensiones

NOTA: puede listar las extensiones existentes haciendo uso de apiextensiones:

https://scgi.duocom.es/cgi-bin/telefacil2/apiextensiones?principal=911922933&pass=miclavesecreta

Para crear una extensión (que no existe previamente y que no solape con alguna ya creada), se llama a la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&accion=crear_ext&ext=1&pin_ext=1111&nombre=Pepe%20Suarez

donde:

ext: Número de extensión a crear.
pin_ext: Un PIN de 4 dígitos para esa extensión.
nombre: Nombre de la extensión (opcional).

Opcionalmente, se puede pasar un campo 'secuencia' para que la extensión sea de tipo "secuencial". La secuencia sería una lista de extensiones separadas por el caracter '_'. Por ejemplo, para hacer una secuencia de extensiones 1, 234, 7 y 889 el campo sería:

&secuencia=1_234_7_889

Para borrarla, se llama a la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&accion=borrar_ext&ext=1<

Creación y borrado de alias de extensiones

Para hacer una extensión 'ext_dest' que sea igual (o que apunte) a una extensión ya existente 'ext_ori', se llama a la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&accion=crear_alias_ext&ext_ori=1&ext_dest=2221

donde:

ext_ori: Número de extensión original (debe existir).
ext_dest: Número de extensión alias ("apunta" a la original). No se debe solapar con las extensiones ya creadas.

Para borrar una extensión alias, se llama a la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&accion=borrar_alias&ext=2221

Configuración del post-desvío (buzón de voz, salto a extensión)

También se puede configurar el comportamiento de lo que viene después del desvío (buzón de voz normalmente) mediante la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=miclavesecreta&nv=910911912&accion=post&valor=26

donde:

'nv' o 'ext': Número virtual o de extensión cuyo buzón se va a configurar.
'accion' = 'post'.
'valor' puede ser:
- Un número entre 1 y 60 segundos (segundos para el desvío antes de enviar al buzón), o
- 'solo_buzon' (no realizar desvío y mandar directamente la llamada al buzón), o
- 'solo_desvio' (desactivar el buzón de voz)
- 'salto_a_extXXX' (donde XXX es el número de extensión a la que se salta) o 'salto_a_centralita'. Esta opción solo sirve para extensiones. Se puede añadir entonces el parámetro opcional 'tiempo_para_salto', que puede estar entre 1 y 60, y que especifica el número se segundos que se realiza el desvío antes de saltar a otra extensión.
Opcionalmente, se puede añadir el parámetro no_grabar=1, que hace sonar sólo el mensaje de buzón pero no graba el mensaje del llamante.

Configuración del email del buzón

Se puede configurar el e-mail asociado al buzón de voz:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=XXXXXXXX&nv=910911912&accion=email_avisos&email=mi.email@midominio.com

'nv' o 'ext': Número virtual o de extensión cuya URL de avisos se va a configurar.
'accion' = 'email_avisos'.
'email' = e-mail donde se desean recibir los buzones de voz. Puede ser vacío (en ese caso, no se recibirán emails).

Configuración de la URL de aviso de llamadas

Se puede configurar también la URL que se invocará cuando una llamada llegue, se realice un desvío o se cuelgue. Para más información acerca de esta opción ver: Opciones avanzadas de aviso de llamada.

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pass=XXXXXXXX&nv=910911912&accion=url_avisos&url=http%3A%2F%2Fdominio.com%2Fa.php%3Fllamante%3D%24llamante%26receptor%3D%24llamado%26extension%3D%24extension&desvio_comienza=1&desvio_descuelga=1&desvio_cuelga=1

'nv' o 'ext': Número virtual o de extensión cuya URL de avisos se va a configurar.
'accion' = 'url_avisos'.
'url' = La URL a la que se llamará cuando llegue una llamada, empiece un desvíos, se descuelgue o se cuelgue. Debe ir codificada (con url_encode). Ver Opciones avanzadas de aviso de llamada.
'url_usuario' (opcional): para la autentificación de la URL (si la tiene).
'url_password' (opcional): para la autentificación de la URL (si la tiene).
'desvio_comienza': si es igual a 1, llama a la URL cuando el desvío comienza.
'desvio_descuelga': si es igual a 1, llama a la URL cuando uno de los desvíos es descolgado.
'desvio_cuelga': si es igual a 1, llama a la URL cuando el desvío que se descolgó se cuelga.
'llamada_entra': (solo números virtuales) si es igual a 1, llama a la URL cuando la llamada llega (antes del desvío).
'llamada_perdida': si es igual a 1, llama a la URL cuando la llamada se pierde (no hay conversación ni buzón de voz).

Indice

Página principal >> Desarrolladores >> API de desvíos.