API de consumos

Sumario

1 Descripción de API de consumos

Descripción de API de consumos

Con la API de consumos, usted puede acceder a un listado de sus consumos vía HTTP sin necesidad de entrar en su cuenta. Esta herramienta es útil para integrar los consumos de Telefácil con su base de datos, CRM, web, etc.

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

Activación de API

La API de consumos debe ser activada explícitamente en la web, en la sección Consumos > API de consumos (o en Desarrolladores > Permisos de las APIs).

URL

La API de consumos se ofrece como un servicio web, accesible mediante la URL:

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

Para los clientes de Canarias, la URL es:

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

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.

Parámetros opcionales

'finicio' indica la fecha de inicio desde la que se quieren consultar los consumos. Debe estar en formato DD-MM-YYYY. Por defecto, toma el valor del día de hoy.
'ffinal' indica la fecha final hasta la que se quieren consultar los consumos. Debe estar en formato DD-MM-YYYY. Por defecto, toma el valor del día de hoy.
'llamante' permite filtrar llamadas según el llamante.
'acceso' permite filtrar llamadas según el acceso usado en la llamada.
'llamado' permite filtrar llamadas según el número llamado final.
'ref_id' permite filtrar llamadas según su referencia interna.
'tipo_filtro': si especifica más de un filtro (llamante, acceso, llamado, ref_id), puede variar el comportamiento con este parámetro. Sus posibles valores son AND (todos los filtros deben cumplirse) y OR (basta con que un filtro se cumpla). El valor por omisión es OR.
'tipo_regla': regula las comparaciones entre los valores de llamado, llamante, acceso y ref_id y los filtros especificados. Sus valores son: ES, EMPIEZA_POR y CONTIENE. El valor por omisión es CONTIENE.
'tipo_salida': puede ser 'text' (por defecto; para salida tipo texto plano), 'html' (para salida tipo tabla de HTML) o 'xml' (para salida tipo XML).

Resultado

La URL api_consumos devuelve una respuesta text/plain (o text/xml o text/html si se especifica con el parámetro 'tipo_salida'), con una serie de líneas de texto con los siguientes campos:

fecha: fecha de la llamada (DD/MM/YYYY).
hora: hora en que empezó la llamada (HH:MM:SS).
duracion: duración de la llamada (HH:MM:SS).
tipo: indica el tipo de llamada. Sus posibles valores son:
- numvirtual_desvio: una llamada a un número virtual que ha sido desviada a un teléfono.
- numvirtual_buzón: una llamada a un número virtual que ha acabado en un buzón de voz.
- fax_recibido: una llamada a un número de fax.
- fax_mandado: un envío de fax.
- centralita_entrante: una llamada a un número de centralita. Dentro de esta llamada pueden producirse múltiples eventos: desvíos, redirecciones a otras extensiones, buzones de voz, menús telefónicos, etc. El tiempo de esta llamada es el total.
- centralita_desvio: un desvío dentro de una extensión. Siempre va unido a una llamada del tipo centralita_entrante.
- llamada_web: una llamada efectuada desde el Identificador de Llamadas o desde la página web. Puede ser cualquiera de sus terminaciones (Origen o Destino): esto viene especificado en el acceso.
- llamada_saliente_voip: una llamada efectuada desde un VoIP
- llamada_saliente: una llamada efectuada desde cualquier medio no VoIP.
- sms_saliente: sms enviado.
llamante: número de teléfono del llamante.
nombre_llamante: nombre del llamante según los contactos del cliente (va encerrado entre comillas simples).
acceso: medio utilizado en la llamada.
llamado: número de teléfono receptor de la llamada.
nombre_llamado: nombre del receptor de la llamada según los contactos del cliente (va encerrado entre comillas simples).
pais: nombre del país del número de teléfono receptor.
cobro: cantidad en euros cobrada por la llamada. (En XML se llama consumo).
saldo: saldo de la cuenta Telefácil después de la llamada.
colgo: indica quién colgó la llamada. Sus posibles valores son Llamante y Receptor.
ref_id: este campo aparecerá a partir del 1 de febrero de 2014, y es una referencia interna única (dentro del mismo día) de la llamada.

Si la respuesta se pide en XML, se devolverá un conjunto de llamadas, con un elemento 'llamada' por cada llamada realizada:

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

<consumos>
  <error>0</error>
  <llamada>
    <fecha>11/04/2012</fecha>
    <hora>05:50:47</hora>
    <duracion>00:00:16</duracion>
    <tipo>fax_mandado</tipo>
    <llamante>822200956</llamante>
    <nombre_llamante></nombre_llamante>
    <acceso>FAX</acceso>
    <llamado>0034928400129</llamado>
    <nombre_llamado></nombre_llamado>
    <pais><![CDATA[Fijo - Duocom]]></pais>
    <consumo>0.00</consumo>
    <saldo>1044.43</saldo>
    <colgo>Receptor</colgo>
  </llamada>
</consumos>

Si la respuesta se pide en HTML, se devolverá una tabla con id y class "tabla_consumos". Posteriormente, le puede aplicar el estilo CSS que desee.

Ejemplos de uso de las APIs

Queremos todas las llamadas del mes de diciembre de 2008, cuyo llamante sea el 912345678 y que las haya respondido el 876543219:

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/api_consumos?principal=9xxxxxxxx&pass=miclavesecreta&llamante=912345678&llamado=876543219&tipo_filtro=AND

El resultado sería de esta forma:

 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
  
 fecha:16/12/2008 hora:08:59:35 duracion:00:00:04 tipo:llamada_saliente llamante:912345678 nombre_llamante:'Pepe Pérez' acceso:911010010
 llamado:0034876543219 nombre_llamado:'Ricardo López' pais:'España' cobro:E0.01 saldo:E9.99 colgo:Llamante
 fecha:29/12/2008 hora:09:00:20 duracion:00:02:11 tipo:llamada_saliente llamante:912345678 nombre_llamante:'Pepe Pérez' acceso:911010010 
 llamado:0034876543219 nombre_llamado:'Ricardo López' pais:'España' cobro:E0.05 saldo:E5.54 colgo:Llamante

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.

Indice

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