Configurazione API 3CX

Che cos'è l'API di configurazione?

L'API di configurazione  3CX (XAPI), introdotta nella V20 del 3CX, offre un'interfaccia basata su REST che consente il controllo programmatico di quasi tutti gli aspetti di configurazione del sistema telefonico 3CX, replicando le funzionalità tipicamente accessibili tramite la console di amministrazione. Basata sugli standard OData e sulle specifiche OpenAPI, questa API consente agli sviluppatori di integrare, automatizzare e personalizzare l'ambiente 3CX in modo efficiente.

Caratteristiche principali dell'API di configurazione

  • Gestione completa: Con endpoint per la gestione di reparti, utenti, instradamento delle chiamate, estensioni di sistema e altre configurazioni, l'API consente agli utenti di eseguire quasi tutte le azioni amministrative in modo programmatico. Dalla verifica dell'esistenza di un reparto alla configurazione di parcheggi condivisi, quasi ogni elemento di 3CX può essere gestito tramite codice.
  • Automazione: L'API consente di automatizzare le attività amministrative più comuni, come la creazione di reparti, l'assegnazione di ruoli utente e la gestione delle estensioni. Questo riduce la necessità di interventi manuali nella console di amministrazione, facendo risparmiare tempo e riducendo al minimo la possibilità di errori.
  • Integrazione: L'API facilita la perfetta integrazione del sistema telefonico 3CX con altre applicazioni aziendali. È possibile utilizzarla per sincronizzare i dati degli utenti, gestire i reparti e configurare l'instradamento delle chiamate per garantire un'interoperabilità senza problemi tra il 3CX e i servizi esterni. L'integrazione del 3CX in flussi di lavoro più ampi migliora la comunicazione e la produttività senza richiedere la sincronizzazione manuale.
  • Scalabilità: Progettata tenendo conto della scalabilità, l'API consente di gestire in modo efficiente le configurazioni in base alla crescita delle organizzazioni, permettendo una facile espansione di utenti, reparti e altre entità senza sovraccarichi amministrativi.

Configurare l'integrazione API

Dalla console amministrativa del 3CX Web Client, andare su Integrazioni > API:

  1. Premere il pulsante Aggiungi per creare una nuova applicazione client.
  2. Specificare l'ID cliente (DN per accedere al punto di instradamento, necessario anche per l'autorizzazione).
  3. Se si utilizza l'ambito di configurazione, selezionare la casella di controllo 3CX Configuration API Access for this application.
  4. Specificare Reparto e Ruolo per il Principale del servizio, per un livello di accesso API appropriato.
  5. Dopo aver creato con successo una nuova istanza API, si riceverà una chiave API per le applicazioni di terzi. Questa chiave verrà visualizzata solo una volta, quindi assicuratevi di salvarla per un uso futuro.

È tutto! La configurazione del PBX è stata completata con successo.

Nota: Per utilizzare l'API di configurazione 3CX è necessario disporre di una licenza 3CX AI o Plus 8SC o superiore.

Come funziona

RESTful API

L'API di configurazione 3CX è un'API Web RESTful costruita sul protocollo OData, che offre endpoint sicuri e versatili per gestire e configurare quasi ogni aspetto del sistema 3CX. Questa API rispecchia le funzionalità disponibili nella console di amministrazione 3CX, consentendo il controllo programmatico della gestione degli utenti, della configurazione dei reparti, dell'instradamento delle chiamate, delle estensioni del sistema e altro ancora. Tutti gli endpoint sono progettati per essere sicuri e affidabili, in modo da non interferire con le funzioni principali del PBX o compromettere la stabilità del sistema.

Per maggiori dettagli, consultare le specifiche degli endpoint dell'API di configurazione 3CX.

Token di autenticazione

L'API di configurazione supporta due tipi di token per l'accesso sicuro:

  • Token di amministrazione multiaziendale: Consentono l'accesso completo per gestire tutti i reparti e le entità del sistema 3CX, adatti agli amministratori di ambienti multiaziendali.
  • Token utente: Garantiscono un accesso limitato ai ruoli assegnati all'utente e ai permessi di reparto, fornendo un accesso controllato a compiti di configurazione specifici.

JSON e OpenAPI

Grazie alla specifica OpenAPI, l'API di configurazione 3CX è compatibile con vari strumenti di sviluppo, tra cui Postman, per un'integrazione semplice. L'API accetta richieste e risposte in formato JSON, rendendo più semplice per gli sviluppatori lavorare e automatizzare le attività di configurazione.

Processo di autenticazione

L'API di configurazione 3CX supporta un accesso sicuro attraverso due tipi di token di autenticazione: Token amministratore multiaziendale e Token utente. Ogni tipo di token fornisce diversi livelli di accesso, consentendo una certa flessibilità nella gestione dei permessi tra i vari ruoli e reparti dell'ambiente 3CX.

Tokens

  • Specificare il dipartimento e il ruolo nelle impostazioni del Service Principal. Impostando un ruolo come “Proprietario del sistema” o “Amministratore del sistema” si ottengono i diritti per tutto il sistema. Altri ruoli avranno diritti corrispondenti.
  • Come ottenerlo:
  • Chiamare l'endpoint /connect/token con una richiesta POST tipo MIME application/x-www-form-urlencoded.

Il corpo della richiesta deve contenere:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Quando l'autenticazione è andata a buon fine, nella risposta viene restituito un token di accesso, che può essere utilizzato per le richieste API successive.

  • Validità del token: Il token è valido per 60 minuti, dopodiché dovrà essere aggiornato o richiesto nuovamente.

Utilizzo dei token di accesso

Una volta ottenuto un token di accesso, includerlo nell'intestazione Authorization delle richieste API come token Bearer:

Authorization: Bearer ACCESS_TOKEN

Test rapido - Convalida dell'autenticazione con token

Per verificare rapidamente che il token sia valido e che la connessione API sia stata stabilita correttamente, utilizzare l'endpoint “Quick Test”:

  • Endpoint: GET /xapi/v1/Defs?$select=Id
  • Risposta: Una risposta 200 OK conferma la validità dell'autenticazione e le intestazioni conterranno la versione del sistema 3CX.

Note importanti

  • Scadenza del token: Tutti i token di accesso scadono dopo un'ora. Le applicazioni devono gestire la scadenza del token effettuando una nuova autenticazione o aggiornando il token per mantenere una connessione continua.
  • Sicurezza: Gestire sempre i token in modo sicuro ed evitare di esporli nel codice lato client o in luoghi di archiviazione non protetti.

Esempio di applicazione XAPI

Per informazioni dettagliate sulla configurazione di un'applicazione XAPI con l'API di configurazione del PBX, consultare il repository Github XAPI Tutorial. L'esempio copre le funzionalità di base e le chiamate API dimostrative.

Per saperne di più

Ultimo aggiornamento

Questo documento è stato aggiornato il 17 febbraio 2026

https://www.3cx.it/doc/configurazione-api-3cx/