API de desvíos

Sumario

1 URL
2 Parámetros obligatorios
3 Leer los desvíos actuales
4 Cambiar los desvíos
5 Borrar los desvíos
6 Cambiar el desvío especial (solo extensiones)
7 Creación y borrado de extensiones
8 Creación y borrado de alias de extensiones
9 Configuración del buzón de voz

URL

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&pin=1234&nv=xxxxxxxxx

Para los clientes de Canarias, la URL es:

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

Para acceder a esta API hay que tener dado de alta un número virtual o un número de centralita. En la pestaña de "Desvíos", sección "Opciones Avanzadas" (o en Opciones > Permisos de las APIs y los servicios web), 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".
'pin' es el PIN 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 pin 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.

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 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&pin=0000&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&pin=0000&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] =>

Por último, 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)

Cambiar los desvíos

Para cambiar un desvío, además de los parámetros obligatorios (principal, pin 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.

'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&pin=0000&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&pin=0000&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).

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&pin=0000&ext=1&accion=borrar&horario=12001300&dias=lmxjv

Cambiar el desvío especial (solo extensiones)

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&pin=0000&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&pin=0000&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

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&pin=0000&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).

Para borrarla, se llama a la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pin=0000&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&pin=0000&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&pin=0000&accion=borrar_alias&ext=2221

Configuración del buzón de voz

También se puede configurar el comportamiento del buzón mediante la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_desvios?principal=911922933&pin=0000&nv=910911912&accion=buzon&valor=26

donde:

'nv' o 'ext': Número virtual o de extensión cuyo buzón se va a configurar.
'accion' = 'buzon'.
'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)
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.

Indice

Portada >> Desarrolladores >> API de desvíos.