---
title: "yuuphone Enterprise API"
canonical: "https://dokucenter.yuutel.at/space/Dokucenter/2238490921/yuuphone%20Enterprise%20API"
format: markdown
---
# Einleitung
Dieses Dokument beschreibt die Schnittstelle, nachfolgend Enterprise API (kurz EAPI) genannt, für die automatisierte Abfrage von anrufbezogenen Daten der yuuphone Lösung.
Damit ist es möglich einzelne Calldaten (Call Data Records, “cdr”) abzufragen um diese bspw. auszuwerten oder in Drittsystemen weiter zu verarbeiten.
yuuphone Kunden erhalten bei Bedarf kostenlosen Zugriff auf die API. Den notwendigen Token zur Abfrage der Daten bekommen Sie von [service@yuutel.at](mailto:service@yuutel.at)
> ✅ Zur Einrichtung der EAPI **benötigen **wir von Ihnen die **externe IP Adresse(n)**, von der aus Sie, auf die EAPI zugreifen.
> ✅
> ✅ Alternativ kann statt der IP-Adresse ein **Zertifikat** verwendet werden, dass Sie von yuutel erhalten. Für die Erstellung des Zertifikats ist eine **Emailadresse **notwendig!
# Eigenschaften der Schnittstelle
Die Schnittstelle ist eine auf HTTP basierende API, deren Endpunkte generell dem REST Modell folgen. Für den Datenaustausch wird JSON als Datenformat genutzt.
## URL Endpunkt
Die EAPI wird unter einer Basis URL bereitgestellt. Dieser Basis URL müssen bestimmte Parameter angefügt werden, um die gewünschten Informationen per REST geliefert zu bekommen. Nachfolgend werden die Endpunkte innerhalb dieser Base-URL beschrieben.
```
Basis Enterprise-API URL: https://api.ipbx.at/eapi/v1
```
Um beispielsweise die Liste der Gesprächsdaten (cdr) abzufragen, erfolgt der Zugriff mit der GET Methode auf die **Basis URL** mit dem **Parameter “cdr”**:
```
https://api.ipbx.at/eapi/v1/cdr
Authorization: Bearer
```
Das OpenAPI Schema (v3) ist verfügbar unter:
- Schema: [https://api.ipbx.at/doc/enterprise/v1/enterprise-api-openapi.yaml](https://api.ipbx.at/doc/enterprise/v1/enterprise-api-openapi.yaml)
- Swagger-UI: [https://api.ipbx.at/swagger-ui/?urls.primaryName=Enterprise API v1](https://api.ipbx.at/swagger-ui/?urls.primaryName=Enterprise%20API%20v1)
## Datenaufbewahrung
Die Aufbewahrungsdauer für Gesprächsdaten entspricht den EU weiten, gesetzlichen Regelungen und liegt derzeit bei 6 Monaten.
## Datenformat
Für die Schnittstelle wird generell JSON (Content-Type: application/json) als Datenaustauschformat verwendet. Alle Zeichen sind UTF-8 kodiert.
Jegliche Anfragen an die Schnittstelle müssen JSON verarbeiten können und dies entsprechend im Accept-Header setzen.
```
Accept: application/json
```
Ist ein Feld für eine Datenstruktur als *optional* angegeben, so kann der Eintrag in der JSON-Repräsentation auch komplett entfallen.
# Sicherheit
## Authentifizierung
Für die Authentifizierung des Zugriffs wird initial ein EAPI-Token vergeben. Den Token erhalten sie von von der yuutel GmbH ([service@yuutel.at](mailto:service@yuutel.at)).
Beispiel für einen Aufruf via CURL mit API-Token:
```shell
curl --compressed -X GET -H 'Authorization: Bearer TOKEN "https://api.ipbx.at/eapi/v1/cdr?since=2020-06-01T00:00:00Z&limit=500"
[{"id":"124644414","type":"ORIG","direction":"O","originatorNumber":"+4311111111",...
```
## Netzwerkzugriff
Der Zugriff zur EAPI wird grundsätzlich auf Basis von IPv4-Adressen eingeschränkt. Für jedes EAPI-Token wird ein definiertes Set an IPv4-Adressen (bzw. auch Subnetze) freigeschaltet. Für eine Änderung der Zugriffe ist ein neuer Token notwendig.
Sollte die Angabe einer IP Adresse bzw. der IP-Adress-Range nicht möglich sein, dann kann eine Authentifizierung per Zertifikat eingesetzt werden. Dazu bekommen Sie von yuutel ein Zertifikat, dass bei jeder Anfrage mit gesendet werden muss. Da das Zertifikat eine Laufzeit von 3 Jahren aufweist, muss nach Ablauf der Laufzeit, eine neues Zertifikat bei [service@yuutel.at](mailto:service@yuutel.at) angefragt werden.
> ❌ IPv6 Adressen werden derzeit nicht unterstützt!
## Abfragebeschränkung
Die Anzahl der Zugriffe ist generell auf 1 Request/s pro EAPI-Token eingeschränkt. Ein Burst auf 5 Requests/s wird kurzzeitig erlaubt. Weitere Requests, die diese Zugriffsrate übersteigen, werden sofort abgelehnt.
## Transport
Der Zugriff erfolgt ausschließlich mittels TLS gesicherter HTTP Verbindung. Um mögliche Attacken auf das Transportprotokoll zu minimieren werden nur moderne Verschlüsselungsalgorithmen (Ciphers) erlaubt.
Dazu zählen aktuell (basierend auf SSLLabs - Best Practices - Jan 2020):
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
# API Methoden für Gesprächsdaten (/cdr)
Für jedes Gespräch wird ein **Call Detail Record** (kurz cdr) erzeugt, der zugehörigen Parameter des Anrufs enthält.
Unter dem EAPI-Pfad /cdr werden Gesprächsdaten in ihrer ursprünglichen Form bereitgestellt.
## Interne Gespräche
Für interne Gespräche wird für jeden Teilnehmer ein eigener CDR erfasst und jeweils mit der korrekten Richtung (direction) hinterlegt.
Bei einem Gespräch von A → B werden somit für A ein originierender CDR und für B ein terminierender CDR erstellt. Die CDRs unterscheiden sich prinzipiell nur in der Richtung (direction), da es sich um den gleichen Anruf handelt.
Der zugehörige Teilnehmer bzw. dessen Nummer für einen CDR ist entsprechend...
- für originierende Gespräche (direction: „O"): originatorNumber
- für terminierende Gespräche (direction: „T"): terminatorNumber
## Zusammengehörige Gespräche
Sind bei einem Gespräch mehrere Teilnehmer beteiligt, wird für jede einzelne Verbindung ein eigener CDR erzeugt. Für eine Weiterleitung eines Anrufs zu einem Teilnehmer (auch Transfer mit/ohne Rückfrage genannt) entstehen somit für die einzelnen Gesprächsteile mehrere CDRs:
- **Eingehender Anruf** (A→B): 1 „TERM" CDR
- **Rückfrage** **zum** **Teilnehmer** (B→C): 2 CDRs, da intern (jeweils für B „ORIG" und C„TERM")
- **Gespräch** **des** **Anrufers** **mit** **dem** **Teilnehmer** (A→C) mit 3 CDRs mit Typ „CONTINUED", 1 für den Transfer und 2x für den ersetzten Anruf (jeweils für B und C, da intern)
Für diese komplexeren Anrufszenarien werden zusätzliche Informationen (replacedCallId und transferredCallId) in den CDRs abgelegt, um eine Zuordnung der einzelnen CDRs zu einem Gespräch zu erleichtern.
Die Gesprächsdauer (duration) der jeweiligen Abschnitte, schließen aus Vergebührungsgründen, auch die Gesprächszeit der weitergeleiteten Gespräche mit ein.
### Beispiel für einen Call Transfer
Teilnehmer für einen Transfer:
```
A = +436769999999 (external)
B = +4311111111 (intern1)
C = +4312222222 (intern2)
```
Ablauf:
```
21:50:46 A->B
21:51:16 B->C (start AXFER)
21:51:37 A->C (execute XFER)
21:52:07 Bye
A->Brr======hhhhhhhh............. 80.0s (ring=2.0)
B->C rrr=====............. 50.7s (ring=7.3)
A->C============= 31.1s (billed to B)
Legende: "r": ringing, "=": talking, "h": held, ".": billed
```
Zugehörige CDRs:
```shell
curl -X GET -H 'Authorization: Bearer TOKEN "https://api.ipbx.at/eapi/v1/cdr? since=2020-05-18T19:50:00Z&limit=6" | aeson-pretty
[
{
"disconnectReason": "BYE-REPL", "direction": "O", "originatorNumber": "+4311111111",
"terminatorNumber": "+4312222222", "startTime": "2020-05-18T21:51:16+02:00",
"duration": 19.457,
"durationRinging": 7.354,
"callId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg", "type": "CONTINUED"
},
{
"disconnectReason": "BYE-REPL", "direction": "T", "originatorNumber": "+4311111111",
"terminatorNumber": "+4312222222",
"startTime": "2020-05-18T21:51:16+02:00",
"duration": 19.457,
"durationRinging": 7.314,
"callId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg",
"type": "CONTINUED"
},
{
"disconnectReason": "BYE-XFER", "direction": "T", "originatorNumber": "+436769999999",
"terminatorNumber": "+4311111111",
"startTime": "2020-05-18T21:50:46+02:00",
"duration": 48.837,
"durationRinging": 2.021,
"callId": "2a15e00013f5-5ec2e714-a51deb-01-UASession-aN6D7X_XKP", "type": "CONTINUED"
},
{
"disconnectReason": "BYE",
"replacedCallId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg",
"originatorNumber": "+436769999999",
"terminatorNumber": "+4311111111",
"startTime": "2020-05-18T21:50:46+02:00",
"direction": "T",
"duration": 80.018,
"durationRinging": 2.021,
"callId": "HEisG7sIYY-UASession-hWuA2OJS~q",
"transferredCallId": "2a15e00013f5-5ec2e714-a51deb-01-UASession-aN6D7X_XKP", "referredByNumber": "+4311111111",
"type": "TERM"
},
{
"disconnectReason": "BYE", "direction": "O",
"replacedCallId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg", "originatorNumber": "+4311111111",
"terminatorNumber": "+4312222222", "startTime": "2020-05-18T21:51:16+02:00",
"duration": 50.714,
"durationRinging": 7.314,
"callId": "HEisG7sIYY-UASession-hWuA2OJS~q",
"transferredCallId": "2a15e00013f5-5ec2e714-a51deb-01-UASession-aN6D7X_XKP", "referredByNumber": "+4311111111",
"type": "ORIG"
},
{
"disconnectReason": "BYE","replacedCallId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg", "originatorNumber": "+4311111111",
"terminatorNumber": "+4312222222", "startTime": "2020-05-18T21:51:16+02:00",
"direction": "T", "duration": 50.714,
"durationRinging": 7.314,
"callId": "HEisG7sIYY-UASession-hWuA2OJS~q",
"transferredCallId": "2a15e00013f5-5ec2e714-6a51deb-01-UASession-aN6D7X_XKP", "referredByNumber": "+4311111111",
"type": "TERM"
}
]
```
Die Dauer der Verbindung für den transferierten Anruf kann über **transferredCallId **ermittelt werden (im Beispiel: 80,018 - 48,837 = 31,181s). Die Nummer des C- Teilnehmers, der schlussendlich mit dem ursprünglichen Anrufer A gesprochen hat, kann über die **replacedCallId **gefunden werden (im Beispiel: +4312222222).
## Datenstruktur CDR
Die Daten für einen Call-Detail-Record sind nachfolgend aufgeschlüsselt.
| | | | |
| --- | --- | --- | --- |
| **Name** | **Typ** | **Optional** | **Beschreibung** |
| id | string | Nein | Eindeutige Kennung des CDRs Beispiel: 2342123123 |
| type | string | Nein | Typ des Anrufes: ORIG (originating), TERM (terminating), CONTINUED (fortgesetzt) oder ATTEMPT (unbeantwortet). |
| direction | enum | Nein | Richtung des Anrufs (originierend, terminiierend) Bespiel: O | T |
| originatorNumber | string | Ja | Nummer des Anrufers im +E164 Format Beispiel: +43987371222 |
| terminatorNumber | string | Ja | Nummer des Angerufenen im +E164 Format Beispiel: +43720620311 |
| startTime | string | Ja | Startzeit des Anrufs im ISO8601 Format Beispiel: 2017-07-11T12:12:44Z |
| duration | float | Ja | Dauer des Anrufs (Gesprächszeit) Beispiel: 15.2 |
| durationRinging | float | Ja | Dauer des Anrufs (Gesprächszeit) Beispiel: 4.67 |
| startTimeMillis | string | Nein | Startzeit in Millisekunden seit der Epoche (UTC) Beispiel: 1589835733321 |
| stopTimeMillis | string | Nein | Stopzeit in Millisekunden seit der Epoche (UTC) Beispiel: 1589835770895 |
| callId | string | Nein | Eindeutige ID für einen Anruf
Beispiel: abe435g2jdu12@UA-4324123132 |
| replacedCallId | string | Ja | Eindeutige ID des Anrufs, der durch diesen ersetzt wurde. Format siehe callId |
| transferredCallId | string | Ja | Eindeutige ID des Anrufs auf den transferiert wurde. Format siehe callId |
| referredByNumber | string | Ja | Rufnummer, die einen Transfer oder Pickup durchgeführt hat |
| disconnectReason | string | Ja | Ursache für Beendigung des Anrufs. Im Normalfall
BYE |
| callProgressState | string | Ja | Status der Signalisierung des Anrufs. Vorwiegend im Fehlerfall gesetzt. |
| callIndicator | string | Ja | Kennung für spezielle Dienste in der Signalisierung des Anrufs |
| publicIP | string | Ja | Öffentliche IP-Adresse des Benutzers (VoIP- Signalisierung).
Beispiel: 193.84.65.22 |
| privateIP | string | Ja | Private IP-Adresse des Benutzers (VoIP- Signalisierung).
Beispiel: 193.84.65.22 |
## GET /cdr
Auflistung der CDRs im angegebenen Zeitraum. Erlaubte Query-Parameter:
| | | | |
| --- | --- | --- | --- |
| **Parameter** | **Typ** | **Optional** | **Beschreibung** |
| since | string (ISO8601) | Ja | Abfrage der CDRs seit dem angegebenen Datum im ISO8601 Format (inklusive Zeitzone). Wird kein Datum angegeben, wird die Abfrage für den heutigen Tag durchgeführt.
Beispiel: 2020-05-18T23:01:55Z |
| sinceUtcMillis | long | Ja | Ähnlich zu since, aber als Timestamp in Millisekunden seit der Epoche (UTC).
Beispiel: 1589835715108 |
| limit | int | Ja | Maximale Anzahl von CDRs, die zurückgegeben werden soll (default: 1000, maximum: 1000)
Beispiel: 500 |
Beispiel:
**GET** **/eapi/v1/cdr?sinceUtcMillis=1589835715108**
```
200 OK [
{
"id": "896469336",
"disconnectReason": "BYE", "originatorNumber": "+436769999999",
"terminatorNumber": "+4311111111", "startTime": "2020-05-18T23:01:55+02:00",
"direction": "T", "startTimeMillis": 1589835715108,
"stopTimeMillis": 1589835721438,
"duration": 6.33,
"durationRinging": 3.46,
"callId": "2a15e00013f5-5ec2f7bf-7a959ebc-UASession-de6RjvU~RO", "type": "TERM",
"publicIP": "80.108.55.43",
"privateIP": "10.17.7.21"
},{
"id": "896464770",
"disconnectReason": "BYE",
"replacedCallId": "0_3348179075@10.17.7.21-UASession-CpqsJJfkzg", "originatorNumber": "+4311111111",
"terminatorNumber": "+4312222222", "startTime": "2020-05-18T21:51:16+02:00",
"direction": "T", "startTimeMillis": 1589831476002,
"stopTimeMillis": 1589831526716,
"duration": 50.714,
"durationRinging": 7.354,
"callId": "HEisG7sIYY-UASession-hWuA2OJS~q",
"transferredCallId": "2a15e00013f5-5ec2e714-01-UASession-aN6D7X_XKP", "referredByNumber": "+4311111111",
"type": "TERM",
"publicIP": "80.108.55.43",
"privateIP": "10.17.7.10"
}
]
```
Return codes:
```
204 No content
200 OK
```