Tabla de Contenidos

12. API de Integria IMS

12. API de Integria IMS

API externa de Integria

La API externa de Integria se utiliza haciendo llamadas remotas via HTTP o HTTPS sobre el fichero /include/api.php. Con este método es posible la integración de aplicaciones de terceros con Integria. El uso del API se hace mediante una llamada con unos parámetros definidos que devuelve un valor o una lista de valores.

El prototipo de llamada al API es el siguiente:

http://<instalación Integria>/include/api.php<parametros>

El API sólo acepta los siguientes parámetros (otros parámetros serán ignorados):

user (obligatorio): nombre del usuario de Integria que accede a los datos, se usa para verificar ACLs.
user_pass (obligatorio): Contraseña del usuario.
op (obligatorio): operación a realizar. Las operaciones están detalladas más abajo.
pass (obligatorio si está habilitado): password del API configurado en la consola de Integria.
params: lista de parámetros que se pasaran a la función separados por un token.
token: token que separa los diferentes parámetros (por defecto es ',').
return_type: formato del resultado de la llamada, puede ser 'xml' o 'csv' (por defecto es 'csv').
info: parámetro especial con el que puede obtenerse la versión antes de autenticarse.

Seguridad

La autenticación para el API de Integria realiza en tres pasos.

Autenticación por IP válida

La seguridad se basa en una lista de IPs que tendrán acceso a la herramienta. Esta lista se puede crear en el menú de configuración de Integria.

Es importante tener en cuenta que este método de autenticación siempre está activo por lo que si no desea usarse será necesario poner el caracter * (todas las IPs autorizadas) como única IP de la lista.

Autenticación por contraseña

Dentro del menú de configuración de Integria es posible establecer una contraseña para el API. Esta contraseña deberá enviarse en la llamada al API en claro, por ello es recomendable usar HTTPS si se quiere usar este método de autenticación.

Si esta contraseña está vacía, significa que la autenticación por contraseña está deshabilitada y no hace falta poner el token pass en la llamada a la API.

Autenticación por usuario y contraseña de usuario (login)

Es necesario en todas las llamadas (excepto las de información) especificar el usuario (user) y la contraseña del usuario (user_pass). No hay forma de deshabilitar este paso de la autenticación.

Funciones del API

Retorno de información sobre Integria IMS

Esta es una función especial que puede ser usada sin autentificarse, ya que la información que devuelve se puede obtener de la pantalla de login y no se considera que vulnere la seguridad.

Devuelve la versión del Integria IMS y es útil para verificar que en esta ruta se encuentra una instalación de Integria IMS o para obtener la versión antes de la autenticación.

Llamada

http://127.0.0.1/integria/include/api.php?info=version

Resultado

Integria IMS OpenEdition v4.0dev - Build 130514 MR5

Incidentes

get_incidents

Resultado: Devuelve una lista con los tickets a las que tiene acceso el usuario que hace la llamada.
Parámetros serializados:
- Filtro de cadena: Muestra solamente los tickets que contienen esa cadena en el título o en la descripción (no obligatorio). Vacío para todos los tickets. No distingue minúsculas ni mayúsculas.
- Filtro de estado: Id del estado (no obligatorio). Puede tomar los siguientes valores:
  - 0 → Todos (por defecto)
  - 1 → Nuevo
  - 2 → No confirmado
  - 3 → Asignado
  - 4 → Re-abierto
  - 5 → Pending to be closed
  - 6 → Pendiente de una tercera persona
  - 7 → Cerrada
  - -10 → Para todos excepto los cerrados
- Filtro de grupo: Id del grupo (obligatorio). 1 para todos.
- Filtro de prioridad: Id de la prioridad (opcional). Puede tener éstos valores:
  - 10 → Mantenimiento
  - 0 → Informativo
  - 1 → Bajo
  - 2 → Medio
  - 3 → Grave
  - 4 → Muy grave
  - -1 → Cualquiera
- Filtro de inventario: Id del inventario relacionado (opcional). 0 para todos o ninguno.
- Filtro de propietario: Id del usuario al que está asignada la incidencia (opcional).
- Filtro de creador: Id del usuario que ha creado la incidencia (opcional).
- Filtro de incidencia: Id de incidencia (opcional).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents&params=day,-10,1,-1,0,admin,usuario1

Resultado CSV

5,"2016-01-19 11:19:42","0000-00-00 00:00:00",Titulo incidencia,
admin,1,1,2,"2014-01-19 11:19:42",,1,0,0,,1,0,0,1,0,[email protected],
,0,"2014-01-20 14:45:01",,,,0,0,0,0,0,0,0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents&params=day,-10,1,-1,0,admin,usuario1&return_type=xml

Resultado XML

<xml version='1.0' encoding='UTF-8'>
  <incident>
     <id_incidencia><![CDATA[5]]></id_incidencia>
     <inicio><![CDATA[2016-01-19 11:19:42]]></inicio>
     <cierre><![CDATA[0000-00-00 00:00:00]]></cierre>
     <titulo><![CDATA[Titulo incidencia]]></titulo>
     <descripcion><![CDATA[Descripcion]]></descripcion>
     <id_usuario><![CDATA[admin]]></id_usuario>
     <estado><![CDATA[1]]></estado>
     <prioridad><![CDATA[1]]></prioridad>
     <id_grupo><![CDATA[2]]></id_grupo>
     <actualizacion><![CDATA[2016-01-19 11:19:42]]></actualizacion>
     <id_creator><![CDATA[]]></id_creator>
     <notify_email><![CDATA[1]]></notify_email>
     <id_task><![CDATA[0]]></id_task>
     <resolution><![CDATA[0]]></resolution>
     <epilog><![CDATA[]]></epilog>
     <id_parent><![CDATA[1]]></id_parent>
     <sla_disabled><![CDATA[0]]></sla_disabled>
     <affected_sla_id><![CDATA[0]]></affected_sla_id>
     <id_incident_type><![CDATA[1]]></id_incident_type>
     <score><![CDATA[0]]></score>
     <email_copy><![CDATA[[email protected]]]></email_copy>
     <editor><![CDATA[]]></editor>
     <id_group_creator><![CDATA[0]]></id_group_creator>
     <last_stat_check><![CDATA[2016-01-20 14:55:01]]></last_stat_check>
     <closed_by><![CDATA[]]></closed_by>
     <extra_data><![CDATA[]]></extra_data>
     <extra_data2><![CDATA[]]></extra_data2>
     <blocked><![CDATA[0]]></blocked>
     <old_status><![CDATA[0]]></old_status>
     <old_resolution><![CDATA[0]]></old_resolution>
     <old_status2><![CDATA[0]]></old_status2>
     <old_resolution2><![CDATA[0]]></old_resolution2>
     <workunits_hours><![CDATA[0]]></workunits_hours>
     <workunits_count><![CDATA[0]]></workunits_count>
  </incident>
</xml>

get_incident_details

Resultado: Devuelve los detalles de un ticket.
Parámetros:
- Id del ticket (obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_details&params=2

Resultado CSV

1,"2010-02-17 01:35:35","0000-00-00 00:00:00",Myfddfe,,demo,
1,1,3,3,"2010-02-17 01:50:05",user,1,0,0,,,0,0,0,0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_details&params=2&return_type=xml

Resultado XML

<xml>
       <id_incidencia>1</id_incidencia>
       <inicio>2010-02-17 01:35:35</inicio>
       <cierre>0000-00-00 00:00:00</cierre>
       <titulo>Myfddfe</titulo>
       <descripcion></descripcion>
       <id_usuario>demo</id_usuario>
       <origen>1</origen>
       <estado>1</estado>
       <prioridad>3</prioridad>
       <id_grupo>3</id_grupo>
       <actualizacion>2010-02-17 01:50:05</actualizacion>
       <id_creator>admin</id_creator>
       <notify_email>1</notify_email>
       <id_task>0</id_task>
       <resolution>0</resolution>
       <epilog></epilog>
       <id_parent></id_parent>
       <sla_disabled>0</sla_disabled>
       <affected_sla_id>0</affected_sla_id>
       <id_incident_type>0</id_incident_type>
       <score>0</score>
</xml>

create_incident

Resultado: Se crea un ticket.
User: Es el creador del ticket.
Parámetros:
- Título (Obligatorio). Títulos vacíos no están admitidos.
- Id del grupo (obligatorio).
- Prioridad (no obligatorio). Puede tener estos valores:
  - 10 → 0 Maintenance.
  - 0 → 1 Informative (por defecto):
  - 1 → 2 Low.
  - 2 → 3 Medium.
  - 3 → 4 Serious.
  - 4 → 5 Very serious.
- Descripción (no obligatorio). Vacío por defecto
- Id de inventario (no obligatorio). Se pueden crear incidencias con varios objetos de inventario. Tendrán que ir separados entre sí por :
- Id de tipo de incidencia (no obligatorio). 0 (ninguno) por defecto.
- Email en copia (no obligatorio): Por defecto vacío.
- Propietario (no obligatorio). Por defecto admin.
- Id ticket padre (no obligatorio). Por defecto, 0 (sin padre)
- Estado (obligatorio). Puede tomar los siguientes valores:
  - 1 → Nuevo (por defecto)
  - 2 → No confirmado
  - 3 → Asignado
  - 4 → Re-abierto
  - 5 → Pending to be closed
  - 6 → Pendiente de una tercera persona
  - 7 → Cerrada
- Info_extra(no obligatorio)
- Resolución
  - 0 → None (por defecto)
  - 1 → Fixed
  - 2 → Invalid
  - 3 → Won't fix
  - 4 → Duplicate
  - 5 → Works for me
  - 6 → Incomplete
  - 7 → Expired
  - 8 → Moved
  - 9 → In process
- Info_extra2 (no obligatorio)
- CampoTipoIncidencia1
- …
- CampoTipoIncidenciaN

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,
2,1,Descripcion%20de%20la%incidencia,1:2:3,1,[email protected],admin,0,1

Resultado CSV

0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=
api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,2,1,
Descripcion%20de%20la%incidencia,1:2:3,1,[email protected],admin,0&return_type=xml

Resultado XML

<xml>
   0
</xml>

update_incident

Resultado: Actualiza los datos de un ticket.
Parámetros:
- Id del ticket (obligatorio).
- Título (Obligatorio). Títulos vacíos no están admitidos.
- Descripción (no obligatorio). Vacío por defecto.
- Epílogo (no obligatorio). Vacío por defecto.
- Id del grupo (obligatorio).
- Prioridad (no obligatorio). Puede tener estos valores:
  - 10 → 0 Maintenance.
  - 0 → 1 Informative (por defecto):
  - 1 → 2 Low.
  - 2 → 3 Medium.
  - 3 → 4 Serious.
  - 4 → 5 Very serious.
- Resolución
  - 0 → None (por defecto)
  - 1 → Fixed
  - 2 → Invalid
  - 3 → Won't fix
  - 4 → Duplicate
  - 5 → Works for me
  - 6 → Incomplete
  - 7 → Expired
  - 8 → Moved
  - 9 → In process
- Estado (no obligatorio). Puede tomar los siguientes valores:
  - 1 → Nuevo (por defecto)
  - 2 → No confirmado
  - 3 → Asignado
  - 4 → Re-abierto
  - 5 → Pending to be closed
  - 6 → Pendiente de una tercera persona
  - 7 → Cerrada
- Propietario (no obligatorio). Por defecto admin.
- Id ticket padre (no obligatorio). Por defecto, 0 (sin padre).
- Id de tipo de incidencia (no obligatorio). 0 (ninguno) por defecto.
- Info_extra (no obligatorio)
- Info_extra2 (no obligatorio)
- Info_extra3 (no obligatorio)
- Info_extra4 (no obligatorio)
- CampoTipoIncidencia1
- …
- CampoTipoIncidenciaN

ADVERTENCIA: Si no se desea modificar el valor actual de los campos del tipo de ticket se deberán rellenar dichos campos con su valor correspondiente. En el caso de estar vacíos, se actualizarán sin valor.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=
update_incident&params=4,nuevo%20titulo,nueva%20descripcion,
nuevo%20epilogo,4,2,1,3,admin,0,6,,Soporte,Hardware

Resultado CSV

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=update_incident
&params=4,nuevo%20titulo,nueva%20descripcion,nuevo%20epilogo,4,2,1,1,3,
admin,0,6,Soporte,Hardware&return_type=xml

Resultado XML

<xml>
   0
</xml>

add_inventory_to_ticket

Resultado: Permite asociar un objeto de inventario a un ticket.
Parámetros:
- Id del ticket (obligatorio).
- Id del objeto de inventario (Obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=add_inventory_to_ticket&params=1,2

Resultado CSV

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=add_inventory_to_ticket&params=1,2&return_type=xml

Resultado XML

<xml>
   1
</xml>

delete_incident

Resultado: Se elimina un ticket.
Parámetros:
- Id del ticket (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user
&pass=api_pass&op=delete_incident&params=3

Resultado CSV

0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&pass=
api_pass&op=delete_incident&params=3&return_type=xml

Resultado XML

<xml>
   0
</xml>

get_incident_workunits

Resultado: Devuelve una lista con los workunits asociados a un ticket.
Parámetros:
- Id del ticket (Obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user
&user_pass=user_pass&pass=api_pass&op=get_incident_workunits&params=3

Resultado CSV

3,"2010-02-17 01:48:48",0.25,admin,"Workunit description",0,0,,1
2,"2010-02-17 01:47:41",0.25,admin,"Another workunit description",0,0,,1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=user_pass&
pass=api_pass&op=get_incident_workunits&params=3&return_type=xml

Resultado XML

<xml>
        <workunit>
                  <id>3</id>
                  <timestamp>2010-02-17 01:48:48</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
        <workunit>
                  <id>2</id>
                  <timestamp>2010-02-17 01:47:41</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Another workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
</xml>

create_workunit

Resultado: Crea un workunit en un ticket
Parámetros:
- Id del ticket (obligatorio).
- Descripción (no obligatorio). Por defecto, vacío
- Duración en horas (no obligatorio). Por defecto 0.00 horas
- Si ha tenido coste (no obligatorio). Por defecto no
- Si es publico o no (no obligatorio). Por defecto no.
- Id del perfil asociado (no obligatorio). Por defecto 0, sin perfil asociado.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1

Resultado CSV

0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1&return_type=xml

Resultado XML

<xml>
   0
</xml>

get_incident_files

Resultado: Devuelve una lista con los ficheros asociados a un ticket
Parámetros:
- Id del ticket (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=
&pass=api_pass&op=get_incident_files&params=1

Resultado CSV

1,1,0,0,admin,file1.php,"php example",764026
2,1,0,0,admin,file2.png,"png example",34026

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=
&pass=api_pass&op=get_incident_files&params=1&return_type=xml

Resultado XML

<xml>
   <file>
       <id_attachment>1</id_attachment>
       <id_incidencia>1</id_incidencia>
             <id_task>0</id_task>
             <id_kb>0</id_kb>
             <id_usuario>admin</id_usuario>
             <filename>file1.php</filename>
             <description>php example</description>
             <size>764026</size>
   </file>
   <file>
     <id_attachment>2</id_attachment>
     <id_incidencia>1</id_incidencia>
             <id_task>0</id_task>
             <id_kb>0</id_kb>
             <id_usuario>admin</id_usuario>
             <filename>file2.png</filename>
             <description>png example</description>
             <size>34026</size>
   </file>
</xml>

download_file

Resultado: Devuelve el contenido de un fichero como texto, en base64.
Parámetros:
- Id del fichero (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=download_file&params=32

Resultado CSV

[contenido del fichero en base64]

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents&params=day,-10,1&return_type=xml

Resultado XML

<xml>
   [contenido del fichero en base64]
</xml>

attach_file

Resultado: Añade un fichero a la lista de ficheros de un ticket
Parámetros:
- Id del ticket: (no obligatorio) 0 por defecto.
- Nombre del fichero: (no obligatorio).
- Tamaño del fichero en Bytes: (no obligatorio) por defecto 0.
- Descripción del fichero: (no obligatorio) por defecto vacío.
- Contenido del fichero en base 64 (no obligatorio) por defecto se crea con contenido vacío.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20ejemplo,aW50ZWdyaWEgcm9ja3M=

Resultado CSV

0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20ejemplo,aW50ZWdyaWEgcm9ja3M=&return_type=xml

Resultado XML

<xml>
   0
</xml>

delete_file

Resultado: Elimina un fichero de la lista de ficheros de un ticket
Parámetros:
- Id del fichero (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_file&params=32

Resultado CSV

0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_file&params=32&return_type=xml

Resultado XML

<xml>
   0
</xml>

create_user

Llamada usada para crear un usuario y asignarlo a un rol/grupo. (Para asignar más perfiles hay que usar una llamada diferente).

Resultado: Devuelve 1 si se crea correctamente, 0 si no.
Parámetros:
- Username: (obligatorio)
- Id del grupo: (obligatorio)
- Id del perfil: (obligatorio)
- Email: (no obligatorio). Por defecto vacío
- Password: (no obligatorio). Por defecto es el nombre del usuario
- Descripción: (no obligatorio). Por defecto vacío.
- Nombre Real: (no obligatorio). Por defecto vacío.
- Externaluser: (no obligatorio). Por defecto 0.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_user&params=jorge,3,4,[email protected],
userpass,description,Jorge%20Apellido,1

Resultado CSV

1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&
op=create_user&params=jorge,3,4,[email protected],userpass,description,
Jorge%20Apellido,1&return_type=xml

Resultado XML

<xml>
   1
</xml>

validate_user

Resultado: Devuelve 1 si la autenticación es correcta, 0 si no
Parámetros:
- User: Username del usuario que se quiere validar (obligatorio).
- Pass: Contraseña para el usuario(obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=
userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass

Resultado CSV

1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=
userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass
&return_type=xml

Resultado XML

<xml>
   1
</xml>

delete_user

Llamada usada para borrar un usuario. admin no puede ser borrado a través de la API.

Devuelve: Devuelve 1 si se borra correctamente, 0 si no.
Parámetros
- Usuario: (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_user&params=pepe

Resultado CSV

1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_user&params=pepe&return_type=xml

Resultado XML

<xml>
   1
</xml>

user_exists

Llamada usada para verificar si un usuario existe.

Resultado: Devuelve 1 si existe, 0 si no.
Parámetros
- Usuario: (obligatorio)

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=user_exists&params=pepe

Resultado CSV

1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=user_exists&params=pepe&return_type=xml

Resultado XML

<xml>
   1
</xml>

create_lead

Llamada usada para crear un lead.

Resultado: Devuelve 1 si se crea correctamente, 0 si no.
Parámetros:
- Nombre completo: (obligatorio)
- Compañía: (obligatorio)
- Email (obligatorio)
- País: (no obligatorio) Por defecto vacío.
- Venta estimada: (no obligatorio) 0 por defecto.
- Progreso: En tanto por ciento (no obligatorio). Por defecto 0%
- Teléfono: (no obligatorio). Por defecto, vacío
- Teléfono móvil: (no obligatorio). Por defecto, vacío
- Posición: (no obligatorio). Por defecto vacío.
- Propietario: Nombre del usuario (obligatorio).
- Idioma: Código de idioma (obligatorio).
  - de → Deutch
  - en_GB → English
  - es → Español
  - fr → Français
  - pl → Polski
  - ru → Русский
  - zh_CN → 简化字
- Comentarios: (no obligatorio). Por defecto vacío.
- Id de categoría: (no obligatorio). Por defecto 0 (ninguna).
- Dirigido por: (no obligatorio). Por defecto 0.
- Campaña: (no obligatorio). Por defecto 0.
- Separador de tags: (obligatorio si se van a añadir varios tags).
- Nombres de tags: Divididos con el separador declarado anteriormente. Si los tags no existen, no se almacenarán.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,
[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,
This%20comment%20is%20very%20important,1,0,7,-%7C-,Software-%7C-
Hardware-%7C-Tag%20con%20espacios

Resultado CSV

1

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,
[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,This%20comment
%20is%20very%20important,1,0,7,-%7C-,Software-%7C-Hardware-%7C-
Tag%20con%20espacios&return_type=xml

Resultado XML

<xml>
   1
</xml>

get_last_invoice_id

Llamada usada para obtener el último ID de factura.

Resultado: Devuelve el último ID de factura, vacío si no.
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_invoice_id

Resultado CSV

140601_0082

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_last_invoice_id&return_type=xml

Resultado XML

<xml>
 <last_invoice_id>
  <id><![CDATA[140601_0082]]></id>
 </last_invoice_id>
</xml>

get_invoice

Llamada para obtener la información de una factura.

Devuelve: Devuelve la información de la factura, vacío en caso contrario.
Parámetros:
- ID de la factura: Es el valor del campo Bill ID (obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_invoice&params=140601_0071

Resultado CSV

2,admin,,1,140601_0071,ads,,,,,222.00,0.00,0.00,0.00,0.00,0.00,
EUR,,0,0,,2014-01-24,0000-00-00,pending,,,Submitted,en_GB

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_invoice&params=140601_0071&return_type=xml

Resultado XML

<xml>
 <invoice>
  <id><![CDATA[2]]></id>
  <id_user><![CDATA[admin]]></id_user>
  <id_task><![CDATA[]]></id_task>
  <id_company><![CDATA[1]]></id_company>
  <bill_id><![CDATA[140601_0071]]></bill_id>
  <concept1><![CDATA[ads]]></concept1>
  <concept2><![CDATA[]]></concept2>
  <concept3><![CDATA[]]></concept3>
  <concept4><![CDATA[]]></concept4>
  <concept5><![CDATA[]]></concept5>
  <amount1><![CDATA[222.00]]></amount1>
  <amount2><![CDATA[0.00]]></amount2>
  <amount3><![CDATA[0.00]]></amount3>
  <amount4><![CDATA[0.00]]></amount4>
  <amount5><![CDATA[0.00]]></amount5>
  <tax><![CDATA[0.00]]></tax>
  <currency><![CDATA[EUR]]></currency>
  <description><![CDATA[]]></description>
  <id_attachment><![CDATA[0]]></id_attachment>
  <locked><![CDATA[0]]></locked>
  <locked_id_user><![CDATA[]]></locked_id_user>
  <invoice_create_date><![CDATA[2014-01-24]]></invoice_create_date>
  <invoice_payment_date><![CDATA[0000-00-00]]></invoice_payment_date>
  <status><![CDATA[pending]]></status>
  <reference><![CDATA[]]></reference>
  <internal_note><![CDATA[]]></internal_note>
  <invoice_type><![CDATA[Submitted]]></invoice_type>
  <id_language><![CDATA[en_GB]]></id_language>
 </invoice>
</xml>

create_invoice

Llamada para crear una factura.

Resultado: Devuelve dos valores, el código de estado (1 si se realizo la operación, 0 si se detecto un fallo) y un mensaje con el resultado de la operación.
Parámetros:
- Id del usuario: (debe existir o vacío)
- Id tarea: (no obligatorio). 0 por defecto.
- Id compañía: (obligatorio).
- Id factura: (obligatorio).
- Concepto: (obligatorio).
- Cantidad: (obligatorio).
- Impuestos: Porcentaje de impuestos (no obligatorio). Por defecto 0.
- Moneda: Cadena de texto (obligatorio).
- Descripción: (no obligatorio). Por defecto vacío.
- Flag bloqueado: Booleano (no obligatorio). Por defecto 0 (no bloqueado).
- Id usuario bloqueador: (obligatorio si flag bloqueado está activo). Por defecto vacío
- Fecha de creación: (no obligatorio). Por defecto el día actual.
- Fecha de pago: (no obligatorio). Por defecto el día actual.
- Estado (no obligatorio). Por defecto pendiente
- Referencia (no obligatorio). Por defecto vacío.
- Nota interna (no obligatorio). Por defecto vacío.
- Tipo de factura (obligatorio: Submitted o Received).
- Id idioma: (no obligatorio).
  - de → Deutch
  - en_GB → English (por defecto)
  - es → Español
  - fr → Français
  - pl → Polski
  - ru → Русский
  - zh_CN → 简化字

Llamada con resultado en CSV sin errores

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&pass=1234&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,
,EUR,,,,,,paid,,,Submitted,

Resultado CSV sin errores

1,"invoice created"

Resultado CSV con errores

0,"invalid billing id"

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,,EUR,
,,,,,paid,,,Submitted,&return_type=xml

Resultado XML sin erroes

<xml>
 <invoice>
  <status><![CDATA[1]]></status>
  <error><![CDATA[invoice created]]></error>
 </invoice>
</xml>

Resultado XML con errores

<xml>
 <invoice>
  <status><![CDATA[0]]></status>
  <error><![CDATA[invalid billing id]]></error>
 </invoice>
</xml>

create_company

Resultado: Devuelve el id de la compañía creada
Parámetros:
- Nombre: (obligatorio)
- Dirección: (no obligatorio). Por defecto vacío.
- Identificación fiscal: (no obligatorio). Por defecto vacío.
- Id del rol de compañía: (no obligatorio). Por defecto 0 (ningún rol).
- País: (no obligatorio). Por defecto, vacío.
- Manager: Nombre del usuario que se encarga de la compañía (debe existir o ponerlo vacío)
- Id de la compañía padre: (no necesario). Por defecto 0.

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,Pais,admin,0

Resultado CSV

6

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,
Pais,admin,0&return_type=xml

Resultado XML

<xml>
 <company>
  <id><![CDATA[6]]></id>
 </company>
</xml>

add_address_to_newsletter

Resultado: Devuelve el id de la dirección de correo creada. Si falla, devuelve un 0.
Parámetros:
- Id newsletter: (obligatorio y debe de existir)
- Nombre: (obligatorio).
- Email: (obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
integria&op=add_address_to_newsletter&params=2,juan,[email protected]

Resultado

10

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
integria&op=add_address_to_newsletter&params=2,juan,[email protected]&return_type=xml

Resultado XML

<xml>
   10
</xml>

get_incident_tracking

Resultado: Devuelve una lista con el tracking de un ticket
Parámetros:
- Id del ticket (obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_tracking&params=2

Resultado CSV

9,2,0,"2010-02-17 01:56:33",demo,0,Created
10,2,2,"2010-02-17 02:06:58",demo,0,"Workunit added"

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_tracking&params=2&return_type=xml

Resultado XML

<xml>
   <tracking>
               <id_it>9</id_it>
               <id_incident>2</id_incident>
               <state>0</state>
               <timestamp>2010-02-17 01:56:33</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Created</description>
   </tracking>
   <tracking>
               <id_it>10</id_it>
               <id_incident>2</id_incident>
               <state>2</state>
               <timestamp>2010-02-17 02:06:58</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Workunit added</description>
   </tracking>
</xml>

get_incidents_resolutions

Resultado: Devuelve una lista con los identificadores y nombres de las resoluciones de los tickets de Integria
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_resolutions

Resultado CSV

1,Fixed
2,Invalid
3,"Wont fix"

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_resolutions&return_type=xml

Resultado XML

<xml>
       <resolution>
               <id>1</id>
               <name>Fixed</name>
       </resolution>
       <resolution>
               <id>2</id>
               <name>Invalid</name>
       </resolution>
       <resolution>
               <id>3</id>
               <name>Wont fix</name>
       </resolution>
</xml>

get_incidents_status

Resultado: Devuelve una lista con los identificadores y nombres de los estados de los tickets de Integria
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_status

Resultado CSV

1,New
2,Unconfirmed
3,Assigned

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incidents_status&return_type=xml

Resultado XML

<xml>
       <status>
               <id>1</id>
               <name>New</name>
       </status>
       <status>
               <id>2</id>
               <name>Unconfirmed</name>
       </status>
       <status>
               <id>3</id>
               <name>Assigned</name>
       </status>
</xml>

get_incident_priorities

Resultado: Devuelve una lista con los identificadores y nombres de las prioridades de los tickets de Integria
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_priorities

Resultado CSV

10,Mantenimiento
0,Informativo
1,Bajo
2,Medio
3,Grave
4,Muy grave

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_priorities&return_type=xml

Resultado XML

<xml>
       <priority>
               <id>10</id>
               <name>Mantenimiento</name>
       </priority>
       <priority>
               <id>0</id>
               <name>Informativo</name>
       </priority>
       <priority>
               <id>1</id>
               <name>Bajo</name>
       </priority>
       <priority>
               <id>2</id>
               <name>Medio</name>
       </priority>
       <priority>
               <id>3</id>
               <name>Grave</name>
       </priority>
       <priority>
               <id>4</id>
               <name>Muy grave</name>
       </priority>
</xml>

get_types

Resultado: Devuelve una lista con los tipos de tickets disponibles en Integria.
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_types

Resultado CSV

1,Tipo 1
2,Tipo 2
3,Tipo 3

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_types&return_type=xml

Resultado XML

<xml>
       <status>
               <id>1</id>
               <name>Tipo 1</name>
       </status>
       <status>
               <id>2</id>
               <name>Tipo 2</name>
       </status>
       <status>
               <id>3</id>
               <name>Tipo 3</name>
       </status>
</xml>

get_incident_fields

Resultado: Devuelve los campos personalizados de un tipo de ticket dado. Si además se especifica un id de ticket, se devolverán sus valores.
Parámetros:
- Id del tipo de ticket (obligatorio).
- Id del ticket (opcional).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_fields&params=4,32

Resultado CSV

cHJvYmFuZG8mI3gyMDtsaXN0YQ==,8,8,4,4,"probando lista","probando lista",text,text,,,1,1,,,0,0,,,1,1,"prueba de contenido",0

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_fields&params=4,32&return_type=xml

Resultado XML

<xml>
   <field>
       <label_enco>cHJvYmFuZG8mI3gyMDtsaXN0YQ==</label_enco>
       <id>8</id>
       <id_incident_type>4</id_incident_type>
       <label>probando lista</label>
       <type>text</type>
       <combo_value></combo_value>
       <show_in_list>1</show_in_list>
       <parent>0</parent>
       <linked_value></linked_value>
       <order>1</order>
       <data>prueba de contenido</data>
       <blocked>0</blocked>
  </field>
</xml>

get_groups

Resultado: Devuelve una lista con los identificadores y nombres de los grupos de Integria
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_groups

Resultado CSV

2,"Customer #A"
3,"Customer #B"
4,Engineering

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_groups&return_type=xml

Resultado XML

<xml>
       <group>
               <id>1</id>
               <name>"Customer #A"</name>
       </group>
       <group>
               <id>2</id>
               <name>"Customer #B"</name>
       </group>
       <group>
               <id>3</id>
               <name>Engineering</name>
       </group>
</xml>

get_users

Resultado: Devuelve una lista con los usuarios sobre los que tiene visibilidad el usuario que hace la llamada
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_users

Resultado CSV

usuario1
usuario2
usuario3

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incidents&params=day,-10,1&return_type=xml

Resultado XML

<xml>
   <id_user>usuario1</id_user>
   <id_user>usuario2</id_user>
   <id_user>usuario3</id_user>
</xml>

get_stats

Resultado: Devuelve un valor correspondiente con la consulta realizada.
Parámetros: Espera los siguientes parámetros: metric, string, status, id_user, id_group, id_company, id_product and id_inventory.
- metric: Métrica de valores estadísticos, pueden ser los siguientes:
  - total_incidents: Número total de tickets (limitado por el número máximo de tickets de Integria).
  - opened: Número total de tickets abiertos.
  - closed: Número total de tickets cerrados.
  - avg_life: Vida media de los tickets en segundos.
  - sla_compliance: Porcentaje de cumplimiento de la SLA.
  - avg_scoring: Puntuación media de los tickets de 0 a 10.
  - avg_worktime: Tiempo medio de trabajo en el ticket en segundos.
- string: String para filtrar la búsqueda de tickets
- status: String con valores separados por comas, puede tomar valores entre 1 y 7. (Por defecto 1,2,3,4,5,6,7)
- id_user: Filtrado por usuario. (Por defecto “”).
- id_group: Filtrado por grupo. (Por defecto 1).
- id_company: Filtrado por compañía. (Por defecto 0).
- id_inventory: Filtrado por inventario. (Por defecto 0).
- priority: String con valores separados por comas, puede tomar los valores 0 (Informativo), 1 (Bajo), 2 (Medio), 3 (Grave), 4 (Muy grave) y 10 (Mantenimiento). (Por defecto, todos)

Llamada con resultado en CSV

Obtener % SLA

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=sla_compliance

Obtener total de tickets abiertas con estado NUEVO (codigo 1), en cualquier grupo:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=opened,,1

Obtener el total de tickets abiertos (cualquier estado, en cualquier grupo)

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=opened

Resultado CSV

1,"Sample inventory object"
2,"Another inventory"
3,Thirdventory

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_stats&params=sla_compliance&return_type=xml

Resultado XML

<xml>
   97
</xml>

get_inventories

Resultado: Devuelve una lista con los identificadores y nombres de los inventarios de Integria
Parámetros: -

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_inventories

Resultado CSV

1,"Sample inventory object"
2,"Another inventory"
3,Thirdventory

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_inventories&return_type=xml

Resultado XML

<xml>
   <inventory>
       <id>1</id>
       <name>Sample inventory object</name>
   </inventory>
   <inventory>
       <id>2</id>
       <name>Another inventory</name>
   </inventory>
   <inventory>
       <id>3</id>
       <name>Thirdventory</name>
   </inventory>
</xml>

get_user_exists_in_group

Resultado: Devuelve 1 si el usuario dado existe en el grupo dado. 0 en caso contrario
Parámetros serializados:
- id_usuario
- id_grupo

get_incident_inventories

Resultado: Devuelve una lista con objetos de inventario asociados a un ticket.
Parámetros serializados:
- Filtro de ticket: Id del ticket (obligatorio).

Llamada con resultado en CSV

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_inventories&params=10

Resultado CSV

2,1,admin,Cenutrio,0,Sancho&#039;s&#x20;computer,0,0,0,0,0000-00-00,new,2013-08-19,0000-00-00
5,3,admin,InventarioCSV,1,descripcion,0,0,0,1,2017-08-02,new,2016-10-09,2017-10-09

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_inventories&params=10&return_type=xml

Resultado XML

<xml version='1.0' encoding='UTF-8'>
  <inventory>
     <id><![CDATA[2]]></id>
     <id_object_type><![CDATA[1]]></id_object_type>
     <owner><![CDATA[admin]]></owner>
     <name><![CDATA[Cenutrio]]></name>
     <public><![CDATA[0]]></public>
     <description><![CDATA[Sancho&#039;s&#x20;computer]]></description>
     <id_contract><![CDATA[0]]></id_contract>
     <id_manufacturer><![CDATA[0]]></id_manufacturer>
     <id_parent><![CDATA[0]]></id_parent>
     <show_list><![CDATA[0]]></show_list>
     <last_update><![CDATA[0000-00-00]]></last_update>
     <status><![CDATA[new]]></status>
     <receipt_date><![CDATA[2013-08-19]]></receipt_date>
     <issue_date><![CDATA[0000-00-00]]></issue_date>
  </inventory>
</xml>

get_last_cron_execution

Resultado: Devuelve el tiempo que ha pasado en minutos desde la última ejecución del Crontask.
Parámetros: -

Llamada

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_cron_execution

Resultado

3

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_cron_execution&return_type=xml

Resultado XML

<xml>
   <cronjob>
               <last_exec>3</last_exec>
   </cronjob>
</xml>

get_num_queued_emails

Resultado: Devuelve el número de emails que están en cola pendientes de ser enviados.
Parámetros: -

Llamada

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_num_queued_emails

Resultado

20

Llamada con resultado en XML

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_num_queued_emails&return_type=xml

Resultado XML

<xml>
   <pending_email>
               <num>20</num>
   </pending_email>
</xml>

Extensión del API

Para desarrollar nuevas llamadas para el API tiene que tener en cuenta que:

La llamada tiene que estar inscrita como una función en el fichero <instalación Integria>/include/functions_api.php, además de estar contemplada en entre las funciones válidas en el archivo <instalación Integria>/include/api.php.
La función debe devolver un único valor o un array de pares por ejemplo nombre-valor.
El formateo del resultado de la llamada a XML o CSV se realiza en el archivo api.php de forma automática.

Ejemplos de funciones para el API

Ejemplo de función que devuelve un único valor

Definición en el archivo functions_api.php:

function host_risk ($host_name) {
   
   $host_id = get_hosts_id($host_name);

   //If there is not a host with this name return false
   if (!$host_id) {
       return false;
   }
   
   $risk = return_last_risk_agent($host_id);   
   
   return $risk;
}

Llamada en el archivo api.php:

switch ($op) {

       ...
    
   case "host_risk":
       if (isset($params['0'])) {
           $result = host_risk ($params['0']);
       } else {
           $result = false;
       }
       break;

      ...
}

Ejemplo de función que devuelve una lista de valores

Definición en el archivo functions_api.php:

function all_host_risk() {
   
   //Get all host  
   $hosts = get_hosts();

   //Check if there is host or not
   if (empty($hosts)) {
       return false;
   }
   
   $result = array();
   foreach ($hosts as $host) {
       $host_name = get_host_name($host['id']);
       $risk = return_last_risk_agent($host['id']);     
       
       $aux = array();
       
       $aux['name'] = $host_name;
       $aux['data'] = $risk;

       array_push($result, $aux);
   }
   
   return $result;
}

Llamada en el archivo api.php:

switch ($op) {

       ...

   case "all_host_risk":
       $result = all_host_risk ();
       break;

       ...

 }

Herramientas de usuario

Tabla de Contenidos

12. API de Integria IMS

API externa de Integria

Seguridad

Autenticación por IP válida

Autenticación por contraseña

Autenticación por usuario y contraseña de usuario (login)

Funciones del API

Retorno de información sobre Integria IMS

get_incidents

get_incident_details

create_incident

update_incident

add_inventory_to_ticket

delete_incident

get_incident_workunits

create_workunit

get_incident_files

download_file

attach_file

delete_file

create_user

validate_user

delete_user

user_exists

create_lead

get_last_invoice_id

get_invoice

create_invoice

add_address_to_newsletter

get_incident_tracking

get_incidents_resolutions

get_incidents_status

get_incident_priorities

get_types

get_incident_fields

get_groups

get_users

get_stats

get_inventories

get_user_exists_in_group

get_incident_inventories

get_last_cron_execution

get_num_queued_emails

Extensión del API

Ejemplos de funciones para el API

Herramientas de la página

Herramientas del sitio