OTOBO Web Services – REST API

OTOBO Web Services – REST API

En esta guía detallada aprenderá cómo activar, configurar e integrar la OTOBO REST API (parte de la Interfaz Genérica) en sus propias aplicaciones.

1. Arquitectura y fundamentos

OTOBO proporciona su Interfaz Genérica a través de Web Services REST y SOAP. La REST API se comunica vía HTTP(S)/JSON y permite:

• Operaciones de tickets: Crear, obtener, modificar, eliminar
• Operaciones de artículos: Publicar, gestionar adjuntos
• Historial y búsqueda: Historial de tickets y consultas de búsqueda complejas

Nota: Una instalación estándar no contiene Web Services preconfigurados; usted debe crearlos en el módulo de administración «Procesos y Automatización → Web Services».

2. Configuración

2.1 Activar la Interfaz Genérica

1. En el área de administración → SysConfig → GenericInterface.Transport cambiar a REST (HTTP).
2. En AdminGenericInterfaceTransportHTTPREST configurar los Timeouts, Host-Header y Debug-Level.
3. En GenericInterface.Operation crear y activar las operaciones deseadas (p. ej., TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet).

2.2 URL base y autenticación

• URL base

  https://SU-SERVIDOR/otobo/nph-genericinterface.pl/Webservice/<SuNombreDeServicio>/

• Autenticación

  • Cookies de sesión de OTOBO
  • API-Keys / Token (crear vía SysConfig)
  • ¡Usar siempre HTTPS!

3. Endpoints y métodos HTTP (detalle)

Para cada endpoint encontrará aquí una visión general 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 un artículo al mismo tiempo.

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:

POST /Webservice/MyConnectorREST/TicketCreate HTTP/1.1
Host: demo.otobo.org
Content-Type: application/json
X-API-Key: abc123

{
  "Data": {
    "SessionID":  42,
    "Ticket": {
      "Title":        "Nuevo pedido",
      "Queue":        "Sales",
      "State":        "new",
      "Priority":     "3 normal",
      "CustomerUser": "max.mustermann@example.com"
    },
    "Article": {
      "Subject":  "Consulta de compra – Producto XY",
      "Body":     "Solicito oferta de precio…",
      "MimeType": "text/plain"
    }
  }
}

Ejemplo de respuesta:

{
  "Success":      1,
  "ErrorMessage": "",
  "Data": {
    "TicketID":     "12345",
    "ArticleID":    "67890"
  }
}

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 cola
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 pasa un par de login.

Ejemplo de Request:

GET /Webservice/MyConnectorREST/TicketSearch?UserLogin=agent1&Password=secreto&Title=%25Pedido%25 HTTP/1.1
Host: demo.otobo.org

Ejemplo de respuesta:

{
  "Success": 1,
  "Data": {
    "TicketID": [1001,1005,1012]
  }
}

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Método: GET

Descripción: Devuelve 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, Default = 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 pasa un par de login.

Ejemplo de Request:

GET /Webservice/MyConnectorREST/TicketGet?SessionID=42&TicketID=12345&AllArticles=1&DynamicFields=1 HTTP/1.1
Host: demo.otobo.org

Ejemplo de respuesta (abreviado):

{
  "Success":1,
  "Data":{
    "Ticket":[{
      "TicketID":12345,
      "TicketNumber":"202501230001",
      "Title":"Nuevo pedido",
      "State":"open",
      "DynamicField":[{"Name":"Urgency","Value":"high"}],
      "Article":[{
        "ArticleID":67890,
        "Subject":"Consulta de compra…",
        "Body":"Solicito oferta de precio…",
        "Attachment":[{"Filename":"Oferta.pdf","Content":"JVBERi0x…="}]
      }]
    }]
  }
}

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Método: PUT

Descripción: Actualiza campos de un ticket existente y opcionalmente crea 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
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:

PUT /Webservice/MyConnectorREST/TicketUpdate HTTP/1.1
Host: demo.otobo.org
Content-Type: application/json
X-API-Key: abc123

{
  "Data":{
    "SessionID":42,
    "TicketID":12345,
    "Ticket":{ "State":"pending reminder","PendingTime":{"Diff":1440} },
    "Article":{ "Subject":"Recordatorio establecido","Body":"El ticket está siendo procesado." }
  }
}

Ejemplo de respuesta:

{ "Success":1, "ErrorMessage":"", "Data":{ "TicketID":12345, "ArticleID":67891 } }

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:

DELETE /Webservice/MyConnectorREST/TicketDelete?SessionID=42&TicketID=12345 HTTP/1.1
Host: demo.otobo.org

Ejemplo de respuesta:

{ "Success":1, "ErrorMessage":"", "Data":{} }

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:

GET /Webservice/MyConnectorREST/TicketHistoryGet?SessionID=42&TicketID=12345,

5. Extensión y personalización

5.1 Definición WADL

Nuevos recursos en GenericTicketConnectorREST.wadl:

<resource path="MyTest" id="MyTest">
    <method name="GET" id="GET_MyTest">
        <response status="200">
            <representation mediaType="application/json"/>
        </response>
    </method>
</resource>

5.2 Importación YAML

Alternativamente vía YAML en development/webservices/GenericTicketConnectorREST.yml:

Provider:
  Operation:
    MyTest:
      Description: "Operación de prueba"
      MappingInbound: { }
      MappingOutbound: { }
      Type: Test::Module
Transport:
  Config:
RouteOperationMapping:
  MyTest:
    RequestMethod: [ GET ]
    Route: /MyTest

---

6. Manejo de errores y Logging

• Indicador de éxito: Success: 0|1
• Mensaje de error: ErrorMessage en el JSON
• Debugging: Establezca en el diálogo de transporte Debug-Level en Debug → Entradas de log visibles en la DB

---

7. 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

---

8. Otros elementos de UI e integración

Clonar Web Service

Módulo de manejo de errores

Conclusión

La OTOBO REST API es flexible, eficiente y altamente extensible gracias a la Interfaz Genérica. Ya sea para la creación simple de tickets o para una automatización compleja de flujos de trabajo, con unos pocos clics en el Admin y peticiones JSON estándar, usted puede realizar integraciones fluidas en cualquier entorno de TI.

Python OTOBO Client Library

Un cliente de Python asíncrono para interactuar con la OTOBO REST API. Construido con httpx y pydantic para seguridad de tipos y facilidad de uso.

Características

• Asíncrono: Peticiones HTTP usando httpx.AsyncClient

• Pydantic: Modelos para la validación de datos de petición y respuesta

• Operaciones CRUD completas para tickets:

  • TicketCreate
  • TicketSearch
  • TicketGet
  • TicketUpdate
  • TicketHistoryGet

• Manejo de errores: vía OTOBOError para errores de la API

• Método de utilidad search_and_get para combinar resultados de búsqueda con recuperación detallada

Instalación

Instalar desde PyPI:

pip install otobo

Inicio rápido

Configurar Web Services de OTOBO:

Cree un nuevo Web Service en OTOBO con la siguiente configuración:

---
Debugger:
  DebugThreshold: debug
  TestMode: '0'
Description: ''
FrameworkVersion: 11.0.5
Provider:
  Operation:
    session-create:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Session::SessionCreate
    ticket-create:
      Description: ''
      IncludeTicketData: '1'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketCreate
    ticket-get:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Config:
          KeyMapDefault:
            MapTo: ''
            MapType: Keep
          ValueMapDefault:
            MapTo: ''
            MapType: Keep
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketGet
    ticket-history-get:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketHistoryGet
    ticket-search:
      Description: ''
      IncludeTicketData: '0'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketSearch
    ticket-update:
      Description: ''
      IncludeTicketData: '1'
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Ticket::TicketUpdate
  Transport:
    Config:
      AdditionalHeaders: ~
      KeepAlive: '1'
      MaxLength: '16000'
      RouteOperationMapping:
        session-create:
          RequestMethod:
            - HEAD
            - OPTIONS
            - PATCH
            - POST
            - PUT
          Route: /session
        ticket-create:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket
        ticket-get:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/get
        ticket-history-get:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/history
        ticket-search:
          RequestMethod:
            - HEAD
            - OPTIONS
            - POST
          Route: /ticket/search
        ticket-update:
          RequestMethod:
            - HEAD
            - OPTIONS
            - PATCH
            - PUT
          Route: /ticket
    Type: HTTP::REST
RemoteSystem: ''
Requester:
  Transport:
    Type: HTTP::REST

Crear un nuevo agente

Cree un nuevo agente de OTOBO con una contraseña segura y asígnele los permisos necesarios para la tarea que desea realizar.

1. Configurar el cliente

from otobo import TicketOperation, OTOBOClientConfig
from otobo import AuthData

config = OTOBOClientConfig(
    base_url="https://your-otobo-server/nph-genericinterface.pl",
    service="OTOBO",
    auth=AuthData(UserLogin="user1", Password="SecurePassword"),
    operations={
        TicketOperation.CREATE.value: "ticket",
        TicketOperation.SEARCH.value: "ticket/search",
        TicketOperation.GET.value: "ticket/get",
        TicketOperation.UPDATE.value: "ticket",
        TicketOperation.HISTORY_GET.value: "ticket/history",
    }
)

2. Inicializar el cliente

import logging
from otobo import OTOBOClient

logging.basicConfig(level=logging.INFO)


client = OTOBOClient(config)

3. Crear un ticket

from otobo import (TicketOperation, OTOBOClientConfig, AuthData, TicketSearchParams, TicketCreateParams,
                   TicketHistoryParams, TicketUpdateParams, \
                   TicketGetParams, OTOBOClient, OTOBOTicketCreateResponse)

payload = TicketCreateParams(
    Ticket={
        "Title": "Nuevo pedido",
        "Queue": "Sales",
        "State": "new",
        "Priority": "3 normal",
        "CustomerUser": "customer@example.com"
    },
    Article={
        "Subject": "Consulta de producto",
        "Body": "Por favor, envíen detalles de precios...",
        "MimeType": "text/plain"
    }
)

response: OTOBOTicketCreateResponse = await client.create_ticket(payload)
print(response.TicketID, response.TicketNumber)

4. Buscar y recuperar tickets

from otobo import TicketSearchParams, TicketGetParams

search_params = TicketSearchParams(Title="%Pedido%")
search_res = await client.search_tickets(search_params)
ids = search_res.TicketID

for ticket_id in ids:
    get_params = TicketGetParams(TicketID=ticket_id, AllArticles=1)
    details = await client.get_ticket(get_params)
    print(details.Ticket[0])

5. Actualizar un ticket

from otobo import TicketUpdateParams

update_params = TicketUpdateParams(
    TicketID=response.TicketID,
    Ticket={"State": "closed"}
)
await client.update_ticket(update_params)

6. Obtener historial del ticket

from otobo import TicketHistoryParams

history_params = TicketHistoryParams(TicketID=str(response.TicketID))
history_res = await client.get_ticket_history(history_params)
print(history_res.History)

7. Búsqueda y obtención combinada

from otobo import FullTicketSearchResponse

full_res: FullTicketSearchResponse = await client.search_and_get(search_params)

Licencia

MIT © Softoft, Tobias A. Bueck