Diferencia entre revisiones de «API de contactos»

Revisión del 10:07 27 feb 2015

¿Qué es?

Descripción

Este servicio web nos permite interactuar con los contactos de una cuenta Telefácil.

Activación

Este servicio debe activarse explícitamente dentro de la web, en Contactos > API (o en Opciones > Permisos de las APIs y los servicios web). En esa sección también se pueden restringir las direcciones IP desde las que se puede llamar a esta aplicación web. Si usted tiene una dirección IP fija por favor introdúzcala aquí, aumenta la seguridad.

Forma de uso

Lista de contactos

Devuelve la lista de contactos (en XML).

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=listar[&eliminados=1&actualizado=1329390208&grupo=Trabajo]

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'listar'.

Opcionalmente, se pueden pasar los siguientes parámetros:

'actualizado', con una fecha en formato UNIX, para que se listen sólo los contactos modificados a partir de dicha fecha. Por ejemplo, actualizado=1329390208.
'eliminados', con un valor mayor que 0 (por ejemplo, eliminados=1), para que se listen los contactos eliminados en el último mes. Si eliminados=1, se listan todos los eliminados (en el último mes); si eliminados tiene un valor en formato UNIX, se listan los contactos eliminados a partir de esa fecha (por ejemplo, eliminados=1329390208). Si se pasa un valor mayor que 0, la lista de contactos eliminados se añade a la lista de contactos normales. Por defecto, no se muestran los contactos eliminados.
'grupo', con el nombre de un grupo de contactos, para que se listen sólo los contactos que pertenecen a dicho grupo (esta condición también afecta a los contactos eliminados).

Vea un ejemplo de respuesta en #Ejemplo de listado de contactos en XML.

Lista de contactos MD5

Cada contacto tiene un código o firma MD5. Dicha firma se genera a partir de sus campos (nombre, apellidos, teléfonos, emails, dirección, etc). Por tanto, si uno de los campos cambia, el MD5 cambia también. Si tenemos almacenados los contactos en una base de datos y queremos ver qué ha cambiado, podemos pedir simplemente los MD5 y comparar con los que tengamos almacenados.

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=listar_md5

Insertar un contacto

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=insertar[&nombre=Juan&...]

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'insertar'.

El resto de campos son opcionales: nombre, apellidos, email1, email2, domicilio, poblacion, cp, provincia, pais, organizacion, puesto, telefono1, telefono2, telefono3, telefono4, telefono5, tipo_telefono1, tipo_telefono2, tipo_telefono3, tipo_telefono4, tipo_telefono5, extra1, extra2, extra3, nombre_extra1, nombre_extra2, nombre_extra3. Vea cómo es cada campo en #Tipos de datos.

Actualizar un contacto

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=actualizar&id=123456[&nombre=Pedro&...]

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'actualizar'.
'id' es el identificador del contacto.

El resto de campos son opcionales: nombre, apellidos, email1, email2, domicilio, poblacion, cp, provincia, pais, organizacion, puesto, telefono1, telefono2, telefono3, telefono4, telefono5, tipo_telefono1, tipo_telefono2, tipo_telefono3, tipo_telefono4, tipo_telefono5, extra1, extra2, extra3, nombre_extra1, nombre_extra2, nombre_extra3. Vea cómo es cada campo en #Tipos de datos.

Eliminar un contacto

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=eliminar&id=123456

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'eliminar'.
'id' es el identificador del contacto.

Eliminar todos los contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=eliminar_todo

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'eliminar_todo'.

Añadir un grupo de contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=insertar_grupo&grupo=MiGrupo

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'insertar_grupo'.
'grupo' es el nombre del nuevo grupo de contactos.

Los grupos deben tener nombres diferentes. Existen 11 grupos predefinidos: Amigos, Asesoria, Clientes, Conocidos, Contabilidad, Familia, Favoritos, General, Oficina, Proveedores y Trabajo.

Eliminar un grupo de contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=eliminar_grupo&grupo=MiGrupo

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'eliminar_grupo'.
'grupo' es el nombre del grupo de contactos que se desea eliminar.

No se pueden borrar los grupos predefinidos: Amigos, Asesoria, Clientes, Conocidos, Contabilidad, Familia, Favoritos, General, Oficina, Proveedores y Trabajo.

Eliminar todos los grupos de contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=eliminar_todos_grupos

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'eliminar_todos_grupos'.

No se pueden borrar los grupos predefinidos: Amigos, Asesoria, Clientes, Conocidos, Contabilidad, Familia, Favoritos, General, Oficina, Proveedores y Trabajo.

Asignar un contacto a un grupo de contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=asignar_grupo&&id=123456grupo=MiGrupo

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'asignar_grupo'.
'id' es el identificador del contacto.
'grupo' es el nombre del grupo de contactos.

Quitar un contacto de un grupo de contactos

La URL debe ser:

https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?principal=xxxxxxxxx&pin=xxxx&accion=quitar_grupo&&id=123456grupo=MiGrupo

donde:

'principal' es su número de usuario de Telefácil.
'pin' es el PIN de la cuenta.
'accion' debe tener el valor 'quitar_grupo'.
'id' es el identificador del contacto.
'grupo' es el nombre del grupo de contactos.

Tipos de datos

Los campos de los contactos son los siguientes:

Campo	Tipo	Longitud máxima	Significado
nombre	ristra	100	Nombre del contacto
apellidos	ristra	200	Apellidos del contacto
domicilio	ristra	128	Dirección, número, piso, etc. del contacto
poblacion	ristra	40	Población del contacto
cp	ristra	10	Código postal del contacto
provincia	ristra	40	Provincia del contacto
pais	ristra	50	País del contacto
organizacion	ristra	64	Organización o empresa del contacto
puesto	ristra	64	Puesto que ocupa el contacto en la organización
email1	ristra	100	E-mail del contacto
email2	ristra	100	E-mail del contacto
telefono1..5	ristra	20	Números de teléfono
tipo_telefono1..5	entero		Tipos de los números de teléfono (ver siguiente tabla)
extra1..3	ristra	96	Campos extra para añadir más información sobre el contacto
nombre_extra1..3	ristra	32	Nombres de los campos extra

El tipo_telefono es un entero que puede tener los siguientes valores:

Valor	Significado
0	Tfno. Principal
1	Tfno. Casa
2	Tfno. Oficina
3	Tfno. Trabajo
4	Tfno. Automovil
5	Tfno. Asistente
6	Tfno. Particular
7	Movil Principal
8	Movil Casa
9	Movil Oficina
10	Movil Trabajo
11	Movil Automovil
12	Movil Asistente
13	Movil Particular
14	Fax Principal
15	Fax Casa
16	Fax Oficina
17	Fax Trabajo
18	Fax Automovil
19	Fax Asistente
20	Fax Particular

Respuesta del servicio

El servicio web retorna todas las respuestas en formato XML. Todas las respuestas están encerradas en la raíz 'contactos', y contiene siempre un campo 'error' que será 0 si el comando o petición enviado al servidor se ejecutó con éxito, o 1 si hubo algún error, en cuyo caso habrá también un campo 'msgerr' que explica dicho error.

Por ejemplo, una respuesta afirmativa sería:

HTTP/1.1 200 OK
Date: Mon, 20 Feb 2012 11:43:37 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" ?>

<contactos>
  <error>0</error>
</contactos>

Una respuesta de error sería:

HTTP/1.1 200 OK
Date: Mon, 20 Feb 2012 11:43:37 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" ?>

<contactos>
  <error>1</error>
  <msgerr>Cuenta incorrecta.</msgerr>
</contactos>

Ejemplos

Ejemplo de llamada al servicio web en PHP + CURL

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.

He aquí un ejemplo en PHP usando cURL, cortesía de tuayudainformatica.com:

<?php
  $usuario = '666111666';
  $pin = '0000';

  $curl = curl_init("https://scgi.duocom.es/cgi-bin/telefacil2/apicontactos2?
                     principal=${usuario}&pin=${pin}&accion=listar"); // LLAMADA DE LA URL
  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);
  $output = substr($output, 0, 1);            // XML
?>

Ejemplo de listado de contactos en XML

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

<contactos>
<error>0</error>
  <num_contactos>7</num_contactos>
  <contacto>
    <id>124744</id>
    <nombre>Ana</nombre>
    <apellidos>Rosa</apellidos>
    <creado>2011-12-21 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Alava</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>1</num_telefonos>
    <telefono>
      <numero>628000001</numero>
      <iposicion>1</iposicion>
      <tipo>Tfno. Principal</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc3344</md5>
    <grupos>
      <num_grupos>2</num_grupos>
      <grupo>Oficina</grupo>
      <grupo>TEST GROUP</grupo>
    </grupos>
  </contacto>
  <contacto>
    <id>34453</id>
    <nombre>Fax de pruebas 1</nombre>
    <apellidos></apellidos>
    <creado>2010-08-09 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Madrid</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>1</num_telefonos>
    <telefono>
      <numero>911011042</numero>
      <iposicion>1</iposicion>
      <tipo>Movil Principal</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc3345</md5>
    <grupos>
      <num_grupos>1</num_grupos>
      <grupo>Trabajo</grupo>
    </grupos>
  </contacto>
  <contacto>
    <id>34454</id>
    <nombre>Fax de pruebas 2</nombre>
    <apellidos></apellidos>
    <creado>2010-08-09 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Madrid</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>1</num_telefonos>
    <telefono>
      <numero>911014571</numero>
      <iposicion>1</iposicion>
      <tipo>Movil Principal</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc3341</md5>
    <grupos>
      <num_grupos>0</num_grupos>
    </grupos>
  </contacto>
  <contacto>
    <id>34455</id>
    <nombre>Fax de pruebas 3</nombre>
    <apellidos></apellidos>
    <creado>2010-08-09 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Las Palmas</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>2</num_telefonos>
    <telefono>
      <numero>928400129</numero>
      <iposicion>1</iposicion>
      <tipo>Tfno. Principal</tipo>
    </telefono>
    <telefono>
      <numero>928445566</numero>
      <iposicion>2</iposicion>
      <tipo>Tfno. Casa</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc3333</md5>
    <grupos>
      <num_grupos>0</num_grupos>
    </grupos>
  </contacto>
  <contacto>
    <id>57474</id>
    <nombre>FILM</nombre>
    <apellidos></apellidos>
    <creado>2011-06-16 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Madrid</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>1</num_telefonos>
    <telefono>
      <numero>0012127773456</numero>
      <iposicion>1</iposicion>
      <tipo>Tfno. Principal</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc3123</md5>
    <grupos>
      <num_grupos>0</num_grupos>
    </grupos>
  </contacto>
  <contacto>
    <id>132630</id>
    <nombre>Oficina</nombre>
    <apellidos></apellidos>
    <creado>2012-02-06 12:21:08.119168+01</creado>
    <modificado>2012-02-06 12:21:08.119168+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Alava</provincia>
    <pais></pais>
    <organizacion></organizacion>
    <puesto></puesto>
    <num_telefonos>2</num_telefonos>
    <telefono>
      <numero>911000111</numero>
      <iposicion>1</iposicion>
      <tipo>Tfno. Principal</tipo>
    </telefono>
    <telefono>
      <numero>911000112</numero>
      <iposicion>2</iposicion>
      <tipo>Tfno. Oficina</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc1344</md5>
    <grupos>
      <num_grupos>0</num_grupos>
    </grupos>
  </contacto>
  <contacto>
    <id>34456</id>
    <nombre>Luis</nombre>
    <apellidos>Pino</apellidos>
    <creado>2010-08-09 00:00:00+01</creado>
    <modificado>2011-12-22 11:39:38.594387+01</modificado>
    <eliminado>NO</eliminado>
    <email1></email1>
    <email2></email2>
    <domicilio></domicilio>
    <poblacion></poblacion>
    <cp></cp>
    <provincia>Las Palmas</provincia>
    <pais><![CDATA[España]]></pais>
    <organizacion><![CDATA[Duocom Europe, S.L.]]></organizacion>
    <puesto></puesto>
    <num_telefonos>2</num_telefonos>
    <telefono>
      <numero>999999999</numero>
      <iposicion>1</iposicion>
      <tipo>Tfno. Principal</tipo>
    </telefono>
    <telefono>
      <numero>888888888</numero>
      <iposicion>2</iposicion>
      <tipo>Tfno. Casa</tipo>
    </telefono>
    <extra>
      <nombre>Extra 1:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 2:</nombre>
      <valor></valor>
    </extra>
    <extra>
      <nombre>Extra 3:</nombre>
      <valor></valor>
    </extra>
    <md5>dfa345678abc2344</md5>
    <grupos>
      <num_grupos>3</num_grupos>
      <grupo>Trabajo</grupo>
      <grupo>Oficina</grupo>
      <grupo>Favoritos</grupo>
    </grupos>
  </contacto>
  <num_contactos_eliminados>1</num_contactos_eliminados>
  <contacto>
    <id>133230</id>
    <nombre>Pedrito</nombre>
    <apellidos>Laso</apellidos>
    <eliminado>2012-02-17 13:50:26.517797</eliminado>
  </contacto>
  <grupos>
    <num_grupos>15</num_grupos>
    <grupo>Amigos</grupo>
    <grupo>Asesoria</grupo>
    <grupo>CAT 1</grupo>
    <grupo>CAT 2</grupo>
    <grupo>CAT 3</grupo>
    <grupo>CAT 4</grupo>
    <grupo>Clientes</grupo>
    <grupo>Conocidos</grupo>
    <grupo>Contabilidad</grupo>
    <grupo>Familia</grupo>
    <grupo>Favoritos</grupo>
    <grupo>Oficina</grupo>
    <grupo>Proveedores</grupo>
    <grupo>TEST GROUP</grupo>
    <grupo>Trabajo</grupo>
  </grupos>
  <ult_modificado>2012-02-06 12:21:08.119168+01</ult_modificado>
  <ult_eliminado>2012-02-17 13:50:26.517797</ult_eliminado>
</contactos>

Indice

Portada >> Desarrolladores >> Servicio web de contactos.

Diferencia entre revisiones de «API de contactos»

Revisión del 10:07 27 feb 2015

Sumario

¿Qué es?

Descripción

Activación

Forma de uso

Lista de contactos

Lista de contactos MD5

Insertar un contacto

Actualizar un contacto

Eliminar un contacto

Eliminar todos los contactos

Añadir un grupo de contactos

Eliminar un grupo de contactos

Eliminar todos los grupos de contactos

Asignar un contacto a un grupo de contactos

Quitar un contacto de un grupo de contactos

Tipos de datos

Respuesta del servicio

Ejemplos

Ejemplo de llamada al servicio web en PHP + CURL

Ejemplo de listado de contactos en XML