Documentación ST-WebServices

# Introducción

Servitux ST-Webservices pone a disposición del cliente las herramientas necesarias para poder interactuar con ST-PBX a través de una API WEB, creada especificamente para facilitar la comunicación con software de terceros. Entre las posibilidades que nos brinda esta API, podemos encontrar:

  • Establecimiento y obtención de listas negras (Black List)
  • Establecimiento y obtención de desvíos de llamadas (Call Forward)
  • Establecimiento y obtención de llamadas en espera (Call Waitings)
  • Realización de llamadas mediante un click (Click2Call)
  • Establecimiento y obtención de estado No Molestar (DND)
  • Obtención de Colas (Queues)

Estas características se irán ampliando en siguientes versiones de esta API, donde iremos añadiendo las funciones más demandadas, además de nuevas características surgidas de las ideas del departamento de I+D de Servitux.

A continuación se detallan las funciones existentes en la actual versión de esta API, con ejemplos de código que le ayudarán a crear sus propias aplicaciones, o con los que podrán ampliar las características de sus aplicaciones ya existentes. Actualmente podrá encontrar ejemplos en los siguientes lenguajes:

  • .NET (C# y VB.NET)
  • PHP
  • Python

Adicionalmente, los resultados a las funciones, ya sean de establecimiento o de obtención de información, podrán ser recibidos en los siguientes formatos:

  • eXtensible Markup Language (XML)
  • JavaScript Object Notation (JSON)

 

 

# Ejemplos de Código

C#

String URI = "http://www.example.com/api/ws/login?extension=108&password=1234";

WebClient webClient = new WebClient();
Stream stream = webClient.OpenRead(URI);
StreamReader reader = new StreamReader(stream);
string response = reader.ReadToEnd();
reader.Close();

//xml response
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.LoadXml(response);

//json response
//You need third party libs

VB.net

dim URI as String = "http://www.example.com/api/ws/login?extension=108&password=1234"

dim webClient as new WebClient()
dim stream as Stream = webClient.OpenRead(URI)
dim reader as new StreamReader(stream)
dim response as String = reader.ReadToEnd()
reader.Close()

//xml response
dim xmlDoc as new XmlDocument()
xmlDoc.LoadXml(response)

//json response
//You need third party libs
$response = file_get_contents("http://www.example.com/api/ws/login?extension=108&password=1234");

//xml response
$xml = new SimpleXMLElement($response);

//json response
$json = json_decode($response);
import requests
r = requests.get("http://example.com/foo/bar")
response = r.content

//xml response
import xml.etree.ElementTree as ET
xml = ET.fromstring(response)

//json response
import json
json_obj = json.loads(response)

 

 

# Login

Volver arriba

Definición:

string Login(extension, password)

Descripción:

Identifica al usuario y le asigna un token para comunicación

Tabla de parámetros
Nombre Tipo Descripción
extension string Nº de la extensión que intenta identificarse
password string Contraseña asociada a la extensión

Devuelve:

result será 1 cuando todo funcione correctamente, y token contendrá el token para comunicación a la hora de llamar a las demás funciones disponibles

<?xml version="1.0"?>
<root>
   <result>1</result>
   <token>trfWXBwEzwaARsW</token>
   <expiration>2017-08-31 09:50:23</expiration>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1002</error>
   <message>La extensión 777 no está registrada</message> 
</root>
Tabla de errores
Error Valor Descripción
WS_MISSING_DATA 1001 Faltan parámetros
WS_USER_NOT_REGISTERED 1002 La extensión {0} no está registrada
WS_USER_DISABLED 1003 La extensión {0} está deshabilitada
WS_INVALID_PASSWORD 1004 El password no es correcto
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetBlackList

Volver arriba

Definición:

string SetBlackList(token, state, telnumber, description)

Descripción:

Añade un número de teléfono a la lista negra.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
state boolean true para añadir a la lista – false para borrar de la lista
telnumber string Nº de teléfono
description string Motivo por el cual se añade a la lista negra. Sólo necesario para añadir (no para borrar)

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <message>Respuesta Asterisk</message>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message> 
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetBlackList

Volver arriba

Definición:

string GetBlackList(token)

Descripción:

Obtiene una lista de los teléfonos incluídos en la BlackList.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login

Devuelve:

result será 1 cuando todo funcione correctamente. blacklist contendrá la lista de teléfonos añadidos a la lista negra.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <blacklist>
      <item>
         <telnumber>966665544</telnumber>
         <description>Spam telefónico</description>
      <item>
   </blacklist>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result> 
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetCallForward

Volver arriba

Definición:

string SetCallForward(token, type, state, extension)

Descripción:

Activar/Desactivar Desvío de Llamadas.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
type string Tipo de desvío. Los valores admitidos son: CF = Siempre – CFB = Ocupado – CFU = No Contesta/Deshabilitado
state boolean true para activar desvío – false para desactivar desvío
extension string Nº de extensión donde desviar las llamadas

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
CF_INVALID_PARAMETER 3002 Tipo Inválido. Tipos admitidos: CF = All – CFB = Busy – CFU = No Answer/Unavailable
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetCallForward

Volver arriba

Definición:

string GetCallForward(token, type, extension)

Descripción:

Obtiene una lista de los dispositivos con CF activado.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
type string Tipo de desvío a devolver. Si se deja a blanco devuelve todos los tipos.
extension string Nº de extensión desviada. Si se deja a blanco devuelve todas las extensiones.

Devuelve:

result será 1 cuando todo funcione correctamente. callforwards contendrá la lista de extensiones con el desvío activado.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <callforwards>
      <item>
         <extension>777</extension>
         <type>CF</type>
         <destination>888</destination>
      <item>
   </callforwards>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
CF_INVALID_PARAMETER 3002 Tipo Inválido. Tipos admitidos: CF = All – CFB = Busy – CFU = No Answer/Unavailable
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetCallWaiting

Volver arriba

Definición:

string SetCallWaiting(token, state)

Descripción:

Activar/Desactivar opción Llamada en Espera.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
state boolean true para activar llamada en espera – false para desactivar llamada en espera

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <message>Respuesta de Asterisk</message>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetCallWaiting

Volver arriba

Definición:

string GetCallWaiting(token, extension)

Descripción:

Obtiene una lista de los dispositivos con CW activado.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
extension string Nº de extensión con llamada en espera activada. Si se deja a blanco devuelve todas las extensiones.

Devuelve:

result será 1 cuando todo funcione correctamente. callwaitings contendrá la lista de extensiones con la llamada en espera activada.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <callwaitings>
      <extension>777</extension>
   </callwaitings>
</root>

result será distinto de cero cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# Click2Call

Volver arriba

Definición:

string Click2Call(token, extension)

Descripción:

Realiza una llamada a otra extensión, y la enlaza con la extensión registrada.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
extension string Nº de extensión o número de teléfono al cual se desea llamar.

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetDND

Volver arriba

Definición:

string SetDND(token, state)

Descripción:

Activar/Desactivar No Molestar.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
state boolean true para activar No Molestar – false para desactivar No Molestar

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <message>Respuesta de Asterisk</message>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetDND

Volver arriba

Definición:

string GetDND(token, extension)

Descripción:

Obtiene una lista de los dispositivos con DND activado.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
extension string Nº de extensión con No Molestar activado. Si se deja a blanco devuelve todas las extensiones.

Devuelve:

result será 1 cuando todo funcione correctamente. callforwards contendrá la lista de extensiones con el No Molestar activado.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <dnds>
      <extension>777</extension>
   </dnds>
</root>

result 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetQueues

Volver arriba

Definición:

string GetQueues(token, queue)

Descripción:

Obtiene una lista de las Colas y sus miembros.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
queue string Nombre de la cola de la que se desea obtener la información. Si se deja a blanco devuelve todas las colas.

Devuelve:

result será 1 cuando todo funcione correctamente. queues contendrá la lista colas y extensiones.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <queues>
      <queue>
         <name>Nombre Cola</name>
         <members>
            <member>
               <name>Nombre Extensión</name>
               <extension>777</extension>
            </member>
         </members>
      </queue>
   </queues>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetCalls

Volver arriba

Definición:

string GetCalls(token, src, dst, fromDate, toDate)

Descripción:

Obtiene una lista las llamadas entrantes y/o salientes.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
src string Nº de teléfono o extensión origen de la llamada. Si se deja a blanco devuelve todos los origenes.
dst string Nº de teléfono o extensión destino de la llamada. Si se deja a blanco devuelve todos los destinos.
fromDate string Fecha a partir de la que se desean obtener registros. Si se deja a blanco devuelve el día actual.
toDate string Fecha límite de la que se desean obtener registros. Si se deja a blanco devuelve el día actual.

Devuelve:

result será 1 cuando todo funcione correctamente. calls contendrá la lista llamadas.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <calls>
      <call>
         <calldate>16/02/2015 12:30:25</calldate>
         <src>777</src>
         <dst>966665544</dst>
         <duration>30</duration>
      </call>
   </calls>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
DATE_FORMAT_INVALID 3001 Formato de fecha inválido
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetInactive

Volver arriba

Definición:

string SetInactive(token, state)

Descripción:

Activar/Desactivar Dispositivo.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
state boolean 0 para activar – 1 para desactivar

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <message>Respuesta de Asterisk</message>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetInactive

Volver arriba

Definición:

string GetInactive(token, extension)

Descripción:

Obtiene una lista de los dispositivos inactivos.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
extension string Nº de extensión con por la que se quiere preguntar. Si se deja a blanco devuelve todas las extensiones.

Devuelve:

result será 1 cuando todo funcione correctamente. extensions contendrá la lista de extensiones inactivas.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <extensions>
      <extension>777</extension>
   </extensions>
</root>

result 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# SetWakeUpService

Volver arriba

Definición:

string SetWakeUpService(token, datetime)

Descripción:

Activar/Desactivar Servicio Despertador.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
datetime string formato Y-m-d H:m:s

Devuelve:

result será 1 cuando todo funcione correctamente.

<?xml version="1.0"?>
<root>
   <result>1</result>
</root>

result será 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos

 

 

# GetWakeUpService

Volver arriba

Definición:

string GetWakeUpService(token, extension)

Descripción:

Obtiene una lista de los dispositivos con el servicio despertador activado.

Tabla de parámetros
Nombre Tipo Descripción
token string Token obtenido con la función Login
extension string Nº de extensión con por la que se quiere preguntar. Si se deja a blanco devuelve todas las extensiones.

Devuelve:

result será 1 cuando todo funcione correctamente. wakeupservice contendrá la lista de extensiones con el servicio despertador activado.

<?xml version="1.0"?>
<root>
   <result>1</result>
   <wakeupservice>
      <wakeup>
         <extension>777</extension>
         <datetime>2017-10-13 20:00</datetime>
      </wakeup>
   </wakeupservice>
</root>

result 0 cuando se encuentre algún error, guardando el mensaje de error en message.

<?xml version="1.0"?>
<root>
   <result>0</result>
   <error>1010</error>
   <message>El Token indicado no es válido</message>
</root>
Tabla de errores
Error Valor Descripción
WS_TOKEN_INVALID 1010 El Token indicado no es válido
WS_TOKEN_EXPIRED 1011 El Token indicado ha expirado
WS_MODULE_INVALID 2001 El Módulo {0} no existe
WS_MODULE_DISABLED 2002 El Módulo {0} está deshabilitado
ASTERISK_ERROR 4001 La descripción del error variará según la respuesta de Asterisk Manager
DB_GENERIC_ERROR 5001 Error de conexión con la Base de Datos