API de Configuración 3CX

¿Qué es la API de Configuración?

La API de Configuración 3CX (XAPI), introducida en la Versión 20 de 3CX, ofrece una interfaz basada en REST que permite el control mediante programación de casi todos los aspectos de configuración dentro del sistema telefónico 3CX, replicando las capacidades a las que normalmente se accede a través de la consola de administración. Basada en los estándares OData y las especificaciones OpenAPI, esta API permite a los desarrolladores integrar, automatizar y personalizar el entorno 3CX de manera eficiente.

Principales Características de la API de Configuración

  • Administración Integral: Con terminales para administrar departamentos, usuarios, enrutamiento de llamadas, extensiones del sistema y otras configuraciones, la API permite a los usuarios realizar casi todas las acciones administrativas mediante programación. Desde verificar si un departamento existe hasta configurar espacios de aparcamiento compartidos, casi todos los elementos de 3CX pueden ser administrados a través de código.
  • Automatización: La API permite automatizar tareas administrativas comunes, como la creación de departamentos, la asignación de funciones a los usuarios y la gestión de extensiones. Esto reduce la necesidad de intervención manual en la consola de administración, ahorrando tiempo y minimizando la posibilidad de errores.
  • Integración: La API facilita la integración sin problemas del sistema telefónico 3CX con otras aplicaciones de negocio. Se puede usar para sincronizar datos de usuario, administrar departamentos, y configurar enrutamiento de llamadas para asegurar una interoperabilidad fluida entre 3CX y servicios externos. Integrando 3CX en flujos de trabajo más amplios, mejora la comunicación y productividad sin requerir sincronización manual.
  • Escalabilidad: Diseñada pensando en la escalabilidad, la API permite una administración eficaz de las configuraciones a medida que crecen las organizaciones, lo que facilita la ampliación de usuarios, departamentos y otras entidades sin una sobrecarga administrativa abrumadora.

Configurando la Integración API

Desde la Consola de Administración en el Cliente Web 3CX, vaya a Integraciones > API:

  1. Presione el botón + Agregar para crear una nueva aplicación cliente.
  2. Especifique el ID de Cliente (DN para acceder al punto de ruta, que también es necesario para la autorización).
  3. Si se utiliza el componente 'scope' de Configuración, marque la casilla Acceso a la API de Configuración 3CX para esta aplicación.
  4. Especifique el Departamento y el Rol para el Servicio Principal, para un nivel de acceso API apropiado.
  5. Después de crear correctamente una nueva instancia de API, recibirá una clave de API para sus aplicaciones de terceros. Esta clave solo se mostrará una vez, así que asegúrese de guardarla para utilizarla en el futuro.

¡Ya está! Ha completado con éxito la configuración del PBX.

Tenga en cuenta: Debe tener una licencia 8SC y superior IA para utilizar la API de configuración de 3CX.

Cómo Funciona

RESTful API

La API de Configuración 3CX es una API Web RESTful construida sobre el protocolo OData, ofreciendo puntos finales seguros y versátiles para administrar y configurar casi todos los aspectos del sistema 3CX. Esta API refleja la funcionalidad disponible en la consola de administración 3CX, permitiendo control mediante programación sobre administración de usuarios, configuración de departamentos, enrutamiento de llamadas, extensiones del sistema, y más. Todos los enlaces están diseñados para ser seguros y confiables, asegurando que no interfieran con las funciones centrales del PBX o comprometan la estabilidad del sistema.

Para más detalles, consulte la Especificación de Terminales API de Configuración 3CX.

Tokens de Autenticación

La API de Configuración admite dos tipos de tokens para un acceso seguro:

  • Tokens de Administración Multi-empresa: Habilite el acceso completo para administrar todos los departamentos y entidades a través del sistema 3CX, adecuado para administradores en ambientes multi-empresa.
  • Tokens de Usuario: Conceda un acceso limitado a las funciones asignadas al usuario y a los permisos departamentales, proporcionando un acceso controlado a tareas de configuración específicas.

JSON y OpenAPI

Con su especificación OpenAPI, el API de Configuración 3CX es compatible con varias herramientas de desarrollo, incluyendo Postman, para una integración directa. La API acepta peticiones y respuestas con formato JSON, facilitando a los desarrolladores trabajar y automatizar tareas de configuración.

Proceso de Autenticación

La API de Configuración 3CX soporta acceso seguro a través de dos tipos de tokens de autenticación: Tokens de Administración Multi-Empresa y Tokens de Usuario. Cada tipo de token provee diferentes niveles de acceso, permitiendo flexibilidad en la administración de permisos a través de varios roles y departamentos dentro del entorno 3CX.

Tokens

  • Especifique el Departamento y el Rol en los Ajustes de su Servicio Principal. Establecer una función como "Propietario del Sistema" o "Administrador del Sistema" otorgará derechos para todo el sistema. Otros roles tendrán los derechos correspondientes.
  • Cómo Obtenerlo:
  • Llame a la terminal /connect/token con una solicitud POST con el tipo MIME application/x-www-form-urlencoded.

El contenido de la solicitud debe ser:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Si la autenticación se realiza correctamente, se devolverá en la respuesta un token de acceso que podrá utilizarse para posteriores solicitudes a la API.

  • Validación del Token: El token es válido durante 60 minutos, transcurridos los cuales habrá que actualizarlo u obtenerlo de nuevo.

Utilizando los Tokens de Acceso

Una vez obtenido el token de acceso, inclúyalo en la cabecera Authorization de sus peticiones API como token Bearer:

Authorization: Bearer ACCESS_TOKEN

Prueba Rápida - Validación del Token de Autenticación

Para verificar rápidamente que su token es válido y que la conexión API se ha establecido correctamente, utilice el terminal "Prueba Rápida":

  • Terminal: GET /xapi/v1/Defs?$select=Id
  • Respuesta: Una respuesta 200 OK confirma autenticación válida, y las cabeceras contendrán la versión del sistema 3CX.

Notas Importantes

  • Expiración del Token: Todos los tokens de acceso caducan al cabo de una hora. Las aplicaciones deben gestionar la caducidad de los tokens volviendo a autenticarse o actualizando el token para mantener una conexión continua.
  • Seguridad: Maneje siempre los tokens de forma segura y evite exponerlos en código del lado del cliente o en ubicaciones de almacenamiento no seguras.

Ejemplo de Aplicación XAPI

Para obtener información detallada sobre cómo configurar una aplicación XAPI con la API de Configuración del PBX, consulte el repositorio de Github Tutorial XAPI, el ejemplo cubre la demostración de la funcionalidad básica y las llamadas a la API.

Ver También

Última Actualización

Este documento se actualizó por última vez el 23 de Abril de 2026

https://www.3cx.es/docs/configuracion-rest-api/