API-Dokumentation

Die API ermöglicht dem Kunden Zugriff auf bestimmte Funktionen der fonial-Telefonanlage. Die API basiert auf HTTP und erwartet POST-Requests. Parameter werden im JSON-Format übergeben.

Authentifizierung

Die Authentifizierung erfolgt mittels Benutzernamen und Passwort Ihres Hauptbenutzers im fonial-Kundenkonto. Bitte beachten Sie, dass die API für Ihr Benutzerkonto freigeschaltet werden muss. Wenden Sie sich dazu bitte an unseren Support.

Version

Die aktuelle API-Version ist 2.0. Daraus ergibt sich die folgende Basis-URL für den Zugriff auf die API: https://kundenkonto.fonial.de/api/2.0

Die in den Methoden beschriebenen Pfade müssen an diese URL angehangen werden. Beispiel: Abruf einer Session-ID: kundenkonto.fonial.de/api/2.0/session

Methoden

POST/ session

Diese Methode generiert eine unauthentifizierte Session-ID, die in allen zukünftigen Requests dieser Session übergeben werden muss.

Request-Body

{}

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok"
}

Wert	Beschreibung
sid	Neue, noch nicht authentifizierte Session-ID
status	ok - Der Request wurde korrekt gestellt error - Der Request wurde falsch oder unvollständig gestellt. Details sind dem Feld "error" zu entnehmen.

POST /session/authenticate

Diese Methode authentifiziert die übergebene Session gegen ein fonial-Hauptbenutzerkonto.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "info@fonial.de",
  "password": "xxxxxxxxxxx"
}

Wert	Beschreibung
sid	Zu authentifizierende Session-ID.
username	Der Benutzername Ihres fonial-Kundenkontos.
passwort	Das Passwort Ihres fonial-Kundenkontos.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
  "authenticated": true,
}

Wert	Beschreibung
sid	Verwendete Session-ID.
status	ok - Der Request wurde korrekt gestellt. Details sind dem Feld "error" zu entnehmen. error - Der Request wurde falsch oder unvollständig gestellt.
authenticated	true - Authentifizierung war erfolgreich, mit der Session-Id können nun Operationen auf der API durchgeführt werden. false - Die Authentifizierung ist fehlgeschlagen.

POST /call/initiate

Diese Methode ermöglicht es einen Anruf mittels Callback-Verfahren auszulösen. Beim Callback wird zunächst das IP-Endgerät des Benutzers angerufen. Nimmt der Benutzer den Anruf entgegen, wird das Ziel angerufen und verbunden. Ausgehend wird die im Ziel hinterlegte Rufnummer angezeigt.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "device": 1234,
  "target": "+4922166966966",
}

Wert	Beschreibung
sid	Authentifizierte Session-ID.
device	Die ID des IP-Endgerätes des Benutzers. Die ID der Endgeräte kann über die Methode /devices/get abgerufen werden.
target	Die Zielrufnummer des Anrufes im e164-Format.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
}

Wert	Beschreibung
sid	Verwendete Session-ID.
status	ok - Der Request wurde korrekt gestellt error - Die Requests wurde falsch oder unvollständig gestellt. Details sind dem Feld "error" zu entnehmen.

POST /devices/get

Diese Methode listet alle verfügbaren IP-Endgeräte eines Benutzerkontos mit deren ID auf. Die ID wird u.a. benötigt, um einen Anruf mittels Callback-Verfahren aufzubauen.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Wert	Beschreibung
sid	Authentifizierte Session-ID.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
    "devices": [
    {
      "name": "Telefon Martin Mustermann",
      "id": 23
    },
    {
      "name": "Telefon Bettina Beispiel",
      "id": 674
    },
    
  ] 
}

Wert

Beschreibung

sid

Verwendete Session-ID.

status

ok - Der Request wurde korrekt gestellt.
error - Der Request wurde falsch oder unvollständig gestellt. Details sind dem Feld "error" zu entnehmen.

device

Die Liste der IP-Endgeräte

name - Im Kundenkonto vergebener Name des IP-Endgeräts.
id - Die ID des IP-Endgeräts.

POST /numbers/get

Diese Methode listet alle verfügbaren Rufnummern eines Benutzerkontos mit deren ID auf.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Wert	Beschreibung
sid	Authentifizierte Session-ID.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
    "numbers": [
    {
      "number": "+4922166966966",
      "id": 21
    },
    {
      "number": "+4922166966999",
      "id": 276
    },
    
  ] 
}

Wert

Beschreibung

sid

Verwendete Session-ID.

status

ok - Der Request wurde korrekt erstellt.
error - Der Request wurde falsch oder unvollständig gestellt. Details sind im Feld "error" zu entnehmen.

numbers

Die Liste der Rufnummern

number - Rufnummer im e164-Format.
id - Die ID der Rufnummer.

POST /evn/get

Diese Methode ermöglicht den Aufruf des Einzelverbindungsnachweises des jeweiligen Benutzerkontos in einer anzugebenden Zeitspanne.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "start": "2016-08-01 10:00:00",
  "end": "2016-08-01 11:00:00"
}

Wert	Beschreibung
sid	Authentifizierte Session-ID.
start	Zeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert den Anfang des auszugebenden Einzelverbindungsnachweises.
end	Zeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert das Ende des auszugebenden Einzelverbindungsnachweises.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
  "evn": [
    {
      "from": "+4922166966966",
      "to": "+4922111223344",
      "destination": "Deutschland (Festnetz)",
      "dateStart": "2016-08-01 10:15:16",
      "dateEnd": "2016-08-01 10:25:23",
      "duration": 667,
      "costs": "0.1000",
      "sipuser": "fo212345ip12345_00",
      "target": "Telefon Empfang"
    }
    
  ]
}

Wert

Beschreibung

sid

Verwendete Session-ID.

status

ok - Der Request wurde korrekt ausgestellt.
error - Der Request wurde falsch oder unvollständig gestellt. Details sind dem Feld "error" zu entnehmen.

evn

Liste der ausgehenden Anrufe in dem angegebenen Zeitraum

from - Ausgehende Rufnummer
to - Angerufene Rufnummer
destination - Zielnetz des Anrufes
dateStart - Beginn des Anrufes
dateEnd - Ende des Anrufes
duration - Dauer des Anrufes in Sekunden
costs - Für den Anruf entstandene Gebühren

POST /journal/get

Diese Methode ermöglicht den Aufruf der eingehenden Verbindungen des jeweiligen Benutzerkontos in einer anzugebenden Zeitspanne.

Request-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "start": "2016-08-01 10:00:00",
  "end": "2016-08-01 11:00:00"
}

Wert	Beschreibung
sid	Authentifizierte Session-ID.
start	Zeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert den Anfang der auszugebenden Verbindungsliste.
end	Zeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert das Ende der auszugebenden Verbindungsliste.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
  "journal": [
    {
      "date": "2017-01-01 12:00:00
      "from": "+4922166966966",
      "to": "+4922111223344",
      "status": "TAKEN"
    }
    
  ]
}

Wert

Beschreibung

sid

Verwendete Session-ID.

status

ok - Der Request wurde korrekt ausgestellt.
error - Der Request wurde falsch oder unvollständig gestellt. Details sind dem Feld "error" zu entnehmen.

journal

Liste der ausgehenden Anrufe in dem angegebenen Zeitraum

from - Ausgehende Rufnummer
to - Angerufene Rufnummer
date - Datum / Uhrzeit des Anrufes
status - Anrufstatus

Das Werte im Feld "status" haben die folgenden Bedeutungen:

TAKEN - Anruf angenommen
TAKEN-EXTERNAL - Anruf auf einem externen Weiterleitungsziel angenommen
MISSED - Anruf verpasst
MAILBOX - Anruf wurde auf Mailbox weitergeleitet