Dokumentation

Number Order API

TENIOS bietet für nahezu alle europäischen Länder geografische Rufnummern an. Kunden können diese Rufnummern über das TENIOS-Kundenportal, oder auch wie hier beschrieben über die TENIOS API bestellen. Damit Sie Rufnummern bestellen können, benötigt TENIOS ein Verifikationsdokument wie z.B. einen Handelsregisterauszug welches nachweist, dass Sie innerhalb eines Vorwahlenbereiches eine gültige Adresse besitzen.

Verifikationsdokument noch nicht vorhanden? Mehr Informationen finden Sie im Abschnitt „Erstellen eines Verifikationsdokuments“

Erstellen eines Verifikationsdokument:

Mit dieser Methode kann vor der Bestellung ein Verifikationsdokument für den gewünschten Vorwahlenbereich angelegt werden. Damit das Dokument genehmigt werden kann, muss die angegebene Adresse im Bereich der Ortsnetzkennzahl (area code) liegen. Sie erhalten eine eindeutige uuid für dieses Dokument zurück. Sobald dieses Dokument von TENIOS genehmigt wurde, können Sie die entsprechende Rufnummern mit der /number/order bestellen.

POST	https://api.tenios.com/verification/create

Anfrageparameter:

access_key String	Der Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
country String	Name des Landes in Englisch (Bsp.:Germany).
city String	Name der Stadt (Bsp.:Berlin).
street String	Name der Straße.(Bsp.:Musterstr).
house_number String	Hausnummer (Bsp.: 4a)
document_type String	Art des Verifikationsdokuments. Mögliche Werte sind: ALLOCATION_NOTICE IDENTITY_CARD BUSINESS_LICENSE IDENTITY_CARD_AND_BUSINESS_LICENSE CERTIFICATE_OF_REGISTRATION CONTRACT
document_data String	Muss ein base64 encodiertes PDF-Dokument sein (RFC-4648).
area_code String	Ortznetzkennzahl der Stadt.(Bsp.: 221 für Köln)

Beispiel für eine erfolgreiche Anfrage:

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "country": "Germany",
   "city": "Aarbergen",
   "zip": "50670",
   "street": "Musterstr.",
   "house_number": "11",
   "document_type": "ALLOCATION_NOTICE",
   "area_code": "221",
   "document_data": "iVBORw0KGgoAAAANSUhEUgAAA3cA..."
}

API Response:

HTTP Status Code: 200 (OK)

{
   "verification_id": "705d5302-d918-454a-b703-c9c23995726e"
}

Die Antwort gibt die verification_id (uuid) des erstellten Verifikationsdokuments zurück. Nachdem die Adresse validiert und genehmigt wurde, können mit dieser uuid Rufnummern aus dem damit verbundenen Vorwahlenbereich bestellt werden. TENIOS kann eine Liste mit allen verfügbaren Ortsnetzkennzahlen aus Deutschland zur Verfügung stellen.

Rufnummerbestellung:

Diese Methode erstellt eine Rufnummernbestellung für den Kunden.

POST	https://api.tenios.com/number/order

Bitte stellen Sie sicher, dass die verification_id (uuid) zu einem bereits genehmigten Verifikationsdokument gehört.

Anfrageparameter:

access_key String	Der Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/Allgemeine Einstellungen im Abschnitt API gefunden werden.
number_type String	Rufnummerntyp. Derzeit wird nur der Typ GEOGRAPHICAL unterstützt.
verification_id String	UUID des (genehmigten) Verifikationsdokuments des Vorwahlenbereichs.
link_to_number String Optional	Der Parameter link_to_number ist optional und erlaubt das verlinken der angefragten Rufnummer mit einer bereits bestehenden Rufnummer.
push_url String Optional	HTTPS URL. Sobald die Bestellung abgeschlossen ist, wird eine POST-Anfrage an die angegebene URL gesendet.
push_secret String Optional	Wenn der Parameter push_url angegeben ist, muss auch ein push_secret angegeben werden. Die maximale Länge beträgt 64 Zeichen.

Beispiel für eine erfolgreiche Anfrage:

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 200 (OK)

{
   "order_id": "300000"
}

Eine erfolgreiche Antwort enthält die order_id der erstellten Rufnummernbestellung. Falls Sie eine push_url in Ihrer Anfrage angegeben haben, sendet unser System eine HTTPS POST Anfrage an die angegebene URL, sobald die Rufnummernbestellung abgeschlossen ist. In diesem Beispiel wird eine POST-Anfrage an https://www.example.com/order-success gesendet.

POST	https://www.example.com/order-success

Anfrageparameter:

phonenumber String	Die für die Order-Id zugewiesene Rufnummer. Diese Rufnummer steht dann ab sofort im Kundenportal zur Verfügung und kann genutzt werden. Falls die bei der Order-Anfrage auch eine Rufnummer im Parameter „link_to_number“ angegeben haben, ist für für diese Rufnummer der gleiche Routingplan hinterlegt.
order_id String	Referenziert die Order-Id zu der eine Rufnummer hinzugefügt wurde (Diese Id haben Sie bei einer erfolgreichen Order-Anfrage als Rückgabewert erhalten).
push_secret String	Das „push_secret“, welches bei der Order-Anfrage gesetzt wurde. Sie können dieses zur Validierung der Anfrage in Ihrer Anwendung verwenden.

Push URL Anfrage:

{
   "phonenumber": "+4912344557",
   "order_id": "28",
   "push_secret": "iwillnottellyou"
}

Beispiele für fehlerhafte Anfragen:

NUMBER_ORDER_ILLEGAL_NUMBER_TYPE

Dieser Fehler wird zurückgegeben, wenn ein falscher oder ungültiger number_type angegeben wurde.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "wrong value",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_ILLEGAL_NUMBER_TYPE",
   "error_message": "Only 'GEOGRAPHICAL' number type is acceptable.",
   "fields": [
      "number_type"
   ]
}

NUMBER_ORDER_VERIFICATION_ID_NOT_VALID

Dieser Fehler wird zurückgegeben, wenn eine falsche oder ungültige verification_id angegeben wurde.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "wrong uuid",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success%22",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_VERIFICATION_ID_NOT_VALID",
   "error_message": "Invalid verificationId. Valid document UUID expected.",
   "fields": [
      "verification_id"
   ]
}

NUMBER_ORDER_WRONG_LINK_NUMBER

Dieser Fehler wird zurückgegeben, wenn eine falsche oder ungültige Eingabe beim Parameterlink_to_number angegeben wurde.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+123",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_WRONG_LINK_NUMBER",
   "error_message": "The provided link phone number is not valid. You can use only suitable for linking numbers which are assigned to your account.",
   "fields": [
      "link_to_number"
   ]
}

NUMBER_ORDER_INVALID_PUSH_SECRET

Dieser Fehler wird zurückgegeben, wenn ein falsches oder ungültiges push_secret angegeben wurde.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://myurl",
   "push_secret": "*****************************************************************"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_INVALID_PUSH_SECRET",
   "error_message": "Provided push secret is not valid. Text up to 64 characters long is allowed.",
   "fields": [
      "push_secret"
   ]
}

Nach durchgelaufenem Bestellprozess wird TENIOS die Rufnummer innerhalb von 24 Stunden bestätigen.

Die Routingeinstellungen der Rufnummer können dann über das TENIOS-Kundenportal editiert werden.

Es ist auch möglich die Rufnummer mit einer bereits bestehenden Rufnummer zu verlinken. In diesem Fall werden Änderungen beim Routing und den Routingeinstellungen der Hauptrufnummer automatisch für diese Rufnummer übernommen. TENIOS hat diesen Mechanismus implementiert, damit ein bestehendes Routing einer neuen Rufnummer über die API zugeordnet werden kann. Setzen Sie den Parameter link_to_number, um so den Routingplan und die Routingoptionen der Haupnummmer der neu bestellten Rufnummer zuzuweisen.