Placetel API

Placetel API 

Programmierschnittstelle 

(Stand: Juni 2012) 

www.placetel.de - DIE TELEFONANLAGE AUS DER CLOUD

INHALTSÜBERSICHT 

1 Einleitung ............................................................................................................ 3 

1.1 Rahmenbedingungen ......................................................................................................................................... 3 

1.1.1 Technischen Informationen ................................................................................................................... 3 

2 API Funktionen ................................................................................................... 4 

2.1.1 Test ..................................................................................................................................................................... 4 

2.1.2 getNumbers ................................................................................................................................................... 4 

2.1.3 getVoIPUsers ............................................................................................................................................... 5 

2.1.4 getPrompts .................................................................................................................................................... 6 

2.1.5 getContacts ................................................................................................................................................... 6 

2.1.6 getIncomingCallsByDay .......................................................................................................................... 7 

2.1.7 getCDRsByDay ........................................................................................................................................... 8 

2.1.8 getRoutingPlans ......................................................................................................................................... 9 

2.1.9 getRouting ..................................................................................................................................................... 9 

2.1.10 initiateCall ................................................................................................................................................... 11 

2.1.11 setRouting_callForward ...................................................................................................................... 12 

2.1.12 setRouting_RoutingPlan .................................................................................................................... 13 

www.placetel.de Dokumentenname Seite 2

1 Einleitung 

Dieses Dokument beschreibt die Funktionen der Placetel API. Die API bietet Zugriff 

auf grundlegende Placetel Funktionen. 

1.1 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 nur eine Anfrage alle 2 Sekunden. Jede zusätzliche Anfrage 

wird mit einer Fehlermeldung beantwortet. Bei höheren Anforderungen 

kontaktieren Sie den Placetel Service. 

- Zudem ist der Zugriff auf 100 Requests pro Tag beschränkt. Bei höheren 

Anforderungen kontaktieren Sie den Placetel Service. 

- Der Zugriff muss über HTTPS erfolgen. 

- Parameter werden nur per POST entgegengenommen. 

1.1.1 Technischen 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. 

Requestart 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 


2 API Funktionen 

2.1.1 Test 

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

Parameter Erlaubte Werte Beschreibung 

URL 

api_key 

/api/test 

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: 

 

 

1 

success 

test login successful 

 

2.1.2 getNumbers 

Gibt eine Liste aller aktiven Rufnummern im betreffenden Placetel Benutzerkonto 

aus. 


URL 

api_key 

/api/getNumbers 








s.u. 

Werte siehe Beispiel 


Beispiel: 

Anfrage: 

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

Antwort: 

 

 

022123434384 

23434384 

0221 

 

 

2.1.3 getVoIPUsers 

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


URL 

api_key 

/api/getVoIPUsers 








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: 

 

Fax 

7 


 

 

 


2.1.4 getPrompts 

Gibt eine Liste aller Voice Prompts (Ansagen) im betreffenden Placetel 

Benutzerkonto aus. 


URL 

api_key 

/api/getPrompts 








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: 

 

10613 

Ansage Test 12 

 

2.1.5 getContacts 

Gibt eine Liste aller Kontakte im betreffenden Placetel Benutzerkonto aus. 


URL 

api_key 

/api/getContacts 









s.u. 


Beispiel: 

Anfrage: 

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

Antwort: 

 

 

02212238238 

01712323823 

089348348 

01513448348 

 

Peter 

Tester 

 

2.1.6 getIncomingCallsByDay 

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

Benutzerkonto aus. 


URL 

api_key 

/api/getIncomingCallsByDay 



year z.B. 2012 Wenn dieser Wert nicht gesetzt 

ist wird das aktuelle Jahr 

angenommen 

month 5 Wenn dieser Wert nicht gesetzt 

ist wird der aktuelle Monat 

angenommen 

day 2 Wenn dieser Wert nicht gesetzt 

ist wird der aktuelle Tag 

angenommen 






callType 1 = Voicemail 

2 = Verpasster Anruf 

3 = Blockierter Anruf 

4 = Angenommener Anruf 

5 = Fax 

s.u. 



Beispiel: 

Anfrage: 

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

Antwort: 

 

2 

 

022123823833 

2012-04-02T08:10:50Z 

022129191999 

 

2.1.7 getCDRsByDay 

Gibt eine Liste aller Anrufe des Einzelverbindungsnachweises pro Tag für das 

betreffenden Placetel Benutzerkonto aus. 


URL 

api_key 

/api/getCDRsByDay 



year z.B. 2012 Wenn dieser Wert nicht gesetzt 

ist wird das aktuelle Jahr 

angenommen 

month 5 Wenn dieser Wert nicht gesetzt 

ist wird der aktuelle Monat 

angenommen 

day 2 Wenn dieser Wert nicht gesetzt 

ist wird der aktuelle Tag 

angenommen 






s.u. 



Beispiel: 

Anfrage: 

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

Antwort: 

 

0.155 

placetel_profi / Germany Mobile - SIP Dialout 

77723234234 

4 

01517334734 

2012-04-02T08:40:25Z 

 

2.1.8 getRoutingPlans 

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


URL 

api_key 

/api/getRoutingPlans 








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: 

 

1 

Testplan 

 

2.1.9 getRouting 


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

aus. 


URL 

api_key 

/api/getRoutingPlans 



number z.B. 0221123456 Placetel Rufnummer für die das 

Routing bestimmt werden soll 






routing 

1 = Weiterleitung 

2 = Fax 

3 = Routingplan 

5 = IVR 

6 = Konferenz 

7 = T38 Fax 

8 = Warteschlange 

9 = Eigene Applikation 

10 = Gruppe 

routing-settings 1 = Direkte Weiterleitung 

3 = Weiterleitung auf Mailbox 

4 = Ansage abspielen und 

auflegen (forward-voiceprompt-id) 


weiterleiten (forward-voiceprompt-id) 

voice-prompt-id z.B. 1,2,... ID der Ansage (siehe 

getPrompts) 

forward-voice- 

z.B. 1,2,... 

ID der Ansage (siehe 

prompt-id 

target1 ... target5 

z.B. 


oder 

77723823@sip.finotel.com,0 

22123823@pstn, ... 

getPrompts) 

Eins oder mehrere Ziele für die 

Weiterleitung der Rufnummer 

Wenn mehrere Ziele parallel 

klingeln sind diese durch 

Komma getrennt. Ziele im 

Telefonnetz enden auf @pstn 

Klingelzeit pro Ziel 

ringing-time1 ... z.B. 5,10,20,.... 

ringing-time5 

routing-plan z.B. 1,2,23,233,... Eindeutige ID des aktiven 

Routingplan (siehe 

getRoutingplans) 


Beispiel: 

Anfrage: 

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

Antwort: 

 

12 

40 

10 

120 

60 

60 

1 

2 

1 


 

 

 

 

11 

 

2.1.10 initiateCall 

Löst einen Callback Anruf auf der gewünschten Sip Nebenstelle aus und verbindet 

den Anrufer dann mit der Zielrufnummer. 


URL 

/api/initiateCall 

api_key 



sipuid 

z.B. 


SIP Nebenstelle die den Anruf 

initiieren will 

target z.B. 0221123456 Zielrufnummer die angerufen 

werden soll 






Beispiel: 

Anfrage: 

curl https://api.placetel.de/api/initiateCall.xml -d api_key=xyz.... -d target=0221123456 -d 

sipuid=7723723723@sip.finotel.com 


2.1.11 setRouting_callForward 

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


URL 

/api/setRouting_callForward 

api_key 



number z.B. 022123434 Rufnummer für die das Routing 

angepasst werden soll 

routing 

1 = Weiterleitung 

2 = Fax 

3 = Routingplan 

5 = IVR 

6 = Konferenz 

7 = T38 Fax 

8 = Warteschlange 

9 = Eigene Applikation 

10 = Gruppe 

routing_settings 1 = Direkte Weiterleitung 

3 = Weiterleitung auf Mailbox 


auflegen (forward-voiceprompt-id) 


weiterleiten (forward-voiceprompt-id) 

voice_prompt_id z.B. 1,2,... ID der Ansage (siehe 

getPrompts) 

forward_voiceprompt_id 

z.B. 1,2,... 

ID der Ansage (siehe 

getPrompts) 

target1 ... target5 z.B. 


oder 

77723823@sip.finotel.com,0 

22123823@pstn, ... 

Eins oder mehrere Ziele für die 

Weiterleitung der Rufnummer 

Wenn mehrere Ziele parallel 

klingeln sind diese durch 

Komma getrennt. Ziele im 

Telefonnetz enden auf @pstn 

ringing_time1 ... z.B. 5,10,20,.... 

Klingelzeit pro Ziel 

ringing_time5 

routing_plan z.B. 1,2,23,233,... Eindeutige ID des aktiven 









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_settings=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 


routing_settings=3 –d voice_prompt_id=12 & number=0232232323 

Umschaltung der Rufnummer auf den Routingplan mit der ID=26 


routing_plan=26 & number=0232232323 

2.1.12 setRouting_RoutingPlan 

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


URL 

api_key 

/api/setRouting_callForward 



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 









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 


Placetel.de 

Die Placetel-Telefonanlage aus der Cloud gehört zum innovativen Produktportfolio der finocom 

AG. Die finocom AG zählt zu den führenden Unternehmen im Bereich sprachbasierter Cloud- 

Services für Geschäftskunden. 

finocom AG 

Gustav-Heinemann-Ufer 58 

50968 Köln 

E-Mail: info@placetel.de 

Tel.: 0221/29 19 1999 

www.placetel.de - DIE TELEFONANLAGE AUS DER CLOUD 

www.placetel.de Dokumentenname Seite 15 

www.0800.de

Placetel API

Sie wollen auch ein ePaper? Erhöhen Sie die Reichweite Ihrer Titel.

Template löschen?

Als Template speichern?