0221 669 669 66

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.

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.

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

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"
}
WertBeschreibung
sidNeue, noch nicht authentifizierte Session-ID
statusok - 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"
}
WertBeschreibung
sidZu authentifizierende Session-ID.
usernameDer Benutzername Ihres fonial-Kundenkontos.
passwortDas Passwort Ihres fonial-Kundenkontos.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
  "authenticated": true,
}
WertBeschreibung
sidVerwendete Session-ID.
statusok - Der Request wurde korrekt gestellt. Details sind dem Feld "error" zu entnehmen.
error - Der Request wurde falsch oder unvollständig gestellt.
authenticatedtrue - 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",
}
WertBeschreibung
sidAuthentifizierte Session-ID.
deviceDie ID des IP-Endgerätes des Benutzers. Die ID der Endgeräte kann über die Methode /devices/get abgerufen werden.
targetDie Zielrufnummer des Anrufes im e164-Format.

Response-Body

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

WertBeschreibung
sidVerwendete Session-ID.
statusok - 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"
}
WertBeschreibung
sidAuthentifizierte 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
    },
    
  ] 
}
WertBeschreibung
sidVerwendete 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"
}
WertBeschreibung
sidAuthentifizierte Session-ID.

Response-Body

{
  "sid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ok",
    "numbers": [
    {
      "number": "+4922166966966",
      "id": 21
    },
    {
      "number": "+4922166966999",
      "id": 276
    },
    
  ] 
}
WertBeschreibung
sidVerwendete 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"
}
WertBeschreibung
sidAuthentifizierte Session-ID.
startZeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert den Anfang des auszugebenden Einzelverbindungsnachweises.
endZeitstempel (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"
    }
    
  ]
}
WertBeschreibung
sidVerwendete 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"
}
WertBeschreibung
sidAuthentifizierte Session-ID.
startZeitstempel (Format YYYY-MM-DD HH:MM:SS), markiert den Anfang der auszugebenden Verbindungsliste.
endZeitstempel (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"
    }
    
  ]
}
WertBeschreibung
sidVerwendete 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