Introduction

Temps estimé :6 minutes

Protocole de communication

Les APIs de PBXware fonctionnent via le protocole HTTP (Hypertext Transfer Protocol). Elle utilise les méthodes GET et POST seulement pour envoyer et recevoir des données entre les applications tierces et PBXware.

Authentification

Pour garantir la sécurité, les APIs utilisent une clé API unique pour chaque utilisateur ou application tierce. Cette clé est essentielle pour authentifier les requêtes envoyées à PBXware.

Pour les requêtes POST et GET l’authentification se fait en “API Key” :

le champs “Key” aura la mention “apikey”

la clé au format “6vs6gwd6fv6x84…” sera dans le champ “Value”.

Par défaut, la clé API n’est pas définie. Cependant, vous pouvez en créer une dans les paramètres d’administration de PBXware.

La clé API doit avoir une taille minimale de 32 caractères aléatoires. Il est également possible de générer une clé aléatoire directement depuis l’interface de PBXware.

Sur le PBXware il est possible de mettre des restrictions (ACL) aux fonctionnalités auxquelles les APIs peuvent accéder.

Il est crucial de garder la clé API secrète, car elle donne accès à des fonctionnalités sensibles, telles que la suppression de données, à des tiers.

Requêtes

Les requêtes vers les APIs de PBXware contiennent plusieurs éléments, dont la clé API et l’action souhaitée. Par exemple, pour récupérer la liste des numéros SDA (Sélection directe à l’Arrivée) la requête ressemblerait à ceci :

				
					GET /?apikey=votre.clé.api&action=pbxware.did.list HTTP/1.0
Host: pbxware.local
User-Agent: Mozilla/5.0

GET https://[PBXware name].bicomsystems.fr/?action=pbxware.did.list&server=2&ext=100&apikey=[clé API secrète]

Dans cet exemple, “pbxware.did.list” est l’action demandée, qui récupère la liste des numéros DID à partir de PBXware.

GET = c’est la requête pour récupérer les informations souhaitées.

https://[PBX name].bicomsystems.fr/ = en https on met l’ip ou l’URL du PBX

?action= on commence par dire que l’on va faire une action

pbxware. = début de chaque commande avant de spécifier l’action.

.did.list = did pour SDA et list pour avoir la liste des SDA disponible sur ce PBXware.

& = c’est pour ajouter des information nécessaires à votre recherche, comme ici le PBX est un multi-tenant et du coup il faut indiquer le numéro du tenant ou server = 2 car “le 1 est réservé pour le master”.

On peut ensuite affiner la recherche en fonction de l’extension ou du trunk etc… Voir les arguments possibles par actions dans la liste ci-dessous.

apikey= et enfin on finit par la Key (clé API).

Le sens de l’action et de l’apikey n’est pas immuable, vous pouvez mettre la clé api avant l’action et vice versa.

donc en résumé on fait une requête sur le server 2 et pour l’extension 100 de la liste des SDA qui lui sont attribués.

Réponses

Les réponses de l’API de PBXware sont généralement renvoyées au format JSON (JavaScript Object Notation), un format de données léger et facilement lisible. Voici un exemple de réponse JSON :

json :

				
					{

"7": {
"number": "12345",
"number2": "",
"server": "7",
"trunk": "6099",
"type": "Extension",
"ext": "530",
"status": "enabled"

}

"8": {
"number": "12346",
"number2": "",
"server": "7",
"trunk": "6099",
"type": "Extension",
"ext": "100",
"status": "enabled"

     }
}

Cette réponse contient des informations sur les numéros SDA disponibles dans le système PBXware.

Formats de réponse

L’API de PBXware prend en charge plusieurs formats de réponse, y compris JSON et PHP (sérialisé).

Pour tester l’API, plusieurs outils en ligne de commande sont disponibles, tels que curl (https://curl.se/), httpie (https://httpie.io/docs/cli/scripting) et curlish (https://pythonhosted.org/curlish/). Voici un exemple d’utilisation de httpie pour interroger l’API :

				
					http -b "http://votre.ipbx.fr/?apikey=votre.clé.api&action=pbxware.ext.list"

Gestion des Erreurs

En cas d’erreur, la réponse de l’API contiendra une clé “error” indiquant la nature de l’erreur. Toute opération ultérieure doit être interrompue si une erreur est détectée.

voir une liste exhaustive ici : https://restfulapi.net/http-status-codes/

sinon les plus commun sont :

200 OK; 302 Found; 400 Bad Request; 401 Unauthorized; 403 Forbidden…etc…

Actions API

L’argument principal qui contrôle l’API est l’argument “action”. Il est structuré en trois parties : application.objet.méthode

Dans le cas de PBXware, l’application est toujours “pbxware”.

application = pbxware (et rien d’autres)

.objet = voir liste exhaustives des objets

.méthode = voir sous les objets les méthodes possible

argument obligatoire = selon la méthode et le type de PBXware. (ie : &server=2)

En comprenant ces principes fondamentaux, les développeurs peuvent commencer à créer des applications et des intégrations personnalisées qui tirent pleinement parti des fonctionnalités de PBXware.

Tester les APIs

Introduction

Protocole de communication

Authentification

Requêtes

Réponses

Formats de réponse

Gestion des Erreurs

Actions API

Introduction

CONTENU