Znuny Web Services – REST API

Znuny Web Services – REST API

En esta guía detallada aprenderá cómo activar, configurar e integrar la Znuny REST API (parte del Generic Interface) en sus propias aplicaciones.

1. Arquitectura y principios básicos

Znuny pone a disposición su Generic Interface a través de servicios web REST y SOAP. La REST API se comunica mediante HTTP(S) con formato de datos JSON y permite:

• Gestión de tickets: Crear, obtener, modificar, eliminar.
• Gestión de artículos: Añadir artículos, gestionar adjuntos.
• Historial y búsqueda: Consultar el historial de tickets y realizar consultas de búsqueda complejas.

Nota importante: Una instalación estándar no contiene servicios web preconfigurados; estos deben crearse manualmente en el área de administración bajo „Procesos y Automatización → Web Services“.

2. Configuración

2.1 Activar el Generic Interface

1. Navegue en el área de administración a SysConfig → GenericInterface.Transport y seleccione REST (HTTP).
2. En AdminGenericInterfaceTransportHTTPREST configure los tiempos de espera (timeouts), el Host-Header y el nivel de depuración (Debug-Level).
3. En GenericInterface.Operation cree las operaciones deseadas (p. ej., TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) y actívelas.

2.2 URL base y autenticación

• URL base TicketCreate
• Autenticación
  • Cookies de sesión de Znuny
  • API-Keys / Token (configurables vía SysConfig)
  • ¡Utilice siempre HTTPS para transferencias seguras!

3. Endpoints y métodos HTTP (Resumen detallado)

Para cada endpoint encontrará aquí una representación detallada de los parámetros, posibles respuestas y ejemplos prácticos.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate Método: POST Descripción: Crea un nuevo ticket y genera simultáneamente un primer artículo.

Parámetro	Tipo	Obligatorio	Descripción
SessionID	Integer	Sí¹	Session-ID o UserLogin+Password
UserLogin	String	Sí²	Login del agente (en combinación con Password)
Password	String	Sí²	Contraseña (en combinación con UserLogin)
Ticket.Title	String	Sí	Asunto del ticket
Ticket.Queue	String	Sí	Nombre de la cola o Ticket.QueueID
Ticket.State	String	Sí	Estado inicial (p. ej., new)
Ticket.Priority	String	Sí	Prioridad (p. ej., 3 normal)
Ticket.CustomerUser	String	Sí	E-mail o login del cliente
Article.Subject	String	Sí	Asunto del primer artículo
Article.Body	String	Sí	Contenido del primer artículo
Article.MimeType	String	Sí	text/plain o text/html

¹ Se requiere SessionID O UserLogin+Password. ² Si no hay un token de SessionID disponible.

Ejemplo de Request: TicketSearch

Ejemplo de respuesta: TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Método: GET Descripción: Busca tickets basándose en diversos criterios de filtro.

Parámetro	Tipo	Obligatorio	Descripción
UserLogin, Password	String,String	Sí¹	Credenciales del agente o SessionID²
SessionID	Integer	Sí²	Token para sesiones autenticadas
Title	String/String[]	No	Búsqueda con comodines en el título (%Pedido%)
TicketNumber	String/String[]	No	Número(s) de ticket
QueueIDs	Integer[]	No	IDs de las colas
States	String[]	No	Estados (new, open, …)
StateType	String/String[]	No	Categoría Open/Closed
DynamicField_Name.Op	Mixed	No	Campos dinámicos con operador (Equals, Like, GreaterThan …)

¹ Se requiere UserLogin+Password O SessionID. ² Si no se transmite un par de login.

Ejemplo de Request: TicketUpdate

Ejemplo de respuesta: TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Método: GET Descripción: Obtiene datos detallados del ticket, incluyendo artículos, adjuntos y campos dinámicos.

Parámetro	Tipo	Obligatorio	Descripción
UserLogin, Password	String,String	Sí¹	Credenciales del agente o SessionID²
SessionID	Integer	Sí²	Token para sesiones autenticadas
TicketID	String/String[]	Sí	Uno o varios Ticket-IDs (separados por coma o array)
DynamicFields	Boolean (0/1)	No	1 = Campos dinámicos en el resultado, estándar = 0
Extended	Boolean	No	1 = Metadatos extendidos (p. ej., FirstResponse)
AllArticles	Boolean	No	1 = Devolver todos los artículos
ArticleLimit	Integer	No	Cantidad máx. de artículos devueltos
Attachments	Boolean	No	1 = Incrustar adjuntos en Base64
GetAttachmentContents	Boolean	No	1 = Cargar también el contenido de los adjuntos
HTMLBodyAsAttachment	Boolean	No	1 = Adjuntar versión HTML del artículo como adjunto

¹ Se requiere UserLogin+Password O SessionID. ² Si no se transmite un par de login.

Ejemplo de Request: TicketHistoryGet

Ejemplo de respuesta (abreviado): /Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Método: PUT Descripción: Actualiza campos de un ticket existente y puede crear opcionalmente un nuevo artículo.

Parámetro	Tipo	Obligatorio	Descripción
SessionID	Integer	Sí¹	Token o UserLogin+Password²
TicketID	Integer	Sí	ID del ticket a actualizar
Ticket.Title	String	No	Nuevo título
Ticket.State	String	No	Nuevo estado
Ticket.Owner	String/ID	No	Nuevo propietario
Ticket.PendingTime	Hash / Diff	No	Nuevo tiempo de espera (pending)
Article.Subject	String	No	Crea un nuevo artículo
Article.Body	String	No	Contenido del nuevo artículo
DynamicField…	Array	No	Actualizar campos dinámicos
Attachment…	Array	No	Añadir nuevos adjuntos

¹ Se requiere SessionID O UserLogin+Password. ² Si no hay un token de SessionID disponible.

Ejemplo de Request: POST

Ejemplo de respuesta: new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Método: DELETE Descripción: Elimina definitiva uno o varios tickets.

Parámetro	Tipo	Obligatorio	Descripción
SessionID	Integer	Sí¹	Token o UserLogin+Password²
TicketID	String/Array	Sí	Uno o varios Ticket-IDs

Ejemplo de Request: 3 normal

Ejemplo de respuesta: text/plain

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet Método: GET Descripción: Obtiene el historial de uno o varios tickets.

Parámetro	Tipo	Obligatorio	Descripción
SessionID	Integer	Sí¹	Token o UserLogin+Password²
TicketID	String/Array	Sí	Uno o varios Ticket-IDs

Ejemplo de Request: text/html

4. Extensión y personalización

4.1 Definición WADL

Definir nuevos recursos en el archivo WADL: /Webservice/<ServiceName>/TicketSearch

4.2 Importación YAML

Alternativamente, puede definir operaciones mediante YAML: GET

---

5. Manejo de errores y Logging

• Indicador de éxito: Success: 0|1
• Mensaje de error: ErrorMessage en el JSON
• Depuración: Establezca en el diálogo de transporte el Debug-Level en Debug → Las entradas de log serán visibles en la base de datos.

---

6. Casos de uso

Escenario	Descripción
Automatización entre sistemas	Crear tickets desde herramientas de monitoreo (Nagios, Zabbix)
Sincronización de datos	Actualizaciones por lotes de campos de ticket desde un CRM externo
Portales de autoservicio	Los clientes crean sus propios tickets vía REST
Aplicaciones móviles	Apps nativas iOS/Android se comunican vía REST

---

Conclusión

La Znuny REST API es flexible, eficiente y altamente extensible gracias al Generic Interface. Ya sea para una creación simple de tickets o una automatización de flujos de trabajo compleja, con unos pocos pasos en el área de administración y peticiones JSON estándar, podrá realizar integraciones fluidas en cualquier entorno de TI.

---

7. Cliente Python: pyznuny

Para desarrolladores de Python, está disponible el paquete oficial pyznuny, que encapsula toda la Znuny REST API en una biblioteca sencilla y tipada. No necesita formular peticiones HTTP manualmente; pyznuny se encarga de la autenticación, la gestión de sesiones y la serialización de todos los parámetros.

7.1 Instalación

pip install pyznuny

7.2 Inicio rápido

from pyznuny import ZnunyClient

client = ZnunyClient(
    url="https://znuny.example.com",
    username="admin",
    password="secreto"
)

# Crear ticket
ticket_id = client.ticket_create(
    title="Servidor no accesible",
    queue="Support",
    state="new",
    priority="3 normal",
    customer_user="cliente@example.com",
    article_subject="Informe inicial",
    article_body="El servidor no responde desde las 08:00 horas.",
    mime_type="text/plain"
)
print(f"Nuevo ticket creado: #{ticket_id}")

# Obtener ticket
ticket = client.ticket_get(ticket_id=ticket_id, all_articles=True)
print(ticket)

# Actualizar ticket
client.ticket_update(ticket_id=ticket_id, state="open", owner="max.muster")

7.3 Operaciones soportadas

Método	Descripción
ticket_create()	Crear nuevo ticket con primer artículo
ticket_get()	Obtener detalles del ticket incl. artículos y adjuntos
ticket_search()	Buscar tickets según filtros
ticket_update()	Actualizar campos, estado, propietario y artículos
ticket_delete()	Eliminar ticket definitivamente
ticket_history_get()	Cargar historial completo de un ticket

Nota: pyznuny está disponible en PyPI y es mantenido activamente por Softoft.

---

8. OpenTicketAI Runtime y Znuny-Connector

Quien no solo quiera utilizar la Znuny REST API, sino automatizarla de forma inteligente, apuesta por el OpenTicketAI Runtime – una plataforma de IA on-premise que clasifica, prioriza y redirige los tickets entrantes de forma totalmente automática.

8.1 Arquitectura del sistema

                            ┌─────────────────────────┐
  E-mails entrantes   ────► │   Znuny (Generic Interface / REST API)  │
                            └────────────┬────────────┘
                                         │  Webhook / Polling
                                         ▼
                            ┌─────────────────────────┐
                            │  OpenTicketAI Runtime   │
                            │  (Docker, On-Premise)   │
                            │  ┌───────────────────┐  │
                            │  │  Modelo IA (NLP)  │  │
                            │  └───────────────────┘  │
                            └────────────┬────────────┘
                                         │  otai-znuny-znuny Connector
                                         ▼
                            ┌─────────────────────────┐
                            │  Znuny REST API          │
                            │  TicketUpdate / Routing  │
                            └─────────────────────────┘

El Runtime se ejecuta completamente de forma local en su centro de datos – ningún dato de ticket abandona su infraestructura.

8.2 Instalación del Znuny-Connector

Instale la biblioteca central de OpenTicketAI junto con el paquete de conector específico para Znuny otai-znuny-znuny:

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Paquete	Función
open-ticket-ai	Núcleo de OpenTicketAI: orquestación, pipelines, config
otai-hf-local	Modelos de IA locales vía Hugging Face (On-Premise)
otai-znuny-znuny	Conector: lee y escribe tickets vía Znuny REST

8.3 Configuración

Cree un archivo config.yaml y conecte el Runtime con su instancia de Znuny:

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: "${ZNUNY_PASSWORD}"

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: "Unclassified"
  rules:
    - category: "Red"
      queue: "Infraestructura TI"
      priority: "4 high"
    - category: "Facturación"
      queue: "Contabilidad"
      priority: "3 normal"

8.4 Proceso de procesamiento automático de tickets

1. El ticket entra en Znuny (vía e-mail o REST TicketCreate)
2. El conector consulta mediante TicketSearch nuevos tickets en el intervalo configurado
3. El modelo de IA analiza el asunto y el texto del artículo con procesamiento de lenguaje natural (NLP)
4. Se determina el resultado de la clasificación (categoría, prioridad, cola sugerida)
5. TicketUpdate vía REST establece la cola, la prioridad y un artículo interno opcional
6. El ticket llega de forma totalmente automática al equipo correcto – sin triaje manual

8.5 Ventajas frente a la integración REST manual

Característica	Integración REST manual	OpenTicketAI + Connector
Clasificación	❌ Manual	✅ Totalmente automática (IA)
Protección de datos	✅ Local	✅ 100 % On-Premise
Enrutamiento basado en reglas	✅ Posible	✅ Incluido
Capacidad de aprendizaje	❌ Reglas rígidas	✅ Modelo entrenable
Esfuerzo de configuración	Alto	Bajo (YAML-Config)

Más información: Visite openticketai.com o contacte a Softoft para una demo personalizada.