Telefonnummern aus einem Präfix bestellen

Aus einem Präfix bestellen

Verwenden Sie diese Operation, wenn der Präfixkatalog Sie dazu auffordert, eine Anzahl von Nummern aus einem Präfix zu bestellen, statt einzelne verfügbare Nummern auszuwählen. Beginnen Sie mit Ländern, Gebieten oder Bundesstaaten sowie Präfixen. Verwenden Sie die Präfixkennung und den Tarif aus demselben aktuellen Ergebnis. Für eine bestimmte Nummer, die Sie aus einer Liste verfügbarer Nummern ausgewählt haben, verwenden Sie Eine ausgewählte Telefonnummer kaufen.

Diese Anfrage kann Nummern kaufen und Kosten verursachen. Sie ist weder ein Preisangebot noch eine Reservierung oder ein Testlauf. Prüfen Sie vor dem Absenden die Einrichtungsgebühren und monatlichen Gebühren, die Minutenpreise für eingehende Anrufe, Inklusivminuten, Kanäle, Registrierungsanforderungen und Kaufbeschränkungen des Kontos. Ein Katalogergebnis reserviert keinen Bestand und schreibt keine Preise fest. Prüfungen zur Kontoaufladung können vor der Erfüllung stattfinden; ein Fehler allein beweist nicht, dass weder ein Kauf noch eine Kontoaufladung stattgefunden hat.

Kauf absenden

Verwenden Sie ein aktiviertes API-Konto über HTTPS von einer zulässigen Quell-IP-Adresse aus. Setzen Sie die Variablen anhand Ihrer aktuellen Katalogauswahl und Ihrer freigegebenen Zustellkonfiguration. Der folgende Befehl kauft eine Nummer.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Oben ist eine Formularanfrage mit POST dargestellt. Der Koordinator liest auch ein JSON-Objekt, wenn Content-Type auf application/json gesetzt ist. JSON-Felder überschreiben entsprechende Formular- bzw. Anfragefelder. Verwenden Sie durchgehend eine Kodierung; senden Sie keine widersprüchlichen Werte in Abfrageparametern und Anfragetext.

Einstellungen für Zustellung und Verlängerung

Wählen Sie dieselben Zustelleinstellungen, die Sie für die Nummer im Portal verwenden würden. Dies sind erweiterte Konfigurationswerte, keine Anweisungen zum Erstellen einer gehosteten Telefonanlage oder eines Origination-Trunks. Verwenden Sie eine bekanntermaßen funktionierende Kontokonfiguration erneut und prüfen Sie die gespeicherte Nummer nach dem Kauf. Ein angenommener Kauf allein bestätigt nicht, dass die Sprach- oder SMS-Zustellung funktioniert.

Diese Felder werden normalisiert und an den Kaufprozess übergeben, ihre Speicherung unterscheidet sich jedoch je nach Verarbeitungspfad des Nummernbestands. Die aktuelle Bestellroute stellt die strikten Felder zur Begrenzung des Angebotspreises aus der Anleitung zum Kauf einer ausgewählten Nummer nicht als gleichwertige Schutzmechanismen bereit. Nutzen Sie die Kaufberechtigungen und Preisgrenzen des Kontos und prüfen Sie die resultierende Nummernkonfiguration.

Vollständiges Ergebnis auswerten

Parsen Sie den JSON-Antworttext und prüfen Sie status.code und status.msg, auch wenn die HTTP-Anfrage erfolgreich ist. Diese Route schreibt ihre eigene JSON-Antwort, und auch die gemeinsame Hilfsfunktion für Antworten bildet den Anwendungscode nicht zwingend auf den HTTP-Status ab. Anwendungscodes können JSON-Zahlen oder numerische Zeichenfolgen sein. Setzen Sie status.results nicht voraus; das Feld ist im normalen Bestellergebnis nicht vorhanden.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

Die Kennung, die Nummer und die Preise oben sind fiktiv. Behandeln Sie die Bestell-ID als opake Kennung, ohne ihre Struktur zu interpretieren. numbers listet die Nummern auf, die diese Antwort als gekauft meldet; vergleichen Sie die Länge der Liste mit der angeforderten Anzahl. Preisbeträge sind Zeichenfolgen, und diese Antwort rundet Geldbeträge und Tarifsätze auf zwei Dezimalstellen, einschließlich per_minute; verwenden Sie den aktuellen Katalog für die ursprüngliche Tarifgenauigkeit. Inklusivminuten und Kanäle können als numerische Werte oder numerische Zeichenfolgen ankommen.

Der Preisblock beschreibt den ausgewählten Tarif, der zum Erstellen der Antwort verwendet wurde, und ist weder eine detaillierte Rechnung für jede Nummer noch der Gesamtbetrag der Bestellung. Mehrere infrage kommende Nummern aus dem Bestand können unterschiedliche Tarife haben. Gleichen Sie die einzelnen gekauften Nummern und die Kontotransaktionen ab, statt die Werte dieses Blocks zu multiplizieren und anzunehmen, dies belege den endgültigen Gesamtbetrag.

Teilkäufe und ungewisse Ergebnisse

Ein Anwendungscode von 200 kann zusammen mit einer Warnung und weniger Nummern als angefordert zurückgegeben werden. Ein späterer Fehler macht bereits erfolgte Nummernkäufe nicht rückgängig. Bewahren Sie die zurückgegebene Bestell-ID, die Nummern und die Meldung auf. Gleichen Sie diese Nummern mit Ihrem Bestand und Ihren Kontotransaktionen ab, bevor Sie entscheiden, ob Sie eine verbleibende Anzahl bestellen.

Eine Zeitüberschreitung, ein Verbindungsabbruch während der Anfrage, eine fehlerhaft formatierte Antwort oder ein Fehler nach dem Absenden belegt nicht, dass nichts geschehen ist. Senden Sie nicht automatisch einen weiteren Kauf ab, auch nicht mit derselben Referenz. Bewahren Sie die ursprüngliche Anfrage, die Referenz und jede zurückgegebene Bestell-ID auf, prüfen Sie den Bestand und die Kontotransaktionen und wenden Sie sich an den Support, wenn das Ergebnis ungewiss bleibt.

Eine unbestätigte Bestellung kann den Anwendungscode 400 mit einer Meldung zurückgeben, dass sie noch bestätigt wird. Bewahren Sie die zurückgegebene Bestell-ID auf und gleichen Sie diesen Kauf ab; dies ist keine Aufforderung, ihn erneut abzusenden. Die Wiederherstellung erfasster Bestellungen verfolgt die ursprüngliche Bestellung intern. Eine neue Anfrage an diese Operation erzeugt einen separaten Kaufversuch, statt eine Bestellung anhand Ihrer Referenz fortzusetzen, und kann daher weitere Nummern kaufen und Kosten dafür verursachen. Verwenden Sie keine wiederholten Kaufanfragen, um den Status zu prüfen oder den Bestand zu durchsuchen.

Registrierung und Aktivierung

Eine gekaufte oder zugeteilte Nummer muss möglicherweise noch registriert oder aktiviert werden. Wenn needs_registration den Wert 1 hat, prüfen Sie restrictions und registration_requirements. Letzteres kann auf v3/get_requirements mit Werten für country und number_type verweisen. Durchlaufen Sie das jeweils erforderliche Verfahren zum Identitäts- bzw. Adressnachweis und bestätigen Sie den Status der Nummer, bevor Sie sich auf eingehende Anrufe oder Nachrichten verlassen.

features beschreibt die angegebenen Leistungsmerkmale; es bestätigt weder das tatsächliche Routing noch die Kampagnenfreigabe, die SMS-Zustellung oder den Faxempfang. Prüfen Sie die gespeicherten Zustelleinstellungen und führen Sie den passenden Diensttest durch, sobald die Nummer aktiv ist.

Callbacks zu Bestellungen

Callbacks senden per POST JSON mit dem Bestellstatus und der Antwort; Ihre Referenz wird hinzugefügt, sofern Sie sie angegeben haben. Sie werden für gemeldete Käufe gesendet, einschließlich Teilergebnissen. Ein fehlgeschlagener Callback macht den Kauf nicht rückgängig. Die Zustellung kann wiederholt werden. Behandeln Sie daher Duplikate anhand der Bestell-ID und gleichen Sie die Nummern ab, statt einen weiteren Kauf auszulösen.

Diese Route fügt keine kryptografische Callback-Signatur hinzu. Betrachten Sie einen Callback als Benachrichtigung, die Sie mit Ihrem über authentifizierten Zugriff abgerufenen Bestand abgleichen müssen, und nicht als eigenständige Berechtigung, Kosten zu berechnen, Dienste bereitzustellen oder Zugriff zu gewähren. Fügen Sie der Callback-URL keine API-Zugangsdaten hinzu. Ein weiterer Kauf mit einer anderen Callback-URL aktualisiert die ursprüngliche Bestellung nicht, sondern erzeugt einen separaten Kaufversuch. Bewahren Sie die ursprüngliche Bestell-ID auf, wenn Sie den Support bitten, den zugehörigen Callback zu untersuchen.

Zu behandelnde Fehlerfälle