Development Richtlinien

Schnittstellendokumentation

Der Buchungsprozess

1. Kunde wählt App und Anzahl der Lizenzen.
2. EULA, Datenschutzbedingungen, AVV des Entwicklungspartners etc. werden angezeigt und von dem Kunden zur Kenntnis genommen.
3. Der Kunde bestätigt die Buchung. Beim Eintreten dieses Events wird ein HTTP-POST-Request (JSON-Format) an den App-Entwickler Endpunkt gesendet.
4. Monatlich wird ein „Invoice String“ auf der Placetel- Endkundenrechnung erstellt.
5. Bei Kündigungen bzw. Löschung der App wird der App-Entwickler über E-Mail bzw. Webhook informiert und der „Invoice String“ von der Placetel-Endkundenrechnung gelöscht.

Schnittstellendokumentation

Eine Buchung oder Änderung der Integration durch den Placetel Nutzer im Kundenkonto löst einen API Request gegen den Endpunkt des Entwicklungspartners aus. Diesen Endpunkt muss der Integrator einrichten, betreiben und Placetel im Vorfeld mitteilen. Ein erfolgreich empfangener Request ist durch den Integrator mit einer 200 OK Response zu beantworten. Erhalten wir keine Antwort oder einen anderen Response Code gehen wir davon aus, dass die Buchung nicht erfolgreich war.

Buchung

Der POST Request übermittelt im Body folgende Informationen im JSON Format:

{ user:  user_email, 
users: license_count, 
integration: integration_name, 
environment: prod/staging }

Der Parameter environment ist optional. Er ermöglicht die Einbindung einer Testumgebung.

{ user: matthias@cisco.com, 
users: 5, 
integration: HubSpot }

Änderung der Anzahl der Lizenzen/ Stornierung

Bei einer Änderung der Anzahl an Lizenzen sendet Placetel einen weiteren POST Request mit dem oben beschriebenen Body. Dabei wird immer die tatsächliche Useranzahl und nicht nur die Änderungen gesendet.

Der Integrator ist verpflichtet den Endpunkt gegen den Zugriff durch Unbefugte zu schützen. Daher darf der Integrator nur Requests von einem spezifischen IP-Adressraum empfangen und verarbeiten. Dieser IP-Adressraum ist im Vorfeld bei Placetel zu erfragen.

Authentifizierung

OAuth: Mit OAuth hat der App-Entwickler die Möglichkeit auf nutzerspezifische Daten (Rufnummern, SIP User, Kontakte, Routingpläne etc.) der Placetel Telefonanlage zuzugreifen. Diesen Zugriff gestattet der Endkunde dem Integrator, in dem der Endkunde sich einmal zur Einrichtung der Integration mit seinen Placetel Benutzerdaten anmeldet. Der Integrator erhält somit einen Access Token, mit dem er Requests gegen unsere REST API ausführen kann. Ein zusätzlicher API Bearer Token ist nicht mehr notwendig.

Der OAuth Zugang kann via integration@placetel.de beantragt werden sobald die App in ihren Grundfunktionen nachweisbar ist.
Für die Erstellung eines OAuth-Zugangs benötigt Placetel folgenden Informationen des Integrators:

• Die spezifischen Callback Links / Redirect URLs des Integrators
• Die Scopes, auf die die Integration Zugriff erhalten soll und ob die gewünschte Operation(lesend, schreibend…) sein soll. Hierbei kann der Integrator sich an den Endpunkten der REST API orientieren, z.B.read:contact read:number read:user read:sip_user iniate:call.
• Der Endpunkt GET /me liefert grundsätzlich Informationen über den eingeloggten Nutzer, z.B. Name, E-Mail, Haupt-VoIP Ziel und Plattform.

Bitte beachte Sie, dass die REST API derzeit nur für Placetel PROFI zur Verfügung stehen. Hierzu sollten Sie auf jeden Fall den Parameter „platform“: „PROFI“ filtern. Falls dort eine andere Plattform hinterlegt ist, sollten Sie sämtliche Operationen verhindern.

Sie benötigen von Placetel:

• Authorization URL: //accounts.placetel.de/oauth/authorize
• Token/Refresh URL: //accounts.placetel.de/oauth/token

Nachdem wir Ihre Informationen erhalten haben, senden wir Ihnen zeitnah auch Ihre Client ID und Ihr Client Secret. Bitte bewahren Sie diese Informationen an einem sicheren Ort. Geben Sie keine Informationen an unbefugte Dritte weiter.