Ein einzelnes Präfix auswählen
Verwenden Sie die Aufrufe zur Ermittlung von Ländern und Abdeckungsbereichen und rufen Sie anschließend getprefixes ohne Gruppierung auf. Kopieren Sie beim ausgewählten Präfix das Feld uuid. Wenn returns_numbers den Wert 0 hat, wird bei diesem Präfix erst bei der Bestellung eine Rufnummer zugewiesen; verwenden Sie das zurückgegebene Feld next_function anstatt eine Liste einzelner Rufnummern vorauszusetzen.
Eine begrenzte Ergebnismenge durchsuchen
Verwenden Sie für eine normale Suche compact=1 und geben Sie die gewünschte Anzahl sowohl im Pfad als auch im Abfrageparameter quantity an, wie unten gezeigt. Es gibt keinen Seiten- oder Cursorparameter. Ein kompaktes Ergebnis ist eine Stichprobe; eine wiederholte Anfrage garantiert keine nächste Seite ohne Überschneidungen. Interpretieren Sie ein leeres oder kleines Ergebnis nicht als Gesamtzahl der verfügbaren Rufnummern.
Ein einprägsames Ziffernmuster finden
Geben Sie number_filter_mode=contains oder ends_with zusammen mit number_filter_value an. Der Wert muss 1–15 Ziffern enthalten. Eine Suche ruft möglicherweise nur begrenzte Mengen potenziell passender Rufnummern ab, bevor sie den Filter anwendet, sodass weitere passende Rufnummern im Bestand übersehen werden können. Wenn die erforderliche Suche über eine unterstützte Quelle ausgeführt werden muss, lassen Sie sich von MultiTEL einen Selektor für pid geben und verwenden Sie filter_required=1; fehlt die Auswahl oder wird sie nicht unterstützt, gibt die API einen Fehler zurück.
Die ausgewählte Rufnummer prüfen
Entnehmen Sie demselben Ergebnis number, info.uuid, das ausgewählte Feld price[].uuid, die Namen der verfügbaren Funktionen und die Registrierungsanforderungen. Das Array price kann mehrere Tarife mit unterschiedlichen Kanalanzahlen und Preisen enthalten. Geldbeträge und Mengen können als Zeichenfolgen kodiert sein. Optionale Metadaten, einschließlich info.state, unterscheiden sich je nach Quelle; setzen Sie keine einheitliche Struktur für die Bundesland- oder Regionsangabe voraus und leiten Sie keine Preise aus einer ID ab.
Im Verarbeitungsweg ohne Streaming werden Duplikate unter den Kandidaten entfernt und die Einträge über die Quellen hinweg zugeteilt, bevor die ausgewählte Ergebnismenge nach dem monatlichen Preis des jeweils ersten Tarifs sortiert wird. Andere Verarbeitungswege können früher mit dem Streaming beginnen; daher gilt nicht für jede Anfrage eine Garantie für eine globale Sortierung oder Duplikatentfernung. Auch die Sortierung belegt nicht, dass die zurückgegebene Stichprobe die günstigste Rufnummer im gesamten Katalog enthält.
Separat bestellen und das Ergebnis bestätigen
Eine Suche kauft oder reserviert nichts. Bewahren Sie die zurückgegebenen Kennungen der Rufnummer und des Tarifs für den Bestellablauf unter demselben Konto auf. Prüfen Sie den tatsächlichen Tarif, die Anforderungen und die Gebühren, bevor Sie eine Bestellung absenden. Registrierungsanforderungen können die Aktivierung verzögern; ein Suchergebnis legt keine feste Aktivierungsfrist fest.
Anfrage
Verwenden Sie ein freigeschaltetes MultiTEL-API-Konto: HTTP-Basic-Zugangsdaten für ein Konto mit Passwort oder Authorization: Bearer bei einem Konto mit Token. Die Berechtigungen und IP-Beschränkungen des Kontos gelten. Beachten Sie die allgemeinen Hinweise zur Authentifizierung.
Pfadparameter und URL-Abfrageparameter. Verwenden Sie GET für den öffentlichen Suchablauf. Die Verarbeitungsroutine akzeptiert auch bestimmte Formular- bzw. Anfragewerte, ist jedoch keine Such-API mit JSON-Anfragetext.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
prefix_id | string | Ja | Die ID eines einzelnen Präfixes aus einer nicht gruppierten getprefixes-Antwort. Kopieren Sie sie exakt; ersetzen Sie sie nicht durch die ID eines Landes, Abdeckungsbereichs, gruppierten Präfixes oder Tarifs. |
quantity | integer | Nein | Angestrebte Abrufmenge, standardmäßig 1. Nicht positive Werte werden zu 1. Der Pfadparameter quantity allein begrenzt die gesamte Ergebnismenge nicht zuverlässig: Eine nicht auf eine Quelle festgelegte Suche ohne den Abfrageparameter quantity kann ihren Abruf ausweiten und vor der weiteren Verarbeitung bis zu 50 Einträge pro Quelle zurückgeben. Verwenden Sie zum normalen Durchsuchen einer begrenzten Ergebnismenge compact=1 und wiederholen Sie die gewünschte Anzahl in der Abfrage, wie im Beispiel. |
| Name | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
quantity | integer | Nein | Gewünschte endgültige Anzahl der Ergebnisse. Nicht leere Werte werden in ganze Zahlen umgewandelt, mindestens jedoch in 1. Im Verarbeitungsweg ohne Streaming und ohne Festlegung auf eine Quelle begrenzt dies die endgültige Zuteilung. Es erzwingt nicht, dass der Dienst entsprechend viele Rufnummern findet. Kompakte Suchen, die auf eine Quelle festgelegt sind, können stattdessen die kompakte Ergebnismenge dieser Quelle zurückgeben, ohne diese Begrenzung anzuwenden. |
compact | string | Nein | Verwenden Sie 1, true oder on für eine kleinere Antwort ohne Streaming mit bis zu 10 Einträgen pro Quelle vor der endgültigen Zuteilung. Die Ergebnisse sind eine Stichprobe des aktuell abgerufenen Bestands, kein vollständiger Katalog. |
number_filter_mode | string | Nein | Optionaler Modus für das Ziffernmuster: contains oder ends_with. Geben Sie zusätzlich number_filter_value an. Die Ergebnisse werden anhand der normalisierten Ziffern der Telefonnummern geprüft; die Suche erfasst nicht den gesamten Bestand, um jeden möglichen Treffer zu garantieren. |
number_filter_value | string | Nein | Zwischen 1 und 15 Ziffern, ohne Leerzeichen, + oder Satzzeichen. Führende Nullen sind relevant; übermitteln Sie den Wert als Text. |
filter_required | string | Nein | Erweitert: 1, true, yes oder on setzt für den Filtermodus eine unterstützte, ausdrücklich ausgewählte Bestandsquelle voraus. Andernfalls gibt die API status.code 422 zurück. Für das normale Durchsuchen des Katalogs ist dies nicht erforderlich. |
pid | string | Nein | Erweiterter Bestandsselektor, der von MultiTEL bereitgestellt wird. Numerische und unterstützte 32-stellige hexadezimale Formen werden akzeptiert; nicht erkannte Werte werden ohne Meldung ignoriert. Lassen Sie ihn bei normaler Nutzung weg. Leiten Sie Selektoren nicht aus Preis-IDs ab und nehmen Sie nicht an, dass ein beliebiger Selektor den Bestand ausschließlich auf die damit bezeichnete Quelle beschränkt. |
Antwort
Ein JSON-Objekt mit status und response. Bei Erfolg ist status.code gleich 200 und response ein Array mit Rufnummerneinträgen. status.results gibt die Anzahl der Einträge im zurückgegebenen Array an; status.msg kann Results: N oder bei einer Streaming-Antwort OK lauten. Ohne compact=1 schreiben manche Suchen das Array response schrittweise und schließen mit status ab; warten Sie daher auf den vollständigen JSON-Antworttext. Es handelt sich nicht um durch Zeilenumbrüche getrennte JSON-Objekte. Prüfen Sie status.code auch bei erfolgreicher HTTP-Übertragung. Typische Felder sind unten dargestellt; quellenspezifische Metadaten und optionale Felder variieren. Behandeln Sie jede Kennung als undurchsichtigen Wert und bewahren Sie die Rufnummer zusammen mit dem ausgewählten Wert von price[].uuid auf.
Beispielhafte Antwortstruktur; keine aktuellen Kontodaten und kein aktuelles Preisangebot.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Fehler
- 401: Authentifizierung fehlgeschlagen. Ungültige oder fehlende Zugangsdaten sowie ein verweigerter Zugriff auf das API-Konto liefern keine Suchergebnisse.
- 404: Invalid prefix ID, Invalid country, Invalid area oder No numbers found. Lesen Sie status.msg; eine Fehlerantwort ist kein Array mit Rufnummern.
- 400: NUMBER_FILTER_INVALID in response.code: ungültiger Modus, ein Wert, der nicht aus 1–15 Ziffern besteht, oder filter_required, ohne dass sowohl Modus als auch Wert angegeben sind.
- 422: NUMBER_FILTER_UNSUPPORTED in response.code: Entweder wird bei diesem Präfix erst bei der Bestellung eine Rufnummer zugewiesen (reason=order_only_prefix und next_function bezeichnet den Bestellendpunkt), oder die ausdrücklich ausgewählte Quelle unterstützt den erforderlichen Filter nicht.
Verfügbarkeit und Nebeneffekte
- Diese Verarbeitungsroutine führt Suchen durch und bereitet Preisangebote vor; sie sendet keine Rufnummernbestellung ab und bucht keine Gebühr für einen Rufnummernkauf ab. Sie kann Katalog-Caches aktualisieren, veraltete Bestandseinträge aus dem Cache entfernen, kontospezifische Tarife speichern und Suchprotokolle schreiben.
- Die Verfügbarkeit ist eine Momentaufnahme, keine Reservierung. Eine anschließende Bestellung kann fehlschlagen oder eine andere Verfügbarkeit zurückmelden. Prüfen und gleichen Sie das Bestellergebnis ab, bevor Sie einen Kauf erneut versuchen.
- Preise sind kontospezifisch. Bewahren Sie die ausgewählte Tarif-ID für dasselbe Konto auf und prüfen Sie die Bestellbedingungen und Gebühren separat; dieser Endpunkt allein belegt nicht, dass ein Preis bis zu einer späteren Bestellung gültig bleibt.
- Die beispielhafte Rufnummer und die Preise sind fiktive Beispiele zur Darstellung der Antwortstruktur, kein aktuelles Preisangebot. Funktionen, Kanalanzahlen, Laufzeit und Registrierungsinformationen müssen dem tatsächlich ausgewählten Ergebnis entnommen werden.
- Einige Beschreibungen zur Registrierung enthalten formatierten Text oder Links. Behandeln Sie zurückgegebene Zeichenfolgen bei der Darstellung in Ihrer eigenen Anwendung als nicht vertrauenswürdige Daten.
- Die Verfügbarkeit von Mobilfunkrufnummern und die entsprechenden Kennzeichnungen hängen von der Berechtigung des Kontos und dem Bestand ab. Ein Katalogpräfix oder die Kennzeichnung is_mobile allein belegt nicht die Mobilfunkfunktionen einer bestimmten Rufnummer.