PROFI Telefonanlage Schnittstellen

API Dokumentation

Einleitung

Dieser Artikel beschreibt die Funktionen der Placetel API . Die API bietet Zugriff auf grundlegende Placetel-Funktionen. Der Placetel API Key steht in der Anwendung unter Stammdaten -> Einstellungen -> API zur Verfügung.

Rahmenbedingungen

Dieses Kapitel definiert die wichtigsten Rahmenbedingungen über den Zugriff auf die Placetel API.

  • Zugriff auf die API Funktionen erhalten Sie mit einem sog. API Key. Dieser Key wird Ihnen nach der Freischaltung der API per Mail zugesendet.
  • Die API erlaubt 180 Request in 180 Sekunden. Jede zusätzliche Anfrage wird als Flooding verstanden und resultiert einem Ablehnen des Verbindungsaufbaus für die nächsten 5 Minuten .
  • Der Zugriff muss über HTTPS erfolgen.
  • Parameter werden nur per POST entgegengenommen.
  • Bei höheren Anforderungen kontaktieren Sie den Placetel Service.

Technische Informationen

Zugriffswerte Erlaubte Werte Beschreibung
API Endpunkt api.placetel.de URL zum Zugriff auf die API
Protokoll HTTPS Zugang zur API erfolgt über HTTPS
Parameter POST Parameter werden nur über POST angenommen
api_key Eigener kundenindividueller Schlüssel Der API Key wird von Placetel zur Verfügung gestellt

Sie versenden ein Kommando an die Placetel API per HTTPS und POST an den entsprechenden API-Endpunkt.

Die Placetel-Antwort besteht aus einer HTML/XML/JSON Struktur mit den gewünschten Daten.

Request-Art Ergebnis Beschreibung
https://api.placetel.de/test HTML Ergebnisse werden als HTML / Plain Text formatiert ausgegeben
https://api.placetel.de/test.xml XML Ergebnisse werden als XML formatiert ausgegeben
https://api.placetel.de/test.json JSON Ergebnisse werden als JSON ausgegeben

API Funktionen

Test

Testet die Verbindung zur Placetel API. Der api_key wird hier geprüft.

Parameter Erlaubte Werte Beschreibung
URL /api/test
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
Beispiel:
Anfrage:
curl https://api.placetel.de/api/test.xml -d api_key=xyz....
Antwort:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<result>1</result>
<result-code>success</result-code>
<descr>test login successful</descr>
</hash>

getNumbers

Gibt eine Liste aller aktiven Rufnummern im betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getNumbers
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getNumbers.xml -d api_key=xyz....

Antwort:
<detail>
<pstn-name type="NilClass" nil="true"></pstn-name>
<pstn-number type="NilClass">022123434384</pstn-number>
<pstn-numonly type="NilClass">23434384</pstn-numonly>
<pstn-prefix type="NilClass">0221</pstn-prefix>
</detail>

getVoIPUsers

Gibt eine Liste aller VoIP Benutzer im betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getVoIPUsers
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
name z.B. Peter Test Name des VoIP Benutzers
stype - 1 /3 = Standard VoIP Benutzertyp
- 2 = BLF
- 7 = FAX
- 8 = TRUNK
Uid z.B. 7772323232@sip.finotel.com SIP URI des Benutzers
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getVoIPUsers.xml -d api_key=xyz....

Antwort:
<sip-user>
<name>Fax</name>
<stype type="integer">7</stype>
<uid type="NilClass">772347324@sip.finotel.com</uid>
<uid2 type="NilClass" nil="true"></uid2>
</sip-user>

getPrompts

Gibt eine Liste aller Voice-Prompts (Ansagen) im betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getPrompts
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
id z.B. 1,2,1102, … Eindeutige ID der Ansage
name z.B. Testansage Name der Ansage
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getPrompts.xml -d api_key=xyz....

Antwort:
<prompt>
<id type="integer">10613</id>
<name>Ansage Test 12</name>
</prompt></details>

getContacts

Gibt eine Liste aller Kontakte im betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getContacts
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
s.u. Werte siehe Beispiel
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getContacts.xml -d api_key=xyz....

Antwort:
<contact>
<company-name type="NilClass"></company-name>
<contact-number1 type="NilClass">02212238238</contact-number1>
<contact-number2 type="NilClass">01712323823</contact-number2>
<contact-number3 type="NilClass">089348348</contact-number3>
<contact-number4 type="NilClass">01513448348</contact-number4>
<contact-number5 type="NilClass" nil="true"></contact-number5>
<first-name type="NilClass">Peter</first-name>
<last-name type="NilClass">Tester</last-name>
</contact>

getIncomingCallsByDay

Gibt eine Liste aller eingegangenen Anrufe pro Tag für das betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getIncomingCallsByDay
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
year z.B. 2012 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
month z.B. 5 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
day z.B. 2 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
callType - 1 = Voicemail
- 2 = Verpasster Anruf
- 3 = Blockierter Anruf
- 4 = Angenommener Anruf
- 5 = Fax
s.u. Werte siehe Beispiel
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getIncomingCallsByDay.xml -d api_key=xyz.... -d month=4 -d day=2

Antwort:
<message>
<callType type="integer">2</callType>
<fileName></fileName>
<fromNumber>022123823833</fromNumber>
<received-at type="datetime">2012-04-02T08:10:50Z</received-at>
<toNumber>022129191999</toNumber>
</message>

getCDRsByDay

Gibt eine Liste aller Anrufe des Einzelverbindungsnachweises pro Tag für das betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getCDRsByDay
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
year z.B. 2012 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
month z.B. 5 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
day z.B. 2 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
s.u. Werte siehe Beispiel
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getCDRsByDay.xml -d api_key=xyz.... -d month=4 -d day=2

Antwort:
<billing-record>
<amount type="float">0.155</amount>
<descr>placetel_profi / Germany Mobile - SIP Dialout </descr>
<from>77723234234</from>
<length type="integer">4</length>
<to>01517334734</to>
<when-date type="datetime">2012-04-02T08:40:25Z</when-date>
</billing-record>

getRoutingPlans

Gibt eine Liste aller Routingpläne für das betreffenden Placetel Benutzerkonto aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getRoutingPlans
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
id z.B. 1,2,1012,… Eindeutige ID des Routingplans
name z.B. Testplan Name des Routingplans
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getRoutingPlans.xml -d api_key=xyz....

Antwort:
<routing-plan>
<id type="integer">1</id>
<name>Testplan</name>
</routing-plan>

getRouting

Gibt eine Liste der Routingeinstellungen für die betreffende Placetel Rufnummern aus.

Parameter Erlaubte Werte Beschreibung
URL /api/getRoutingPlans
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
number z.B. 0221123456 Placetel Rufnummer für die das Routing bestimmt werden soll
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
id z.B. 1,2,1012,… Eindeutige ID des Routingplans
routing - 1 = Weiterleitung
- 2 = Fax
- 3 = Routingplan
- 5 = IVR
- 6 = Konferenz
- 7 = T38 Fax
- 8 = Warteschlange
- 9 = Eigene Applikation
- 10 = Gruppe
routing-setting - 1 = Direkte Weiterleitung
- 3 = Weiterleitung auf Mailbox
- 4 = Ansage abspielen und auflegen (forward-voice-prompt-id)
- 5 = Ansage abspielen und weiterleiten (forward-voice-prompt-id)
voice-prompt-id z.B. 1,2,… ID der Ansage (siehe getPrompts)
forward-voice-prompt-id z.B. 1,2,… ID der Ansage (siehe getPrompts)
target1 … target5 z.B. - 77723823@sip.finotel.com - Eins oder mehrere Ziele für die Weiterleitung der Rufnummer
oder
- 77723823@sip.finotel.com - Wenn mehrere Ziele parallel klingeln sind diese durch Komma getrennt.
- 022123823@pstn - Ziele im Telefonnetz enden auf @pstn
ringing-time1 … ringing-time5 z.B. 5,10,20,…. Klingelzeit pro Ziel
routing-plan z.B. 1,2,23,233,… deutige ID des aktiven Routingplan (siehe getRoutingplans)
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getRouting.xml -d api_key=xyz.... -d number=0221123456

Antwort:
<detail>
<forward-voice-prompt-id type="NilClass">12</forward-voice-prompt-id>
<ringing-time1 type="NilClass">40</ringing-time1>
<ringing-time2 type="NilClass">10</ringing-time2>
<ringing-time3 type="NilClass">120</ringing-time3>
<ringing-time4 type="NilClass">60</ringing-time4>
<ringing-time5 type="NilClass">60</ringing-time5>
<routing type="NilClass">1</routing>
<routing-plan type="NilClass">2</routing-plan>
<routing-setting type="NilClass">1</routing-setting>
<target1 type="NilClass">77701223445@sip.finotel.com</target1>
<target2 type="NilClass"></target2>
<target3 type="NilClass"></target3>
<target4 type="NilClass"></target4>
<target5 type="NilClass"></target5>
<voice-prompt-id type="NilClass">11</voice-prompt-id>
</detail>

initiateCall

Löst einen Callback Anruf auf der gewünschten SIP-Nebenstelle aus und verbindet den Anrufer dann mit der Zielrufnummer.

Parameter Erlaubte Werte Beschreibung
URL /api/initiateCall
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
sipuid z.B. 777332423@sip.finotel.coml SIP Nebenstelle die den Anruf initiieren will
target z.B. 0221123456 Zielrufnummer die angerufen werden soll
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
Beispiel:

Anfrage:
curl https://api.placetel.de/api/initiateCall.xml -d api_key=xyz.... -d target=0221123456 -d
sipuid=7723723723@sip.finotel.com

setRouting_callForward

Ändert das Callrouting für die gewünschte Rufnummer.

Parameter Erlaubte Werte Beschreibung
URL /api/setRouting_callForward
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
sipuid z.B. 777332423@sip.finotel.coml Rufnummer für die das Routing angepasst werden soll
number - 1 = Weiterleitung
- 2 = Fax
- 3 = Routingplan
- 5 = IVR
- 6 = Konferenz
- 7 = T38 Fax
- 8 = Warteschlange
- 9 = Eigene Applikation
- 10 = Gruppe
routing_setting - 1 = Direkte Weiterleitung
- 3 = Weiterleitung auf Mailbox
- 4 = Ansage abspielen und auflegen (forward-voice-prompt-id)
- 5 = Ansage abspielen und weiterleiten (forward-voice-prompt-id) Zielrufnummer die angerufen werden soll
voice_prompt_id z.B. 1,2,… ID der Ansage (siehe getPrompts)
forward_voice_prompt_id z.B. 1,2,… ID der Ansage (siehe getPrompts)
target1 … target5 z.B.
- 77723823@sip.finotel.com - Eins oder mehrere Ziele für die Weiterleitung der Rufnummer
oder
- 77723823@sip.finotel.com - Wenn mehrere Ziele parallel klingeln sind diese durch Komma getrennt.
- 022123823@pstn - Ziele im Telefonnetz enden auf @pstn
- …
ringing_time1 … ringing_time5 z.B. 5,10,20,…. Klingelzeit pro Ziel
routing_plan z.B. 1,2,23,233,… Eindeutige ID des aktiven Routingplan (siehe getRoutingplans)
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
Beispiele:

Anfrage:
Anruf wird zuerst weitergeleitet auf 2 parallele Ziele mit einer Klingelzeit von 10 Sekunden und
danach falls keine Verbindung zustande kommt an eine Mobilfunkrufnummer mit 20 Sekunden
Klingelzeit.

curl https://api.placetel.de/api/setRouting_callForward.xml -d api_key=xyz.... -d routing=1 -d
routing_setting=1 –d target1=777238@sip.finotel.com,0221823@pstn -d ringing_time1=10 –d
target2=0151343242@pstn -d ringing_time2=20 –d number=02212348348

Mailbox mit der Ansage (ID=12) wird aktiviert

curl https://api.placetel.de/api/setRouting_callForward.xml -d api_key=xyz.... -d routing=1 -d
routing_setting=3 –d voice_prompt_id=12 & number=0232232323

Umschaltung der Rufnummer auf den Routingplan mit der ID=26

curl https://api.placetel.de/api/setRouting_callForward.xml -d api_key=xyz.... -d routing=3 -d
routing_plan=26 & number=0232232323

setRouting_RoutingPlan

Ändert den Routingplan für die gewünschte Rufnummer.

Parameter Erlaubte Werte Beschreibung
URL /api/setRouting_callForward
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
number z.B. 022123434 Rufnummer für die das Routing angepasst werden soll
routing_plan z.B. 1,2,23,233,… Eindeutige ID des aktiven Routingplan (siehe getRoutingplans)
Rückgabewerte Erlaubte Werte Beschreibung
result -1 / 1 Eine „1“ steht für Ok. Eine „-1“ für einen Fehler
result-code success / error „success“ steht für erfolgreich. „error“ steht für Fehler.
Beispiele:

Anfrage:
Umschaltung der Rufnummer auf den Routingplan mit der ID=26

curl https://api.placetel.de/api/setRouting_RoutingPlan.xml -d api_key=xyz.... -d routing_plan=26 &
number=0232232323

getCcCalls

Gibt eine Liste aller Call Center Anrufe im Rohdatenformat zurück.

Parameter Erlaubte Werte Beschreibung
URL /api/getCcCalls
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
year z.B. 2012 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
month z.B. 5 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
day z.B. 2 Wenn dieser Wert nicht gesetzt ist wird das aktuelle Jahr angenommen
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getCcCalls.xml -d api_key=xyz.... -d month=4 -d day=2

Antwort:
Alle Call Center Anrufe im Rohdatenformat für den betreffenden Zeitraum

getCcAgentStates

Gibt eine Liste aller Call Center Agenten und deren aktuellem Online Status zurück .

Parameter Erlaubte Werte Beschreibung
URL /api/getCcAgentStates
api_key Von Placetel zur Verfügung gestellter Zugriffsschlüssel
Beispiel:

Anfrage:
curl https://api.placetel.de/api/getCcAgentStates.xml -d api_key=xyz.... 

Antwort:
Alle Call Center Agenten und deren aktueller online Status.
Mögliche Stati:    
    OFFLINE = -1
    ONLINE = 1
    BUSY/TALKING = 2
    WORKING = 3
    PAUSE = 4

Numerische Fehlercodes

Fehlercode Beschreibung
401 Authentifizierung fehlgeschlagen, fehlerhafter API-Key
402 Ungültiger Request (Request erfordert POST & SSL)
429 Pause nach dem letzten Request zu kurz. Nur alle 2 Sekunden ist ein Request möglich.
900 Die API steht derzeit nicht zur Verfügung.
901 Tägliches Request-Limit überschritten.
902 Request fehlgeschlagen. Bitte Parameter des Requests überprüfen.

Direktzugriff

Ticket aufgeben Status Kontakt Remote-Support