Diferencia entre revisiones de «API de contactos»
| Línea 7: | Línea 7: | ||
===Activación=== | ===Activación=== | ||
| − | Este servicio '''debe activarse explícitamente dentro de la web''', en Contactos > API. 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. | + | 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. |
Revisión del 13:23 25 abr 2012
Sumario
- 1 ¿Qué es?
- 2 Forma de uso
- 2.1 Lista de contactos
- 2.2 Insertar un contacto
- 2.3 Actualizar un contacto
- 2.4 Eliminar un contacto
- 2.5 Eliminar todos los contactos
- 2.6 Añadir un grupo de contactos
- 2.7 Eliminar un grupo de contactos
- 2.8 Eliminar todos los grupos de contactos
- 2.9 Asignar un contacto a un grupo de contactos
- 2.10 Quitar un contacto de un grupo de contactos
- 2.11 Tipos de datos
- 2.12 Respuesta del servicio
- 3 Ejemplos
¿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 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).
- '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.
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:
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:
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:
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:
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:
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:
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:
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>
<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>
<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>
<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>
<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>
<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>
<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>
<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.