API de filtros
Sumario
URL de API de filtros
Si no sabe lo que es una API lea ¿Qué son las APIs de Mi Oficina Web?
La API de filtros se ofrece como un servicio web, accesible mediante la URL:
https://scgi.duocom.es/cgi-bin/oficinaweb/api_filtros?principal=xxxxxxxxx&pass=xxxxxxxx&nv=xxxxxxxxx
Para los clientes de Canarias, la URL es:
https://cgi.duocom.es/cgi-bin/oficinaweb/api_filtros?principal=xxxxxxxxx&pass=xxxxxxxx&nv=xxxxxxxxx
Para acceder a esta API hay que tener dado de alta un número virtual, un número de centralita virtual o un número de fax. 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 Mi Oficina Web".
- 'pass' es la contraseña de la cuenta Mi Oficina Web.
- Además, hace falta especificar:
- o bien 'nv' como el número virtual al que se quieren consultar o modificar los filtros.
- o bien 'centralita' como el número de centralita al que se quieren consultar o modificar los filtros
- o bien 'ext' como la extensión a la que se quieren consultar o modificar los filtros.
- o bien 'fax' como el número de fax al que se quieren consultar o modificar los filtros.
- o bien nada si se desea consultar o modificar los filtros que afectan a todos los números de centralita de la cuenta (antes de las extensiones).
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.
Leer los filtros actuales
Para leer los filtros que actualmente están espeficicados, hay que llamar a la URL de la API sin ninguna acción. Por ejemplo, para un número virtual:
https://scgi.duocom.es/cgi-bin/telefacil2/api_filtros?principal=999888777&pass=1111&nv=902009955
Para una extensión:
https://scgi.duocom.es/cgi-bin/telefacil2/api_filtros?principal=999888777&pass=1111&ext=1234
La API devolverá un XML de este tipo:
<filtros>
<res>1</res>
<max_filtros>250</max_filtros>
<num_filtros>2</num_filtros>
<filtro>
<id>Privado</id>
<telefono>Privado</telefono>
<accion>no_contestar</accion>
</filtro>
<filtro>
<id>1</id>
<telefono>912345678</telefono>
<comentario/>
<accion>no filtrar</accion>
</filtro>
<filtro>
<id>2</id>
<telefono>987654321</telefono>
<comentario>TEST</comentario>
<accion>buzon</accion>
</filtro>
</filtros>
La respuesta incluye un campo 'res' (resultado de la petición, 0 si error, 1 si éxito). Si 'res' es 1 (OK), se añaden a la respuesta un campo 'max_filtros' (número máximo de filtros que puede tener un número o extensión, sin contar con los filtros para números privados y resto de números) y un campo 'num_filtros' (indica cuántos filtros se han definido para el número o extensión especificado, sin contar con los filtros para números privados y resto de números).
Seguidamente se listan los filtros (si 'res' es 1). Cada filtro consta de una 'id' (necesaria para eliminarlo), un 'telefono' (el número de teléfono que se está filtrando), un 'comentario' acerca del filtro (opcional) y una 'accion' de filtrado. Las acciones de filtrado pueden ser:
- 'buzon': mandar al buzón de voz
- 'comunicar': dar comunicando
- 'no_contestar': dejar sonando al llamante pero no contestar
- 'mensaje': dar un mensaje configurado en la pestaña Voz
- 'no_filtrar': no realizar ningún filtrado (se suele usar en conjunción con el filtro "Resto de números")
Insertar un nuevo filtro
Además de los parámetros obligatorios, pasamos:
- accion=insertar
- telefono=XXXXXXXXX, donde XXXXXXXXX es el número de teléfono que queremos filtrar (también puede tomar los valores 'privado' para todos los números privados o 'resto' para todos los teléfonos no especificados en los otros filtros)
- accion_filtro={buzon|comunicar|no_contestar|mensaje|no_filtrar}, es la acción filtradora a realizar cuando llame el anterior número de teléfono
- comentario=... (opcional)
Ejemplo:
https://scgi.duocom.es/cgi-bin/telefacil2/api_filtros?principal=666555444&pass=2211&ext=1253&accion=insertar&telefono=912345678&accion_filtro=buzon&comentario=TEST
Si todo es correcto, se listarán los filtros después de la inserción.
Eliminar un filtro
Para eliminar un filtro debemos saber la ID que le asigna la API. Para eso hay que listar los filtros existentes y buscar el campo 'id'. Llamaremos a la API con ese valor de ID. A los parámetros obligatorios, añadimos estos:
- accion=eliminar
- id=X, donde X es la ID del filtro a borrar (normalmente un número, aunque también puede ser 'resto' o 'privado')
Ejemplo:
https://scgi.duocom.es/cgi-bin/telefacil2/api_filtros?principal=666555444&pass=2211&ext=1253&accion=eliminar&id=2
Si todo es correcto, se listarán los filtros después del borrado.
Eliminar todos los filtros
Para eliminar todos los filtros pasamos accion=eliminar_todo. Por ejemplo:
https://scgi.duocom.es/cgi-bin/telefacil2/api_filtros?principal=666555444&pass=2211&ext=1253&accion=eliminar_todo
Si todo es correcto, se listarán los filtros después del borrado total.
Ejemplo de la API de filtros
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:
<?php
$usuario = '666111666';
$pass = 'MiClaveSecreta';
$nv = '911010000';
$curl = curl_init("https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/api_filtros?principal=${usuario}&pass=${pass}&nv=${nv}");
curl_setopt($curl, CURLOPT_HEADER, false); // PARA EVITAR DEVOLUCION DE CABEZERAS HTTP
curl_setopt($curl, CURLOPT_TIMEOUT, 5); // TIEMPO DE ESPERA
$output = curl_exec($curl); // EJECUTAMOS LA LLAMADA
curl_close($curl);
// en $output esta la respuesta XML
?>
Indice
Página principal >> Desarrolladores >> API de filtros.