Volver al blog
Tickets

Guía de Integración API - Tickets

Guia de integración de sistemas externos para envío y consulta de tickets.

4 de noviembre de 2026

Esta documentación técnica describe cómo integrar el envío y consulta de tickets e incidencias desde sistemas externos (formularios web propios, aplicaciones de terceros o plataformas CRM) mediante peticiones HTTP seguras.

1. Obtención del Token Público y Autenticación

Cómo obtener el token en el sistema

Para obtener el token de acceso público necesario para realizar la integración, realice el siguiente procedimiento:

  1. Ingrese a la plataforma con su cuenta autorizada.
  2. Navegue al módulo de Tickets / Incidencias.
  3. Seleccione la opción de Configuración.
  4. En este apartado encontrará la sección con la información de acceso público, donde podrá visualizar y copiar su token (public_token).

Método de Autenticación

El acceso a todos los endpoints públicos utiliza un Bearer Token enviado en el encabezado HTTP Authorization.

  • Formato del Header:
Authorization: Bearer <TU_PUBLIC_TOKEN>
  Content-Type: application/json

Nota de Seguridad: Si detecta uso indebido o tráfico no deseado, el token puede regenerarse desde el apartado de Configuración. Al hacerlo, la clave anterior quedará invalidada inmediatamente.

2. Endpoints Previos Recomendados (Consulta de Catálogos)

Para crear una incidencia es necesario especificar un ID de Producto/Servicio (simpleipbxincidenceproductid) y un ID de Área (simpleipbxcustomerareaid). La API dispone de dos endpoints públicos para consultar estos listados antes de presentar el formulario al usuario final.

2.1. Consultar Productos / Servicios Disponibles

Retorna la lista de categorías o productos habilitados para el reporte de incidencias.

  • Método: POST
  • URL: https://<TUDOMINIO>/simpleipbxApiRest/simpleipbxincidence_products/getAllPublic
  • Headers:
  • Authorization: Bearer <TUPUBLICTOKEN>
  • Content-Type: application/json

Respuesta Exitosa (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Soporte Técnico",
      "description": "Problemas con hardware o software"
    },
    {
      "id": 2,
      "name": "Facturación",
      "description": "Consultas sobre cobros y pagos"
    }
  ],
  "error": null,
  "meta": null
}

2.2. Consultar Áreas Disponibles

Retorna la lista de áreas o departamentos disponibles para la asignación de la incidencia.

  • Método: POST
  • URL: https://<TUDOMINIO>/simpleipbxApiRest/simpleipbxcustomer_areas/getAllPublic
  • Headers:
  • Authorization: Bearer <TUPUBLICTOKEN>
  • Content-Type: application/json

Respuesta Exitosa (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 2,
      "name": "Ventas",
      "description": "Ventas"
    },
    {
      "id": 3,
      "name": "Soporte",
      "description": "Soporte"
    },
    {
      "id": 4,
      "name": "Recuperación de Cartera",
      "description": "Recuperación de cartera."
    }
  ],
  "error": null,
  "meta": null
}

3. Creación de Incidencias

Una vez obtenidos los identificadores de producto y área, se realiza el registro de la incidencia.

  • Método: POST
  • URL: https://<TUDOMINIO>/simpleipbxApiRest/simpleipbxincidences/createPublic
  • Headers:
  • Authorization: Bearer <TUPUBLICTOKEN>
  • Content-Type: application/json

Parámetros de la Petición (JSON Payload)

CampoTipoRequeridoDescripción
simpleipbxincidenceproduct_idnumberSíID del producto/servicio (campo id obtenido en el listado de productos).
descriptionstringSíDetalle explicativo de la situación o requerimiento.
customer_emailstringSíCorreo electrónico del usuario final que reporta la incidencia.
simpleipbxcustomerarea_idnumberNoID del área seleccionada (campo id obtenido en el listado de áreas). (Opcional si su organización maneja distribución manual).
attachments[]arrayNoLista de adjuntos asociados (opcional).

Ejemplo de Request Body

{
  "simpleipbx_incidence_product_id": 3,
  "description": "El sistema no permite ingresar desde el navegador Firefox.",
  "customer_email": "usuario@example.com",
  "simpleipbx_customer_area_id": 7,
  "attachments[]": []
}

Respuesta Exitosa (201 Created)

{
  "success": true,
  "data": {
    "simpleipbx_incidence_id": 128,
    "tracking_code": "INC-128",
    "simpleipbx_incidence_product_id": 1,
    "description": "El sistema no permite ingresar desde el navegador Firefox.",
    "customer_type": "externo",
    "customer_email": "usuario@example.com",
    "status": "created",
    "priority": "medium",
    "simpleipbx_customer_area_id": 3,
    "created_at": "2026-08-27 05:00:00"
  }
}

4. Consulta de Incidencia por Código (Tracking Code)

Permite consultar el estado actual de un ticket, sus detalles y el historial de intervenciones o respuestas registradas utilizando el código de seguimiento (tracking_code).

  • Método: POST
  • URL: https://<TUDOMINIO>/simpleipbxApiRest/simpleipbxincidences/getByIdPublic
  • Headers:
  • Authorization: Bearer <TUPUBLICTOKEN>
  • Content-Type: application/json

Parámetros de la Petición (JSON Payload)

CampoTipoRequeridoDescripción
idstringSíCódigo de seguimiento amigable generado al crear la incidencia (ej. "INC-70").

Ejemplo de Request Body

{
  "id": "INC-70"
}

Respuesta Exitosa (200 OK)

{
  "success": true,
  "data": [
    {
      "tracking_code": "INC-70",
      "product": {
        "id": 7,
        "name": "Software",
        "description": "Venta del servicio de Software"
      },
      "area": {
        "id": 20,
        "name": "Operaciones",
        "description": "Área principal creada por defecto para la gestión general."
      },
      "attachments": [],
      "status": "closed",
      "priority": "low",
      "interventions": [
        {
          "id": 56,
          "description": "Respuesta enviada por el equipo de soporte...",
          "type_intervening": "agente",
          "intervening_user": "",
          "timestamp": "2026-10-01 15:03:14"
        },
        {
          "id": 50,
          "description": "Nota interna o respuesta de seguimiento",
          "type_intervening": "agente",
          "intervening_user": "",
          "timestamp": "2026-09-30 09:54:45"
        }
      ],
      "timestamp": "2026-09-21 20:11:57"
    }
  ],
  "error": null,
  "meta": {
    "timestamp": "2026-10-28T23:55:27Z",
    "api_version": "1.0.0"
  }
}

Snippets

cURL

curl -X POST "https://<TU_DOMINIO>/simpleipbxApiRest/simpleipbx_incidences/createPublic" \
  -H "Authorization: Bearer TU_PUBLIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "simpleipbx_incidence_product_id": 1,
    "description": "El sistema no permite ingresar desde el navegador Firefox.",
    "customer_email": "usuario@example.com",
    "simpleipbx_customer_area_id": 3,
    "attachments[]": []
  }'

JavaScript (Fetch API)

const publicToken = "TU_PUBLIC_TOKEN";
const endpoint = "https://<TU_DOMINIO>/simpleipbxApiRest/simpleipbx_incidences/createPublic";

const payload = {
  simpleipbx_incidence_product_id: 1,
  description: "El sistema no permite ingresar desde el navegador Firefox.",
  customer_email: "usuario@example.com",
  simpleipbx_customer_area_id: 3,
  "attachments[]": []
};

fetch(endpoint, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${publicToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log("Número de ticket generado:", data.data.tracking_code);
    } else {
      console.error("Error en la solicitud:", data.message);
    }
  })
  .catch(error => console.error("Error de conexión:", error));

PHP (cURL)

<?php

$publicToken = 'TU_PUBLIC_TOKEN';
$url = 'https://<TU_DOMINIO>/simpleipbxApiRest/simpleipbx_incidences/createPublic';

$payload = json_encode([
    'simpleipbx_incidence_product_id' => 1,
    'description' => 'El sistema no permite ingresar desde el navegador Firefox.',
    'customer_email' => 'usuario@example.com',
    'simpleipbx_customer_area_id' => 3,
    'attachments[]' => []
]);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $publicToken,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 201 && !empty($result['success'])) {
    echo "Ticket registrado exitosamente. Código de seguimiento: " . $result['data']['tracking_code'];
} else {
    echo "Error (" . $httpCode . "): " . ($result['message'] ?? 'Error al procesar la solicitud');
}

Errores Frecuentes

  • 400 Bad Request (AUTHINVALIDTOKEN): Header Authorization ausente o malformado.
  • 400 Bad Request (VALREQUIREDFIELD): Faltan campos requeridos en la estructura del JSON.
  • 403 Forbidden (UNAUTHORIZED / AUTH_INVALID): Token no válido o cliente inactivo.
  • 404 Not Found (NOT_FOUND): El ID de producto, ID de área o código de seguimiento no existen en el sistema.
  • 500 Internal Server Error (SYSINTERNALERROR): Excepción o error inesperado del servidor.